OpenVMS DCL Dictionary
The APPEND command appends the files A.DAT and B.MEM to the file C.DAT,
which must already exist.
| #4 |
$ APPEND/LOG A.* B.*
%APPEND-S-APPENDED, USE$:[MAL]A.DAT;5 appended to USE$:[MAL]B.DAT;1 (5 records)
%APPEND-S-APPENDED, USE$:[MAL]A.DOC;2 appended to USE$:[MAL]B.DAT;1 (1 record)
|
Both the input and output file specifications contain wildcard
characters in the file type field. The APPEND command appends each file
with a file name of A to an existing file with B as its file name. The
file type of the first input file located determines the output file
type.
| #5 |
$ APPEND BOSTON"BILL_BESTON YANKEE"::DEMO1.DAT, DEMO2.DAT
$ _To: DALLAS::DISK1:[MODEL.TEST]TEST.DAT
|
This APPEND command adds the contents of the files DEMO1.DAT and
DEMO2.DAT at remote node BOSTON to the end of the file TEST.DAT at
remote node DALLAS.
ASSIGN
Creates a logical name and assigns an equivalence string, or a list of
strings, to the specified logical name. If you specify an existing
logical name, the new equivalence name replaces the existing
equivalence name.
Format
ASSIGN equivalence-name[,...] logical-name[:]
Parameters
equivalence-name[,...]
Specifies a character string of 1 to 255 characters. Defines the
equivalence name, usually a file specification, device name, or other
logical name, to be associated with the logical name in the specified
logical name table. If the string contains other than uppercase
alphanumeric, dollar sign ($), or underscore (_) characters, enclose it
in quotation marks (" "). Use two sets of quotation marks
("" "") to denote an actual quotation mark within
the string. Specifying more than one equivalence name for a logical
name creates a search list.
When you specify an equivalence name that will be used as a file
specification, you must include the punctuation marks (colons (:),
brackets ([]), and periods (.)) that would be required if the
equivalence name were used directly as a file specification. Therefore,
if you specify a device name as an equivalence name, terminate the
device name with a colon.
The ASSIGN command allows you to assign the same logical name to more
than one equivalence name. When you specify more than one equivalence
name for a logical name, you create a search list. For more information
on search lists, refer to the OpenVMS User's Manual.
logical-name[:]
Specifies the logical name string, which is a character string
containing up to 255 characters. You choose a logical name to represent
the equivalence name in the specified logical name table.
If the string contains other than uppercase alphanumeric, dollar sign,
or underscore characters, enclose it in quotation marks. Use two sets
of quotation marks to denote an actual quotation mark. If you terminate
the logical-name parameter with a colon, the system removes the colon
before placing the name in a logical name table. (This differs from the
DEFINE command, which saves the colon.) If the logical name is to be
entered into the process directory (LNM$PROCESS_DIRECTORY) or system
directory (LNM$SYSTEM_DIRECTORY) logical name tables, then the name may
only have from 1 to 31 alphanumeric characters (including the dollar
sign and underscore). By default, the logical name is placed in the
process logical name table.
If the logical name contains any characters other than alphanumeric
characters, the dollar sign, or the underscore, enclose the name in
quotation marks. If the logical name contains quotation marks, enclose
the name in quotation marks and use two sets of quotation marks in the
places where you want one set of quotation marks to occur. Note that if
you enclose a name in quotation marks, the case of alphabetic
characters is preserved.
Description
The ASSIGN command creates an entry in a logical name table by defining
a logical name to stand for one or more equivalence names. An
equivalence name can be a device name, another logical name, a file
specification, or any other string.
To specify the logical name table where you want to enter a logical
name, use the /PROCESS, /JOB, /GROUP, /SYSTEM, or /TABLE qualifier. If
you enter more than one of these qualifiers, only the last one entered
is accepted. If you do not specify a table, the default is
/TABLE=LNM$PROCESS (or /PROCESS).
To specify the access mode of the logical name you are creating, use
the /USER_MODE, /SUPERVISOR_MODE, or /EXECUTIVE_MODE qualifier. If you
enter more than one of these qualifiers, only the last one entered is
accepted. If you do not specify an access mode, then a supervisor-mode
name is created. You can create a logical name in the same mode as the
table in which you are placing the name or in an outer mode. (User mode
is the outermost mode; executive mode is the innermost mode.)
You can enter more than one logical name with the same name in the same
logical name table, as long as each name has a different access mode.
(However, if an existing logical name within a table has the NO_ALIAS
attribute, you cannot use the same name to create a logical name in an
outer mode in this table.)
If you create a logical name with the same name, in the same table, and
in the same mode as an existing name, the new logical name assignment
replaces the existing assignment.
You can also use the DEFINE command to create logical names. To delete
a logical name from a table, use the DEASSIGN command.
Note
Avoid assigning a logical name that matches the file name of an
executable image in SYS$SYSTEM:. Such an assignment will prohibit you
from invoking that image.
|
For additional information on creating and using logical names, refer
to the OpenVMS User's Manual.
Qualifiers
/EXECUTIVE_MODE
Requires SYSNAM (system logical name) privilege.
Creates an executive-mode logical name. If you specify executive mode,
but do not have SYSNAM privilege, a supervisor-mode logical name is
created. The mode of the logical name must be the same as or external
to (less privileged than) the mode of the table in which you are
placing the name.
/GROUP
Requires SYSPRV (system privilege) or GRPNAM (group logical
name) privilege.
Places the logical name in the group logical name table. Other users
who have the same group number in their user identification codes
(UICs) can access the logical name. The /GROUP qualifier is synonymous
with the /TABLE=LNM$GROUP qualifier.
/JOB
Places the logical name in the jobwide logical name table. All
processes within the same job tree as the process creating the logical
name can access the logical name. The /JOB qualifier is synonymous with
the /TABLE=LNM$JOB qualifier.
/LOG (default)
/NOLOG
Displays a message when a new logical name supersedes an existing name.
/NAME_ATTRIBUTES[=(keyword[,...])]
Specifies the attributes for a logical name. By default, no attributes
are set. You can specify the following keywords for attributes:
|
CONFINE
|
Does not copy the logical name into a spawned subprocess; this keyword
is relevant only for logical names in a private table.
|
|
NO_ALIAS
|
Prohibits creation of logical names with the same name in an outer
(less privileged) access mode within the specified table. If another
logical name with the same name and an outer access mode already exists
in this table, the name is deleted.
|
If you specify only one keyword, you can omit the parentheses. Only the
attributes you specify are set.
/PROCESS (default)
Places the logical name in the process logical name table. The /PROCESS
qualifier is synonymous with the /TABLE=LNM$PROCESS qualifier.
/SUPERVISOR_MODE (default)
Creates a supervisor-mode logical name in the specified table.
/SYSTEM
Requires SYSNAM (system logical name) or SYSPRV (system
privilege) privilege.
Places the logical name in the system logical name table. All system
users can access the logical name. The /SYSTEM qualifier is synonymous
with the /TABLE=LNM$SYSTEM qualifier.
/TABLE=name
Requires write (W) access to the table if the table is
shareable.
Specifies the logical name table in which the logical name is to be
entered. You can use the /TABLE qualifier to specify a user-defined
logical name table (created with the CREATE/NAME_TABLE command); to
specify the process, job, group, or system logical name tables; or to
specify the process or system logical name directory tables.
If you specify the table name using a logical name that has more than
one translation, the logical name is placed in the first table found.
For example, if you specify ASSIGN/TABLE=LNM$FILE_DEV and LNM$FILE_DEV
is equated to LNM$PROCESS, LNM$JOB, LNM$GROUP, and LNM$SYSTEM, then the
logical name is placed in LNM$PROCESS.
If you do not explicitly specify the /TABLE qualifier, the default is
the /TABLE=LNM$PROCESS qualifier.
/TRANSLATION_ATTRIBUTES[=(keyword[,...])]
Equivalence-name qualifier.
Specifies attributes of the equivalence-name parameter. Possible
keywords are as follows:
|
CONCEALED
|
Indicates that the equivalence string is the name of a concealed device.
When a concealed device name is defined, the system displays the
logical name, rather than the equivalence string, in messages that
refer to the device. If you specified the CONCEALED attribute, then the
equivalence string must be a physical device name.
|
|
TERMINAL
|
Indicates that the equivalence string should not be translated
iteratively; logical name translation should terminate with the current
equivalence string.
|
If you specify only one keyword, you can omit the parentheses. Only the
attributes you specify are set.
Note that different equivalence strings of the same logical name can
have different translation attributes specified.
/USER_MODE
Creates a user-mode logical name in the specified table.
If you specify a user-mode logical name in the process logical name
table, that logical name is used for the execution of a single image
only; user-mode entries are deleted from the logical name table when
any image executing in the process exits; that is, after any DCL
command that executes an image or user program completes execution.
Also, user-mode logical names are automatically deleted when invoking
and exiting a command procedure.
Examples
| #1 |
$ ASSIGN $DISK1:[CREMERS.MEMOS] MEMOSD
|
The ASSIGN command in this example equates the partial file
specification $DISK1:[CREMERS.MEMOS] to the logical name MEMOSD.
| #2 |
$ ASSIGN/USER_MODE $DISK1:[FODDY.MEMOS]WATER.TXT TM1
|
The ASSIGN command in this example equates the logical name TM1 to a
file specification. After the next image runs, the logical name is
deassigned automatically.
| #3 |
$ ASSIGN XXX1:[HEROLD] ED
$ PRINT ED:TEST.DAT
Job 274 entered on queue SYS$PRINT
|
The ASSIGN command in this example associates the logical name ED with
the directory name [HEROLD] on the disk XXX1. Subsequent references to
the logical name ED result in the correspondence between the logical
name ED and the disk and directory specified. The PRINT command queues
a copy of the file XXX1:[HEROLD]TEST.DAT to the system printer.
| #4 |
$ ASSIGN YYY2: TEMP:
$ SHOW LOGICAL TEMP
"TEMP" = "YYY2:" (LNM$PROCESS_TABLE)
$ DEASSIGN TEMP
|
The ASSIGN command in this example equates the logical name TEMP to the
device YYY2. TEMP is created in supervisor mode and placed in the
process logical name table. The SHOW LOGICAL command verifies that the
logical name assignment was made. Note that the logical name TEMP was
terminated with a colon in the ASSIGN command, but that the command
interpreter deleted the colon before placing the name in the logical
name table. Thus, you can specify TEMP without a colon in the
subsequent DEASSIGN command. You should omit the colon in the SHOW
LOGICAL command (for example, SHOW LOGICAL TEMP).
| #5 |
$ MOUNT TTT1: MASTER TAPE
$ ASSIGN TAPE:NAMES.DAT PAYROLL
$ RUN PAYROLL
.
.
.
|
The MOUNT command in this example establishes the logical name TAPE for
the device TTT1, which has the volume labeled MASTER mounted on it. The
ASSIGN command equates the logical name PAYROLL with the file named
NAMES.DAT on the logical device TAPE. Thus, an OPEN request in a
program referring to the logical name PAYROLL results in the
correspondence between the logical name PAYROLL and the file NAMES.DAT
on the tape whose volume label is MASTER.
| #6 |
$ CREATE/NAME_TABLE TABLE1
$ ASSIGN/TABLE=LNM$PROCESS_DIRECTORY TABLE1,-
_$ LNM$PROCESS,LNM$JOB,LNM$GROUP,LNM$SYSTEM LNM$FILE_DEV
$ ASSIGN/TABLE=TABLE1 -
_$ /TRANSLATION_ATTRIBUTES=CONCEALED DKA1: WORK_DISK
|
The CREATE/NAME_TABLE command in this example creates the process
private logical name table TABLE1.
The first ASSIGN command ensures that TABLE1 is searched first in any
logical name translation of a file specification or device name
(because TABLE1 is the first item in the equivalence string for the
logical name LNM$FILE_DEV, which determines the default search sequence
of logical name tables whenever a device or file specification is
translated).
The second ASSIGN command assigns the logical name WORK_DISK to the
physical device DKA1, and places the name in TABLE1. The logical name
has the concealed attribute. Therefore, the logical name WORK_DISK will
be displayed in system messages.
| #7 |
$ ASSIGN/TABLE=LNM$PROCESS/TABLE=LNM$GROUP DKA0: SYSFILES
$ SHOW LOGICAL SYSFILES
"SYSFILES" = "DKA0:" (LNM$GROUP_000240)
|
The ASSIGN command in this example contains conflicting qualifiers.
When you specify conflicting qualifiers, the ASSIGN command uses the
last qualifier specified. The response from the SHOW LOGICAL command
indicates that the name was placed in the group logical name table.
| #8 |
$ ASSIGN/TABLE=LNM$GROUP 'F$TRNLNM("SYS$COMMAND")' TERMINAL
%DCL-I-SUPERSEDE, previous value of TERMINAL has been superseded
|
The ASSIGN command in this example uses the lexical function F$TRNLNM
to translate the logical name SYS$COMMAND and use the result as the
equivalence name for the logical name TERMINAL. The message from the
ASSIGN command indicates that an entry for the logical name TERMINAL
already existed in the group logical name table, and that the new entry
has replaced the previous one.
If this command is used in a LOGIN.COM file, the entry for TERMINAL
will be redefined at the beginning of each terminal session. The
current process and any subprocesses it creates can execute images that
use the logical name TERMINAL to write messages to the current terminal
device.
| #9 |
$ ASSIGN DALLAS::DMA1: DATA
|
The ASSIGN command in this example associates the logical name DATA
with the device specification DMA1 on remote node DALLAS. Subsequent
references to the logical name DATA result in references to the disk on
the remote node.
| #10 |
$ CREATE AVERAGE.COM
$ ASSIGN/USER_MODE SYS$COMMAND: SYS$INPUT
$ EDIT/EDT AVERAGE.FOR
$ FORTRAN AVERAGE
$ LINK AVERAGE
$ RUN AVERAGE
87
80
90
9999
$ EXIT
[Ctrl/Z]
$ @AVERAGE.COM
|
The CREATE command in this example creates the command procedure
AVERAGE.COM. Then the command procedure is executed.
The command procedure uses the ASSIGN command with the /USER_MODE
qualifier to change temporarily the value of SYS$INPUT. When the EDT
editor is invoked, it accepts input from the terminal. This allows you
to create or modify the program AVERAGE.FOR interactively.
When you exit from EDT, SYS$INPUT is reassigned to its original value
(the input stream provided by the command procedure). Thus, when the
program AVERAGE.FOR is ready to accept input, it looks for that input
in the command procedure.
ASSIGN/MERGE
Removes all jobs from one queue and merges them into another existing
queue. This command does not affect jobs that are executing.
Requires manage (M) access to both queues.
Format
ASSIGN/MERGE target-queue[:] source-queue[:]
Parameters
target-queue[:]
Specifies the name of the queue into which the jobs are being merged.
source-queue[:]
Specifies the name of the queue from which the jobs are being removed.
Description
The ASSIGN/MERGE command removes the pending jobs in one queue and
places them in another queue. This command does not affect any
executing jobs in either the target queue or the source queue. Jobs
currently running in the source queue complete in that queue. This
command is generally used with printer queues, although it can be used
with batch queues.
The ASSIGN/MERGE command is particularly useful when a line printer
malfunctions. By entering the ASSIGN/MERGE command, you can reroute
existing jobs to a different printing device. To perform the merge
operation without losing or disrupting any jobs, stop the source queue
with the STOP/QUEUE/NEXT command. Then enter the STOP/QUEUE/REQUEUE
command to ensure that the current job on the source queue is requeued
for processing on the target queue. (If the STOP/QUEUE/REQUEUE command
fails to requeue the job, use the STOP/QUEUE/RESET command to regain
control of the queue.) Once you enter the STOP commands, enter the
ASSIGN/MERGE command.
Example
|
$ STOP/QUEUE/NEXT LPB0
$ STOP/QUEUE/REQUEUE=LPA0 LPB0
$ ASSIGN/MERGE LPA0 LPB0
|
In this example, the STOP/QUEUE/NEXT command prevents another job from
executing on queue LPB0. The STOP/QUEUE/REQUEUE command requeues the
current job running on LPB0 to the target queue LPA0. The ASSIGN/MERGE
command removes the remaining jobs from the LPB0 printer queue and
places them in the LPA0 printer queue.
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 OpenVMS System Manager's Manual and the 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.
|
