HP OpenVMS Systems Documentation

A Ctrl/Y action can be specified for each active command level; the Ctrl/Y action specified for the currently executing command level overrides actions specified for previous levels.

Examples

$ ON SEVERE_ERROR THEN CONTINUE
      

A command procedure that contains this statement continues to execute normally when a warning or error occurs during execution. When a severe error occurs, the ON statement signals the procedure to execute the next statement anyway. Once the statement has been executed as a result of the severe error condition, the default action (ON ERROR THEN EXIT) is reinstated.

$ ON ERROR THEN GOTO BYPASS
$ RUN A
$ RUN B
   .
   .
   .
$ EXIT
$ BYPASS:
$      RUN C

      

If either program A or program B returns a status code with a severity level of error or severe error, control is transferred to the statement labeled BYPASS and program C is run.

$ ON WARNING THEN EXIT
   .
   .
   .
$ SET NOON
$ RUN [SSTEST]LIBRA
$ SET ON
   .
   .
   .

      

The ON command requests that the procedure exit when any warning, error, or severe error occurs. Later, the SET NOON command disables error checking before executing the RUN command. Regardless of any status code returned by the program LIBRA.EXE, the procedure continues. The next command, SET ON, reenables error checking and reestablishes the most recent ON condition.

$ ON CONTROL_Y THEN GOTO CTRL_EXIT
   .
   .
   .
$ CTRL_EXIT:
$ CLOSE INFILE
$ CLOSE OUTFILE
$ EXIT

      

The ON command specifies action to be taken when Ctrl/Y is pressed during the execution of this procedure: the GOTO command transfers control to the line labeled CTRL_EXIT. At CTRL_EXIT, the procedure performs cleanup operations (in this example, closing files and exiting).

Opens a file for reading, writing, or both; assigns a logical name to a file; and places the name in the process logical name table.

See the qualifier descriptions for restrictions.

Format

OPEN logical-name[:] filespec

Parameters

logical-name[:]

Specifies the logical name and a character string to be assigned to the file.

filespec

Specifies the name of the file or device being opened for input or output. The file type defaults to DAT. The asterisk (*) and the percent sign (%) wildcard characters are not allowed.

To create a new, sequential file, specify the /WRITE qualifier. See the description of the /WRITE qualifier for more information.

Description

A file can be opened for either reading or writing, or for both reading and writing. After the file is opened, it is available for input or output at the command level with the READ and WRITE commands.

The OPEN command opens files as process permanent. Therefore, these files remain open until you close them with the CLOSE command, or until you log out. If a command procedure that opens a file terminates without closing an open file, the file remains open; the command interpreter does not automatically close it. The OPEN command uses OpenVMS RMS to open files, and is subject to RMS restrictions on using process-permanent files. The OPEN command opens sequential, relative, or indexed sequential files.

The logical devices SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR do not have to be opened explicitly before they can be read or written at the command level. All other files must be opened explicitly.

Do not use the same logical name when you open different files. If you specify a logical name with the OPEN command and the logical name is currently assigned to another file, no warning message is issued; however, the file is not opened, and the next READ request will access the file to which the logical name was originally assigned.

You can enter more than one OPEN command for the same file and assign it different logical names if you use the /SHARE qualifier the first time the file is opened. Also, if you open the file by using the /SHARE=READ or the /SHARE=WRITE qualifier, other users can access the file with the TYPE or the SEARCH command.

When you use the OPEN command to create a new file, variable fixed control (VFC) record format is used. Concatenating a file of this record format with a file of another record format might be impossible due to record format incompatibilities. To avoid the VFC format, use the CREATE command to create the file.

When the OPEN command is specified on an existing file, the record type of that file is used.

Qualifiers

/APPEND

Opens an existing file for writing and positions the record pointer at the end-of-file (EOF). New records are added to the end of the file.

Only sequential files allow more than one user to append records concurrently.

