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

    The CLI$GET_VALUE routine retrieves a value associated with a
    specified qualifier, parameter, keyword, or keyword path from the
    parsed command string.

    Format

      CLI$GET_VALUE  entity_desc ,retdesc [,retlength]

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 Condition Values Returned.

2 - Arguments

 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. The entity_desc argument can be expressed as
    one of the following:

    o  A parameter, qualifier, keyword name, or label

    o  A keyword path

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

    Use a keyword path to reference keywords used as values of
    parameters, qualifiers, or other keywords. A keyword path
    contains a list of entity names or labels separated by periods.
    If the LABEL clause was used to assign a label to an entity, you
    must specify the label in the keyword path. Otherwise, you must
    use the name of the entity.

    The following command string illustrates a situation where
    keyword paths are needed to uniquely identify keywords. In this
    command string, you can use the same keywords with more than one
    qualifier. (This is defined in the command definition file by
    having two qualifiers refer to the same DEFINE TYPE statement.)

    $ NEWCOMMAND/QUAL1=(START=5,END=10)/QUAL2=(START=2,END=5)

    The keyword path QUAL1.START identifies the START keyword when it
    is used with QUAL1; the keyword path QUAL2.START identifies the
    keyword START when it is used with QUAL2. Because the name START
    is an ambiguous reference if used alone, the keywords QUAL1 and
    QUAL2 are needed to resolve the ambiguity.

    You can omit keywords from the beginning of a keyword path if
    they are not needed to unambiguously resolve a keyword reference.
    A keyword path can be no more than eight names long.

    If you use an ambiguous keyword reference, DCL resolves the
    reference by checking, in the following order:

    1. The parameters in your command definition file, in the order
       they are listed

    2. The qualifiers in your command definition file, in the order
       they are listed

    3. The keyword paths for each parameter, in the order the
       parameters are listed

    4. The keyword paths for each qualifier, in the order the
       qualifiers are listed

    DCL uses the first occurrence of the entity as the keyword path.
    Note that DCL does not issue an error message if you provide
    an ambiguous keyword. However, because the keyword search order
    may change in future releases of OpenVMS, you should never use
    ambiguous keyword references.

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

 retdesc

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor
    Character string containing the value retrieved by CLI$GET_
    VALUE. The retdesc argument is the address of a string descriptor
    pointing to the buffer to receive the string value retrieved
    by CLI$GET_VALUE. The string is returned using the STR$COPY_DX
    Run-Time Library routine.

    If there are errors in the specification of the return descriptor
    or in copying the results using that descriptor, the STR$COPY_DX
    routine will signal the errors. For a list of these errors, see
    the OpenVMS RTL String Manipulation (STR$) Manual.

 retlength

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Word containing the number of characters DCL returns to retdesc.
    The retlength argument is the address of the word containing the
    length of the retrieved value.

3 - Description

    The CLI$GET_VALUE routine retrieves a value associated with a
    specified qualifier, parameter, keyword, or keyword path from the
    parsed command string.

                                   NOTE

       Only use the CLI$GET_VALUE routine to retrieve values from
       parsed command strings (through DCL or CLI$DCL_PARSE). When
       you use a foreign command to activate an image, the DCL
       parsing process is interrupted. As a result, CLI$GET_VALUE
       returns either values from the previously parsed command
       string or a status of CLI$_ABSENT if it is the first command
       string parsed.

    You can use the following label names with CLI$GET_VALUE to
    retrieve special strings:

    $VERB  Describes the verb in the command string (the first four
           letters of the spelling as defined in the command table,
           instead of the string that was actually typed).
    $LINE  Describes the entire command string as stored internally
           by DCL. In the internal representation of the command
           string, multiple spaces and tabs are removed, alphabetic
           characters are converted to uppercase, and comments are
           stripped. Integers are converted to decimal. If dates and
           times are specified in the command string, DCL fills in
           any defaulted fields. Also, if date-time strings (such
           as YESTERDAY) are used, DCL substitutes the corresponding
           absolute time value.

    To obtain the values for a list of entities, call CLI$GET_
    VALUE repeatedly until all values have been returned. After
    each CLI$GET_VALUE call, the returned condition value indicates
    whether there are more values to be obtained. Call CLI$GET_VALUE
    until you receive a condition value of CLI$_ABSENT.

    When you are using CLI$GET_VALUE to obtain a list of qualifier
    or keyword values, get all values in the list before starting to
    parse the next entity.

4 - Condition Values Returned

    SS$_NORMAL         Returned value terminated by a blank or an
                       end-of-line. This shows that the value is the
                       last, or only, value in the list.
    CLI$_ABSENT        No value returned. The value is not present,
                       or the last value in the list was already
                       returned.
    CLI$_COMMA         Returned value terminated by a comma. This
                       shows there are additional values in the list.
    CLI$_CONCAT        Returned value concatenated to the next
                       value with a plus sign. This shows there are
                       additional values in the list.
    CLI$_INVREQTYP     Calling process did not have a CLI to perform
                       this function or the CLI did not support the
                       request.