|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
Provides a name for an object module and for a global symbol that refers to the address of a command table within an image into which the object module is linked.
MODULE module-name
module-name
The module-name is used to create a global symbol that refers to the address of the command table within the image into which the object module is to be linked.By default, CDU uses the object file name specified with the /OBJECT command qualifier. If no object file is explicitly specified, then CDU uses the name of the first command definition file as the module name.
$ CREATE TEST.CLDMODULE TEST_TABLEDEFINE VERB SEND ROUTINE SEND_ROUT PARAMETER P1 . . .DEFINE VERB SEARCH ROUTINE SEARCH_ROUT PARAMETER P1^Z$ SET COMMAND/OBJECT=TEST.OBJ TEST$ LINK PROG,TEST$ RUN PROG |
TEST.CLD defines two commands (SEND and SEARCH) that call routines in PROG.EXE, a program that uses DCL to parse command strings and execute routines.
The SET COMMAND command creates a command table object module that is linked with the program object module (PROG.OBJ) to produce an image (PROG.EXE) that includes the code for the program and for the command table. TEST_TABLE refers to the address of the command table in the image.
When you run PROG.EXE, it calls DCL parsing routines to parse the command string using the command table in module TEST_TABLE.
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.
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.
$ SET COMMAND /ALPHA /OBJECT=A TESTMODULE 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.
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.
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.
| #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.
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.
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.
| #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.
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.
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.
| #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.
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.
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.
| #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.
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.
SET COMMAND/REPLACE [filespec [,...]]
filespec
The file to be processed (wildcard characters are allowed). The default file type is .CLD.
| #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.
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.
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.
| #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.
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.
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.
$ 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.
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 Compaq; 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 exampleshows 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 |
| Previous | Next | Contents | Index |