OpenVMS User's Manual

Then, to execute the procedure SETD.COM, enter the symbol name as you would any command:

$ SETD [Return]

By default, when you execute a command procedure interactively, the operating system displays output at your terminal. However, you can redirect output to a file by using the /OUTPUT qualifier to the execute command.

When you redirect command procedure output to a file, the procedure sends any error messages to the terminal and to the file that is receiving the output.

15.18.6 Example

This command writes the output from SETD.COM to the file RESULTS.TXT instead of to the terminal:

$ @SETD/OUTPUT=RESULTS.TXT 

Always place the /OUTPUT qualifier immediately after the command procedure name, with no intervening spaces. Otherwise, DCL interprets the qualifier as a parameter to be passed to the procedure.

15.19 Executing Command Procedures as Batch Jobs

If you use command procedures that require lengthy processing time (for example, compiling or assembling large programs), submitting these procedures as batch jobs will allow you to continue using your terminal interactively.

15.19.1 Submitting Batch Jobs

To execute a command procedure in batch mode, submit your command procedure to a batch queue (a list of batch jobs waiting to execute) by entering the DCL command SUBMIT. When you submit a job, it is directed to the default batch queue SYS$BATCH where it is added to the end of the queue of jobs waiting to be executed. When the jobs preceding yours are completed, your job is executed. On OpenVMS systems, the number of batch jobs that can execute simultaneously is specified when the batch queue is created by the system manager.

15.19.2 Example

The following example shows how to execute the command procedure named JOB1.COM. The SUBMIT command uses the default file type .COM; therefore you do not have to enter the file type if your command procedure has the file type .COM:

$ SUBMIT JOB1 
Job JOB1 (queue SYS$BATCH, entry 651, started on SYS$BATCH)) 

If your system is part of a network, you can submit a command procedure as a batch job on a remote node. Within a command procedure, you can use DCL commands to open and close files on remote notes and to read and write records in those files, using the same commands and qualifiers for local files.

15.19.4 Restarting Batch Jobs

By default, if the system fails before the job is finished, batch jobs are reexecuted beginning with the first line. However, you can use the following symbols in your command procedure to specify a different restarting point:

• $RESTART
  A global symbol whose value is true if the batch job has been started at least once before this execution. Do not specify a value for $RESTART; the system will assign the appropriate value.
• BATCH$RESTART
  A global symbol whose value you specify using the SET RESTART_VALUE command.

The following procedure describes how to use the $RESTART and the BATCH$RESTART symbols:

Step	Action
1	Begin each possible starting point of the procedure with a label.
2	As the first step in each section, equate the value of BATCH$RESTART to the label using the SET RESTART_VALUE command.
3	At the beginning of the procedure, test $RESTART.
4	If $RESTART is true, issue a GOTO statement using BATCH$RESTART as the transfer label.

15.19.6 Example

This command procedure extracts a number of modules from a library, concatenates those modules, and then sorts the resulting file:

$! SORT_MODULES.COM 
! 
$! Set default to the directory containing 
$! the library whose modules are to be sorted 
$ SET DEFAULT WORKDISK:[ACCOUNTS.DATA83] 
$! 
$! Check for restarting 
$ IF $RESTART THEN GOTO "BATCH$RESTART" 
$! 
$ EXTRACT_LIBRARIES: 
$ SET RESTART_VALUE=EXTRACT_LIBRARIES 
   .
   .
   .
$ CONCATENATE_LIBRARIES: 
$ SET RESTART_VALUE=CONCATENATE_LIBRARIES 
   .
   .
   .
$ SORT_FILE: 
$ SET RESTART_VALUE=SORT_FILE 
   .
   .
   .
$ EXIT 

If this command procedure aborts, it reexecutes from the beginning of the file, from the statement labeled CONCATENATE_LIBRARIES, or from the statement labeled SORT_FILE, depending on the value of BATCH$RESTART. If you were extracting a number of separate modules, you could make each extraction a separate section.

15.20 Executing Command Procedures on Disk and Tape Volumes

The following sections describe how to execute command procedures on disk and tape volumes.

15.20.1 Executing on Private Disk Volumes

When you submit a command procedure with the SUBMIT command, you cannot access files on allocated devices. You can, however, execute a command procedure that is located on a private disk volume if the volume is mounted with the /SHARE qualifier.

15.20.2 Executing on Tape Volumes

You can execute command procedures that reside on tape volumes if:

• The procedure does not invoke any other procedures
• The procedure does not issue any GOTO commands that refer to labels in the procedure preceding the GOTO command

If either of these conditions occur, you can execute the command procedure by doing the following:

Step	Action
1.	Copy the command procedure to a shared disk volume.
2.	Execute the command procedure on the shared disk volume.

15.21 Exiting and Interrupting Command Procedures

When you use any of the methods described in this section to exit from a command procedure, you need to be aware of command levels.

A command level is an input stream for the DCL level interpreter. When you enter commands at your terminal, you are entering commands at command level 0. A simple interactive command procedure (such as CLEANUP.COM) executes at command level 1. When the procedure terminates and the DCL prompt reappears on your screen, you are back at command level 0.

15.21.1 Methods of Exiting

There are three ways to exit from a command procedure while it is executing:

• Place an EXIT command in the command procedure
• Place a STOP command in the command procedure
• Enter Ctrl/Y during the execution of the program

If an exit is caused by the end of the procedure or an EXIT command, control returns to the next higher command level. You can return a status value to the next higher command level by specifying the value as the parameter of the EXIT command.

15.21.3 Example

If you invoke the command procedure called SUB at the DCL level and SUB calls the subroutine SUB1, the following occurs:

1. Exiting from SUB1 returns you to SUB at the command line following the call to SUB1.
2. Exiting from SUB returns you to DCL command level.

If an exit is caused by a STOP command, control always returns to DCL command level, regardless of the command level in which the STOP command executes.

If you execute the STOP command in a batch job, the batch job terminates.

15.21.5 Exiting with Ctrl/Y

You can interrupt a command procedure by pressing Ctrl/Y and then using the EXIT or STOP command to terminate the procedure. In this case, both the EXIT and STOP command return you to the DCL level.

15.21.6 Example

In the following example, the TESTALL procedure is interrupted by pressing Ctrl/Y. The EXIT command terminates processing of the procedure and returns you to DCL level. (Note that you can also enter the STOP command after you interrupt the procedure.)

$ @TESTALL[Return]
[Ctrl/Y]
$ EXIT[Return]
$ 

When you interrupt a command procedure, if the command (or image) that you interrupt declares any exit-handling routines, the EXIT command gives these routines control. However, the STOP command does not execute these routines.

15.22 Handling Errors

By default, the command interpreter executes an EXIT command when a command results in an error or severe error. This causes the procedure to exit to the previous command level. For other severity levels (success, warning, and informational), the command procedure continues.

When the system issues an EXIT command as part of an error-handling routine, it passes the value of $STATUS back to the previous command level, with one change. The command interpreter sets the high-order digit of $STATUS to 1 so that the command interpreter does not redisplay the message associated with the status value.

15.22.1 Handling Label Errors

There is one exception to the way that the command interpreter handles errors. If you reference a label in a command procedure and the label does not exist (for example, if you include the command GOTO ERR1 and ERR1 is not used as a label in the procedure), the GOTO command issues a warning and the command procedure exits.

15.22.2 Example: Displaying Errors

In the following example, the command procedure TEST.COM contains an error in the output file specification:

$ CREATE DUMMY.DAT\
THIS IS A TEST FILE 
$ SHOW TIME 

