Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Command Definition, Librarian, and Message Utilities Manual
Previous Contents Index

CDU Qualifiers

The following pages describe the qualifiers that can be used with the DCL command SET COMMAND. The qualifiers are as follows:

The /DELETE, /OBJECT, and /REPLACE qualifiers indicate SET COMMAND modes; these qualifiers are mutually exclusive.

/ALPHA

Causes CDU to create an OpenVMS Alpha object module when used with the /OBJECT qualifier. The default is to create OpenVMS Alpha object modules on OpenVMS Alpha systems and to create OpenVMS VAX object modules on OpenVMS VAX systems

Format

SET COMMAND/ALPHA/OBJECT [=object-filespec] filespec

object-filespec

The file specification for the object file. If no file name is specified, default to the name of the first input (command definition) file; the default file type is .OBJ.

filespec

The command definition file to be processed (wildcard characters are allowed). The default type is .CLD.

Example


$ SET COMMAND /ALPHA /OBJECT=A  TEST
MODULE TEST_TABLE

In this example, the command definition file TEST.CLD is processed and the command table is written as an OpenVMS Alpha object module to a file named A.OBJ

/DELETE

Used to delete verb names or synonym names from the command table. If a verb name has synonyms, this qualifier deletes the specified verb or synonym name. If any synonyms remain, or if you delete synonyms and the original verb name remains, the remaining names still reference the verb definition.

You can use the /DELETE qualifier to delete a verb in either your process command table or in a command table file specified with the /TABLE qualifier. If you do not use the /TABLE qualifier to specify an alternate command table, the default is to delete verbs from your process command table. If you do not use the /OUTPUT qualifier to specify an output file, the default is to return the modified command table to your process.

You cannot use the /LISTING, /OBJECT, or /REPLACE qualifier with /DELETE.

Format

SET COMMAND/DELETE= (verb[,...])

verb

A verb or verb synonym to be deleted from the specified command table. If you specify two or more names, separate them with commas and enclose the list in parentheses.

Examples

#1 

$ SET COMMAND/DELETE=DO

In this example, SET COMMAND deletes the verb DO from your process command table.

#2 

$ SET COMMAND/DELETE=(PUSH,SHOVE)/TABLE=TEST_TABLE/OUTPUT=NEW_TABLE

The commands PUSH and SHOVE are deleted from the command table TEST_TABLE.EXE. The /OUTPUT qualifier writes the modified table to the file NEW_TABLE.EXE. If you do not include the /OUTPUT qualifier, CDU uses the modified table to overwrite your process command table.

/LISTING

Controls whether an output listing is created and optionally provides an output file specification for the listing file. A listing file contains a listing of the command definitions along with any error messages. The listing file is similar to a compiler listing.

If you specify the /LISTING qualifier and omit the file specification, output is written to the default device and directory; the listing file has the same name as the first command definition file and a file type of .LIS.

You can use the /LISTING qualifier only in /OBJECT or /REPLACE mode; you cannot create a listing in /DELETE mode. In /OBJECT and /REPLACE modes, the default is /NOLISTING.

Format

SET COMMAND/LISTING [=listing-filespec] [filespec[,...]]

SET COMMAND/NOLISTING

listing-filespec

The file specification for the listing file. The default file name is the name of the first command definition file. The default file type is .LIS.

filespec

The name of the command definition file to be processed (wildcard characters are allowed). The default file type is .CLD.

Examples

#1 

$ SET COMMAND/LISTING TEST

In this example, the command definition file TEST.CLD is processed by CDU, and the new verbs are added to your process command table. (By default, SET COMMAND uses /REPLACE mode.) The modified table is returned to your process, and a listing file named TEST.LIS is created.

#2 

$ SET COMMAND/LISTING=A TEST

The command definition file TEST.CLD is processed by CDU, and the verb definitions are added to your process command table. The modified table is returned to your process, and a listing file named A.LIS is created.

