[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Command Definition, Librarian, and Message Utilities Manual


Previous Contents Index

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.

/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  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

#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 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