HP OpenVMS Systems Documentation

The label can precede or follow the CALL statement in the current command procedure. A label in a command procedure must be terminated with a colon (:). Labels for subroutines must be unique.

Labels declared in inner procedure levels are inaccessible from outer levels, as in the following example:

$CALL B
$A: SUBROUTINE
$  B: SUBROUTINE
$  ENDSUBROUTINE
$ENDSUBROUTINE

In this example, the label B in subroutine A is inaccessible from the outer procedure level.

parameter [...]

You can specify a parameter with a character string value containing alphanumeric or special characters, with the following restrictions:

• The command interpreter converts alphabetic characters to uppercase and uses blanks to delimit each parameter. To pass a parameter that contains embedded blanks or lowercase letters, enclose the parameter in quotation marks (" ").
• If the first parameter begins with a slash (/), you must enclose the parameter in quotation marks.
• To pass a parameter that contains quotation marks and spaces, enclose the entire string in quotation marks and use two sets of quotation marks within the string. For example:

  $ CALL SUB1 "Never say ""quit"""

  
  When control transfers to SUB1, the parameter P1 is equated to the following string:

  Never say "quit"

  
  If a string contains quotation marks and does not contain spaces, the quotation marks are preserved in the string and the letters within the quotation marks remain in lowercase. For example:

  $ CALL SUB2 abc"def"ghi

  
  When control transfers to SUB2, the parameter P1 is equated to the string:

  ABCdefGHI