#3 

$ SET COMMAND/LISTING/OBJECT GAMES

SET COMMAND is used to create an object module (GAMES.OBJ) that contains the command definitions in GAMES.CLD. The output object module can then be linked with a program. A listing file named GAMES.LIS is created.

/OBJECT

Creates an object module from a command definition file and optionally provides an object file specification. You cannot use the /OBJECT qualifier to create an object module from a command definition that contains the IMAGE clause.

An object module containing a command table can be linked with the object modules from your program. This enables the program to use its own command table for parsing command strings and executing routines.

On OpenVMS VAX systems, the /OBJECT qualifier creates a VAX module by default. Note that you cannot combine VAX modules and Alpha modules in the same object file. For more information, see the description of the /VAX qualifier.

On OpenVMS Alpha systems, the /OBJECT qualifier creates an Alpha module by default. Note that you cannot combine Alpha modules and VAX modules in the same object file. For more information, see the description of the /ALPHA qualifier.

You can specify only one command definition file when you use SET COMMAND/OBJECT.

If you specify the /OBJECT qualifier and omit the file specification, output is written to the default device and directory; the object file has the same name as the input file and a file type of .OBJ.

You cannot use the /DELETE, /OUTPUT, /REPLACE, or /TABLE qualifier with /OBJECT.

Format

SET COMMAND/OBJECT [=object-filespec]

filespec

object-filespec

The file specification for the object file. If no file name is specified, defaults to the name of the first input (command definition) file; the default file type is .OBJ.

filespec

The command definition file to be processed (wildcard characters are allowed). The default file type is .CLD.

Examples

#1 

$ SET COMMAND/OBJECT TEST

In this example, the command definition file TEST.CLD is processed and a new command table is created. This table is written as an object module to a file named TEST.OBJ. (If not explicitly given, the name of the object module defaults to the name of the command definition file with a file type of .OBJ.)

#2 

$ SET COMMAND/OBJECT=A TEST

In this example, the command definition file TEST.CLD is processed and the command table is written as an object module to a file named A.OBJ.

/OUTPUT

Controls where the modified command table should be placed. If you provide an output file specification, the modified command table is written to the specified file. If you do not provide an output file specification, the modified command table is placed in your process. The /NOOUTPUT qualifier indicates that no output is to be generated.

You can use the /OUTPUT qualifier only in /DELETE or /REPLACE mode; the default is /OUTPUT with no file specification. You cannot use the /OUTPUT qualifier in /OBJECT mode.

Format

SET COMMAND/OUTPUT [=output-filespec] [filespec[,...]]

SET COMMAND/NOOUTPUT

output-filespec

The specification of the output file that contains the edited command table. The default file type is .EXE.

You can specify an output file only when you use the /TABLE=filespec qualifier to describe an input table.

filespec

The name of the command definition file to be processed (wildcard characters are allowed). The default file type is .CLD.

Examples

#1 

$ SET COMMAND/OUTPUT TEST

The file TEST.CLD is processed and the definitions are added to your process command table. The modified table is returned to your process. (The result is the same as if you had issued the command SET COMMAND TEST.)

#2 

$ SET COMMAND/TABLE=A/OUTPUT=A TEST

The definitions from TEST.CLD are added to command table A.EXE. CDU writes the modified table to the new A.EXE, which has a version number one greater than the input table file.

If you use the /TABLE qualifier and do not provide an output file specification, the modified command table replaces your process command table.

#3 

$ SET COMMAND/NOOUTPUT TEST

The definitions from TEST.CLD are added to your process command table, and the modified table is not written anywhere. You can use this command string to test whether a command definition file is written correctly.

/REPLACE

Used to add or replace verbs in the command table.

You can use the /REPLACE qualifier to either modify the process command table or, with the /TABLE qualifier, to modify a command table file.

You cannot use the /REPLACE qualifier with the /OBJECT or /DELETE qualifier. If you do not explicitly specify /DELETE, /OBJECT, or /REPLACE, the default is /REPLACE.

Format

SET COMMAND/REPLACE [filespec [,...]]

filespec

The file to be processed (wildcard characters are allowed). The default file type is .CLD.

Examples

#1 

$ SET COMMAND SCROLL

This command adds the command definitions from the file SCROLL.CLD to your process command table. The /REPLACE, /TABLE, and /OUTPUT qualifiers are present by default. The /REPLACE qualifier indicates /REPLACE mode; the /TABLE qualifier indicates that your process command table is to be modified; and the /OUTPUT qualifier indicates that the modified command table is to be written to your process.

#2 

$ SET COMMAND/TABLE/OUTPUT SCROLL

This command adds the command definitions from the file SCROLL.CLD to your process command table and returns the modified table to your process. (The /TABLE and /OUTPUT qualifiers, with no specified files, default to your process command table.) This command is the same as the command SET COMMAND SCROLL.

#3 

$ SET COMMAND/TABLE=COMMAND_TABLE/OUTPUT=NEW_TABLE TEST

CDU adds command definitions from TEST.CLD to the command table in the file COMMAND_TABLE.EXE, and the modified command table is written to NEW_TABLE.EXE.

If you use the /TABLE qualifier to provide an input command table, be sure to provide an output file specification. Otherwise, CDU uses the modified command table to replace your process command table.

#4 

$ SET COMMAND/TABLE=TEST_TABLE MYCOMS

In this example, the definitions from MYCOMS.CLD are added to the command table in TEST_TABLE.EXE. The modified command table is written to your process and replaces your process command table. You should replace your process command table only if the new command table contains all the commands you need to perform your work. DCL commands copied to your process command table when you logged in are overwritten.

/TABLE

Specifies the command table to be modified. If you specify the /TABLE qualifier and omit the file specification, the current process command table is modified.

Can be used with /DELETE or /REPLACE but not with /OBJECT; the default is /TABLE with no input file specification.

If you include a file specification, the specified command table is modified.

If you use the /TABLE qualifier without the /OUTPUT qualifier, the modified command table replaces your process command table.

Format

SET COMMAND/TABLE [=input-filespec]

[filespec [,...]]

SET COMMAND/NOTABLE

input-filespec

The input file that contains the command table to be edited. The default file type is .EXE.

filespec

The command definition file to be processed (wildcard characters are allowed). The default file type is .CLD.

Examples

#1 

$ SET COMMAND/TABLE TEST

The commands from TEST.CLD are added to your process command table and the results are returned to your process. The /TABLE qualifier with no file specification indicates that your process command table is to be modified. This command is the same as the command SET COMMAND TEST.

#2 

$ SET COMMAND/TABLE=A/OUTPUT=B TEST

CDU adds the command definitions from TEST.CLD to the command table in A.EXE and writes the modified command table to B.EXE.

If you use the /TABLE qualifier to provide an input command table, be sure to provide an output file specification. Otherwise, the modified command table replaces your process command table.

#3 

$ SET COMMAND/TABLE=A

In this example, the command table in A.EXE is written to your process and replaces your process command table. You should replace your process command table only if the new command table contains all the commands you need to perform your work. DCL commands copied to your process command table when you logged in are overwritten.

/VAX

Causes CDU to create an OpenVMS VAX object module when used with the /OBJECT qualifier. The default is to create OpenVMS Alpha object modules on OpenVMS Alpha systems and to create OpenVMS VAX object modules on OpenVMS VAX systems.

Format

SET COMMAND/VAX/OBJECT [=object-filespec] filespec

object-filespec

The file specification for the object file. If no file name is specified, defaults to the name of the first input (command definition) file; the default file type is .OBJ.

filespec

The command definition file to be processed (wildcard characters are allowed). The default file type is .CLD.

Example


