[Digital logo]
[HR]

OpenVMS DCL Dictionary


Previous | Contents

If you specify more than one function, separate each with a comma and enclose the list in parentheses. If you specify no functions in the /SHOW qualifier, it increments the listing level count; the /NOSHOW qualifier decrements the count in similar circumstances. Because these qualifiers contribute to the listing file, you must also specify the /LIST qualifier when you use them. If you do not specify the /SHOW qualifier, the MACRO command assumes a default of /SHOW=(CONDITIONALS,CALLS,DEFINITIONS). If you specify only one function, you can omit the parentheses.

/UPDATE[=(update-filespec[,...])]

/NOUPDATE

Positional qualifier. The /UPDATE qualifier cannot be used with the /ALPHA, the /LIBRARY, or the /MIGRATION qualifier.

Updates the input file it qualifies by using the SUMSLP batch editor and the specified update file or files. By default, the assembler assumes that the update file has the same file name as the input source file and a file type of UPD. You cannot include the asterisk (*) and the percent sign (%) wildcard characters in the file specifications. If it cannot find a specified update file, the assembler prints an informational message and continues the assembly.

If you specify only one update file, you can omit the parentheses. If you specify more than one update file, the assembler merges the contents into a single list of updates before applying the updates to the source file.

The /NOUPDATE qualifier has the same effect as not specifying the /UPDATE qualifier, or negates any /UPDATE qualifiers specified earlier in the command line. The input source file and update files are not changed by the update operation. The effects of the update appear in the compiled output. If you specify the /LIST qualifier with the /UPDATE qualifier, the assembler writes an audit trail of the changes to the listing file.


Examples

#1
$ MACRO/LIST  CYGNUS, LYRA/OBJECT=LYRAN + MYLIB/LIBRARY

In this example, the MACRO command requests two separate assemblies. Using MAR as the default file type, MACRO assembles CYGNUS.MAR to produce CYGNUS.LIS and CYGNUS.OBJ. Then it assembles LYRA.MAR and creates a listing file named LYRA.LIS and an object module named LYRAN.OBJ. The default output file type for a listing is LIS.

The command requests the search of the MYLIB library file in the current directory for macro definitions.

#2
$ MACRO  ORION

MACRO assembles the file ORION.MAR and creates an object file named ORION.OBJ. Executing the command in a batch job causes MACRO to create a listing file named ORION.LIS.

#3
$ MACRO  ALPHA/LIST+MYLIB/LIBRARY-
_$ + [TEST]OLDLIB/LIBRARY + []BETA
$ PRINT ALPHA

MACRO concatenates the files ALPHA.MAR and BETA.MAR to produce an object file named ALPHA.OBJ and a listing file named ALPHA.LIS. The command line requests the search of libraries MYLIB.MLB (in the current default directory) and OLDLIB.MLB (in the directory [TEST]) for macro definitions. When macro calls are found in BETA.MAR, MACRO searches the libraries OLDLIB, MYLIB, and the system library STARLET.MLB, in that order, for the definitions.

The PRINT command prints the listing file ALPHA.LIS.

#4
$ MACRO  DELTA+TESTLIB/LIBRARY, ALPHA+MYLIB/LIBRARY

MACRO requests two separate assemblies. MACRO searches TESTLIB.MLB and the system library STARLET.MLB for macro definitions when macro calls are found in DELTA.MAR, and searches MYLIB.MLB and the system library STARLET.MLB for macro definitions when macro calls are found in ALPHA.MAR.


MAIL

Invokes the Mail utility, which is used to send messages to other users of the system. For a complete description of the Mail utility, see the OpenVMS User's Manual.

Format

MAIL [filespec] [recipient-name]


MERGE

Invokes the Sort/Merge utility, which combines 2 to 10 similarly sorted input files and creates a single output file. Note that input files to be merged must be in sorted order. For a complete description of the Sort/Merge utility, see the OpenVMS User's Manual.

Format

MERGE input-filespec1,input-filespec2[,...] output-filespec


MESSAGE

Invokes the Message utility, which compiles one or more files of message definitions. For a complete description of the Message utility, see the OpenVMS Command Definition, Librarian, and Message Utilities Manual.

Format

MESSAGE filespec[,...]


MONITOR

Invokes the Monitor utility, which monitors classes of systemwide performance data at a specified interval. For a complete description of the Monitor utility, see the OpenVMS System Management Utilities Reference Manual.

Format

MONITOR [/qualifier[,...]] classname[,...] [/qualifier[,...]]


MOUNT

Invokes the Mount utility, which makes a disk or magnetic tape volume available for processing. For a complete description of the Mount utility, see the OpenVMS System Management Utilities Reference Manual.

Format

MOUNT device-name[:][,...] [volume-label[,...]] [logical-name[:]]


NCS

Invokes the OpenVMS National character set (NCS) utility, which provides a convenient method of implementing alternative (non-ASCII) string collating sequences, typically using subsets of the DEC Multinational character set. NCS also facilitates the implementation of string conversion functions.

For a complete description of the NCS utility, see the OpenVMS National Character Set Utility Manual.


Format

NCS [filespec[,...]]


ON

Performs a specified action when a command or program executed within a command procedure encounters an error condition or is interrupted by Ctrl/Y. The specified actions are performed only if the command interpreter is enabled for error checking or Ctrl/Y interrupts (the default conditions). Use the ON command only in a command procedure.

Format

ON condition THEN [$] command


PARAMETERS

condition

Specifies either the severity level of an error or a Ctrl/Y interrupt. Specify one of the following keywords, which may be abbreviated to one or more characters:
WARNING Return status of warning occurs ($SEVERITY equals 0).
ERROR Return status of error occurs ($SEVERITY equals 2).
SEVERE_ERROR Return status of error occurs ($SEVERITY equals 4).
CONTROL_Y Ctrl/Y character occurs on SYS$INPUT.

The default error condition is ON ERROR THEN EXIT.

command

Specifies the DCL command line to be executed. Optionally, you can precede the command line with a dollar sign ($).

If you specified an error condition as the condition parameter, the action is taken when errors equal to or greater than the specified level of error occur.


DESCRIPTION

During the execution of a command procedure, the command interpreter checks the condition code returned from each command or program that executes. With the ON command, you can establish a course of action for the command interpreter to take based on the result of the check.

The system places condition codes in the global symbol $STATUS. The severity of the condition code is represented in the first 3 low-order bits of $STATUS. This severity level is also represented by the global symbol $SEVERITY. See the description of the EXIT command for information on severity level values.

If an ON command action specifies the severity level of an error, the command interpreter executes the ON command action for errors at the specified severity level or greater. For example, the following command causes a procedure to exit on warnings, errors, or severe errors:

$ ON WARNING THEN EXIT 

The default action is as follows:

$ ON ERROR THEN EXIT 

That is, the command interpreter continues when a warning occurs, and executes an EXIT command when an error or severe error occurs. An ON command action that specifies a severity level is executed only once; after the ON command action is taken, the default ON action is reset. There is an exception to the default ON action. If you use the GOTO command and specify a label that does not exist in the current command procedure, the procedure issues a warning message and exits.

The action specified by an ON command applies only within the command procedure in which the command is executed. Therefore, if you execute an ON command in a procedure that calls another procedure, the ON command action does not apply to the nested procedure. An ON command executed at any command procedure level does not affect the error condition handling of procedures at any other level.

To disable error checking with the ON command, use the SET NOON command. You can enable error checking with the SET ON command, or by entering another ON command.