When you execute this procedure, the CREATE command returns an error in $STATUS and displays the corresponding message. The command interpreter then examines the value of $STATUS, determines that an error occurred, issues an EXIT command, and returns the value of $STATUS. When the procedure exits, the error message is not redisplayed because the CREATE command already displayed the message once. At DCL command level, you can see that $STATUS contains the error message but the high-order digit has been set to 1. For example:

$ @TEST 
%CREATE-E-OPENOUT, error opening DUMMY.DAT as output 
-RMS-F-SYN, file specification syntax error 
%DCL-W-SKPDAT, image data (records not beginning with "$") ignored 
$ SHOW SYMBOL $STATUS 
  $STATUS = "%X109110A2" 
$ WRITE SYS$OUTPUT F$MESSAGE(%X109110A2) 
  %CREATE-E-OPENOUT, error opening !AS as output 

The following table describes the default action taken when an error condition or a Ctrl/Y interruption occurs while a command procedure is executing. You can override these default actions with the ON, SET [NO]ON, and SET [NO]CONTROL=Y commands.

Interrupt	Default Action
Error or severe error	Procedure exits to the next command level.
Ctrl/Y at DCL command level or command level 1	Procedure is interrupted; the procedure can continue if no other image forces it to exit.
Ctrl/Y at command level lower than level 1	Procedure exits to the next higher command level.

15.23 Other Methods of Error Handling

The following sections describe other methods of handling errors.

15.23.1 ON Command

The ON command specifies an action to be performed if an error of a certain severity or greater severity occurs. If such an error occurs, the system takes the following actions:

• Performs the action specified by the ON command.
• Sets $STATUS and $SEVERITY to indicate the result of the specified ON action. In general, they are set to success.
• Resets the default error action (to exit if an error or severe error occurs).

An ON command action is executed only once. Therefore, after a command procedure performs the action specified in an ON command, the default error action is reset.

The action specified by an ON command applies only within the command level in which the command is executed. Therefore, if you execute an ON command in a procedure that invokes another procedure, the ON command action does not apply to the nested procedure.

15.23.2 ON Command Format

The format of the ON command is as follows:

ON condition THEN [$] command 

Where "condition" is one of the following keywords:

ON Keyword	Action Taken
WARNING	Command procedure performs the specified action if a warning, error, or severe error occurs.
ERROR	Command procedure performs the specified action if an error or severe error occurs. The procedure continues if a warning occurs.
SEVERE_ERROR	Command procedure performs the specified action if a severe (fatal) error occurs. The procedure continues if a warning or error occurs.

If an ON command action is established for a specific severity level, the command interpreter performs the specified action when errors of the same or worse severity occur. When less severe errors occur, the command interpreter continues processing the file.

15.23.3 Example: Using the ON Command

This command can be used to override the default error handling so that a procedure exits when warnings, errors, or severe errors occur:

$ ON WARNING THEN EXIT 

If your command procedure incudes this command, the command procedure executes normally until an error or severe error occurs:

$ ON ERROR THEN GOTO ERR1 

If such an error occurs, then the procedure resumes executing at ERR1. $STATUS and $SEVERITY are set to success and the default error action is reset. If a second error occurs before another ON or SET NOON command is executed, the procedure exits to the previous command level.

15.23.5 Figure: ON Command Actions

Figure 15-1 illustrates ON command actions.

Figure 15-1 ON Command Actions

1. This ON command overrides the default command action (on warning, continue; on error or severe error, exit). If an error or severe error occurs while A.FOR is being compiled, the command procedure continues with the next command.
2. The default command action is reset if the previous ON command takes effect. Thus, if an error or severe error occurs while both A.FOR and B.FOR are being compiled, the command procedure exits.
3. If a warning, error, or severe error occurs while C.FOR is being compiled, the command procedure exits.
4. If the command procedure does not exit before a command is executed, the command action takes effect.

The sample command procedures FORTUSER.COM and CALC.COM in Appendix C also illustrate the use of the ON command to establish error handling.

15.24 Using the SET NOON Command

