OpenVMS DCL Dictionary

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. See 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 (i.e. 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

Some aspects of DCL function differently in the context of a pipeline.

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 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, see the OpenVMS Guide to System Security.

Examples

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

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

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

$ PIPE COPY LARGE_FILE.DAT REMOTE"user password"::[DESTINATION]*.*  &

This PIPE command creates a background process to handle the copying of the large file.

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

$ PIPE SHOW SYSTEM | SEARCH SYS$INPUT HIB

This example uses the pipeline function to identify all hibernating processes on the system in one command.

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

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

$ more :== TYPE/PAGE=SAVE SYS$INPUT 
$ PIPE    ANA/RMS PAGE.TXT | more 
 
Check RMS File Integrity                  26-JAN-1996 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-1996 16:08:50.05 
    Revision Date:   26-NOV-1996 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.

PPPD

Invokes the Point-to-Point Protocol utility (PPPD) that you can use to initiate and manage an Internet Protocol (IP) network connection over an asynchronous, serial data line. PPPD extends the networking capability of OpenVMS Alpha by enabling you to do the following:

Establish temporary, high-speed network connections between remote hosts. This includes both dial-in capability from a remote host to an OpenVMS Alpha host and dial-out capability from an OpenVMS Alpha host to a remote system or server box that supports the Point-to-Point Protocol (PPP).
Establish permanent, low-speed network connections between local hosts, such as between a laptop computer and an Alpha workstation connected by a serial data line.
Set and display communication characteristics, such as address compression, flow control, and line speed.
Note
This utility is enabled by your TCP/IP provider during the network registration process. If you receive one of the following error messages, contact your system administrator to verify whether PPPD is currently available on your network.
%PPPD-E-PPPNOTAVAIL, point-to-point driver is not installed %PPPD-E-NOTREG, network protocol has not been registered

For information about network registration, see the SET NETWORK command.
For a complete description of PPPD, see TCP/IP Networking on OpenVMS Systems. For detailed information about the asynchronous (ASN) and PPP device drivers that support this utility, see the documentation contained in the files PPP_INTERFACES.PS and PPP_INTERFACES.TXT located in the SYS$SYSROOT:[SYSHLP.EXAMPLES.PPPD.DOC] directory.

Format

PPPD [subcommand]...

PRINT

Queues one or more files for printing to an output queue.
Requires read (R) access to the file and submit (S) access to the queue.
To specify functions unique to particular print symbionts, use the /PARAMETERS qualifier.

Format

PRINT filespec[,...]

PARAMETER

filespec[,...]
Specifies one or more files to be printed. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the directory specification, file name, file type, and version number fields. The default file type is that of the preceding file. If no previous file specification contains an explicit file type, the default file type is .LIS.
If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+).
If you specify a node name, you must use the /REMOTE qualifier.

DESCRIPTION

The PRINT command places the specified files in an output queue for printing. By default, this queue is SYS$PRINT. All files queued by a single PRINT command are processed serially as one job. By default, the name of the print job is the name of the first file specified in the PRINT command.
The system assigns a unique entry number to each print job in the queue. When you enter the PRINT command, by default, the system displays the job name, the queue name, the entry number, and the job status.
The system automatically creates or updates the local symbol $ENTRY when a PRINT or SUBMIT command is completed successfully. The value of $ENTRY is a string that identifies the entry number of the most recently queued job. If you want to refer to a job's entry number later, store the value of $ENTRY in another symbol.
After you queue a print job, the version of the file submitted is printed, even if a newer version of the file is created before the print job runs. Also, another file with the same name and version number as the file queued cannot be substituted for the file that was queued.

QUALIFIERS

/AFTER=time

/NOAFTER
Holds the job until the specified time. The time can be specified as absolute time or a combination of absolute and delta times. If the specified time has passed, the job is queued for printing immediately.
For complete information on specifying time values, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.
/BACKUP

/NOBACKUP
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/BEFORE[=time]

/NOBEFORE
Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information on specifying time values, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help.
/BURST[=keyword]

/NOBURST
Positional qualifier.
Controls whether two file flag pages with a burst bar between them are printed preceding a file. If the /BURST qualifier is specified between the PRINT command and the file specifications, it can take either of the following keywords:

ALL Prints the flag pages and a burst bar before each file in the job.

ONE Prints the flag pages and a burst bar before the first file in the job.

