 |
OpenVMS DCL Dictionary
PATCH (VAX Only)
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
PHONE
Invokes the Phone utility, which lets you communicate with other users
on your system or any other system connected to your system by DECnet
for OpenVMS.
For more information about the Phone utility, refer to the
OpenVMS User's Manual or online help.
Format
PHONE [phone-command]
PIPE
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.
The return status of the PIPE command is the return status of the last
executed command sequence. Each command sequence sets the global symbol
$STATUS with a returned value after it finishes execution.
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.
When SYS$ERROR is redirected, the redirected error file is only created
when the command sequence actually writes to the SYS$ERROR during
execution, and there is no existing file with the same name as the
redirected error file. If a file with the same name as the redirected
error file already exists, that file is opened as the redirected error
file. The error output generated by this command sequence is then
appended to the end of the redirected error file. (This behavior is the
same as using the DEFINE or ASSIGN command to redefine SYS$ERROR in
supervisor mode.)
Pipelines and TEEs
This section describes aspects of DCL that function differently in the
context of a pipeline.
Some of the following constructs are used in the implementation of a
TEE.
Using SYS$COMMAND
The SYS$COMMAND of a subprocess is normally the same as its SYS$INPUT
(if no command procedures are involved). In a pipeline, however, the
SYS$COMMAND of a subprocess is set to the SYS$COMMAND of the parent
process instead of to the preceding pipe (which is the SYS$INPUT of the
pipeline-segment command).
Using TEEs and SYS$PIPE
In most cases, input from the pipe can be obtained by reading the data
from SYS$INPUT; however, when a command procedure is invoked as a
pipeline segment command, SYS$INPUT is redirected to the command
procedure file. To obtain data from the pipe inside a command
procedure, the logical SYS$PIPE can be used.
The following is an example of a pipeline DCL application TEE.COM:
$ ! TEE.COM - command procedure to display/log data flowing through
$ ! a pipeline
$ ! Usage: @TEE log-file
$
$ OPEN/WRITE tee_file 'P1'
$ LOOP:
$ READ/END_OF_FILE=EXIT SYS$PIPE LINE
$ WRITE SYS$OUTPUT LINE ! Send it out to the next stage of the pipeline
$ WRITE tee_file LINE ! Log output to the log file
$ GOTO LOOP
$ EXIT:
$ CLOSE tee_file
$ EXIT
|
The PIPE command to use TEE.COM can be:
$ PIPE SHOW SYSTEM | @TEE showsys.log | SEARCH SYS$INPUT LEF
|
The command procedure TEE.COM is used to log the data flowing through
the pipeline. It reads in the data from SYS$PIPE instead of SYS$INPUT.
Image Verification in a Pipeline
In a pipeline, image verification is turned off by default, even when
the command SET VERIFY=IMAGE is executed before the PIPE command is
entered. This prevents duplication of data records going through the
pipeline.
To turn on image verification in a pipeline, an explicit SET
VERIFY=IMAGE command must precede the pipeline segment command. You can
use a subshell to do this, as follows:
$ PIPE ... | (SET VERIFY=IMAGE ; ...) | ...
|
File Access Methods in a Pipeline
A pipeline segment command can only use the RMS sequential file access
method to read and write to the pipes. Certain OpenVMS utilities may
access their input and output files using methods other than sequential
access. These operations are not supported in a pipeline, and will
fail, as in the following example:
$ PIPE CC/NOOBJ/NOLIS TEST.C | SEARCH SYS$INPUT/WIND=(1,1) "%cc-w-"
%SEARCH-F-RFAERR, RMS error using RFA access
-RMS-F-RAC, invalid record access mode
|
In this example, the /WINDOW qualifier for the SEARCH command requires
the relative file access method.
Qualifiers
/LOGICAL_NAMES (default)
/NOLOGICAL_NAMES
Copies process logical names and logical name tables to the subprocess
of a command sequence. By default, all process logical names and
logical name tables are copied to the subprocess except those
explicitly marked CONFINE or created in executive or kernel mode.
/PRIVILEGES={CURRENT|AUTHORIZED}
Determines whether the subprocess inherits the current process's
current or authorized privileges as its authorized privileges. By
default, the authorized privilege mask for the subprocess is taken from
the current privileges of its creator. (This corresponds to
/PRIVILEGES=CURRENT.) If the /PRIVILEGES=AUTHORIZED qualifier is
specified, the subprocess's authorized privileges are taken from the
creator's authorized privileges.
/SYMBOLS (default)
/NOSYMBOLS
Determines whether global and local symbols (except $RESTART,
$SEVERITY, and $STATUS) are passed to the subprocess. $RESTART,
$SEVERITY, and $STATUS symbols are never passed to the subprocess.
/TRUSTED
/NOTRUSTED
Indicates that the PIPE command input originates in a trusted command
procedure. PIPE commands are not allowed in CAPTIVE accounts. The
/TRUSTED qualifier provides a way for properly written captive command
procedures to perform PIPE operations when the command input originates
in the captive command procedure where it can be trusted. For more
information about trusted command procedures, refer to the
OpenVMS Guide to System Security.
Examples
| #1 |
$ PIPE SHOW SYSTEM | SEARCH SYS$INPUT HIB
|
This example uses the pipeline function to identify all hibernating
processes on the system in one command.
| #2 |
$ PIPE RUN TEST | SORT/SPECIFICATION=TEST.SRT SYS$INPUT SYS$OUTPUT -
| DIFF SYS$INPUT TEST.BENCHMARK
|
This example uses the pipeline function to run a test, sort the result,
and compare the result to the benchmark file in a single command
without generating unnecessary intermediate files.
| #3 |
$ PIPE ( SET DEF WRK$:[WORK] ; RUN REPORT ) | MAIL SYS$INPUT SMITH
|
This example shows one way a subshell can be specified as a pipe
segment command in a pipeline.
| #4 |
$ more :== TYPE/PAGE=SAVE SYS$INPUT
$ PIPE ANA/RMS PAGE.TXT | more
Check RMS File Integrity 26-DEC-2001 16:12:00.06 Page 1
SYS$SYSDEVICE:[TEST]PAGE.TXT;2
FILE HEADER
File Spec: SYS$SYSDEVICE:[TEST]PAGE.TXT;2
File ID: (4135,58220,0)
Owner UIC: [PIPE]
Protection: System: RWED, Owner: RWED, Group: RE, World:
Creation Date: 26-NOV-2001 16:08:50.05
Revision Date: 26-NOV-2001 16:09:09.06, Number: 1
Expiration Date: none specified
Backup Date: none posted
Contiguity Options: none
Performance Options: none
Reliability Options: none
Journaling Enabled: none
RMS FILE ATTRIBUTES
RETURN/SPACE=More, PREV/NEXT=Scroll, INS/REM=Pan, SELECT=80/132, Q=Quit
|
This example shows the use of the /PAGE qualifier within a pipeline.
The /PAGE function exists in a number of other DCL commands as well,
and can be used similarly in conjunction with the PIPE command to form
other useful tools.
| #5 |
$ ! TEE.COM - command procedure to display/log data flowing through
$ ! a pipeline
$ ! Usage: @TEE log-file
$
$ OPEN/WRITE tee_file 'P1'
$ LOOP:
$ READ/END_OF_FILE=EXIT SYS$PIPE LINE
$ WRITE SYS$OUTPUT LINE ! Send it out to next stage of the pipeline
$ WRITE tee_file LINE ! Log output to the log file
$ GOTO LOOP
$ EXIT:
$ CLOSE tee_file
$ EXIT
|
This is an example of a pipeline DCL application TEE.COM.
The PIPE command to use TEE.COM can be:
$ PIPE SHOW SYSTEM | @TEE showsys.log | SEARCH SYS$INPUT LEF
|
The command procedure TEE.COM is used to log the data flowing through
the pipeline. It reads in the data from SYS$PIPE instead of SYS$INPUT.
| #6 |
$ CD_WORK :== PIPE SAVE_DIR=F$DIRECTORY() ; SET DEFAULT FOO:[WORK]
$ BACK :== SET DEF 'SAVE_DIR'
$
$ CD_WORK ! Switch to working directory
$ :
$ :
$ BACK ! Switch back to home directory
$ GET_RECORD :== PIPE READ/END_OF_FILE=CLEANUP IN RECORD ; -
F$EDIT(RECORD, "COMPRESS, TRIM")
$
$ OPEN IN EMPLOYEE.DAT
$ LOOP:
$ GET_RECORD
$ :
$ :
$ GOTO LOOP
$
$ CLEAN_UP:
$ :
|
This example shows two simple uses of multiple commands with symbol
definitions to build useful tools in command procedures.
| #7 |
$ PIPE cc foo.c && link foo, sys$library:vaxcrtl.olb/lib
|
If the compilation does not generate any error, the object file is
linked to produce an executable image. If the program compilation
generates an error, the linking step is skipped.
| #8 |
$
$ PIPE RUN COLLECT_DATA.EXE || GOTO CLEAN_UP
$ :
$ :
$ EXIT
$
$ CLEAN_UP:
$ :
$ :
|
Using conditional command execution, it is easy to set up simple error
handling control flow in a command procedure. If the image COLLECT_DATA
fails, control is directed to CLEAN_UP.
| #9 |
$ PIPE COPY LARGE_FILE.DAT REMOTE"user password"::[DESTINATION]*.* &
|
This PIPE command creates a background process to handle the copying of
the large file.
| #10 |
$ PIPE (SET DEF [.DATA_DIR] ; BACKUP DATA.SAV/SAV [...]) ; RUN FOO
|
The subshell command sequence is done in a subprocess. This means that
changing a process-specific characteristic (for example, the default
directory) will not affect the current process after the subshell is
finished. In this example, the save set is restored in a subdirectory
to provide the necessary data to run the program FOO.
|
