 |
HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
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
HP 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.
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 software 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
and refer to the HP OpenVMS System Management Utilities Reference Manual.
|
For a complete description of PPPD, refer to TCP/IP Networking on OpenVMS Systems (available
on the Documentation CD-ROM).
For detailed information about the asynchronous (ASN) and PPP device
drivers that support this utility, refer to 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, refer to the
OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/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, refer to the
OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time).
/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
HP 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 Return. 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 HP. 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.
|
If you want the /FLAG qualifier to apply to individual files in a
multifile job, place the qualifier directly after each file that you
want to have a flag page.
Use the /[NO]FLAG qualifier to override the /DEFAULT=[NO]FLAG option
that has been set for the output queue you are using. The /[NO]FLAG
qualifier does not override the /SEPARATE=[NO]FLAG option 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 the file.
/FORM=form
Specifies the name or number of the form to be associated with the
print job. If you omit the /FORM qualifier, the default form for the
execution queue is associated with the job.
Forms have attributes such as print image width and length or paper
stock, which the print symbiont associates with a job when the job is
processed. To see which forms have been defined for your system, use
the SHOW QUEUE/FORM command. To find out which form is mounted
currently on a particular queue and which form is specified as that
queue's default form, use the SHOW QUEUE/FULL command.
The stock of the form associated with the job must match the stock of
the form mounted on the execution queue on which you want the job to be
processed. If the stocks do not match, the job remains pending until
one or more of the following occurs:
- A form with the same stock as the job's form is mounted on the
queue (using, for example, the SET QUEUE/FORM_MOUNTED command).
- A form with the same stock as the queue's mounted form is specified
with the job (using, for example, the SET ENTRY/FORM command).
- The job is moved to a queue on which the stock of the mounted form
matches the stock of the job's form (using, for example, the SET
ENTRY/REQUEUE command).
- The job is deleted (using, for example, the DELETE/ENTRY command).
/HEADER
/NOHEADER (default)
Positional qualifier.
Controls whether a heading line is printed at the top of each page.
/HOLD
/NOHOLD (default)
Controls whether a job is available for printing immediately. The /HOLD
qualifier holds the job until released by a SET ENTRY/RELEASE or SET
ENTRY/NOHOLD command.
/IDENTIFY (default)
/NOIDENTIFY
Displays the job name, queue name, entry number, and status of the job
when it is queued.
/JOB_COUNT=n
Prints the job n times. The value of the parameter n
can be from 1 to 255 and defaults to 1.
/LOWERCASE
/NOLOWERCASE (default)
Indicates whether the print job must be printed on a printer that can
print both lowercase and uppercase letters. The /NOLOWERCASE qualifier
means that files can be printed on printers supporting only uppercase
letters. If all available printers can print both uppercase and
lowercase letters, you do not need to specify the /LOWERCASE qualifier.
/MODIFIED
/NOMODIFIED
Modifies the time value specified with the /BEFORE or the /SINCE
qualifier. The /MODIFIED qualifier selects files according to the dates
on which they were last modified. This qualifier is incompatible with
the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to
select files according to time attributes. If you specify none of these
four time modifiers, the default is the /CREATED qualifier.
/NAME=job-name
Names the job. The name consists of 1 to 39 alphanumeric characters. If
characters other than alphanumerics, underscores (_), or dollar signs
($) are used in the name, enclose the name in quotation marks ("
"). The default is the name of the first (or only) file in the
job. The job name appears in the SHOW ENTRY and SHOW QUEUE command
display and is printed on the flag page for the job.
/NOTE=string
Specifies a message string of up to 255 characters to appear on the
flag page of the job.
/NOTIFY
/NONOTIFY (default)
Controls whether a message is broadcast to your terminal session when
the job is printed or aborted.
/OPERATOR=string
Specifies a message of up to 255 characters to be sent to the operator
when the job begins to print.
/PAGES=([lowlim,]uplim)
Positional qualifier.
|
