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 VSI 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.