/sys$common/syshlp/helplib.hlb CLI Routines, CLI$GET_VALUE, Arguments  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 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.