If you want the /BURST qualifier to apply to individual files in a multifile job, place the qualifier directly after each file that you want to have the flag pages and a burst bar.
Use the /[NO]BURST qualifier to override the /DEFAULT options that have been set for the output queue you are using. The /[NO]BURST qualifier does not override the /SEPARATE options set for the queue.
When you specify the /BURST qualifier for a file, the /[NO]FLAG qualifier does not add or subtract a flag page from the two flag pages that are printed preceding a file.

/BY_OWNER[=uic]

/NOBY_OWNER
Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.
Specify the UIC by using standard UIC format as described in the OpenVMS Guide to System Security.
/CHARACTERISTICS=(characteristic[,...])
Specifies the name or number of one or more characteristics to be associated with the job. Characteristics can refer to such things as color of ink. If you specify only one characteristic, you can omit the parentheses.
A characteristic's number must range from 0 to 127. To see which characteristics have been defined for your system, use the SHOW QUEUE/CHARACTERISTICS command. To see which characteristics are associated with a particular queue, use the SHOW QUEUE/FULL command.
A print job can be processed on an execution queue if the job's characteristics are a subset of the queue's characteristics. However, if any of the characteristics associated with the job are not associated with the queue, the job remains pending until one or more of the following occurs:

The characteristics specified with the queue are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET QUEUE/CHARACTERISTICS command).
The characteristics specified with the job are changed to make the job's characteristics a subset of the queue's characteristics (using, for example, the SET ENTRY/CHARACTERISTICS command).
The job is moved to a queue on which all the job's characteristics have been specified (using, for example, the SET ENTRY/REQUEUE command).
The job is deleted (using, for example, the DELETE/ENTRY command).

/CONFIRM

/NOCONFIRM (default)
Controls whether a request is issued before each file is queued for printing to confirm that the operation should be performed on that file. The following responses are valid:

YES NO QUIT

TRUE FALSE Ctrl/Z

1 0 ALL

[Return]

You can use any combination of uppercase and lowercase letters for word responses. Word responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing the Return key. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process, but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.

/COPIES=n
Positional qualifier.
Specifies the number of copies to print. The value of the parameter n can be from 1 to 255 and defaults to 1. If you place the /COPIES qualifier after the PRINT command name, each file in the parameter list is printed the specified number of times. If you specify the /COPIES qualifier following a file specification, only that file is printed the specified number of times.
/CREATED (default)

/NOCREATED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/DELETE

/NODELETE (default)
Positional qualifier.
Controls whether files are deleted after printing. If you place the /DELETE qualifier after the PRINT command name, all specified files are deleted. If you specify the /DELETE qualifier after a file specification, only that file is deleted after it is printed.
The protection applied to the file must allow delete (D) access for the life of the job. You need to have delete access when you submit the job and delete access when the system deletes your file at the end of the job.
/DEVICE=queue-name[:]
Places the print job in the specified queue (rather than the default queue SYS$PRINT). This qualifier is synonymous with the /QUEUE qualifier, except that the /DEVICE qualifier is reserved for special use by Digital. Its usage, therefore, is not recommended.
/EXCLUDE=(filespec[,...])

/NOEXCLUDE
Excludes the specified files from the print operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification. However, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.
/EXPIRED

/NOEXPIRED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.

/FEED

/NOFEED
Positional qualifier.
Controls whether form feeds are inserted into the print job when the printer reaches the bottom margin of the form in use. You can suppress this automatic form feed (without affecting any of the other carriage control functions that are in place) by using the /NOFEED qualifier. The /[NO]FEED qualifier does not affect user-formatted files and can be used to override the installation-defined defaults that have been set for the output queue you are using.
/FLAG[=keyword]

/NOFLAG
Positional qualifier.
Controls whether a file flag page is printed preceding a file. The flag page contains the name of the user submitting the job, the job entry number, and other information about the file being printed. If the /FLAG qualifier is positioned between the PRINT command and the file specifications, it can take either of the following keywords:

ALL Prints a file flag page before each file in the job.

ONE Prints a file flag page before the first file in the job.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  9996P033.HTM
  OSSG Documentation
  26-NOV-1996 11:17:50.04
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

ALL	Prints the flag pages and a burst bar before each file in the job.
ONE	Prints the flag pages and a burst bar before the first file in the job.

ALL	Prints a file flag page before each file in the job.
ONE	Prints a file flag page before the first file in the job.