The ON command also provides a way to define an action routine for a Ctrl/Y interrupt that occurs during execution of a command procedure. The default (Ctrl/Y) action is to prompt for command input at the Ctrl/Y command level. The Ctrl/Y command level is a special command level where you can enter DCL commands. If you enter a command that is executed within the command interpreter, you can resume execution of the procedure with the CONTINUE command. (For a list of commands that are executed within the command interpreter, see the OpenVMS User's Manual.)

If you enter any other DCL command, the command interpreter returns to command level 0 and executes the image invoked by the command. If you interrupt the command procedure while it is executing an image that contains an exit handler, the exit handler is allowed to execute before the new command (image) is executed. (However, if you enter the STOP command after you interrupt a command procedure by pressing Ctrl/Y, exit handlers declared by the interrupted image are not executed.)

You can use the ON command to change the default action for a Ctrl/Y interrupt. If you change the default Ctrl/Y action, the execution of a Ctrl/Y interrupt does not automatically reset the default Ctrl/Y action. A Ctrl/Y action remains in effect until one of the following occurs:

A Ctrl/Y action can be specified for each active command level; the Ctrl/Y action specified for the currently executing command level overrides actions specified for previous levels.


Note

The ON CONTROL_Y and SET NOCONTROL=Y commands are intended for special applications. Digital does not recommend, in general, that you disable Ctrl/Y interrupts. For example, if a procedure that disables Ctrl/Y interrupts begins to loop uncontrollably, you cannot gain control to stop the procedure from your terminal.


Examples

#1
$ ON SEVERE_ERROR THEN CONTINUE 

A command procedure that contains this statement continues to execute normally when a warning or error occurs during execution. When a severe error occurs, the ON statement signals the procedure to execute the next statement anyway. Once the statement has been executed as a result of the severe error condition, the default action (ON ERROR THEN EXIT) is reinstated.

#2
$ ON ERROR THEN GOTO BYPASS 
$ RUN A 
$ RUN B 
   .
   .
   .
$ EXIT 
$ BYPASS: 
$      RUN C 
 

If either program A or program B returns a status code with a severity level of error or severe error, control is transferred to the statement labeled BYPASS and program C is run.

#3
$ ON WARNING THEN EXIT 
   .
   .
   .
$ SET NOON 
$ RUN [SSTEST]LIBRA 
$ SET ON 
   .
   .
   .
 

The ON command requests that the procedure exit when any warning, error, or severe error occurs. Later, the SET NOON command disables error checking before executing the RUN command. Regardless of any status code returned by the program LIBRA.EXE, the procedure continues. The next command, SET ON, reenables error checking and reestablishes the most recent ON condition.

#4
$ ON CONTROL_Y THEN GOTO CTRL_EXIT 
   .
   .
   .
$ CTRL_EXIT: 
$ CLOSE INFILE 
$ CLOSE OUTFILE 
$ EXIT 
 

The ON command specifies action to be taken when Ctrl/Y is pressed during the execution of this procedure: the GOTO command transfers control to the line labeled CTRL_EXIT. At CTRL_EXIT, the procedure performs cleanup operations (in this example, closing files and exiting).


OPEN

Opens a file for reading, writing, or both; assigns a logical name to a file; and places the name in the process logical name table.

See the qualifier descriptions for restrictions.


Format

OPEN logical-name[:] filespec


PARAMETERS

logical-name[:]

Specifies the logical name and a character string to be assigned to the file.

filespec

Specifies the name of the file or device being opened for input or output. The file type defaults to DAT. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.

To create a new, sequential file, specify the /WRITE qualifier. See the description of the /WRITE qualifier for more information.


DESCRIPTION

A file can be opened for either reading or writing, or for both reading and writing. After the file is opened, it is available for input or output at the command level with the READ and WRITE commands.

The OPEN command opens files as process permanent. Therefore, these files remain open until you close them with the CLOSE command, or until you log out. If a command procedure that opens a file terminates without closing an open file, the file remains open; the command interpreter does not automatically close it. The OPEN command uses OpenVMS RMS to open files, and is subject to RMS restrictions on using process-permanent files. The OPEN command opens sequential, relative, or indexed sequential files.

The logical devices SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR do not have to be opened explicitly before they can be read or written at the command level. All other files must be opened explicitly.

Do not use the same logical name when you open different files. If you specify a logical name with the OPEN command and the logical name is currently assigned to another file, no warning message is issued. However, the file is not opened, and the next READ request will access the file to which the logical name was originally assigned.

You can enter more than one OPEN command for the same file and assign it different logical names if you use the /SHARE qualifier the first time the file is opened. Also, if you open the file by using the /SHARE=READ or the /SHARE=WRITE qualifier, other users may access the file with the TYPE or the SEARCH command.

When you use the OPEN command to create a new file, variable fixed control (VFC) record format is used. Concatenating a file of this record format with a file of another record format might be impossible due to record format incompatibilities. To avoid the VFC format, use the CREATE command to create the file.

When the OPEN command is specified on an existing file, the record type of that file is used.


QUALIFIERS

/APPEND

Opens an existing file for writing and positions the record pointer at the end-of-file (EOF). New records are added to the end of the file.

Only sequential files allow more than one user to append records concurrently.

Use the /APPEND qualifier only to add records to an existing file. The /APPEND and the /WRITE qualifiers are mutually exclusive.

/ERROR=label

Transfers control to the location specified by the label keyword (in a command procedure) if the open operation results in an error. The error routine specified for this qualifier overrides any ON condition action specified. If the /ERROR qualifier is not specified, the current ON condition action is taken.

If an error occurs and the target label is successfully given control, the global symbol $STATUS retains the code for the error that caused the error path to be taken.

/READ (default)

Opens the file for reading. If you specify the /READ qualifier without the /WRITE qualifier, you must specify an existing file.

/SHARE[=option]

Opens the specified file as a shareable file to allow other users read or write access. If you specify the /SHARE=READ qualifier, other users are allowed read (R) access to the file, but not write (W) access. If you specify the /SHARE=WRITE or the /SHARE qualifier with no option, users are allowed read and write access to the specified file.

If the /SHARE qualifier is not present, other users are allowed only read access to the specified file.

/WRITE

Opens the file for writing. The following restrictions apply to the /WRITE qualifier:

Examples

#1
$ OPEN INPUT_FILE AVERAGE.DAT 
$ READ_LOOP: 
$ READ/END_OF_FILE=ENDIT  INPUT_FILE  NUM 
   .
   .
   .
$ GOTO READ_LOOP 
$ ENDIT: 
$ CLOSE INPUT_FILE 

The OPEN command opens the file named AVERAGE.DAT as an input file and assigns it the logical name INPUT_FILE. The file is opened with read access because the /READ qualifier is present by default. The READ command reads a record from the logical file INPUT_FILE into the symbol named NUM. The procedure executes the lines between the labels READ_LOOP and ENDIT until the end of the file is reached. At the end of the file, the CLOSE command closes the file.

#2
$ OPEN/WRITE/ERROR=OPEN_ERROR  OUTPUT_FILE  TEMP.OUT 
$ COUNT = 0 
$ WRITE_LOOP: 
$ COUNT = COUNT + 1 
$ IF COUNT .EQ. 11 THEN GOTO ENDIT 
$ WRITE OUTPUT_FILE "Count is ''COUNT'." 
   .
   .
   .
$ GOTO WRITE_LOOP 
$ ENDIT: 
$ CLOSE OUTPUT_FILE 
$ EXIT 
$ 
$ OPEN_ERROR: 
$ WRITE SYS$OUTPUT "Cannot open file TEMP.OUT" 
$ EXIT 

The OPEN command with the /WRITE qualifier creates the file TEMP.OUT and assigns it the logical name OUTPUT_FILE. TEMP.OUT is a sequential file.

The /ERROR qualifier specifies that if any error occurs while opening the file, the command interpreter should transfer control to the line at the label OPEN_ERROR. The command procedure writes records to the file TEMP.OUT until the symbol COUNT equals 11.

#3
$ OPEN/READ INPUT_FILE TRNTO::DBA0:[COST]INVENTORY.DAT 
$ READ_LOOP: 
$ READ/END_OF_FILE=ENDIT  INPUT_FILE  NUM 
$ FIRST_CHAR = F$EXTRACT(0,1,NUM) 
$ WRITE SYS$OUTPUT FIRST_CHAR 
$ GOTO READ_LOOP 
$ ENDIT: 
$ CLOSE INPUT_FILE 

This command procedure opens the file INVENTORY.DAT located at remote node TRNTO as an input file, and assigns it the logical name INPUT_FILE. The READ command reads a record from the logical file INPUT_FILE into the symbol named NUM. The next two commands extract the first character from the record and write the character to the SYS$OUTPUT device. These two steps occur for all records in the file until the procedure reaches the end-of-file (EOF). At this point, the CLOSE command closes the file and deassigns the logical name INPUT_FILE.


PASSWORD

Provides the password associated with the user name that you specify with the JOB card when you submit a batch job through a card reader. Although the PASSWORD card is required, the password on the card is optional if the account has a null password.

The PASSWORD command is valid only in a batch job submitted through a card reader and requires that a dollar sign ($) precede the PASSWORD command on the card.


Format

$ PASSWORD [password]


Note

To change your password, use the SET PASSWORD command. For information on this command, see the description of SET PASSWORD.


PARAMETER

password

Specifies the password associated with the user name specified with the JOB command. The password can be 1 to 31 characters long.

If you are submitting the job from an account with a null password, omit the password specifier on the PASSWORD card.


DESCRIPTION

The PASSWORD command is used in conjunction with the JOB command. The JOB card identifies the user submitting the batch job through a card reader and is followed by a PASSWORD card giving the password. The password is checked by the system to verify that it matches the password associated with the user name on the JOB card. If the passwords do not match, the job is rejected.

Note that you might want to suppress printing when you originally keypunch the PASSWORD card to prohibit other users from seeing the password when the PASSWORD card is in use.


Example





The JOB and PASSWORD commands precede a batch job submitted from the card reader. An EOJ command marks the end of the job.


PATCH (VAX Only)

On VAX, invokes the Patch utility, which patches an executable image, a shareable image, or a device driver image. For a complete description of the Patch utility, see the OpenVMS VAX Patch Utility Manual.

Format

PATCH filespec


PHONE

Invokes the Phone utility, which lets you communicate with other users on your system or any other system connected to your system by DECnet for OpenVMS. For a complete description of the Phone utility, see the OpenVMS User's Manual.

Format

PHONE [phone-command]


PIPE

Executes one or more DCL command strings from the same command line. The PIPE command enables you to perform UNIX style command processing, such as command pipelining, input/output redirection, and conditional and background execution.

Format

PIPE command-sequence [separator command-sequence]...


PARAMETER

command-sequence

A DCL command, a pipeline, or a subshell:

Input/output redirection is allowed in a command sequence. The command before an angle bracket (> or <) redefines its SYS$INPUT, SYS$OUTPUT, or SYS$ERROR during execution. You cannot use angle brackets (<>) to represent a directory specification in a PIPE command because the PIPE command interprets angle brackets as input/output redirection syntax.

separator

Determines the processing action of the command sequences specified in a PIPE command. The valid PIPE separators are described in Table DCLII-16.

Table DCLII-16 PIPE Command Separators
Separator Action
; Sequential execution. The command sequence following the semicolon (;) is executed after the preceding command sequence is completed. You must precede this separator with a blank space. Otherwise, it is parsed as the Record Management System (RMS) file specification version number delimiter.
&& Conditional execution (upon success). The command sequence following the double ampersand (&&) is executed only if the preceding command sequence succeeds.
|| Conditional execution (upon failure). The command sequence following the double vertical bar (||) is executed only if the preceding command sequence fails.
& Background execution. All command sequences that precede the ampersand (&) are executed asynchronously in a subprocess environment. The & separator is similar to the SPAWN/NOWAIT command.

Note: Any ampersand that precedes a character string without spaces in between is parsed as a conventional DCL symbol substitution expression rather than the background execution syntax.

In a PIPE command line, the & has the highest precedence, followed by ;, &&, and ||, which have equal precedence.


DESCRIPTION

The PIPE command allows you to perform UNIX style command processing by executing multiple DCL commands in a single command line. You can use the PIPE command to execute DCL commands in a number of ways: