OpenVMS DCL Dictionary

Document revision date: 30 March 2001

OpenVMS DCL Dictionary

Contents

Index

If SYS$INPUT is a terminal, it cannot have an associated terminal mailbox.

/KEYPAD (default)

/NOKEYPAD

Copies keypad key definitions and the current keypad state from the parent process. By default, if you have established key definitions or states with the DEFINE/KEY or the SET KEY command, these settings are copied to the subprocess. Use the /NOKEYPAD qualifier if you do not want the key settings to be copied.

/LOG (default)

/NOLOG

Displays the assigned subprocess name and any messages indicating transfer of control between processes.

/LOGICAL_NAMES (default)

/NOLOGICAL_NAMES

Copies process logical names and logical name tables to the subprocess. 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.

/NOTIFY

/NONOTIFY (default)

Controls whether a message is broadcast to your terminal notifying you that your subprocess has completed or aborted. This qualifier should not be used unless you specify the /NOWAIT qualifier. The /NOTIFY qualifier cannot be specified when the SPAWN command is executed from within a noninteractive process.

Note that messages broadcast as a result of using the /NOTIFY qualifier are considered to be DCL messages. Therefore, if SET BROADCAST=NODCL is in effect, all such notification messages are suppressed.

/OUTPUT=filespec

Specifies the output file to which the results of the SPAWN operation are written. The asterisk (*) and the percent sign (%) wildcard characters cannot be used in the file specification. (Do not specify SYS$COMMAND as a file specification for the /OUTPUT qualifier when using the /NOWAIT qualifier; both parent and subprocess output will be displayed simultaneously on your terminal.)

Caution

If you include a version number in the filespec argument of the /OUTPUT qualifier, and that version of the specified file already exists, the existing file is replaced with the new output.

You cannot explicitly specify non-record-oriented, process-permanent files (NRO PPFs) with the /OUTPUT qualifier. The system displays an error message when it encounters such a file as the value for the /OUTPUT qualifier.

Note that when NRO PPFs are used as implicit output, the SPAWN command can succeed, as shown in the following table:

Process Type SYS$OUTPUT Implicit Output

Any NRO PPF Mailbox transmitting records for parent to write to its current SYS$OUTPUT device

Any Any other SYS$OUTPUT

Process Type	SYS$OUTPUT	Implicit Output
Any	NRO PPF	Mailbox transmitting records for parent to write to its current SYS$OUTPUT device
Any	Any other	SYS$OUTPUT

If you omit the /OUTPUT qualifier, output is written to the current SYS$OUTPUT device.

/PRIVILEGES={CURRENT|AUTHORIZED}

Determines whether the spawned process inherits the current process' 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' authorized privileges will be taken from the caller's authorized privileges.

/PROCESS=subprocess-name

Specifies the name of the subprocess to be created. If you omit the /PROCESS qualifier, a unique process name is assigned with the same base name as the parent process and a unique number. The default subprocess name format is username_n. If you specify a process name that already exists, an error message is displayed. If the /LOG qualifier has been specified, the assigned name of the subprocess is displayed.

/PROMPT[=string]

Specifies the prompt string for DCL to use in the subprocess. The default is the prompt of the parent process.

The string can consist of more than one character. All valid ASCII characters can be used in the string. The string must be enclosed in quotation marks (" ") if it contains spaces, special characters, or lowercase characters. Otherwise, letters are automatically converted to uppercase, and leading and trailing spaces are removed.

If no string is specified, the dollar sign ($) DCL default prompt string is used for the subprocess.

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

/TABLE=command-table

Specifies the name of an alternate command table to be used by the subprocess.

/TRUSTED

/NOTRUSTED

Indicates that the SPAWN command input originates in a trusted command procedure. SPAWN commands are not allowed in CAPTIVE accounts. The /TRUSTED qualifier provides a way for properly written captive command procedures to perform SPAWN operations when the command input originates in the captive command procedure where it can be trusted. For more information about trusted command procedures, refer to the OpenVMS Guide to System Security.

/WAIT (default)

/NOWAIT

Requires that you wait for the subprocess to terminate before you enter another DCL command. The /NOWAIT qualifier allows you to enter new commands while the subprocess is running. (Use the /OUTPUT qualifier with the /NOWAIT qualifier to avoid displaying both parent and subprocess output on the terminal simultaneously.)

Note that specifying the /NOWAIT qualifier causes both input and output to be shared with the parent process. If the input device is a terminal, control characters, such as Ctrl/T or Ctrl/Y, also affect all subprocesses sharing the input device. The Ctrl/Y control character, for example, interrupts all such subprocesses.