$ SET COMMAND/VAX/OBJECT=A TEST

In this example, the command definition file TEST.CLD is processed and the command table is written as an OpenVMS VAX object module to a file named A.OBJ.

CDU Examples

Adding a Command to Your Process Command Table

This example shows how to add a command to your process command table and how to use command language routines in the image invoked by the new command.

The following command definition file defines a new verb called SAMPLE: 


DEFINE VERB SAMPLE 
       IMAGE  "USERDISK:[MYDIR]SAMPLE" 
       PARAMETER  P1,LABEL=FILESPEC 
       QUALIFIER  EDIT

To process this command definition file, use the DCL command SET COMMAND: 


$ SET COMMAND SAMPLE

This command string invokes CDU to process the command definition file (SAMPLE.CLD) and to add the verb SAMPLE to your process command table. The modified table is returned to your process.

The following program illustrates a program called SAMPLE.BAS. It uses the CLI$PRESENT and CLI$GET_VALUE command language routines to obtain information about a command string parsed by DCL. 


1    EXTERNAL INTEGER FUNCTION CLI$PRESENT,CLI$GET_VALUE 
 
10   IF CLI$PRESENT('EDIT') AND 1% 
     THEN 
         PRINT '/EDIT IS PRESENT',A$ 
 
20   IF CLI$PRESENT('FILESPEC') AND 1% 
     THEN 
         CALL CLI$GET_VALUE('FILESPEC',A$) 
         PRINT 'FILESPEC = ',A$ 
 
30   END

This source program must be compiled and linked before it can be invoked by a command verb. When you compile and link the source program, the output file (SAMPLE.EXE) contains an executable image.

You can now use the SAMPLE command to invoke the image SAMPLE.EXE, as follows: 


$ SAMPLE

DCL processes this command in the same way it processes the DCL commands provided by Digital; that is, DCL checks the syntax and then invokes SAMPLE.EXE to execute the command.

You can include in the command string any parameters and qualifiers defined for the SAMPLE command verb. For example, you can enter the following command string: 


$ SAMPLE MYFILE

In this case, you receive the following display on your screen: 


FILESPEC = MYFILE

You can also include the /EDIT qualifier in the command string. For example: 


$ SAMPLE MYFILE/EDIT

In this case, you receive the following display on your screen: 


/EDIT IS PRESENT 
FILESPEC = MYFILE

If you include a qualifier that is not accepted by the command verb, you receive a DCL error message. For example: 


$ SAMPLE MYFILE/UPDATE
%DCL-W-IVQUAL, unrecognized qualifier - check validity, spelling, and placement
  \UPDATE\

If you include two or more parameters in the command string for a verb that was defined to accept only one parameter, you receive an error message. For example: 


$ SAMPLE MYFILE INFILE
%DCL-W-MAXPARM, too many parameters - reenter command with fewer parameters
  \INFILE\

Creating an Object Module Table for Your Program

This example shows how to create an object module table for your program. It also shows how to use command language routines to parse a command string and to invoke the correct program routine.

When you write a command definition file to create an object module table, specify routines (not images) for each command verb. Your program calls these routines when it processes command strings.

The following example illustrates a command definition file called TEST.CLD that defines three verbs: SEND, SEARCH, and EXIT. Each verb invokes a routine in the program USEREXAMP.BAS. 


MODULE TEST_TABLE 
 
DEFINE VERB SEND 
        ROUTINE SEND_COMMAND 
        PARAMETER P1, LABEL = FILESPEC 
        QUALIFIER EDIT 
 
DEFINE VERB SEARCH 
        ROUTINE SEARCH_COMMAND 
        PARAMETER P1, LABEL = SEARCH_STRING 
 
DEFINE VERB EXIT 
       ROUTINE EXIT_COMMAND

Process TEST.CLD by using SET COMMAND with the /OBJECT qualifier to create object module TEST.OBJ: 


