VMS Help CLI Routines, CLI$PRESENT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The CLI$PRESENT routine examines the parsed command string to
    determine whether the entity referred to by the entity_desc
    argument is present.

    Format

      CLI$PRESENT  entity_desc

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Conditon Values Returned.

2 - Argument

 entity_desc

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Character string containing the label (or name if no label is
    defined) of the entity. The entity_desc argument is the address
    of a string descriptor that points to an entity that may appear
    on a command line. An entity can be expressed as one of the
    following:

    o  A parameter, qualifier, or keyword name or label

    o  A keyword path

    A keyword path is used to reference keywords that are accepted
    by parameters, qualifiers, or other keywords. A keyword path
    contains a list of entity names separated by periods. See the
    description of the entity_desc argument in the CLI$GET_VALUE
    routine for more information about specifying keyword paths as
    arguments for CLI routines.

    The entity_desc argument can contain parameter, qualifier, or
    keyword names, or can contain labels that were assigned with
    the LABEL clause in the command definition file. If the LABEL
    clause was used to assign a label to a qualifier, parameter, or
    keyword, you must specify the label in the entity_desc argument.
    Otherwise, you must use the actual name of the qualifier,
    parameter, or keyword.

    If the entity_desc argument does not exist in the command table,
    CLI$PRESENT signals a syntax error (by means of the signaling
    mechanism described in the OpenVMS Programming Concepts Manual).

3 - Description

    The CLI$PRESENT routine examines the parsed command string to
    determine whether the entity referred to by the entity_desc
    argument is present.

    When CLI$PRESENT tests whether a qualifier is present, the
    condition value indicates whether the qualifier is used globally
    or locally. You can use a global qualifier anywhere in the
    command line; you use a local qualifier only after a parameter.
    A global qualifier is defined in the command definition file
    with PLACEMENT=GLOBAL; a local qualifier is defined with
    PLACEMENT=LOCAL.

    When you test for the presence of a global qualifier, CLI$PRESENT
    determines if the qualifier is present anywhere in the command
    string. If the qualifier is present in its positive form,
    CLI$PRESENT returns CLI$_PRESENT; if the qualifier is present
    in its negative form, CLI$PRESENT returns CLI$_NEGATED.

    You can test for the presence of a local qualifier when you are
    parsing parameters that can be followed by qualifiers. After you
    call CLI$GET_VALUE to fetch the parameter value, call CLI$PRESENT
    to determine whether the local qualifier is present. If the local
    qualifier is present in its positive form, CLI$PRESENT returns
    CLI$_LOCPRES; if the local qualifier is present in its negative
    form, CLI$PRESENT returns CLI$_LOCNEG.

    A positional qualifier affects the entire command line if
    it appears after the verb but before the first parameter. A
    positional qualifier affects a single parameter if it appears
    after a parameter. A positional qualifier is defined in the
    command definition file with the PLACEMENT=POSITIONAL clause.

    To determine whether a positional qualifier is used globally,
    call CLI$PRESENT to test for the qualifier before you call
    CLI$GET_VALUE to fetch any parameter values. If the positional
    qualifier is used globally, CLI$PRESENT returns either CLI$_
    PRESENT or CLI$_NEGATED.

    To determine whether a positional qualifier is used locally,
    call CLI$PRESENT immediately after a parameter value has been
    fetched by CLI$GET_VALUE. The most recent CLI$GET_VALUE call to
    fetch a parameter defines the context for a qualifier search.
    Therefore, CLI$PRESENT tests whether a positional qualifier was
    specified after the parameter that was fetched by the most recent
    CLI$GET_VALUE call. If the positional qualifier is used locally,
    CLI$PRESENT returns either CLI$_LOCPRES or CLI$_LOCNEG.

4 - Condition Values Returned

    CLI$_ABSENT        Specified entity not present, and it is not
                       present by default.
    CLI$_DEFAULTED     Specified entity not present, but it is
                       present by default.
    CLI$_INVREQTYP     Calling process did not have a CLI to perform
                       this function, or the CLI did not support the
                       request.
    CLI$_LOCNEG        Specified qualifier present in negated form
                       (with /NO) and used as a local qualifier.
    CLI$_LOCPRES       Specified qualifier present and used as a
                       local qualifier.
    CLI$_NEGATED       Specified qualifier present in negated form
                       (with /NO) and used as a global qualifier.
    CLI$_PRESENT       Specified entity present in the command
                       string. This status is returned for all
                       entities except local qualifiers and
                       positional qualifiers that are used locally.