The command language interface (CLI) routines process command
strings using information from a command table. A command table
contains command definitions that describe the allowable formats
for commands. To create or modify a command table, you must
write a command definition file and then process this file with
the Command Definition Utility (the SET COMMAND command). For
information about how to use the Command Definition Utility,
see the VSI OpenVMS Command Definition, Librarian, and Message
Utilities Manual.
1 – CLI$DCL_PARSE
The CLI$DCL_PARSE routine supplies a command string to DCL for
parsing. DCL separates the command string into its individual
elements according to the syntax specified in the command table.
Format
CLI$DCL_PARSE [command_string] ,table [,param_routine]
[,prompt_routine] [,prompt_string]
1.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.
1.2 – Arguments
command_string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor-fixed length
Character string containing the command to be parsed. The
command_string argument is the address of a descriptor specifying
the command string to be parsed. If the command string includes
a comment (delimited by an exclamation mark), DCL ignores the
comment.
If the command string contains a hyphen to indicate that the
string is being continued, DCL uses the routine specified in
the prompt_routine argument to obtain the rest of the string.
The command string is limited to 256 characters. However, if the
string is continued with a hyphen, CLI$DCL_PARSE can prompt for
additional input until the total number of characters is 1024.
If you specify the command_string argument as zero and specify a
prompt routine, then DCL prompts for the entire command string.
However, if you specify the command_string argument as zero and
also specify the prompt_routine argument as zero, DCL restores
the parse state of the command string that originally invoked the
image.
CLI$DCL_PARSE does not perform DCL-style symbol substitution on
the command string.
table
OpenVMS usage:address
type: address
access: read only
mechanism: by value
Address of the compiled command tables to be used for command
parsing. The command tables are compiled separately by
the Command Definition Utility using the DCL command SET
COMMAND/OBJECT and are then linked with your program. A global
symbol is defined by the Command Definition Utility that provides
the address of the tables. The global symbol's name is taken
from the module name given on the MODULE statement in the command
definition file, or from the file name if no MODULE statement is
present.
param_routine
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Name of a routine to obtain a required parameter not supplied in
the command text. The param_routine argument is the address of a
routine containing a required parameter that was not specified in
the command_string argument.
To specify the parameter routine, use the address of LIB$GET_
INPUT or the address of a routine of your own that has the
same three-argument calling format as LIB$GET_INPUT. See the
description of LIB$GET_INPUT in the VSI OpenVMS RTL Library (LIB$)
Manual for information about the calling format.
If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates
the error status outward or signals RMS$_EOF in the cases listed
in the Description help topic.
You can obtain the prompt string for a required parameter from
the command table specified in the table argument.
prompt_routine
OpenVMS usage:procedure
type: procedure value
access: read only
mechanism: by reference
Name of a routine to obtain all or part of the text of a command.
The prompt_routine argument is the address of a routine to obtain
the text or the remaining text of the command depending on the
command_string argument. If you specify a zero in the command_
string argument, DCL uses this routine to obtain an entire
command line. DCL uses this routine to obtain a continued command
line if the command string (obtained from the command_string
argument) contains a hyphen to indicate that the string is being
continued.
To specify the prompt routine, use the address of LIB$GET_INPUT
or the address of a routine of your own that has the same three-
argument calling format as LIB$GET_INPUT. See the description
of LIB$GET_INPUT in the VSI OpenVMS RTL Library (LIB$) Manual for
information about the calling format.
If LIB$GET_INPUT returns error status, CLI$DCL_PARSE propagates
the error status outward or signals RMS$_EOF in the cases listed
in the Description help topic.
prompt_string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Character string containing a prompt. The prompt_string argument
is the address of a string descriptor pointing to the prompt
string to be passed as the second argument to the prompt_routine
argument.
If DCL is using the prompt routine to obtain a continuation line,
DCL inserts an underscore character before the first character
of the prompt string to create the continuation prompt. If DCL is
using the prompt routine to obtain an entire command line (that
is, a zero was specified as the command_string argument), DCL
uses the prompt string exactly as specified.
The prompt string is limited to 32 characters. The string
COMMAND> is the default prompt string.
1.3 – Description
The CLI$DCL_PARSE routine supplies a command string to DCL for
parsing. DCL parses the command string according to the syntax in
the command table specified in the table argument.
The CLI$DCL_PARSE routine can prompt for required parameters if
you specify a parameter routine in the routine call. In addition,
the CLI$DCL_PARSE routine can prompt for entire or continued
command lines if you supply the address of a prompt routine.
If you do not specify a command string to parse and the user
enters a null string in response to the DCL prompt for a command
string, CLI$DCL_PARSE immediately terminates and returns the
status CLI$_NOCOMD.
If DCL prompts for a required parameter and the user presses
Ctrl/Z, CLI$DCL_PARSE immediately terminates and returns the
status CLI$_NOCOMD, regardless of whether you specify or do not
specify a command string to parse. If DCL prompts for a parameter
that is not required and the user presses Ctrl/Z, CLI$DCL_PARSE
returns the status CLI$_NORMAL.
Whenever CLI$DCL_PARSE encounters an error, it both signals and
returns the error.
1.4 – Condition Values Returned
CLI$_INVREQTYP Calling process did not have a CLI to perform
this function, or the CLI did not support the
request.
CLI$_IVKEYW Invalid keyword.
CLI$_IVQUAL Unrecognized qualifier.
CLI$_IVVERB Invalid or missing verb.
CLI$_NOCOMD Routine terminated. You entered a null string
in response to a prompt from the prompt_
routine argument, causing the CLI$DCL_PARSE
routine to terminate.
CLI$_NORMAL Normal successful completion.
CLI$_ONEVAL List of values not allowed; enter one only.
RMS$_EOF Routine terminated. You pressed Ctrl/Z in
response to a prompt, causing the CLI$DCL_
PARSE routine to terminate.
2 – CLI$DISPATCH
The CLI$DISPATCH routine invokes the subroutine associated with
the verb most recently parsed by a CLI$DCL_PARSE routine call.
Format
CLI$DISPATCH [userarg]
2.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. The condition value that this routine
can return is listed under Condition Values Returned.
2.2 – Argument
userarg
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Data to be passed to the action routine. The userarg argument
is a longword that contains the data to be passed to the action
routine. This data can be used in any way you want.
2.3 – Description
The CLI$DISPATCH routine invokes the subroutine associated with
the verb most recently parsed by a CLI$DCL_PARSE routine call.
If the routine is successfully invoked, the return status is the
status returned by the action routine. Otherwise, a status of
CLI$_INVROUT is returned.
2.4 – Condition Values Returned
CLI$_INVREQTYP Calling process did not have a CLI to perform
this function or the CLI did not support the
request.
CLI$_INVROUT CLI$DISPATCH unable to invoke the routine. An
invalid routine is specified in the command
table, or no routine is specified.
3 – CLI$GET_VALUE
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]
3.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.
3.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.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.
3.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.
4 – CLI$PRESENT
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
4.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.
4.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 VSI OpenVMS Programming Concepts
Manual).
4.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.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.