$ SET COMMAND/OBJECT TEST

You can then link TEST.OBJ with an object module that was created from your source program.

The following BASIC program, entitled USEREXAMP.BAS, invokes the routines listed in the command table in TEST.OBJ. It uses the command language routines CLI$DCL_PARSE and CLI$DISPATCH to parse command strings and to invoke the routine associated with the command. The program also uses CLI$PRESENT and CLI$GET_VALUE to obtain information about command strings. 


10  SUB SEND_COMMAND 
    EXTERNAL INTEGER FUNCTION CLI$PRESENT,CLI$GET_VALUE 
 
    PRINT 'SEND COMMAND' 
    PRINT '' 
 
20  IF CLI$PRESENT ('EDIT') AND 1% 
    THEN 
        PRINT '/EDIT IS PRESENT' 
 
30  IF CLI$PRESENT ('FILESPEC') AND 1% 
    THEN 
        CALL CLI$GET_VALUE ('FILESPEC',A$) 
        PRINT 'FILESPEC = ',A$ 
 
90  SUBEND 
 
100 SUB SEARCH_COMMAND 
    EXTERNAL INTEGER FUNCTION CLI$PRESENT,CLI$GET_VALUE 
 
    PRINT 'SEARCH COMMAND' 
    PRINT '' 
 
110 IF CLI$PRESENT('SEARCH_STRING') AND 1% 
    THEN 
        CALL CLI$GET_VALUE('SEARCH_STRING',A$) 
        PRINT 'SEARCH_STRING = ',A$ 
 
190 SUBEND 
 
 
200 SUB EXIT_COMMAND 
    CALL SYS$EXIT(1% BY VALUE) 
 
290 SUBEND 
 
 
1   EXTERNAL INTEGER FUNCTION CLI$DCL_PARSE,CLI$DISPATCH 
    EXTERNAL INTEGER FUNCTION SEND_COMMAND,SEARCH_COMMAND,EXIT_COMMAND 
    EXTERNAL INTEGER TEST_TABLE,LIB$GET_INPUT 
 
 
2   IF NOT CLI$DCL_PARSE(,TEST_TABLE,LIB$GET_INPUT,LIB$GET_INPUT,'TEST>') AND 1% 
    THEN 
        GOTO 2 
 
 
3   PRINT '' 
    CALL CLI$DISPATCH 
    PRINT '' 
    GOTO 2 
    END

This source program must be compiled before it can be linked with an object module created from the SET COMMAND/OBJECT command. To compile this program, invoke the VAX BASIC compiler: 


$ BASIC USEREXAMP

You now have a USEREXAMP.OBJ file in addition to the original USEREXAMP.BAS source file. Link USEREXAMP.OBJ with TEST.OBJ by entering the following command: 


$ LINK USEREXAMP,TEST

You now have a file containing an executable image (USEREXAMP.EXE). To execute the image, enter the following command: 


$ RUN USEREXAMP

USEREXAMP.EXE displays the following prompt on your screen: 


TEST>

You can now enter any of the commands you defined in TEST.CLD. For example: 


TEST> SEND

The program calls CLI$DCL_PARSE to parse the command string SEND. SEND is a valid command, so CLI$DISPATCH transfers control to the SEND_COMMAND routine. This routine displays the following text: 


SEND COMMAND 
 
TEST>

You can also include a parameter with the SEND command. For example: 


TEST> SEND MESSAGE.TXT

DCL invokes the SEND_COMMAND routine, which displays the following text: 


SEND COMMAND 
 
FILESPEC = MESSAGE.TXT 
 
TEST>

You can also enter the /EDIT qualifier with SEND. For example: 


TEST> SEND/EDIT MESSAGE.TXT
 
SEND COMMAND 
 
/EDIT is present 
 
FILESPEC = MESSAGE.TXT 
 
TEST>

You can enter other commands that your program accepts. For example:

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
6100PRO_004.HTML