1 CLI_Routines 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 OpenVMS Command Definition, Librarian, and Message Utilities Manual. 2 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] 3 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 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. 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. 3 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. 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] 3 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. 3 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. 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. 3 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. 2 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 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 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 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. 3 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. 2 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 3 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. 3 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 OpenVMS Programming Concepts Manual). 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. 3 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.