Document revision date: 15 July 2002
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS User's Manual

Previous Contents Index

13.11.2 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.

13.12 Setting Ctrl/Y Action Routines

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

13.12.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:


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.

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

13.12.2 Effects of Entering Ctrl/Y

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:

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

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.


Figure 13-2 illustrates the flow of execution following Ctrl/Y interruptions.

Figure 13-2 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.

Figure 13-3 illustrates what happens when Ctrl/Y is pressed during the execution of nested command procedures.

Figure 13-3 Ctrl/Y in Nested 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.

13.13 Disabling and Enabling Ctrl/Y Interruptions

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

13.13.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.

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:


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.

13.13.2 Using SET CONTROL=Y

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.

In this command procedure, pressing Ctrl/Y while a file is being typed passes control to the label END_TYPE:

$! Type a file 
$! Reset default 


The ON CONTROL_Y and SET NOCONTROL=Y commands are intended for special applications. Compaq 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.

13.14 Detecting Errors in Command Procedures Using Condition Codes

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.

13.14.1 Displaying Condition Codes ($STATUS)

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-E-OPENOUT, error opening %FRED.LIS; as output 
-RMS-F-WLD, invalid wildcard operation 
  $STATUS = " %X109110A2" 
  %CREATE-E-OPENOUT, error opening !AS as output 

13.14.2 Condition Codes with the EXIT Command

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 
$ 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.

13.14.3 Determining Severity Levels

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.

13.14.4 Testing for Successful Completion

You can test for the successful completion of a command with IF commands that perform logical tests on $SEVERITY or $STATUS as follows:


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:


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 13.9.

13.15 Using Commands That Do Not Set $STATUS

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:

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.

13.16 Login Command Procedures

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 two types of login command procedures:

13.16.1 Systemwide 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.

13.16.2 Personal Login Command Procedures

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.

The following is an example of a LOGIN.COM procedure:

$EDIT :== EDIT/EDT      

13.16.3 Login Command Procedures in Captive Accounts

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 about captive accounts, refer to the OpenVMS System Manager's Manual.

13.17 Extended File Specifications and Parsing Styles

A command procedure that requires a specific file name parsing style can include commands within the procedure to switch between styles. The following command procedure saves the current parsing style, sets the parsing style to TRADITIONAL, performs (unspecified) commands, then restores the saved parsing style.

$ original_style= f$getjpi("","parse_style_perm") 
$ SET PROCESS/PARSE_STYLE='original_style' 

The first command equates 'original_style' with the current parse style. The second command sets the parsing style to TRADITIONAL. The last command resets the parsing style to the original style.

13.18 Using Extended File Names in DCL Command Parameters

Command procedures that use file names as parameters can produce different results in an ODS-5 environment.

You can switch from the TRADITIONAL to the EXTENDED parsing style, and this section describes the following areas that may be affected if you choose to do so:

See Section 5.3 for more information on switching between parsing styles.

13.18.1 Command Procedure File Specification

If indirect command procedures are used, you may need to put quotes around some procedure arguments.

The following examples show the differences in output between TRADITIONAL and EXTENDED parsing styles when using the same command file, SS.COM:

       $ create 
       $ if p1 .nes. "" then write sys$output "p1 = ",p1 
       $ if p2 .nes. "" then write sys$output "p2 = ",p2 
       $ if p3 .nes. "" then write sys$output "p3 = ",p3 

13.18.2 Case Preservation and $FILE

DCL attempts to preserve the case of file specifications. It can do this only for commands defined with the Command Definition Utility (CDU). DCL preserves case for any item defined in the command definition file (.CLD) with the $FILE parse type.

Refer to the OpenVMS Command Definition, Librarian, and Message Utilities Manual for more information.

13.18.3 Ampersand Versus Apostrophe Substitution

You can use ampersand (&) substitution, as opposed to apostrophe substitution, to preserve case during traditional parsing.

The following traditional parsing example shows a series of commands that change the case of a character string:

       $ set process/parse_style=traditional 
       $ x = "string" 
       $ define y 'x' 
       $ sho log y 
          "Y" = "STRING" (LNM$PROCESS_TABLE) 
       $ define y &x 
       %DCL-I-SUPERSEDE, previous value of Y has been superseded 
       $ sho log y 
          "Y" = "string" (LNM$PROCESS_TABLE) 

Note that the use of the ampersand (&) preserved the case of the character string assigned to the x variable.

Apostrophe substitution takes place before the command line is set to uppercase, and ampersand substitution takes place after the command line is set to uppercase.

The following extended parsing example shows the same series of commands:

       $ set process/parse_style=extended 
       $ define y 'x' 
       %DCL-I-SUPERSEDE, previous value of Y has been superseded 
       $ sho log y 
          "Y" = "string" (LNM$PROCESS_TABLE) 
       $ define y &x 
       %DCL-I-SUPERSEDE, previous value of Y has been superseded 
       $ sho log y 
          "Y" = "string" (LNM$PROCESS_TABLE) 

Note that both character strings for the y variable are returned lowercase. This happens because the DEFINE command uses $FILE, which preserves the case.

Ampersand substitution can therefore be used to specify EXTENDED file names even though the parsing style is set to TRADITIONAL, as shown in the following example:

$ set process/parse=extended 
$ cre file^ name.doc 
Contents of an ODS5 file 
$ set process/parse=traditional 
$ a = "file^ name.doc" 
$ type file^ name.doc 
%DCL-W-PARMDEL, invalid parameter delimiter - check use of special characters 
$ type 'a' 
%DCL-W-PARMDEL, invalid parameter delimiter - check use of special characters 
$ type &a 
Contents of an ODS5 file 


Ampersand substitution does not work for foreign commands.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement