| Previous | Contents | Index |
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 HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.
4.1 Introduction to CLI Routines
The CLI routines include the following:
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 HP OpenVMS System Services Reference Manual.
Do not use the CLI routines to obtain values from foreign commands. Using a foreign command to activate an image (instead of the SET COMMAND command) disrupts the building of the DCL parse tables. |
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
|
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.
CLI$DCL_PARSE [command_string] ,table [,param_routine] [,prompt_routine] [,prompt_string]
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.
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 HP 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 HP 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.
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.
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.
The CLI$DISPATCH routine invokes the subroutine associated with the verb most recently parsed by a CLI$DCL_PARSE routine call.
CLI$DISPATCH [userarg]
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.
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.
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.
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.
CLI$GET_VALUE entity_desc ,retdesc [,retlength]
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.
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:
- The parameters in your command definition file, in the order they are listed
- The qualifiers in your command definition file, in the order they are listed
- The keyword paths for each parameter, in the order the parameters are listed
- 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 HP 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.
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.
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.
| Previous | Next | Contents | Index |