This problem may be avoided by specifying /INPUT=NL:.

Example


$ RUN MYPROG . . . $ `[Ctrl/Y]` $ SPAWN MAIL %DCL-S-SPAWNED, process SKONETSKI_1 spawned %DCL-S-ATTACHED, terminal now attached to process SKONETSKI_1 MAIL> READ . . . MAIL> EXIT %DCL-S-RETURNED, control returned to process SKONETSKI $ CONTINUE

$ RUN MYPROG
      .
      .
      .
 
$ [Ctrl/Y]
$ SPAWN MAIL
%DCL-S-SPAWNED, process SKONETSKI_1 spawned
%DCL-S-ATTACHED, terminal now attached to process SKONETSKI_1
MAIL> READ
   .
   .
   .
MAIL> EXIT
%DCL-S-RETURNED, control returned to process SKONETSKI
$ CONTINUE

The SPAWN command in this example allows you to enter the OpenVMS Mail utility (MAIL) without terminating the currently running program. After you exit from Mail, control is returned to the parent process.

START/CPU

Starts the specified secondary processor or processors (and any associated vector processors). The /CPU qualifier is required.
Applies only to OpenVMS multiprocessing systems. Requires CMKRNL (change mode to kernel) privilege.

Format

START/CPU [cpu-id[,...]]

Parameter

cpu-id[,...]
Specifies a decimal value representing the identity of a processor in a OpenVMS multiprocessing system. On a VAX 6000 system or an Alpha 7000 system, the CPU ID is the backplane slot number of the processor. If you do not specify a CPU ID and do not include the /ALL qualifier, the START/CPU command selects a single available processor to join the multiprocessing system.

Description

The START/CPU command starts a secondary processor in a OpenVMS multiprocessing system.
You can issue a START/CPU command only for processors in the STOPPED or TIMOUT state, as represented by the SHOW CPU command; otherwise, the START/CPU command has no effect.

Qualifiers

/ALL
Selects all remaining processors in the system's available set to join the multiprocessing system.
/DEFAULT_CAPABILITIES
Eliminates all previous capability (user and system) modifications for the specified CPU and reinitializes them with the values in the global initialization variable SCH$GL_DEFAULT_CPU_CAP.
Normally, user capabilities survive CPU shutdowns and restarts (not reboots), making the downtime as transparent to the user as possible. The CPU user capability bits are only initialized from SCH$GL_DEFAULT_CPU_CAP at the first boot of the CPU. (The system capability bits, however, are reinitialized to their defaults taken from SCH$GL_DEFAULT_CPU_CAP.)
However, there may be times when the CPU needs to be returned to a known, consistent state. The /DEFAULT_CAPABILITIES qualifier mimics the behavior of the initial bootstrap of the CPU.

Examples

#1
$ START/CPU

The START/CPU command in this example selects a single inactive processor from the set of those processors that are currently available but inactive. When it completes its initialization, the selected processor becomes part of the system's active set and is capable of scheduling and executing processes.

#2
$ START/CPU 4,7

The START/CPU command in this example selects the processors with CPU IDs 4 and 7, if they are currently available and inactive. When they complete initialization, these processors become part of the system's active set and are capable of scheduling and executing processes.

#3
$ START/CPU/ALL

The START/CPU/ALL command in this example selects all remaining inactive and available processors. When they complete initialization, these processors become part of the system's active set and are capable of scheduling and executing processes.

START/NETWORK

Starts or restarts the specified network service on the local node. The /NETWORK qualifier is required.

Format

START/NETWORK network-service

Parameter

network-service
Specifies the name of the network service to be started or restarted.

Description

The START/NETWORK command causes a network service to begin executing on the local node.
Use the STOP/NETWORK command to pause the network.

Example


$ START/NETWORK DECnet

This command starts the DECnet network service.

START/QUEUE

Starts or restarts the specified queue after it has been initialized. You also can use this command to change the options of the specified queue. The /QUEUE qualifier is required.
Requires manage (M) access to the queue.

Format

START/QUEUE queue-name[:]

Parameter

queue-name[:]
Specifies the name of the queue to be started or restarted.

Description

The START/QUEUE command restarts a queue that has been stopped or paused. You must create the queue with the INITIALIZE/QUEUE command before you can use the START/QUEUE command. To create and start the queue at the same time, use the INITIALIZE/QUEUE/START command.
If the specified queue is an autostart queue, the START/QUEUE command activates the queue for autostart. The queue begins processing jobs when autostart is enabled with the ENABLE AUTOSTART/QUEUES command for any node on which the queue can run.
You can specify with the START/QUEUE command most qualifiers that can be used with the INITIALIZE/QUEUE command. The defaults for the START/QUEUE qualifiers depend on the qualifiers specified when the queue was initialized. For example, the default for /JOB_LIMIT with INITIALIZE/QUEUE is 1. However, if the queue you are altering was initialized with a job limit of 3, and if you do not specify the /JOB_LIMIT qualifier with the START/QUEUE command, the job limit remains at 3 for that queue.
Values or options specified with qualifiers on the START/QUEUE command override the values or options of those same qualifiers that were specified when the queue was initialized.
If the specified queue is running when you enter the START/QUEUE command, the system returns an error message. To change the options of a running queue, use the SET QUEUE command. To change queue options that cannot be altered with the SET QUEUE command, use the following procedure:

Stop the queue with the STOP/QUEUE/NEXT command.
Restart the queue with the START/QUEUE or INITIALIZE/QUEUE/START command, specifying the appropriate qualifiers for the options you desire.

The /TOP_OF_FILE, /BACKWARD, /FORWARD, /SEARCH, /ALIGN, and /NEXT qualifiers are effective only when restarting an output execution queue from a paused state. They do not apply to queues that are stopped or to batch queues. When you specify more than one of the first five of these qualifiers, the print symbiont processes them in the following order:

/TOP_OF_FILE
/BACKWARD
/FORWARD
/SEARCH
/ALIGN

Qualifiers

/ALIGN[=(option[,...])]
Prints alignment pages to aid in aligning printer forms. Use this qualifier only when restarting an output execution queue from a paused state.
After the alignment is complete, the queue enters a paused state until you restart it by reentering the START/QUEUE command. Printing resumes from the point where alignment data started; that is, the task is backspaced over the pages printed for alignment.
Possible options are as follows:

MASK Specifies that input data is masked by replacing alphabetic characters with x's and numbers with 9s; nonalphanumeric characters are not masked. Mask characters allow you to prevent the printing of sensitive information. If you omit the MASK option, data is printed unaltered.

n Specifies the number of alignment pages to print. The value of n can be from 1 to 20. By default, one page of alignment data is printed.

/AUTOSTART_ON=(node::[device][,...])
Designates the queue as an autostart execution queue and specifies the node, or node and device, on which the queue can be located. Both node and device must be specified for output queues. For batch queues, only node is applicable.
In an OpenVMS Cluster, you can specify more than one node (or node and device) on which a queue can run, in the preferred order in which nodes should claim the queue. This allows the queue to fail over to another node if the node on which the queue is running leaves the cluster.
For autostart queues, the START/QUEUE command activates the queue for autostart. The queue will begin processing jobs when the ENABLE AUTOSTART/QUEUES command is entered for a node on which the queue can run.
This qualifier cannot be used with the /ON or /GENERIC qualifier; however, you can specify the /AUTOSTART_ON qualifier for a queue previously created or started with the /ON qualifier. Doing so overrides the /ON option and makes the queue an autostart queue.
For more information about autostart queues, refer to the chapter about managing queues in the OpenVMS System Manager's Manual.
/BACKWARD=n
Restarts a print queue n pages before the current page; n defaults to 1. If you omit the page value, printing resumes at the top of the current page. Use this qualifier only when restarting an output execution queue from a paused state.

Note
Using the START/QUEUE/BACKWARD=n command to restart a print job that uses Fortran carriage control and that was printed with the /NOFEED qualifier can have unexpected results, in particular:

The page positioning in the restarted job may not be correct: the output may not begin at the top of the page specified by n.
The output from the print job may be preceded by extra meaningless information.

/BASE_PRIORITY=n
Specifies the base process priority at which jobs are initiated from a batch execution queue. By default, if you omit the qualifier, jobs are initiated at the same priority as the base priority established by DEFPRI at system generation (usually 4). The base priority specifier can be any decimal value from 0 to 15.
/BLOCK_LIMIT=([lowlim,]uplim)

/NOBLOCK_LIMIT
Limits the size of print jobs that can be processed on an output execution queue. This qualifier allows you to reserve certain printers for certain size jobs. You must specify at least one of the parameters.
The lowlim parameter is a decimal number referring to the minimum number of blocks that are accepted by the queue for a print job. If a print job is submitted that contains fewer blocks than the the lowlim value, the job remains pending until the block limit for the queue is changed. After the block limit for the queue is decreased sufficiently, the job is processed.
The uplim parameter is a decimal number referring to the maximum number of blocks that are accepted by the queue for a print job. If a print job is submitted that exceeds this value, the job remains pending until the block limit for the queue is changed. After the block limit for the queue is increased sufficiently, the job is processed.
If you specify only an upper limit for jobs, you can omit the parentheses. For example, /BLOCK_LIMIT=1000 means that only jobs with 1000 blocks or less are processed in the queue. To specify only a lower job limit, you must use a null string ("") to indicate the upper specifier. For example, /BLOCK_LIMIT=(500,"") means any job with 500 or more blocks is processed in the queue. You can specify both a lower and upper limit. For example, /BLOCK_LIMIT=(200,2000) means that jobs with less than 200 blocks or more than 2000 blocks are not processed in the queue.
The /NOBLOCK_LIMIT qualifier cancels the previous setting established by the /BLOCK_LIMIT qualifier for the queue.
/CHARACTERISTICS=(characteristic[,...])

/NOCHARACTERISTICS
Specifies one or more characteristics for processing jobs on an execution queue. If a queue does not have all the characteristics that have been specified for a job, the job remains pending. If you specify only one characteristic, you can omit the parentheses. Each time you specify the /CHARACTERISTICS qualifier, all previously set characteristics are canceled. Only the characteristics specified with the qualifier are established for the queue.
Queue characteristics are installation specific. The characteristic parameter can be either a value from 0 to 127 or a characteristic name that has been defined by the DEFINE/CHARACTERISTIC command.
The /NOCHARACTERISTICS qualifier cancels any settings previously established by the /CHARACTERISTICS qualifier for the queue.
/CLOSE
Prevents jobs from being entered in the queue through PRINT or SUBMIT commands or as a result of requeue operations. To allow jobs to be entered, use the /OPEN qualifier. Whether a queue accepts or rejects new job entries is independent of the queue's state (such as paused, stopped, or stalled). When a queue is marked closed, jobs executing continue to execute. Jobs already pending in the queue continue to be candidates for execution.
/CPUDEFAULT=time
Defines the default CPU time limit for jobs in this batch execution queue. You can specify time as delta time, 0, INFINITE, or NONE. You can specify up to 497 days of delta time.
If the queue does not have a specified CPUMAXIMUM time limit and the value established in the user authorization file (UAF) has a specified CPU time limit of NONE, either the value 0 or the keyword INFINITE allows unlimited CPU time. If you specify NONE, the CPU time value defaults to the value specified either in the UAF or by the SUBMIT command (if included). CPU time values must be greater than or equal to the number specified by the system parameter PQL_MCPULM.
For information on specifying delta times, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time). For more information on specifying CPU time limits, see the CPU Time Limit Specifications and Actions table for the INITIALIZE/QUEUE command.
/CPUMAXIMUM=time
Defines the default CPU time limit for all jobs in this batch execution queue. You can specify time as delta time, 0, INFINITE, or NONE. You can specify up to 497 days of delta time.
If the queue does not have a specified CPUMAXIMUM time limit and the value established in the UAF has a specified CPU time limit of NONE, either the value 0 or the keyword INFINITE allows unlimited CPU time. If you specify NONE, the CPU time value defaults to the value specified either in the UAF or by the SUBMIT command (if included). CPU time values must be greater than or equal to the number specified by the system parameter PQL_MCPULM. The time cannot exceed the CPU time limit set by the /CPUMAXIMUM qualifier. For information on specifying delta time, refer to the OpenVMS User's Manual or the online help topic DCL_Tips (subtopic Date_Time). For more information on specifying CPU time limits, see the CPU Time Limit Specifications and Actions table for the INITIALIZE/QUEUE command.
/DEFAULT=(option[,...])

/NODEFAULT
Establishes defaults for certain options of the PRINT command. Defaults are specified by the list of options. If you specify only one option, you can omit the parentheses. After you set an option for the queue with the /DEFAULT qualifier, you do not have to specify that option in your PRINT commands. If you do specify these options in your PRINT command, the values specified with the PRINT command override the values established for the queue with the /DEFAULT qualifier.
You cannot use the /DEFAULT qualifier with the /GENERIC qualifier.
Possible options are as follows:

[NO]BURST[=keyword] Controls whether two file flag pages with a burst bar between them are printed preceding output. If you specify the value ALL (default), these flag pages are printed before each file in the job. If you specify the value ONE, these flag pages are printed once before the first file in the job.

[NO]FEED Specifies whether a form feed is inserted automatically at the end of a page.

[NO]FLAG[=keyword] Controls whether a file flag page is printed preceding output. If you specify the value ALL (default), a flag page is printed before each file in the job. If you specify the value ONE, a flag page is printed once before the first file in the job.

FORM=type Specifies the default form for an output execution queue. If a job is submitted without an explicit form definition, this form is used to process the job. If no form type is explicitly specified with the FORM keyword, the system assigns the form "DEFAULT" to the queue. See also the description of the /FORM_MOUNTED qualifier.

[NO]TRAILER[=keyword] Controls whether a file trailer page is printed following output. If you specify the value ALL (default), a trailer page is printed after each file in the job. If you specify the value ONE, a trailer page is printed once after the last file in the job.

When you specify the BURST option for a file, the [NO]FLAG option does not add or subtract a flag page from the two flag pages that are printed preceding the file. For information on establishing mandatory queue options, see the description of the /SEPARATE qualifier. For more information on specifying default queue options, refer to the OpenVMS System Manager's Manual.
/DESCRIPTION=string

/NODESCRIPTION
Specifies a string of up to 255 characters that is used to provide operator-supplied information about the queue.
Enclose strings containing lowercase letters, blanks, or other nonalphanumeric characters (including spaces) in quotation marks (" ").
The /NODESCRIPTION qualifier removes any descriptive text that may be associated with the queue.
/DISABLE_SWAPPING

/NODISABLE_SWAPPING
Controls whether batch jobs executed from a queue can be swapped in and out of memory.
/ENABLE_GENERIC

/NOENABLE_GENERIC
Specifies whether files queued to a generic queue that does not specify explicit queue names with the /GENERIC qualifier can be placed in this execution queue for processing. For more information, see the description of the /GENERIC qualifier.
/FORM_MOUNTED=type
Specifies the mounted form for an output execution queue.
If no form type is explicitly specified, the system assigns the form "DEFAULT" to the queue.
If the stock of the mounted form does not match the stock of the default form, as indicated by the /DEFAULT=FORM qualifier, all jobs submitted to this queue without an explicit form definition enter a pending state and remain pending until the stock of the mounted form of the queue is identical to the stock of the form associated with the job.
If a job is submitted with an explicit form and the stock of the explicit form is not identical to the stock of the mounted form, the job enters a pending state and remains pending until the stock of the mounted form of the queue is identical to the stock of the form associated with the job.
To specify the form type, use either a numeric value or a form name that has been defined by the DEFINE/FORM command. Form types are installation-specific. You cannot use the /FORM_MOUNTED qualifier with the /GENERIC qualifier.
/FORWARD=n
Advances the specified number of pages before resuming printing the current file in the current job; the default is 1. If you omit the page value, printing resumes at the top of the next page. Use this qualifier only when restarting an output execution queue from a paused state.
/GENERIC[=(queue-name[,...])]

/NOGENERIC
Specifies a generic queue. Also specifies that jobs placed in this queue can be moved for processing to compatible execution queues. The /GENERIC qualifier optionally accepts a list of target execution queues that have been previously defined. For a generic batch queue, these target queues must be batch execution queues. For a generic output queue, these target queues must be output execution queues, but can be of any type (printer, server, or terminal). For example, a generic printer queue can feed a mixture of printer and terminal execution queues.

Previous Next Contents Index

privacy and legal statement

9996PRO_077.HTML

MASK	Specifies that input data is masked by replacing alphabetic characters with x's and numbers with 9s; nonalphanumeric characters are not masked. Mask characters allow you to prevent the printing of sensitive information. If you omit the MASK option, data is printed unaltered.
n	Specifies the number of alignment pages to print. The value of n can be from 1 to 20. By default, one page of alignment data is printed.

[NO]BURST[=keyword]	Controls whether two file flag pages with a burst bar between them are printed preceding output. If you specify the value ALL (default), these flag pages are printed before each file in the job. If you specify the value ONE, these flag pages are printed once before the first file in the job.
[NO]FEED	Specifies whether a form feed is inserted automatically at the end of a page.
[NO]FLAG[=keyword]	Controls whether a file flag page is printed preceding output. If you specify the value ALL (default), a flag page is printed before each file in the job. If you specify the value ONE, a flag page is printed once before the first file in the job.
FORM=type	Specifies the default form for an output execution queue. If a job is submitted without an explicit form definition, this form is used to process the job. If no form type is explicitly specified with the FORM keyword, the system assigns the form "DEFAULT" to the queue. See also the description of the /FORM_MOUNTED qualifier.
[NO]TRAILER[=keyword]	Controls whether a file trailer page is printed following output. If you specify the value ALL (default), a trailer page is printed after each file in the job. If you specify the value ONE, a trailer page is printed once after the last file in the job.