To use a symbol as a parameter, enclose the symbol in single quotation marks (` ') to force symbol substitution. For example:

$ NAME = "JOHNSON"
$ CALL INFO 'NAME'

The single quotation marks cause the value "JOHNSON" to be substituted for the symbol `NAME'. Therefore, the parameter "JOHNSON" is passed as P1 to the subroutine INFO.

Description

The CALL command transfers control to a labeled subroutine within a command procedure. The CALL command is similar to the @ (execute procedure) command in that it creates a new procedure level. The advantage of the CALL command is that it does not require files to be opened and closed to process the procedure. Using the CALL command also makes managing a set of procedures easier because they can all exist in one file rather than in several files.

When you use the CALL command to transfer control to a subroutine, a new procedure level is created and the symbols P1 to P8 are assigned the values of the supplied arguments. Execution then proceeds until an EXIT command is encountered. At this point, control is transferred to the command line following the CALL command.

Procedures can be nested to a maximum of 32 levels, which includes any combination of command procedure and subroutine calls. Local symbols and labels defined within a nested subroutine structure are treated the same way as if the routines had been invoked with the @ command; that is, labels are valid only for the subroutine level in which they are defined.

Local symbols defined in an outer subroutine level are available to any subroutine levels at an inner nesting level; that is, the local symbols can be read, but they cannot be written to. If you assign a value to a symbol that is local to an outer subroutine level, a new symbol is created at the current subroutine level. However, the symbol in the outer procedure level is not modified.

The SUBROUTINE and ENDSUBROUTINE commands define the beginning and end of a subroutine. The label defining the entry point to the subroutine must appear either immediately before the SUBROUTINE command or on the same command line.

A subroutine can have only one entry point. The subroutine must begin with the SUBROUTINE command as the first executable statement. If an EXIT command is not specified in the procedure, the ENDSUBROUTINE command functions as an EXIT command.

The SUBROUTINE command performs two different functions depending on the context in which it is executed. If executed as the result of a CALL command, it initiates a new procedure level, defines the parameters P1 to P8 as specified in the CALL statement, and begins execution of the subroutine. If the SUBROUTINE verb is encountered in the execution flow of the procedure without having been invoked by a CALL command, all the commands following the SUBROUTINE command are skipped until the corresponding ENDSUBROUTINE command is encountered.

Note The SUBROUTINE and ENDSUBROUTINE commands cannot be abbreviated to fewer than 4 characters.

Qualifier

/OUTPUT=filespec

Writes all output to the file or device specified. By default, the output is written to the current SYS$OUTPUT device and the output file type is .LIS. System responses and error messages are written to SYS$COMMAND as well as to the specified file. If you specify /OUTPUT, the qualifier must immediately follow the CALL command. The asterisk (*) and the percent sign (%) wildcard characters are not allowed in the output file specification.

You can also redefine SYS$OUTPUT to redirect the output from a command procedure. If you place the following command as the first line in a command procedure, output will be directed to the file you specify:

$ DEFINE SYS$OUTPUT filespec

When the procedure exits, SYS$OUTPUT is restored to its original equivalence string. This produces the same result as using the /OUTPUT qualifier when you execute the command procedure.

Example

$
$! CALL.COM
$
$! Define subroutine SUB1
$!
$ SUB1: SUBROUTINE
   .
   .
   .
$ CALL SUB2 !Invoke SUB2 from within SUB1
   .
   .
   .
$ @FILE  !Invoke another procedure command file
   .
   .
   .
$ EXIT
$ ENDSUBROUTINE !End of SUB1 definition
$!
$! Define subroutine SUB2
$!
$ SUB2: SUBROUTINE
   .
   .
   .
$ EXIT
$ ENDSUBROUTINE !End of SUB2 definition
$!
$! Start of main routine. At this point, both SUB1 and SUB2
$! have been defined but none of the previous commands have
$! been executed.
$!
$ START:
$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS P1"
   .
   .
   .
$ CALL SUB2 "THIS IS P1" "THIS IS P2"
   .
   .
   .
$ EXIT  !Exit this command procedure file

      

The command procedure in this example shows how to use the CALL command to transfer control to labeled subroutines. The example also shows that you can call a subroutine or another command file from within a subroutine. The CALL command invokes the subroutine SUB1, directing output to the file NAMES.LOG and allowing other users write (W) access to the file. The subroutine SUB2 is called from within SUB1. The procedure executes SUB2 and then uses the @ (execute procedure) command to invoke the command procedure FILE.COM. When all the commands in SUB1 have executed, the CALL command in the main procedure calls SUB2 a second time. The procedure continues until SUB2 has executed.

Cancels wakeup requests for a specified process, including wakeup requests scheduled with either the RUN command or the $SCHDWK system service.

Requires one of the following:

• Ownership of the process.
• GROUP privilege to cancel scheduled wakeup requests for processes in the same group but not owned by you.
• WORLD privilege to cancel scheduled wakeup requests for any process in the system.

Format

CANCEL [[node-name::]process-name]

Parameters

node-name::

The name of the node on which the specified process is running.

You cannot specify a node name on a different OpenVMS Cluster system from the current process.

process-name

The name of the process for which wakeup requests are to be canceled. The process name can have up to 15 alphanumeric characters.

The specified process must be in the same group as the current process.

Description

The CANCEL command cancels scheduled wakeup requests for the specified process.

The CANCEL command does not delete the specified process. If the process is executing an image when the CANCEL command is issued for it, the process hibernates instead of exiting after the image completes execution.

To delete a hibernating process for which wakeup requests have been canceled, use the STOP command. You can determine whether a subprocess has been deleted by entering the SHOW PROCESS command with the /SUBPROCESSES qualifier.

A local process name can look like a remote process name. Therefore, if you specify ATHENS::SMITH, the system checks for a process named ATHENS::SMITH on the local node before checking node ATHENS for a process named SMITH.

You also can use the /IDENTIFICATION=pid qualifier to specify a process name. If you use the /IDENTIFICATION qualifier and the process-name parameter together, the qualifier overrides the parameter. If you do not specify either the process-name parameter or the /IDENTIFICATION qualifier, the CANCEL command cancels scheduled wakeup requests for the current (that is, the issuing) process.

Qualifier

/IDENTIFICATION=pid

Identifies the process by its process identification (PID). You can omit leading zeros when you specify the PID.

Examples

$ CANCEL CALENDAR
      

The CANCEL command in this example cancels a wakeup request for a process named CALENDAR (which continues to hibernate until it is deleted with the STOP command).

$ RUN/SCHEDULE=14:00 STATUS
%RUN-S-PROC_ID, identification of created process is 0013012A
   .
   .
   .
$ CANCEL/IDENTIFICATION=13012A
      

The RUN command in this example creates a process to execute the image STATUS. The process hibernates and is scheduled to be awakened at 14:00. Before the process is awakened, the CANCEL command cancels the wakeup request.

$ RUN/PROCESS_NAME=LIBRA/INTERVAL=1:00    LIBRA
%RUN-S-PROC_ID, identification of created process is 00130027
   .
   .
   .
$ CANCEL LIBRA
$ STOP LIBRA
      

The RUN command in this example creates a subprocess named LIBRA to execute the image LIBRA.EXE at hourly intervals.

Subsequently, the CANCEL command cancels the wakeup request. The process continues to exist, but in a state of hibernation, until the STOP command deletes it.

Closes a file opened with the OPEN command and deassigns the associated logical name.

Format

CLOSE logical-name[:]

Parameter

logical-name[:]

Specifies the logical name assigned to the file when it was opened with the OPEN command.

Description

Files that are opened for reading or writing at the command level remain open until closed with the CLOSE command, or until the process terminates. If a command procedure that opens a file terminates without closing the open file, the file remains open; the command interpreter does not automatically close it.

Qualifiers

/ERROR=label

Specifies a label in the command procedure to receive control if the close operation results in an error. Overrides any ON condition action specified. 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.

/LOG (default)

/NOLOG

Generates a warning message when you attempt to close a file that was not opened by DCL. If you specify the /ERROR qualifier, the /LOG qualifier has no effect. If the file has not been opened by DCL, the error branch is taken and no message is displayed.

Examples

$ OPEN/READ INPUT_FILE   TEST.DAT
$ READ_LOOP:
$ READ/END_OF_FILE=NO_MORE  INPUT_FILE  DATA_LINE
   .
   .
   .
$ GOTO READ_LOOP
$ NO_MORE:
$ CLOSE INPUT_FILE

      

The OPEN command in this example opens the file TEST.DAT and assigns it the logical name of INPUT_FILE. The /END_OF_FILE qualifier on the READ command requests that, when the end-of-file (EOF) is reached, the command interpreter should transfer control to the line at the label NO_MORE. The CLOSE command closes the input file.

$ @READFILE
[Ctrl/Y]
$ STOP
$ SHOW LOGICAL/PROCESS
   .
   .
   .
  "INFILE" = "_DB1"
  "OUTFILE" = "_DB1"
$ CLOSE INFILE
$ CLOSE OUTFILE

      

In this example, pressing Ctrl/Y interrupts the execution of the command procedure READFILE.COM. Then, the STOP command stops the procedure. The SHOW LOGICAL/PROCESS command displays the names that currently exist in the process logical name table. Among the names listed are the logical names INFILE and OUTFILE, assigned by OPEN commands in the procedure READFILE.COM.

The CLOSE commands close these files and deassign the logical names.

Connects your physical terminal to a virtual terminal that is connected to another process.

You must connect to a virtual terminal that is connected to a process with your user identification code (UIC). No other physical terminals may be connected to the virtual terminal.

Format

CONNECT virtual-terminal-name

Parameter

virtual-terminal-name

Specifies the name of the virtual terminal to which you are connecting. A virtual terminal name always begins with the letters VTA. To determine the name of the virtual terminal that is connected to a process, enter the SHOW USERS command.

Description

The CONNECT command connects you to a separate process, as opposed to the SPAWN and ATTACH commands, which create and attach subprocesses.

The CONNECT command is useful when you are logged in to the system using telecommunications lines. If there is noise over the line and you lose the carrier signal, your process does not terminate. After you log in again, you can reconnect to the original process and log out of your second process.

To use the CONNECT command, the virtual terminal feature must be enabled for your system with the System Manager utility (SYSMAN) on OpenVMS Alpha systems and the System Generation utility (SYSGEN) on OpenVMS VAX systems.

If virtual terminals are allowed on your system, use the SET TERMINAL/DISCONNECT/PERMANENT command to enable the virtual terminal characteristic for a particular physical terminal. When you enable this characteristic, a virtual terminal is created when a user logs in to the physical terminal. The physical terminal is connected to the virtual terminal, which is in turn connected to the process.

For new virtual terminals, you must first set the TT2$V_DISCONNECT bit in the TTY_DEFCHAR2 system parameter and reboot the system. This is done by creating the virtual device VTA0: using the ttdriver. For example, on Alpha:

$ MCR SYSMAN IO CONNECT/NOADAPTER - _$ /DRIVER=SYS$LOADABLE_IMAGES:SYS$TTDRIVER VTA0:

On VAX:

$ MCR SYSGEN CONNECT /NOADAPTER/DRIVER=TTDRIVER VTA0:

When the connection between the physical terminal and the virtual terminal is broken, you are logged out of your current process (and any images that the process is executing stop running) unless you have specified the /NOLOGOUT qualifier.

If you have specified the /NOLOGOUT qualifier, the process remains connected to the virtual terminal. If the process is executing an image, it continues until the process needs terminal input or attempts to write to the terminal. At that point, the process waits until the physical terminal is reconnected to the virtual terminal.

You can connect to a virtual terminal even if you are not currently using a virtual terminal; however, to log out of your current process you must use the CONNECT command with the /LOGOUT qualifier. If you connect to a virtual terminal from another virtual terminal, you can save your current process by using the /NOLOGOUT qualifier.

Qualifiers

/CONTINUE

/NOCONTINUE (default)

Controls whether the CONTINUE command is executed in the current process just before connecting to another process. This qualifier allows an interrupted image to continue processing after you connect to another process.

The /CONTINUE qualifier is incompatible with the /LOGOUT qualifier.

/LOGOUT (default)

/NOLOGOUT

Logs out your current process when you connect to another process using a virtual terminal.

When you enter the CONNECT command from a process that is not connected to a virtual terminal, you must specify the /LOGOUT qualifier; otherwise, DCL displays an error message.

The /LOGOUT qualifier is incompatible with the /CONTINUE qualifier.

Examples

$ RUN AVERAGE
[Ctrl/Y]
$ CONNECT/CONTINUE VTA72
      

In this example, you use the RUN command to execute the image AVERAGE.EXE. You enter this command from a terminal that is connected to a virtual terminal. Next, you press Ctrl/Y to interrupt the image. After you interrupt the image, enter the CONNECT command with the /CONTINUE qualifier. This operation issues the CONTINUE command, so the image continues to run and connects you to another virtual terminal. You can reconnect to the process later.

$ SHOW USERS/FULL
     VAX/VMS User Processes at 22-DEC-2001 14:11:56.91
   Total number of users = 51,  number of processes = 158

Username    Node   Process Name       PID     Terminal
KIDDER     BUKETT  KIDDER           29A0015E  FTA3:
KIDDER     BUKETT  _FTA4:           29A0015F  FTA4:
KIDDER     RACEY1  KIDDER           05800062  FTA5:
KIDDER     RACEY1  DECW$MWM         0580005D  MBA44:   Disconnected
KIDDER     RACEY1  DECW$SESSION     05800059
KIDDER     RACEY1  VUE$KIDDER_2     0580005E  (subprocess of 05800059)
KIDDER     RACEY1  VUE$KIDDER_3     0580005F  MBA51:   Disconnected
KIDDER     RACEY1  VUE$KIDDER_4     05800060  MBA53:   Disconnected
SMITH      BUKETT  SMITH            29A002C1  FTA7:
SMITH      BUKETT  SMITH_1          29A006C2  (subprocess of 29A002C1)
SMITH      BUKETT  SMITH_2          29A00244  (subprocess of 29A002C1)
SMITH      HAMLET  SMITH            24800126  FTA6:
SMITH      HAMLET  DECW$BANNER      24800155  (subprocess of 24800126)
SMITH      HAMLET  DECW$MWM         2480011F  MBA170:  Disconnected
SMITH      HAMLET  DECW$SESSION     2480011D  FTA5:
.
.
.

$ CONNECT VTA273
  SMITH         logged out at 22-DEC-2001 14:12:04.53
$
      

This example shows how to reconnect to your original process after you have lost the carrier signal. First, you must log in again and create a new process. After you log in, enter the SHOW USERS/FULL command to determine the virtual terminal name for your initial process. Then enter the CONNECT command to connect to the virtual terminal associated with your original process. The process from which you enter the CONNECT command is logged out because you have not specified any qualifiers.

When you reconnect to the original process, you continue running the image that you were running when you lost the carrier signal. In this example, the user SMITH was at interactive level when the connection was broken.

Resumes execution of a DCL command, a program, or a command procedure that was interrupted by pressing Ctrl/Y or Ctrl/C. You cannot resume execution of the image if you have entered a command that executes another image or if you have invoked a command procedure.

Format

CONTINUE

Parameters

None.

Description

The CONTINUE command enables you to resume processing an image or a command procedure that was interrupted by pressing Ctrl/Y or Ctrl/C. You cannot resume execution of the image if you have entered a command that executes another image or if you have invoked a command procedure; however, you can use CONTINUE after commands that do not execute separate images. For a list of these commands, refer to the OpenVMS User's Manual.

You can abbreviate the CONTINUE command to a single letter, C.

The CONTINUE command serves as the target command of an IF or ON command in a command procedure. The CONTINUE command is also a target command when it follows a label that is the target of a GOTO command. In addition, you can use the CONTINUE command to resume processing of a program that has executed either a VAX Fortran PAUSE statement or a VAX COBOL-74 STOP literal statement.

Examples

$ RUN MYPROGRAM_A
[Ctrl/Y]
$ SHOW TIME
  14-DEC-2001 13:40:12
$ CONTINUE

      

In this example, the RUN command executes the program MYPROGRAM_A. While the program is running, pressing Ctrl/Y interrupts the image. The SHOW TIME command requests a display of the current date and time. The CONTINUE command resumes the image.

$ ON SEVERE_ERROR THEN CONTINUE
      

In this example, the command procedure statement requests the command interpreter to continue executing the procedure if any warning, error, or severe error status value is returned from the execution of a command or program. This ON statement overrides the default action, which is to exit from a procedure following errors or severe errors.