HP OpenVMS Systems Documentation
OpenVMS User's Manual
16.4 Using Parameters to Pass Data to Nested Command Procedures
You can pass up to eight parameters to nested command procedures. The local symbols P1 to P8 in the nested procedure are not related to the local symbols P1 to P8 in the invoking procedure.
In the following example, DATA.COM invokes the nested command procedure NAME.COM:
If P1 in DATA.COM is the string Paul Cramer, which contains no quotation marks, it is passed to NAME.COM as two parameters. In NAME.COM, P1 to P8 are defined as follows:
P1 = PAUL
If P1 in DATA.COM is "Paul Cramer" (quotation marks included), you can pass the value to NAME.COM as one parameter by enclosing P1 in three sets of quotation marks, as follows:
In this example, P1 is Paul Cramer and P2 is Joe Cooper in the command
You can use the INQUIRE command (as described in Chapter 15) or the READ command to obtain data for command procedures interactively. Both commands prompt for input and assign the response to a symbol.
The READ command is different from the INQUIRE command in the following ways:
The READ command accepts all characters typed on the terminal in response to the prompt, as an exact character string value (case, spaces, and tabs are preserved). If you omit the /PROMPT qualifier, the READ command displays Data: as the default prompt.
You can also write command procedures that can either accept parameters or prompt for user input if the required parameters are not specified.
In the following example, the command issues the prompt Filename: to the terminal, reads the response from the source specified by the logical name SYS$COMMAND (by default, the terminal), and assigns the response to the symbol FILE:
In the following example, if a file name is not specified when the procedure is invoked, the user is prompted for a file name:
16.6 Using the SYS$INPUT Logical Name to Obtain Data
Commands, utilities, and other system images get their input from the
source specified by the logical name SYS$INPUT, which is the default
input stream. In a command procedure, SYS$INPUT is defined as the
command procedure file; commands or images that require data look for
data lines in the file. However, by redefining SYS$INPUT, you can
provide data from your terminal or from a separate input file.
You can redefine SYS$INPUT to be your terminal. This enables images called from command procedures to obtain input interactively, rather than from data lines in command procedures.
Note that you must redefine SYS$INPUT to be your terminal if you want to use a DCL command or utility that requires interactive input in command procedures.
In the following example, the command procedure allows you to provide input interactively to the image CENSUS.EXE:
The DEFINE/USER_MODE command temporarily redefines SYS$INPUT while CENSUS.EXE is running, so CENSUS.EXE obtains its input from the terminal. After CENSUS.EXE completes, SYS$INPUT reverts to its original definition (the command procedure file).
In the following example, the command procedure uses EVE as the text editor:
The command procedure prompts for file names until you terminate the
loop by pressing the Return key. When you enter a file name, the
procedure automatically invokes EVE to edit the file. While the editor
is running, SYS$INPUT is defined as the terminal so you can enter your
A command procedure can also get input from a file by defining SYS$INPUT as a file. Note that DCL does not process data lines; command procedures pass text on data lines directly to commands or images. If you include DCL symbols or expressions on data lines, DCL will not substitute values for the symbols or evaluate the expressions. If you use an exclamation point (!) in a data line, the image to which you pass the data processes the exclamation point.
You can also place programs in the command procedure file by specifying the name of the data file as SYS$INPUT. This causes the compiler to read the program from the command procedure rather than from another file.
The following example shows a command procedure that contains a FORTRAN command followed by the program's statements:
The FORTRAN command uses the logical name SYS$INPUT to identify the
file to be compiled. Because SYS$INPUT equates to the command
procedure, the FORTRAN compiler compiles the statements following the
FORTRAN command (up to the next line that begins with a dollar sign).
When the compilation completes, two output files are created:
TESTER.OBJ and TESTER.LIS. The PRINT command then prints the file.
Output from command procedures such as data, error messages, and verification of command lines can be directed to either terminals or other files. The following methods of directing output are covered in this section:
16.7.1 Writing Data to Terminals
Use the TYPE command to display text that is several lines long and does not require symbol substitution. The TYPE command writes data from the file you specify to SYS$OUTPUT.
In the following example, SYS$INPUT is specified as the data file. The TYPE command reads data from the data lines that follow and displays the lines on the terminal.
To use the WRITE command to display a character string as literal text, enclose the string in quotation marks (" "). For example:
To include quotation marks in character strings, use two sets of quotation marks ("" ""). For example:
To continue a line of text on more than one line, concatenate the two strings with a plus sign (+) and a hyphen (-). For example:
The WRITE command performs symbol substitutions automatically and displays the values of symbols. To force symbol substitutions within character strings, enclose the symbol in apostrophes. For example:
In this example, STAT1.DAT is the translation of the symbol AFILE;
STAT2.DAT is the translation of the symbol BFILE.
Commands, utilities, and other system images write their output to the source specified by the logical name SYS$OUTPUT. By default, SYS$OUTPUT equates to the terminal. However, you can redirect the output in one of the following ways:
In the following example, the command procedure redirects the output from the SHOW USERS command to a file. The new definition for SYS$OUTPUT is in effect only for the execution of the SHOW USERS command.
In the following example, SYS$OUTPUT is defined as a null device (NL:).
The /USER_MODE qualifier is used to create a temporary logical name assignment that is in effect only until the next image completes. After the command executes, SYS$OUTPUT reverts to the default definition (usually the terminal).
You cannot use the DEFINE/USER_MODE command to redirect output from DCL commands that are executed within the command interpreter. Instead, use the DEFINE command to redefine SYS$OUTPUT and use the DEASSIGN command to delete the definition when you are through with it.
The following is a complete list of DCL commands that are performed within the command interpreter:
The following example shows the commands that would be used to redirect output from the SHOW TIME command to the file TIME.DAT. After you deassign SYS$OUTPUT, it reverts to the default definition (the terminal).
16.7.3 Returning Data from Command Procedures
Global symbols and logical names return data from a command procedure to a calling procedure or to DCL command level. You can read a global symbol or a logical name at any command level. Logical names can return data from a nested command procedure to the calling procedure.
The following example shows how a command procedure passes a value with a global symbol created with a global assignment statement:
DATA.COM invokes the command procedure NAME.COM, passing NAME.COM a full name. NAME.COM places the last name in the global symbol LAST_NAME. When NAME.COM completes, DCL continues executing DATA.COM, which reads the last name by specifying the global symbol LAST_NAME. The command procedure NAME.COM would be in a separate file. It is shown indented in this example for clarity.
In this command procedure, REPORT.COM obtains the file name for a report, equates the file name to the logical name REPORT_FILE, and executes a program that writes a report to REPORT_FILE:
In the following example, the command procedure REPORT.COM is invoked from another procedure. The calling procedure uses the logical name REPORT_FILE to refer to the report file.
16.7.4 Redirecting Error Messages
The following sections describe how to redirect error messages.
By default, command procedures send system error messages to the file indicated by SYS$ERROR. You can redefine SYS$ERROR to direct system error messages to a specified file. However, if you redefine SYS$ERROR to be different from SYS$OUTPUT (or if you redefine SYS$OUTPUT without also redefining SYS$ERROR), DCL commands and images that use standard system error display mechanisms send system error level and system severe level error messages to both SYS$ERROR and SYS$OUTPUT. Therefore, you receive these messages twice---once in the file indicated by the definition of SYS$ERROR and once in the file indicated by SYS$OUTPUT. Success, informational, and warning level messages are sent only to the file indicated by SYS$OUTPUT. If you want to suppress system error messages from a DCL command, be sure that neither SYS$ERROR nor SYS$OUTPUT is equated to the terminal.
If you run one of your own images from a command procedure and the image references SYS$ERROR, the image sends system error messages only to the file indicated by SYS$ERROR --- even if SYS$ERROR is different from SYS$OUTPUT. Only DCL commands and images that use standard system error display mechanisms send messages to both SYS$ERROR and SYS$OUTPUT when these files are different.
This command procedure accepts a directory name as a parameter, sets the default to that directory, and purges files in the directory. To suppress system error messages, the procedure temporarily defines SYS$ERROR and SYS$OUTPUT as the null device:
126.96.36.199 Suppressing System Error Messages
You can also use the SET MESSAGE command to suppress system messages. By using the qualifiers /NOFACILITY, /NOIDENTIFICATION, /NOSEVERITY, or /NOTEXT, you can suppress the facility name, message identification, severity level, or the message text.
In the following example, the facility, identification, severity, and text messages are temporarily suppressed, until the second SET MESSAGE command is issued:
16.8 Reading and Writing Files (File I/O)
The basic steps in reading and writing files from command procedures are:
The following sections describe:
16.9 Using the OPEN Command
The OPEN command opens sequential, relative, or indexed sequential files. The files are opened as process-permanent; they remain open for the duration of your process unless you explicitly close them (with the CLOSE command). While the files are open, they are subject to OpenVMS RMS restrictions on using process-permanent files.
When you open a file, the OPEN command assigns a logical name (specified as the first parameter) to the file (specified as the second parameter) and places the name in the process logical name table. Subsequent READ, WRITE, and CLOSE commands use this logical name to refer to the file.
In the following example, the OPEN command assigns the logical name INFILE to the file DISK4:[MURPHY]STATS.DAT:
To ensure that the command procedure can access the correct files, use complete file specifications (for example, DISK4:[MURPHY]STATS.DAT) or use the SET DEFAULT command to specify the proper device and directory before you open a file.
You can also specify shareable files. The /SHARE qualifier enables other opened files. In addition, users can access shareable files with the DCL commands TYPE and SEARCH.
The OPEN/READ command opens the files, assigns logical names to the files, and places record pointers at the beginning of the files. When you open files for reading, you can read but not write records. Each time you read a record, the pointer moves to the next record.
The OPEN/READ command in this command procedure opens the file STATS.DAT and assigns the logical name INFILE to the file:
Use the OPEN/WRITE command when you want to write to a new file. The OPEN/WRITE command creates a sequential file in print file format. The record format for the file is variable with fixed control (VFC), with a 2-byte record header. The /WRITE qualifier cannot be used with the /APPEND qualifier.
If you specify a file that already exists, the OPEN/WRITE command opens a new file with a version number that is one greater than the existing file.
The command procedure in the following example creates a new file (NAMES.DAT) that can be used for writing:
The OPEN/APPEND command appends records to the end of an existing file. If you attempt to open a file that does not exist, an error occurs and the file is not opened. The /APPEND qualifier cannot be used with the /WRITE qualifier.
In the following example, records are appended to the end of an existing file, NAMES.DAT:
The OPEN/READ/WRITE command places the record pointer at the beginning of a file so you can read the first record. When you use this method to open a file, you can replace only the record you have read most recently; you cannot write new records to the end of the file. In addition, a revised record must be exactly the same size as the record being replaced.
In the following example, the record pointer is placed at the beginning of the file STATS.DAT so the first record can be read: