HP OpenVMS DCL Dictionary
HP OpenVMS DCL Dictionary
ASSIGN/QUEUE
Assigns, or redirects, a logical queue to a single execution queue. The
ASSIGN/QUEUE command can be used only with printer or terminal queues.
Requires manage (M) access to both queues.
Format
ASSIGN/QUEUE queue-name[:] logical-queue-name[:]
Parameters
queue-name[:]
Specifies the name of the execution queue. The queue cannot be a
logical queue, a generic queue, or a batch queue.
logical-queue-name[:]
Specifies the name of the logical queue.
Description
The ASSIGN/QUEUE command sets up a one-to-one correspondence between a
logical queue and an execution queue. Jobs submitted to the logical
queue are always queued to the specified execution queue for eventual
printing.
When you enter the ASSIGN/QUEUE command, the logical queue cannot be
running.
Once you initialize a logical queue, use the ASSIGN/QUEUE command to
associate the logical queue with an existing execution queue. You must
perform the following tasks to set up a logical queue:
- Initialize the logical queue with the INITIALIZE/QUEUE command. (Do
not use the /START qualifier.)
- Assign the logical queue name to an existing execution queue.
- Start the logical queue with the START/QUEUE command.
After you enter the START/QUEUE command for the logical queue, jobs can
be sent to the logical queue for processing.
Examples
| #1 |
$ INITIALIZE/QUEUE/DEFAULT=FLAG=ONE/START LPA0
$ INITIALIZE/QUEUE TEST_QUEUE
$ ASSIGN/QUEUE LPA0 TEST_QUEUE
$ START/QUEUE TEST_QUEUE
|
This example first initializes and starts the printer queue LPA0. The
LPA0 queue is set to have a flag page precede each job. The second
INITIALIZE/QUEUE command creates the logical queue TEST_QUEUE. The
ASSIGN/QUEUE command assigns the logical queue TEST_QUEUE to the
printer queue LPA0. The START/QUEUE command starts the logical queue.
| #2 |
$ INITIALIZE/QUEUE/START LPB0
|
The ASSIGN/QUEUE command is not needed in this example because a
logical queue is not being initialized. A printer queue is being
initialized; LPB0 is the name of a line printer. After you enter the
INITIALIZE/QUEUE/START command, jobs can be queued to LPB0 for printing.
ATTACH
Transfers control from your current process (which then hibernates) to
the specified process.
The ATTACH and SPAWN commands cannot be used if your terminal
has an associated mailbox.
Format
ATTACH [process-name]
Parameter
process-name
Specifies the name of a parent process or spawned subprocess to which
control passes. The process must already exist, be part of your current
job, and share the same input stream as your current process. However,
the process cannot be your current process or a subprocess created with
the /NOWAIT qualifier.
Process names can contain from 1 to 15 alphanumeric characters. If a
connection to the specified process cannot be made, an error message is
displayed.
The process-name parameter is incompatible with the
/IDENTIFICATION qualifier.
Description
The ATTACH command allows you to connect your input stream to another
process. You can use the ATTACH command to change control from one
subprocess to another subprocess or to the parent process.
When you enter the ATTACH command, the parent or "source"
process is put into hibernation, and your input stream is connected to
the specified destination process. You can use the ATTACH command to
connect to a subprocess that is part of a current job left hibernating
as a result of the SPAWN/WAIT command or another ATTACH command as long
as the connection is valid. (No connection can be made to the current
process, to a process that is not part of the current job, or to a
process that does not exist. If any of these connections are attempted,
an error message is displayed.)
You can also use the ATTACH command in conjunction with the SPAWN/WAIT
command to return to a parent process without terminating the created
subprocess. See the description of the SPAWN command for more details.
Qualifier
/IDENTIFICATION=pid
Specifies the process identification (PID) of the process to which
terminal control will be transferred. Leading zeros can be omitted. The
/IDENTIFICATION qualifier is incompatible with the
process-name parameter.
If you omit the /IDENTIFICATION qualifier, you must specify a process
name.
Examples
The ATTACH command transfers the terminal's control to the subprocess
JONES_2.
| #2 |
$ ATTACH/IDENTIFICATION=30019
|
The ATTACH command switches control from the current process to a
process having the PID 30019. Notice that because the /IDENTIFICATION
qualifier is specified, the process-name parameter is omitted.
BACKUP
Invokes the Backup utility (BACKUP) to perform one of the following
backup operations:
- Make copies of disk files.
- Save disk files as data in a file created by BACKUP on disk or
magnetic tape. (Files created by BACKUP are called save sets.)
- Restore disk files from a BACKUP save set.
- Compare disk files or files in a BACKUP save set with other disk
files.
- List information about files in a BACKUP save set to an output
device or file.
You cannot invoke BACKUP to back up a system disk; a system disk must
be bootstrapped to run.
For more information about BACKUP and backing up the system disk, refer
to the HP OpenVMS System Manager's Manual and the HP OpenVMS System Management Utilities Reference Manual or online help.
Format
BACKUP input-specifier output-specifier
CALL
Transfers control to a labeled subroutine within a command procedure.
Format
CALL label [parameter [...]]
Parameters
label
Specifies a label of 1 to 255 alphanumeric characters that appears as
the first item on a command line. A label cannot contain embedded
blanks. When the CALL command is executed, control passes to the
command following the specified label.
The label can precede or follow the CALL statement in the current
command procedure. A label in a command procedure must be terminated
with a colon (:). Labels for subroutines must be unique.
Labels declared in inner procedure levels are inaccessible from outer
levels, as in the following example:
$CALL B
$A: SUBROUTINE
$ B: SUBROUTINE
$ ENDSUBROUTINE
$ENDSUBROUTINE
|
In this example, the label B in subroutine A is inaccessible from the
outer procedure level.
parameter [...]
Specifies from one to eight optional parameters to pass to the command
procedure. Use quotation marks (" ") to specify a null
parameter. The parameters assign character string values to the symbols
named P1, P2, and so on in the order of entry, to a maximum of eight.
The symbols are local to the specified command procedure. Separate each
parameter with one or more spaces.
You can specify a parameter with a character string value containing
alphanumeric or special characters, with the following restrictions:
- The command interpreter converts alphabetic characters to uppercase
and uses blanks to delimit each parameter. To pass a parameter that
contains embedded blanks or lowercase letters, enclose the parameter in
quotation marks (" ").
- If the first parameter begins with a slash (/), you must enclose
the parameter in quotation marks.
- To pass a parameter that contains quotation marks and spaces,
enclose the entire string in quotation marks and use two sets of
quotation marks within the string. For example:
$ CALL SUB1 "Never say ""quit"""
|
When control transfers to SUB1, the parameter P1 is equated to the
following string:
If a string contains quotation marks and does not contain spaces,
the quotation marks are preserved in the string and the letters within
the quotation marks remain in lowercase. For example:
When control transfers to SUB2, the parameter P1 is equated to the
string:
To use a symbol as a parameter, enclose the symbol in single quotation
marks (` ') to force symbol substitution. For example:
$ NAME = "JOHNSON"
$ CALL INFO 'NAME'
|
The single quotation marks cause the value "JOHNSON" to be
substituted for the symbol `NAME'. Therefore, the parameter
"JOHNSON" is passed as P1 to the subroutine INFO.
Description
The CALL command transfers control to a labeled subroutine within a
command procedure. The CALL command is similar to the @ (execute
procedure) command in that it creates a new procedure level. The
advantage of the CALL command is that it does not require files to be
opened and closed to process the procedure. Using the CALL command also
makes managing a set of procedures easier because they can all exist in
one file rather than in several files.
When you use the CALL command to transfer control to a subroutine, a
new procedure level is created and the symbols P1 to P8 are assigned
the values of the supplied arguments. Execution then proceeds until an
EXIT command is encountered. At this point, control is transferred to
the command line following the CALL command.
Procedures can be nested to a maximum of 32 levels, which includes any
combination of command procedure and subroutine calls. Local symbols
and labels defined within a nested subroutine structure are treated the
same way as if the routines had been invoked with the @ command; that
is, labels are valid only for the subroutine level in which they are
defined.
Local symbols defined in an outer subroutine level are available to any
subroutine levels at an inner nesting level; that is, the local symbols
can be read, but they cannot be written to. If you assign a value to a
symbol that is local to an outer subroutine level, a new symbol is
created at the current subroutine level. However, the symbol in the
outer procedure level is not modified.
The SUBROUTINE and ENDSUBROUTINE commands define the beginning and end
of a subroutine. The label defining the entry point to the subroutine
must appear either immediately before the SUBROUTINE command or on the
same command line.
A subroutine can have only one entry point. The subroutine must begin
with the SUBROUTINE command as the first executable statement. If an
EXIT command is not specified in the procedure, the ENDSUBROUTINE
command functions as an EXIT command.
The SUBROUTINE command performs two different functions depending on
the context in which it is executed. If executed as the result of a
CALL command, it initiates a new procedure level, defines the
parameters P1 to P8 as specified in the CALL statement, and begins
execution of the subroutine. If the SUBROUTINE verb is encountered in
the execution flow of the procedure without having been invoked by a
CALL command, all the commands following the SUBROUTINE command are
skipped until the corresponding ENDSUBROUTINE command is encountered.
Note
The SUBROUTINE and ENDSUBROUTINE commands cannot be abbreviated to
fewer than 4 characters.
|
Qualifier
/OUTPUT=filespec
Writes all output to the file or device specified. By default, the
output is written to the current SYS$OUTPUT device and the output file
type is .LIS. System responses and error messages are written to
SYS$COMMAND as well as to the specified file. If you specify /OUTPUT,
the qualifier must immediately follow the CALL command. The asterisk
(*) and the percent sign (%) wildcard characters are not allowed in the
output file specification.
You can also redefine SYS$OUTPUT to redirect the output from a command
procedure. If you place the following command as the first line in a
command procedure, output will be directed to the file you specify:
$ DEFINE SYS$OUTPUT filespec
|
When the procedure exits, SYS$OUTPUT is restored to its original
equivalence string. This produces the same result as using the /OUTPUT
qualifier when you execute the command procedure.
Example
|
$
$! CALL.COM
$
$! Define subroutine SUB1
$!
$ SUB1: SUBROUTINE
.
.
.
$ CALL SUB2 !Invoke SUB2 from within SUB1
.
.
.
$ @FILE !Invoke another procedure command file
.
.
.
$ EXIT
$ ENDSUBROUTINE !End of SUB1 definition
$!
$! Define subroutine SUB2
$!
$ SUB2: SUBROUTINE
.
.
.
$ EXIT
$ ENDSUBROUTINE !End of SUB2 definition
$!
$! Start of main routine. At this point, both SUB1 and SUB2
$! have been defined but none of the previous commands have
$! been executed.
$!
$ START:
$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS P1"
.
.
.
$ CALL SUB2 "THIS IS P1" "THIS IS P2"
.
.
.
$ EXIT !Exit this command procedure file
|
The command procedure in this example shows how to use the CALL command
to transfer control to labeled subroutines. The example also shows that
you can call a subroutine or another command file from within a
subroutine.
The CALL command invokes the subroutine SUB1, directing output to the
file NAMES.LOG and allowing other users write (W) access to the file.
The subroutine SUB2 is called from within SUB1. The procedure executes
SUB2 and then uses the @ (execute procedure) command to invoke the
command procedure FILE.COM.
When all the commands in SUB1 have executed, the CALL command in the
main procedure calls SUB2 a second time. The procedure continues until
SUB2 has executed.
CANCEL
Cancels wakeup requests for a specified process, including wakeup
requests scheduled with either the RUN command or the $SCHDWK system
service.
Requires one of the following:
- Ownership of the process
- GROUP privilege to cancel scheduled wakeup requests for
processes in the same group but not owned by you
- WORLD privilege to cancel scheduled wakeup requests for any
process in the system
Format
CANCEL [[node-name::]process-name]
Parameters
node-name::
The name of the node on which the specified process is running.
You cannot specify a node name on a different OpenVMS Cluster system
from the current process.
process-name
The name of the process for which wakeup requests are to be canceled.
The process name can have up to 15 alphanumeric characters.
The specified process must be in the same group as the current process.
Description
The CANCEL command cancels scheduled wakeup requests for the specified
process.
The CANCEL command does not delete the specified process. If the
process is executing an image when the CANCEL command is issued for it,
the process hibernates instead of exiting after the image completes
execution.
To delete a hibernating process for which wakeup requests have been
canceled, use the STOP command. You can determine whether a subprocess
has been deleted by entering the SHOW PROCESS command with the
/SUBPROCESSES qualifier.
A local process name can look like a remote process name. Therefore, if
you specify ATHENS::SMITH, the system checks for a process named
ATHENS::SMITH on the local node before checking node ATHENS for a
process named SMITH.
You also can use the /IDENTIFICATION=pid qualifier to specify a process
name. If you use the /IDENTIFICATION qualifier and the
process-name parameter together, the qualifier overrides the
parameter. If you do not specify either the process-name
parameter or the /IDENTIFICATION qualifier, the CANCEL command cancels
scheduled wakeup requests for the current (that is, the issuing)
process.
Qualifier
/IDENTIFICATION=pid
Identifies the process by its process identification (PID). You can
omit leading zeros when you specify the PID.
Examples
The CANCEL command in this example cancels a wakeup request for a
process named CALENDAR (which continues to hibernate until it is
deleted with the STOP command).
| #2 |
$ RUN/SCHEDULE=14:00 STATUS
%RUN-S-PROC_ID, identification of created process is 0013012A
.
.
.
$ CANCEL/IDENTIFICATION=13012A
|
The RUN command in this example creates a process to execute the image
STATUS. The process hibernates and is scheduled to be awakened at
14:00. Before the process is awakened, the CANCEL command cancels the
wakeup request.
| #3 |
$ RUN/PROCESS_NAME=LIBRA/INTERVAL=1:00 LIBRA
%RUN-S-PROC_ID, identification of created process is 00130027
.
.
.
$ CANCEL LIBRA
$ STOP LIBRA
|
The RUN command in this example creates a subprocess named LIBRA to
execute the image LIBRA.EXE at hourly intervals.
Subsequently, the CANCEL command cancels the wakeup request. The
process continues to exist, but in a state of hibernation, until the
STOP command deletes it.
CLOSE
Closes a file opened with the OPEN command and deassigns the associated
logical name.
Format
CLOSE logical-name[:]
Parameter
logical-name[:]
Specifies the logical name assigned to the file when it was opened with
the OPEN command.
Description
Files that are opened for reading or writing at the command level
remain open until closed with the CLOSE command, or until the process
terminates. If a command procedure that opens a file terminates without
closing the open file, the file remains open; the command interpreter
does not automatically close it.
Qualifiers
/DISPOSITION=option
Specifies what action to take when the file is closed. The options are:
|
DELETE
|
Delete the file.
|
|
KEEP (default)
|
Keep the file.
|
|
PRINT
|
Print the file.
|
|
SUBMIT
|
Submit the file.
|
/ERROR=label
Specifies a label in the command procedure to receive control if the
close operation results in an error. Overrides any ON condition action
specified. If an error occurs and the target label is successfully
given control, the global symbol $STATUS retains the code for the error
that caused the error path to be taken.
/LOG (default)
/NOLOG
Generates a warning message when you attempt to close a file that was
not opened by DCL. If you specify the /ERROR qualifier, the /LOG
qualifier has no effect. If the file has not been opened by DCL, the
error branch is taken and no message is displayed.
Examples
| #1 |
$ OPEN/READ INPUT_FILE TEST.DAT
$ READ_LOOP:
$ READ/END_OF_FILE=NO_MORE INPUT_FILE DATA_LINE
.
.
.
$ GOTO READ_LOOP
$ NO_MORE:
$ CLOSE INPUT_FILE
|
The OPEN command in this example opens the file TEST.DAT and assigns it
the logical name of INPUT_FILE. The /END_OF_FILE qualifier on the READ
command requests that, when the end-of-file (EOF) is reached, the
command interpreter should transfer control to the line at the label
NO_MORE. The CLOSE command closes the input file.
| #2 |
$ @READFILE
[Ctrl/Y]
$ STOP
$ SHOW LOGICAL/PROCESS
.
.
.
"INFILE" = "_DB1"
"OUTFILE" = "_DB1"
$ CLOSE INFILE
$ CLOSE OUTFILE
|
In this example, pressing Ctrl/Y interrupts the execution of the
command procedure READFILE.COM. Then, the STOP command stops the
procedure. The SHOW LOGICAL/PROCESS command displays the names that
currently exist in the process logical name table. Among the names
listed are the logical names INFILE and OUTFILE, assigned by OPEN
commands in the procedure READFILE.COM.
The CLOSE commands close these files and deassign the logical names.
|