Use the /APPEND qualifier only to add records to an existing file. The /APPEND and the /WRITE qualifiers are mutually exclusive.

/ERROR=label

Transfers control to the location specified by the label keyword (in a command procedure) if the open operation results in an error. The error routine specified for this qualifier overrides any ON condition action specified. If the /ERROR qualifier is not specified, the current ON condition action is taken.

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.

/READ (default)

Opens the file for reading. If you open a file with /READ, other users are also allowed read access to the file, but no user is allowed write access. If you open a file with /READ/WRITE, no other users are allowed access while the file is open. If you specify the /READ qualifier without the /WRITE qualifier, you must specify an existing file.

/SHARE[=option]

Opens the specified file as a shareable file to allow other users read or write access. If you specify the /SHARE=READ qualifier, other users are allowed read (R) access to the file, but not write (W) access. If you specify the /SHARE=WRITE or the /SHARE qualifier with no option, users are allowed read and write access to the specified file.

To open a file with no shared access, specify OPEN/READ/WRITE.

/WRITE

Opens the file for writing. The following restrictions apply to the /WRITE qualifier:

• Use the /WRITE qualifier to open and create a new, sequential file. If the file specification on an OPEN/WRITE command does not include a file version number, and if a file with the specified file name and file type already exists, a new file with a version number one greater than the existing file is created.
• Use the /READ qualifier with the /WRITE qualifier to open an existing file. While the file is open, no other user will have access to it. When the file is first opened, the pointer is positioned to the beginning of the file. (This differs from OPEN/APPEND, which positions the pointer at the end of the file.) You cannot use OPEN/READ/WRITE to create a new file.
• The /WRITE and the /APPEND qualifiers are mutually exclusive.

Examples

$ OPEN INPUT_FILE AVERAGE.DAT
$ READ_LOOP:
$ READ/END_OF_FILE=ENDIT  INPUT_FILE  NUM
   .
   .
   .
$ GOTO READ_LOOP
$ ENDIT:
$ CLOSE INPUT_FILE
      

The OPEN command opens the file named AVERAGE.DAT as an input file and assigns it the logical name INPUT_FILE. The file is opened with read access because the /READ qualifier is present by default. The READ command reads a record from the logical file INPUT_FILE into the symbol named NUM. The procedure executes the lines between the labels READ_LOOP and ENDIT until the end of the file is reached. At the end of the file, the CLOSE command closes the file.

$ OPEN/WRITE/ERROR=OPEN_ERROR  OUTPUT_FILE  TEMP.OUT
$ COUNT = 0
$ WRITE_LOOP:
$ COUNT = COUNT + 1
$ IF COUNT .EQ. 11 THEN GOTO ENDIT
$ WRITE OUTPUT_FILE "Count is ''COUNT'."
   .
   .
   .
$ GOTO WRITE_LOOP
$ ENDIT:
$ CLOSE OUTPUT_FILE
$ EXIT
$
$ OPEN_ERROR:
$ WRITE SYS$OUTPUT "Cannot open file TEMP.OUT"
$ EXIT
      

The OPEN command with the /WRITE qualifier creates the file TEMP.OUT and assigns it the logical name OUTPUT_FILE. TEMP.OUT is a sequential file.

The /ERROR qualifier specifies that if any error occurs while opening the file, the command interpreter should transfer control to the line at the label OPEN_ERROR. The command procedure writes records to the file TEMP.OUT until the symbol COUNT equals 11.

$ OPEN/READ INPUT_FILE TRNTO::DKA0:[COST]INVENTORY.DAT
$ READ_LOOP:
$ READ/END_OF_FILE=ENDIT  INPUT_FILE  NUM
$ FIRST_CHAR = F$EXTRACT(0,1,NUM)
$ WRITE SYS$OUTPUT FIRST_CHAR
$ GOTO READ_LOOP
$ ENDIT:
$ CLOSE INPUT_FILE
      

