HP OpenVMS Command Definition, Librarian, and Message Utilities
Manual
MODULE
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.
Format
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.
Example
|
$ 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.
CDU Qualifiers
The following pages describe
the qualifiers that can be used with the DCL command SET COMMAND. The qualifiers
are as follows:
- /ALPHA
- /DELETE
- /LISTING
- /OBJECT
- /OUTPUT
- /REPLACE
- /TABLE
- /VAX
The /DELETE, /OBJECT, and /REPLACE qualifiers indicate SET COMMAND modes;
these qualifiers are mutually exclusive.
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 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.
/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
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.
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:
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:
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:
In this case, you receive the following display on your screen:
You can also include the /EDIT qualifier in the command string. For example:
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:
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:
|
