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