Updated: 11 December 1998

OpenVMS Utility Routines Manual

The command language (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 OpenVMS Command Definition, Librarian, and Message Utilities Manual.

4.1 Introduction to CLI Routines

The CLI routines include the following:

• CLI$DCL_PARSE
• CLI$DISPATCH
• CLI$GET_VALUE
• CLI$PRESENT

When you use the Command Definition utility to add a new command to your process command table or to the DCL command table, use the CLI$PRESENT and CLI$GET_VALUE routines in the program invoked by the new command. These routines retrieve information about the command string that invokes the program.

When you use the Command Definition utility to create an object module containing a command table and you link this module with a program, you must use all four CLI routines. First, use CLI$DCL_PARSE and CLI$DISPATCH to parse command strings and invoke routines. Then, use CLI$PRESENT and CLI$GET_VALUE within the routines that execute each command.

Note that the application program should declare referenced constants and return status symbols as external symbols; these symbols are resolved upon linking with a utility shareable image.

A CLI must be present in order to use the CLI routines. If your application can be run from a detached process, the application should first verify that a CLI exists. For information about how to verify that a CLI exists for a process, see the description of the $GETJPI system service in the OpenVMS System Services Reference Manual.

Example 4-1 contains a command definition file (SUBCOMMANDS.CLD) and a Fortran program (INCOME.FOR). INCOME.FOR uses the command definitions in SUBCOMMANDS.CLD to process commands. To execute the example, enter the following commands:

$ SET COMMAND SUBCOMMANDS/OBJECT=SUBCOMMANDS $ FORTRAN INCOME $ LINK INCOME,SUBCOMMANDS $ RUN INCOME

INCOME.FOR accepts a command string and parses it using CLI$DCL_PARSE. If the command string is valid, the program uses CLI$DISPATCH to execute the command. Each routine uses CLI$PRESENT and CLI$GET_VALUE to obtain information about the command string.

Example 4-1 Using the CLI Routines to Retrieve Information About Command Lines in a Fortran Program

**************************************************** SUBCOMMANDS.CLD **************************************************** MODULE INCOME_SUBCOMMANDS DEFINE VERB ENTER ROUTINE ENTER DEFINE VERB FIX ROUTINE FIX QUALIFIER HOUSE_NUMBERS, VALUE (LIST) DEFINE VERB REPORT ROUTINE REPORT QUALIFIER OUTPUT, VALUE (TYPE = $FILE, DEFAULT = "INCOME.RPT") DEFAULT **************************************************** INCOME.FOR **************************************************** PROGRAM INCOME INTEGER STATUS, 2 CLI$DCL_PARSE, 2 CLI$DISPATCH INCLUDE '($RMSDEF)' INCLUDE '($STSDEF)' EXTERNAL INCOME_SUBCOMMANDS, 2 LIB$GET_INPUT ! Write explanatory text STATUS = LIB$PUT_OUTPUT 2 ('Subcommands: ENTER - FIX - REPORT') IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) STATUS = LIB$PUT_OUTPUT 2 ('Press Ctrl/Z to exit') IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Get first subcommand STATUS = CLI$DCL_PARSE (%VAL (0), 2 INCOME_SUBCOMMANDS, ! CLD module 2 LIB$GET_INPUT, ! Parameter routine 2 LIB$GET_INPUT, ! Command routine 2 'INCOME> ') ! Command prompt ! Do it until user presses Ctrl/Z DO WHILE (STATUS .NE. RMS$_EOF) ! If no error on dcl_parse IF (STATUS) THEN ! Dispatch depending on subcommand STATUS = CLI$DISPATCH () IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) ! Do not signal warning again ELSE IF (IBITS (STATUS, 0, 3) .NE. STS$K_WARNING) THEN CALL LIB$SIGNAL (%VAL (STATUS)) END IF ! Get another subcommand STATUS = CLI$DCL_PARSE (%VAL (0), 2 INCOME_SUBCOMMANDS, ! CLD module 2 LIB$GET_INPUT, ! Parameter routine 2 LIB$GET_INPUT, ! Command routine 2 'INCOME> ') ! Command prompt END DO END INTEGER FUNCTION ENTER () INCLUDE '($SSDEF)' TYPE *, 'ENTER invoked' ENTER = SS$_NORMAL END INTEGER FUNCTION FIX () INTEGER STATUS, 2 CLI$PRESENT, 2 CLI$GET_VALUE CHARACTER*15 HOUSE_NUMBER INTEGER*2 HN_SIZE INCLUDE '($SSDEF)' EXTERNAL CLI$_ABSENT TYPE *, 'FIX invoked' ! If user types /house_numbers=(n,...) IF (CLI$PRESENT ('HOUSE_NUMBERS')) THEN ! Get first value for /house_numbers STATUS = CLI$GET_VALUE ('HOUSE_NUMBERS', 2 HOUSE_NUMBER, 2 HN_SIZE) ! Do it until the list is depleted DO WHILE (STATUS) TYPE *, 'House number = ', HOUSE_NUMBER (1:HN_SIZE) STATUS = CLI$GET_VALUE ('HOUSE_NUMBERS', 2 HOUSE_NUMBER, 2 HN_SIZE) END DO ! Make sure termination status was correct IF (STATUS .NE. %LOC (CLI$_ABSENT)) THEN CALL LIB$SIGNAL (%VAL (STATUS)) END IF END IF FIX = SS$_NORMAL END INTEGER FUNCTION REPORT () INTEGER STATUS, 2 CLI$GET_VALUE CHARACTER*255 FILENAME INTEGER*2 FN_SIZE INCLUDE '($SSDEF)' TYPE *, 'REPORT entered' ! Get value for /output STATUS = CLI$GET_VALUE ('OUTPUT', 2 FILENAME, 2 FN_SIZE) IF (.NOT. STATUS) CALL LIB$SIGNAL (%VAL (STATUS)) TYPE *, 'Output file: ', FILENAME (1:FN_SIZE) REPORT = SS$_NORMAL END

4.3 CLI Routines

This section describes the individual CLI routines.

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]

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.

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

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

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.

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.

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$_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.
RMS$_EOF	Routine terminated. You pressed Ctrl/Z in response to a prompt, causing the CLI$DCL_PARSE routine to terminate.

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]

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.

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.

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.

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.

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]

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.

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:

• A parameter, qualifier, keyword name, or label
• 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.

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.

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4493PRO_003.HTML