This command procedure opens the file INVENTORY.DAT located at remote node TRNTO as an input file, and assigns it the logical name INPUT_FILE. The READ command reads a record from the logical file INPUT_FILE into the symbol named NUM. The next two commands extract the first character from the record and write the character to the SYS$OUTPUT device. These two steps occur for all records in the file until the procedure reaches the end-of-file (EOF). At this point, the CLOSE command closes the file and deassigns the logical name INPUT_FILE.

Provides the password associated with the user name that you specify with the JOB card when you submit a batch job through a card reader. Although the PASSWORD card is required, the password on the card is optional if the account has a null password.

The PASSWORD command is valid only in a batch job submitted through a card reader and requires that a dollar sign ($) precede the PASSWORD command on the card.

Format

PASSWORD [password]

Parameter

password

Specifies the password associated with the user name specified with the JOB command. The password can be 1 to 31 characters long.

If you are submitting the job from an account with a null password, omit the password specifier on the PASSWORD card.

Description

The PASSWORD command is used in conjunction with the JOB command. The JOB card identifies the user submitting the batch job through a card reader and is followed by a PASSWORD card giving the password. The password is checked by the system to verify that it matches the password associated with the user name on the JOB card. If the passwords do not match, the job is rejected.

Note that you might want to suppress printing when you originally keypunch the PASSWORD card to prohibit other users from seeing the password when the PASSWORD card is in use.

Example

The JOB and PASSWORD commands precede a batch job submitted from the card reader. An EOJ command marks the end of the job.

On VAX, invokes the Patch utility, which patches an executable image, a shareable image, or a device driver image.

For more information about the Patch utility, refer to the OpenVMS VAX Patch Utility Manual (available on the Documentation CD-ROM) or online help.

Format

PATCH filespec

Invokes the Phone utility, which lets you communicate with other users on your system or any other system connected to your system by DECnet-Plus or DECnet for OpenVMS.

For more information about the Phone utility, refer to the OpenVMS User's Manual or online help.

Format

PHONE [phone-command]

Executes one or more DCL command strings from the same command line. The PIPE command enables you to perform UNIX style command processing, such as command pipelining, input/output redirection, and conditional and background execution.

Format

PIPE command-sequence [separator command-sequence]...

Parameter

command-sequence

A DCL command, a pipeline, or a subshell:

• DCL command
  A DCL command string, which can include qualifiers, parameters, keywords, and values.
• Pipeline
  A pipeline is a sequence of pipeline-segment commands connected by pipes, represented by the vertical-bar (|) separator. A pipeline-segment command is a DCL command that appears in a pipeline. The pipe connects the SYS$OUTPUT of one pipeline-segment command to the SYS$INPUT of the next command. The format of a pipeline is as follows:

  pipeline-segment-command | pipeline-segment-command [|...]

• Subshell
  A subshell is one or more command sequences separated by separators and enclosed in parentheses. The format of a subshell is as follows:

  (command-sequence [separator command-sequence]...)

Input/output redirection is allowed in a command sequence. The command before an angle bracket (> or <) redefines its SYS$INPUT, SYS$OUTPUT, or SYS$ERROR during execution. You cannot use angle brackets (<>) to represent a directory specification in a PIPE command because the PIPE command interprets angle brackets as input/output redirection syntax.

separator

Determines the processing action of the command sequences specified in a PIPE command. The valid PIPE separators are described in Table DCLII-14.

Table DCLII-14 PIPE Command Separators

Separator	Action
|	Key pipe separator. The pipe connects the SYS$OUTPUT of one pipeline-segment command to the SYS$INPUT of the next command.
;	Sequential execution. The command sequence following the semicolon (;) is executed after the preceding command sequence is completed. You must precede this separator with a blank space; otherwise, it is parsed as the Record Management System (RMS) file specification version number delimiter.
&&	Conditional execution (upon success). The command sequence following the double ampersand (&&) is executed only if the preceding command sequence succeeds.
||	Conditional execution (upon failure). The command sequence following the double vertical bar (||) is executed only if the preceding command sequence fails.
&	Background execution. All command sequences that precede the ampersand (&) are executed asynchronously in a subprocess environment. The & separator is similar to the SPAWN/NOWAIT command. Note: Any ampersand that precedes a character string without spaces in between is parsed as a conventional DCL symbol substitution expression rather than the background execution syntax.
@TEE	Command file, TEE.COM. Used for redirecting output to two targets (for example, one output is directed to the next stage in pipeline, and the other to a file). See the Examples section for an example of how to use TEE.COM.

In a PIPE command line, the "&" has the highest precedence, followed by "|", ";", "&&", and "||", which have equal precedence.

Description

The PIPE command allows you to perform UNIX style command processing by executing multiple DCL commands in a single command line. You can use the PIPE command to execute DCL commands in a number of ways:

• Multiple command execution
  Multiple DCL commands are specified in a single PIPE command and executed sequentially. The syntax for multiple command execution is as follows:

  PIPE command-sequence ; command-sequence [; command-sequences]...

• Conditional command execution
  A command sequence is executed conditionally depending on the execution result of the preceding command sequence.
  Using the following form, command-sequence2 executes if, and only if, command-sequence1 succeeds:

  PIPE command-sequence1 && command-sequence2

  
  Using the following form, command-sequence2 executes if, and only if, command-sequence1 fails:

  PIPE command-sequence1 || command-sequence2

• Pipeline command execution
  A pipeline is formed by connecting DCL commands with pipes as follows:

  PIPE pipeline-segment-command | pipeline-segment-command [|...]

  
  Each pipeline-segment command runs in a separate subprocess with its SYS$OUTPUT connected to the SYS$INPUT of the next pipeline-segment command. These subprocesses execute in parallel; however, they are synchronized to the extent that each pipeline-segment command, except the first, reads the standard output of its predecessor as its standard input. A pipeline finishes execution when the last pipeline-segment command is done.
  It is very common to use filter applications in a pipeline. A filter application is a program that takes data from SYS$INPUT, transforms it in a specific way, and writes it to SYS$OUTPUT.

• Subshell execution
  Command sequences can be executed in a subprocess environment by using the subshell execution form:

  PIPE ( command-sequence [separator command-sequence]... )

  
  The command sequences in a subshell are executed in a subprocess environment. DCL waits for the subshell to complete before executing the next command sequence. The ( ) separator is similar to the SPAWN/WAIT command.

• Background execution
  Command sequences can be executed in a subprocess environment by using the following form:

  PIPE command-sequence [ separator command-sequence]... &

  
  DCL does not wait for the command sequences to finish. Control passes back to DCL once the background subprocess is created.

• Input/output redirection
  A command sequence can redirect its SYS$INPUT, SYS$OUTPUT, or SYS$ERROR to a file during execution of the command as follows:
  To redirect SYS$INPUT:

  PIPE command-sequence < redirected-input-file

  
  To redirect SYS$OUTPUT:

  PIPE command-sequence > redirected-output-file

  
  To redirect SYS$ERROR:

  PIPE command-sequence 2> redirected-error-file

  
  A pipeline-segment command can also redirect its SYS$INPUT, SYS$OUTPUT, or SYS$ERROR; however, SYS$OUTPUT redirection is allowed only for the last pipeline-segment command, and SYS$INPUT redirection is allowed only for the first pipeline-segment command.

You can interrupt a PIPE command by pressing Ctrl/Y. If the PIPE command is executing in a pipeline or a subshell command sequence, the command sequence and the PIPE command are deleted. In this case, a CONTINUE command entered immediately after the interrupt will not resume the execution of the PIPE command.

If the PIPE command is executing a command sequence other than a subshell or a pipeline command sequence, DCL behaves as if the command sequence were entered as a DCL command without the PIPE command verb and interrupted by Ctrl/Y. Refer to the OpenVMS User's Manual for more information on the Ctrl/Y interrupt.

Each command sequence sets the global symbol $STATUS with a returned value after it finishes execution. The return status of the PIPE command is the return status of the last command performed in the last segment. If all segments fail with some kind of error and the last segment returns with success, the status returned to DCL is the success.

When a PIPE command is executed in a command procedure with the ON condition processing, the conditional execution of command sequences (&&, ||) takes precedence over the action previously specified by the ON condition statement.

DCL Command Restrictions

The PIPE command creates a special execution context for its command sequences. The following DCL commands either do not work or exhibit new behavior in this context:

• PIPE --- Nested PIPE commands in the same command procedure level are not allowed. There can only be one PIPE command context for each command procedure level; however, nested PIPE commands at different procedure levels are allowed. For example:

  $ TYPE FOO.COM $ ! FOO.COM $ : $ PIPE ... $ : $ $ PIPE @FOO.COM ; ...

  
  In this example, the PIPE command inside FOO.COM is allowed because it is executed at a different command procedure level.
• GOTO and EXIT --- These two commands, when executed as PIPE command sequences, delete the PIPE command context before the GOTO or EXIT command is executed. Any command sequences following these two commands in a PIPE command are flushed.
• STOP --- The STOP command, when executed after a PIPE command is interrupted by Ctrl/Y, deletes the PIPE command context.
• THEN, ELSE, ENDIF, SUBROUTINE, ENDSUBROUTINE, RETURN, and DCL labels --- These commands cannot execute as PIPE command sequences because it is not possible to realize their functions in a PIPE command context.

Improving Subprocess Performance

A PIPE command can generate a number of subprocesses during execution. Often, the applications invoked by command sequences do not depend on the process logical names and symbol names. In this case, the spawning of subprocesses can be accelerated by using the /NOLOGICAL_NAMES and /NOSYMBOLS qualifiers, which suppress the passing of process logical names and symbols to the subprocesses created by the PIPE command.

Input/Output Redirection

DCL users can use the DEFINE or ASSIGN command to redirect SYS$INPUT, SYS$OUTPUT, or SYS$ERROR. Such redirection can be created as either the user-mode (using the /USER_MODE qualifier) or supervisor-mode (using the /SUPERVISOR_MODE qualifier) redirection. A user-mode redirection only affects the environment of the next user-mode image.

In a PIPE command, redirection can be achieved by using the redirection syntax. A PIPE command redirection is quite different from that created by the DEFINE or ASSIGN command, as follows:

• Redirections are created in supervisor mode. This means that both user-mode applications and DCL commands are affected by the redirections.
• The redirected environment only applies to the command sequence or the pipeline-segment command that specifies the redirection syntax. After the execution of the command sequence or pipeline-segment command, the original process input/output environment (that is, SYS$INPUT, SYS$OUTPUT, and SYS$ERROR) is restored before command execution continues.

When SYS$OUTPUT is redirected, the redirected output file is always created, whether or not the command sequence actually writes to SYS$OUTPUT. If a version of a file with the same name as the redirected output file already exists, a new version of that file is created. (This behavior is the same as using the DEFINE or ASSIGN command to redefine SYS$OUTPUT in supervisor mode.) Note that the redirected file is created before the command sequence is executed. If the redirected file is also used in the command sequence, the operation may fail, as in the following example:

$ PIPE SEARCH TRANS.LOG "alpha" > TRANS.LOG %SEARCH-W-OPENIN, error opening TRANS.LOG;2 as input -RMS-E-FLK, file currently locked by another user

In this example, a new version of TRANS.LOG is created and opened for write access; the SEARCH command then tries to get read access to the most recent version of TRANS.LOG instead of the expected previous version.

---

Previous

Next

Contents

Index