The following sections describe how to use the SET NOON command.

15.24.1 Disabling Error Checking

You can prevent the command interpreter from checking the status returned from commands by using the SET NOON command in your command procedure, which sets the ON command to NO status. When you use the SET NOON command, the command interpreter continues to place values in $STATUS and $SEVERITY but does not perform any error checking. You can restore error checking with the SET ON command or with an ON command.

When a procedure disables error checking, it can explicitly check the value of $STATUS following the execution of a command or program.

15.24.2 Example: Disabling Error Checking

In the following example, the SET NOON command preceding the RUN commands ensures that the command procedure continues if either of the programs TESTA or TESTB return an error condition. The SET ON command restores the default error checking by the command interpreter.

$ SET NOON 
$ RUN TESTA 
$ RUN TESTB 
$ SET ON 

In the following example, the first IF command checks whether $STATUS has a true value (that is, if it is an odd numeric value). If so, the FORTRAN command was successful and the LINK command executes. After the LINK command executes, $STATUS is tested again. If $STATUS is odd, the RUN command executes; otherwise, the RUN command does not execute. The SET ON command restores the current ON condition action; that is, whatever condition was in effect before the SET NOON command was executed:

$ SET NOON 
$ FORTRAN MYFILE 
$ IF $STATUS THEN LINK MYFILE 
$ IF $STATUS THEN RUN MYFILE 
$ SET ON 

The SET ON or SET NOON command applies only at the current command level; that is, the command level at which the command is executed. If you use the SET NOON command in a command procedure that calls another command procedure, the default error-checking mechanism will be in effect within the nested procedure. Note that SET NOON has no meaning when entered interactively at DCL level.

15.25 Handling Ctrl/Y Interruptions

This section describes methods of overriding the way that command procedures process Ctrl/Y interruptions by using the ON command.

15.25.1 Stopping Command Procedures

You can interrupt a command procedure that is executing interactively by pressing Ctrl/Y. When you press Ctrl/Y, the command interpreter establishes a new command level, called the Ctrl/Y level, and prompts for command input. When the interruption occurs depends on the command or program that is executing:

• If the command is executed by the command interpreter itself (for example, IF, GOTO, or an assignment statement), the command completes execution before the command interpreter prompts for a command at the Ctrl/Y level.
• If the command or program is a separate image (that is, an image other than the command interpreter), the command is interrupted and the command interpreter prompts for a command at the Ctrl/Y level.

At the Ctrl/Y level, the command interpreter stores the status of all previously established command levels so that it can restore the correct status after any Ctrl/Y interrupt.

15.25.2 After Ctrl/Y Is Entered

After you interrupt a procedure, you can do the following:

• Enter a DCL command that is executed within the command interpreterng these commands are the SET VERIFY, SHOW TIME, SHOW TRANSLATION, ASSIGN, EXAMINE, DEPOSIT, SPAWN and ATTACH commands. After you enter one or more of these commands, you can resume the execution of the procedure with the CONTINUE command. See Section 16.10.5 for a complete list of commands that are executed within the command interpreter.
  When you enter the CONTINUE command, the command procedure resumes execution with the interrupted command or program or with the line after the most recently completed command.
• Enter a DCL command that executes another image.
  When you enter any command that invokes a new image, the command interpreter returns to command level 0 and executes the command. This terminates the command procedure's execution. Any exit handlers declared by the interrupted image are allowed to execute before the new image is started.
• Enter the EXIT or STOP command to terminate the command procedure's execution.
  If you use the EXIT command, exit handlers declared by the interrupted image are allowed to execute. However, the STOP command does not execute these routines.

If you do not exit from a command procedure (either explicitly from the command level or as part of an ON routine) following a Ctrl/Y, the next command you enter is interpreted in the context of the command procedure. For example, suppose you define the following symbol at the interactive level:

$ MAIL = "mail/edit=(send,reply,forward)" 

If you enter Ctrl/Y to interrupt a command procedure that does not include this definition and then enter the command MAIL to send a message, your editor is not invoked automatically.

15.25.4 Stopping Privileged Images

If you interrupt the execution of a privileged image, you can enter only the CONTINUE, SPAWN, or ATTACH commands if you want to save the context of the image. If you enter any other commands (except from within a subprocess that you have spawned or attached to), the privileged image is forced to exit.

15.26 Setting Ctrl/Y Action Routines

The following sections describe how to set Ctrl/Y action routines.

15.26.1 Using the ON Command

The ON command, which defines an action to be taken in case of error conditions, also provides a way to define an action routine for a Ctrl/Y interruption that occurs during execution of a command procedure. The action that you specify overrides the default Ctrl/Y action (that is, to prompt for command input at the Ctrl/Y command level). For example:

$ ON CONTROL_Y THEN EXIT 

If a procedure executes this ON command, a subsequent Ctrl/Y interruption during the execution of the procedure causes the procedure to exit. Control is passed to the previous command level.

15.26.2 When Ctrl/Y Is Pressed

When you press Ctrl/Y to interrupt a procedure that uses ON CONTROL_Y, the following actions are taken:

• If the command currently executing is a command executed within the command interpreter, the command completes and the Ctrl/Y action is taken.
• If the current command or program is executed by an image other than the command interpreter, the image is forced to exit and the Ctrl/Y action is taken. If the image has declared an exit handler, however, the exit handler is executed before the Ctrl/Y action is taken. The image cannot be continued following the Ctrl/Y action.

The execution of Ctrl/Y does not automatically reset the default Ctrl/Y action (that is, to prompt for command input at the Ctrl/Y command level). A Ctrl/Y action remains in effect until one of the following conditions occurs:

• The procedure terminates (as a result of pressing Ctrl/Y, executing an EXIT or STOP command, or a default error condition handling action).
• Another ON CONTROL_Y command is executed.
• The procedure executes the SET NOCONTROL=Y command (see Section 15.27).

A Ctrl/Y action can be specified in each active command level and affects only the command level in which it is specified.

15.26.4 Example: Using the ON Command

When the command procedure shown in the following example executes, each Ctrl/Y interruption results in the execution of the SHOW TIME command. After each SHOW TIME command executes, the procedure resumes execution at the command following the command that was interrupted:

$ ON CONTROL_Y THEN SHOW TIME 

15.26.5 Figure: Flow of Execution Following Ctrl/Y Action

1. The Ctrl/Y interruption occurs during the execution of the TYPE command.
2. Control is then transferred to the label CLEAN_UP.
3. After executing the routine, the command procedure exits and returns to the interactive command level.
4. The Ctrl/Y interruption occurs during the execution of the TYPE command.
5. The WRITE command specified in the ON command is executed.
6. The command procedure continues execution at the command following the interrupted command.

The following figure illustrates what happens when Ctrl/Y is pressed during the execution of nested command procedures:

1. If a Ctrl/Y interruption occurs while SEARCH.COM is executing, control is transferred to the label CLEAN_UP.
2. If a Ctrl/Y interruption occurs while SUBSEARCH.COM is executing, control is transferred to the label NEXT_STEP in SEARCH.COM.
3. Because no Ctrl/Y action is specified in SUBSEARCH.COM, the procedure exits to the previous command level when a Ctrl/Y interruption occurs.
4. If a Ctrl/Y interruption occurs while SUBSUB.COM is executing, the SHOW TIME is executed.

The following sections describe how to disable and enable Ctrl/Y interruptions.

15.27.1 Using SET NOCONTROL=Y

The SET NOCONTROL=Y command disables Ctrl/Y handling. That is, if a command procedure executes the SET NOCONTROL=Y command, pressing Ctrl/Y has no effect.

  6489P028.HTM
  OSSG Documentation
  22-NOV-1996 13:17:18.45

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal