![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
The SET NOCONTROL=Y command also cancels the current Ctrl/Y action established with the ON CONTROL_Y command. To reestablish the default Ctrl/Y action, use the following two commands:
$ SET NOCONTROL=Y $ SET CONTROL=Y
The SET NOCONTROL=Y command disables Ctrl/Y handling and cancels the current ON CONTROL_Y action. The SET CONTROL=Y command enables Ctrl/Y handling. At this point, the default action is reinstated. That is, if Ctrl/Y is pressed during the execution of the procedure, the command interpreter prompts for a command at the Ctrl/Y command level.
You can use the SET NOCONTROL=Y command at any command level. It affects all command levels until the SET CONTROL=Y command reenables Ctrl/Y handling.
An ON CONTROL_Y command remains in effect until another ON CONTROL_Y or a SET NOCONTROL=Y command executes or the command procedure exits.
To exit from a nonterminating loop when Ctrl/Y is disabled, you must delete your process from another terminal using the DCL command STOP. If you disable the default Ctrl/Y action, reset it as soon as possible. To reset the default Ctrl/Y action, execute the SET NOCONTROL=Y command followed by the SET CONTROL=Y command.
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 interruptions. To exit from a nonterminating loop when Ctrl/Y is disabled, you must delete (from another terminal) the process from which the looping procedure is executing.
In this command procedure, pressing Ctrl/Y while a file is being typed passes control to the label END_TYPE:
. . . $! Type a file $ IF COMMAND .NES. "TY" THEN GOTO END_TYPE $ ON CONTROL_Y THEN GOTO END_TYPE $ TYPE 'FILESPEC' $END_TYPE: $! $! Reset default $ SET NOCONTROL=Y $ SET CONTROL=Y . . .
When each DCL command in a command procedure completes execution, the command interpreter saves a condition code that describes the reason why the command terminated. This code can indicate successful completion or it can identify an informational or error message.
The command interpreter examines the condition code after it performs each command in a command procedure. If an error that requires special action has occurred, the system performs the action. Otherwise, the next command in the procedure executes.
The command interpreter saves the condition code as a 32-bit longword in the reserved global symbol $STATUS. The $STATUS symbol conforms to the format of a system message code as follows:
When a command completes successfully, $STATUS has an odd value. (Bits 0--2 contain a 1 or a 3.) When any type of warning or error occurs, $STATUS has an even value. (Bits 0--2 contain a 0, 2, or 4.) The command interpreter maintains and displays the current hexadecimal value of $STATUS. You can display the ASCII translation of $STATUS by entering the SHOW SYMBOL $STATUS command.
In the following example, the file name (%FRED.LIS) is entered incorrectly:
$ CREATE %FILE.LIS %CREATE-E-OPENOUT, error opening %FRED.LIS; as output -RMS-F-WLD, invalid wildcard operation $ SHOW SYMBOL $STATUS $STATUS = " %X109110A2" $ WRITE SYS$OUTPUT F$MESSAGE(%X109110A2) %CREATE-E-OPENOUT, error opening !AS as output
When a command procedure exits, the command interpreter returns the condition code for the previous command in $STATUS. The condition code provides information about whether the most recent command executed successfully.
When you use the EXIT command in a command procedure, you can specify a value that overrides the value that DCL would have assigned to $STATUS. This value, called a status code, must be specified as an integer expression.
When a command procedure contains nested procedures to create multiple command levels, you can use the EXIT command to return a value that explicitly overrides the default condition codes.
Examine the following two command procedures:
$! This is file A.COM $! $ @B . . .
$! This is file B.COM $! $ ON WARNING THEN GOTO ERROR . . . $ ERROR: $ EXIT 1
The ON command in B.COM means that if any warnings, errors, or severe errors occur when B.COM is executing, the procedure is directed to the label ERROR. Here, the condition code is explicitly set to 1, indicating success. Therefore, when B.COM terminates, it passes a success code back to A.COM regardless of whether an error occurred.
The low-order three bits of $STATUS represent the severity of the condition that caused the command to terminate. This portion of the condition code is contained in the reserved global symbol $SEVERITY. The $SEVERITY symbol can have the values 0 to 4, with each value representing one of the following severity levels:
| Value | Severity |
|---|---|
| 0 | Warning |
| 1 | Success |
| 2 | Error |
| 3 | Information |
| 4 | Fatal (severe) error |
Note that the success and information codes have odd numeric values, and warning and error codes have even numeric values.
You can test for the successful completion of a command with IF commands that perform logical tests on $SEVERITY or $STATUS as follows:
$ IF $SEVERITY THEN GOTO OKAY $ IF $STATUS THEN GOTO OKAY
These IF commands branch to the label OKAY if $SEVERITY and $STATUS have true (odd) values. When the current value in $SEVERITY and $STATUS is odd, the command or program completed successfully. If the command or program did not complete successfully, then $SEVERITY and $STATUS are even; therefore, the IF expression is false.
Instead of testing whether a condition is true, you can test whether it is false. For example:
$ IF .NOT. $STATUS THEN ...
The command interpreter uses the severity level of a condition code to determine whether to take the action defined by the ON command as described in Section 15.23.
Most DCL commands invoke system utilities that generate status values and error messages when they complete. However, there are several commands that do not change the values of $STATUS and $SEVERITY if they complete successfully. These commands are as follows:
| CONTINUE | DECK | DEPOSIT |
| EOD | EXAMINE | GOTO |
| IF | RECALL | SET SYMBOL/SCOPE |
| SHOW STATUS | SHOW SYMBOL | STOP |
| WAIT |
If any of these commands result in a nonsuccessful status, the condition code is placed in $STATUS and the severity level is placed in $SEVERITY.
A login command procedure is a command procedure that the operating system automatically executes each time you log in. The system also executes this procedure at the beginning of every batch job that you submit.
There are 2 types of login command procedures:
Systemwide login command procedures have the following characteristics:
To establish a systemwide login command procedure, your system manager equates the logical name SYS$SYLOGIN to the appropriate login command procedure. Your system manager can specify that this login command procedure be used for all system users or for a certain group of users.
You can create a personal login command procedure to execute the same commands each time you log in.
Your system manager assigns the file specification for your login command procedure. In most installations, the login command procedure is called LOGIN.COM. Therefore, you should name your login command procedure LOGIN.COM unless your system manager tells you otherwise.
Your system manager can set up captive accounts by placing the name of a special command procedure in the LGICMD field for your account. If you log in to a captive account, you can perform only functions specified in the command procedure for your account; you cannot use the complete set of DCL commands. For more information on captive accounts, see the OpenVMS System Manager's Manual.
Refer to Appendix C for a complete annotated LOGIN.COM procedure.
Advanced DCL programming includes the use of complex command procedures and the DCL command PIPE.
Complex command procedures can perform program-like functions. You can use variable input in a command procedure, execute sections of the procedure only if certain conditions are true, execute subroutines, or invoke other command procedures.
You can also use the DCL command PIPE to perform program-like functions. For example, using the PIPE command, you can execute one or more of the following operations from the same DCL command line:
This chapter includes information about the following:
You should read this chapter if you:
For additional information on the commands discussed in this chapter, refer to the OpenVMS DCL Dictionary.
Command procedures frequently require data provided by a user. This data, or input, can be obtained either interactively (as described in Chapter 15) or noninteractively. This chapter discusses noninteractive input methods, and different interactive methods than those described in Chapter 15.
You can use the same data each time a command procedure executes. To do this, place the data in the command procedure on data lines following the command that requires the data.
This command procedure executes the command procedure CENSUS.EXE. CENSUS.EXE reads the data 1993, 1994, and 1995 each time the procedure executes:
$ ! CENSUS.COM $ ! $ RUN CENSUS 1993 1994 1995 $ EXIT
DCL passes the text on a data line directly to the command procedure. Therefore, it will not process data that must be translated such as:
Other methods of obtaining input data for command procedures that are described in the following sections are:
The following sections describe how to use parameters to pass data.
The following list contains rules and guidelines for passing parameters as data to command procedures:
DCL places parameters passed to command procedures in the local symbols P1 to P8. P1 is assigned to the first parameter value, P2 the second, P3 the third, and so on. For example, the following command invokes the command procedure SUM.COM and passes eight parameters to the procedure:
$ @SUM 34 52 664 89 2 72 87 3
When you specify an integer as a parameter, it is converted to a string. In the following example, P1 is the string value 24; P2 is the string value 25:
$ @ADDER 24 25
You can use the symbols P1 to P8 in both integer and character string expressions; DCL performs the necessary conversions automatically.
To preserve spaces, tabs, or lowercase characters in a character string, place quotation marks (" ") before and after the string. For example:
$ @DATA "Paul Cramer"
In the following example, P1 is Paul Cramer and P2 is null. If you omit the quotation marks, each character string is passed as a separate parameter. For example:
$ @DATA Paul Cramer
In this example, the strings Paul and Cramer are converted to uppercase letters; P1 is PAUL and P2 is CRAMER.
As another example, if you invoke DATA.COM with the following command:
$ @DATA "Paul Cramer" 24 "(555) 111-1111")
P1 to P8 are defined in DATA.COM as follows:
To pass the value of a symbol, place an apostrophe before and after the symbol. To preserve spaces, tabs, and lowercase characters in the symbol value, enclose the value in three sets of quotation marks. You must also use three sets of quotation marks to include a quotation mark as part of a string.
An alternative is to enclose the text in quotation marks and where a symbol appears, precede the symbol with two apostrophes and follow it with one apostrophe.
$ NAME = "Paul Cramer" $ @DATA 'NAME'
$ NEW_NAME = """Paul Cramer""" $ @DATA 'NEW_NAME'
$ ! DATA.COM $ @NAME "''P1'"
To pass a null parameter, use one set of quotation marks as a placeholder in the command string. In the following example, the first parameter passed to DATA.COM is a null parameter:
$ @DATA "" "Paul Cramer"
In this example, P1 is null and P2 is Paul Cramer.
The following sections describe how to use parameters to pass data to batch jobs.
To pass parameters to a command procedure executed in batch mode, use the SUBMIT command qualifier /PARAMETERS.
If you execute more than one command procedure using a single SUBMIT command, the specified parameters are used for each command procedure in the batch job.
In the following example, the command passes three parameters to the command procedures ASK.COM and GO.COM, which are executed as batch jobs:
$ SUBMIT/PARAMETERS=(TODAY,TOMORROW,YESTERDAY) ASK.COM, GO.COM)
In the following example, the SUBMIT command passes two parameters to the command procedures: LIBRARY.COM and SORT.COM:
$ SUBMIT- _$ /PARAMETERS=(DISK:[ACCOUNT.BILLS]DATA.DAT,DISK:[ACCOUNT]NAME.DAT) - _$ LIBRARY.COM, SORT.COM
The batch job executes as if you had logged in and executed each of the command procedures. This SUBMIT command executes a batch job that logs in under your account, executes your login command procedure, and then executes the following commands:
$ @LIBRARY DISK:[ACCOUNT.BILLS]DATA.DAT DISK:[ACCOUNT]NAME.DAT) $ @SORT DISK:[ACCOUNT.BILLS]DATA.DAT DISK:[ACCOUNT]NAME.DAT)
You can also pass data to a batch job by including the data in a command procedure or by defining SYS$INPUT to be a file. The specified parameters are used for each command procedure in the batch job.
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:
$ ! DATA.COM $ @NAME 'P1' Joe Cooper
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:
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:
$ ! DATA.COM $ QUOTE = """ $ P1 = QUOTE + P1 + QUOTE $ @NAME 'P1' "Joe Cooper"
In this example, P1 is Paul Cramer and P2 is Joe Cooper in the command procedure NAME.COM.
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 INQUIRE command... | The READ command... |
|---|---|
| Prompts for a value | Prompts for a value |
| Reads the value from the terminal | Reads the value from the source specified by the first parameter |
| Assigns the value to a symbol | Assigns the value to the symbol named as the second parameter |
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.
$ READ/PROMPT="Filename: " SYS$COMMAND FILE
$ ! Prompt for a file name if name $ ! is not passed as a parameter $ IF P1 .EQS. "" THEN INQUIRE P1 "Filename" $ COPY 'P1' DISK5:[RESERVED]*.* $ EXIT
If you submit a command procedure for execution as a batch job, DCL reads the value for a symbol specified in an INQUIRE command from the data line following the INQUIRE command. If you do not include a data line, the symbol is assigned a null value.
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.
$ ! Execute CENSUS getting data from the terminal $ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND $ RUN CENSUS $ EXIT
$ ! Obtain a list of your files $ DIRECTORY $ ! $ ! Get file name and invoke the EVE editor $ EDIT_LOOP: $ INQUIRE FILE "File to edit (Press Return to end)" $ IF FILE .EQS. "" THEN EXIT $ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND $ EDIT/TPU 'FILE' $ GOTO EDIT_LOOP
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:
$ FORTRAN/OBJECT=TESTER/LIST=TESTER SYS$INPUT C THIS IS A TEST PROGRAM A = 1 B = 2 STOP END $ PRINT TESTER.LIS $ EXIT
6489P029.HTM OSSG Documentation 22-NOV-1996 13:17:20.01
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.