OpenVMS DCL Dictionary
Use the /GENERIC qualifier to change the list of target nodes for a
generic queue. The queue must have been initialized as a generic queue
with the INITIALIZE/QUEUE/GENERIC command.
If you do not specify any target execution queues with the /GENERIC
qualifier, jobs can be moved to any execution queue that (1) is
initialized with the /ENABLE_GENERIC qualifier, and (2) is the same
type (batch or output) as the generic queue.
To define the queue as a generic batch or output queue, you use the
/GENERIC qualifier with either the /BATCH or the /DEVICE qualifier. If
you specify neither the /BATCH nor the /DEVICE qualifier on creation of
a generic queue, by default the queue becomes a generic printer queue.
/JOB_LIMIT=n
Specifies the number of batch jobs that can be executed concurrently
from the queue. Specify a number in the range 0 to 255.
/LIBRARY=filename
/NOLIBRARY
Specifies the file name for the device control library. When you
initialize an output execution queue, you can use the /LIBRARY
qualifier to specify an alternate device control library. You can use
only a file name as the parameter of the /LIBRARY qualifier. The system
always assumes that the file is located in SYS$LIBRARY and that the
file type is .TLB.
/NEXT
Aborts the currently suspended print job and begins processing of the
first pending job in the queue. Use this qualifier only when restarting
an output execution queue from a paused state.
/NO_INITIAL_FF
/NONO_INITIAL_FF (default)
Specifies whether a form feed should be sent to a printer device when a
queue starts. To suppress the initial form feed, use the /NO_INITIAL_FF
qualifier.
The /NONO_INITIAL_FF qualifier sends a form feed to the output device
to ensure that the paper is at the top of a page before printing begins.
/ON=[node::]device[:] (printer, terminal, server queue)
/ON=node:: (batch queue)
Specifies the node or device, or both, on which this execution queue is
located. For batch execution queues, you can specify only the node
name. For output execution queues, you can include both the node name
and the device name.
The node name is used only in VAXcluster systems; it must match the
node name specified by the system parameter SCSNODE for the VAX
computer on which the queue executes.
You cannot use the /ON qualifier with the /AUTOSTART_ON or /GENERIC
qualifier; however, you can specify the /ON qualifier for a queue
previously created or started with the /AUTOSTART_ON qualifier. Doing
so overrides the /AUTOSTART_ON qualifier and makes the queue a
nonautostart queue.
/OPEN
Allows jobs to be entered in the queue through PRINT or SUBMIT commands
or as the result of requeue operations. To prevent jobs from being
entered in the queue, use the /CLOSE qualifier. Whether a queue accepts
or rejects new job entries is independent of the queue's state (such as
paused, stopped, or stalled).
/OWNER_UIC=uic
Requires manage (M) access to the queue.
Enables you to change the user identification code (UIC) of the queue.
Specify the UIC by using standard format as described in the
OpenVMS User's Manual.
/PROCESSOR=filename
/NOPROCESSOR
Requires OPER (operator) privilege to change the file name from
the one with which the queue was initialized.
Allows you to specify your own print symbiont for an output execution
queue. You can use any valid file name as a parameter of the /PROCESSOR
qualifier. The system supplies the device and directory name SYS$SYSTEM
and the file type .EXE. If you use this qualifier for an output queue,
it specifies that the symbiont image to be executed is
SYS$SYSTEM:filename.EXE.
By default, SYS$SYSTEM:PRTSMB.EXE is the symbiont image associated with
an output execution queue.
The /NOPROCESSOR qualifier cancels any previous setting established by
the /PROCESSOR qualifier, and causes SYS$SYSTEM:PRTSMB.EXE to be used.
/PROTECTION=(ownership[:access],...)
Requires OPER (operator) privilege, or control (C) and execute
(E) access to the queue.
Specifies the protection of the queue.
- Specify the ownership parameter as system (S), owner (O),
group (G), or world (W).
- Specify the access parameter as read (R), submit (S),
manage (M), or delete (D). A null access specification means no access.
If you include only one protection code, you can omit the parentheses.
For more information on specifying protection codes, refer to the
OpenVMS Guide to System Security. For more information on controlling queue operations
through UIC-based protection, refer to the OpenVMS System Manager's Manual.
/RECORD_BLOCKING
/NORECORD_BLOCKING
Determines whether the symbiont can concatenate (or block together)
output records for transmission to the output device. If you specify
the /NORECORD_BLOCKING qualifier, the symbiont sends each formatted
record in a separate I/O request to the output device. For the standard
OpenVMS print symbiont, record blocking can have a significant
performance advantage over single-record mode.
/RETAIN[=option]
/NORETAIN
Holds jobs in the queue in a retained status after they have executed.
The /NORETAIN qualifier enables you to reset the queue to the default.
Possible options are as follows:
|
ALL
|
Holds all jobs in the queue after execution.
|
|
ERROR
|
Holds in the queue only jobs that fail to complete.
|
A user can request a job retention option for a job by specifying the
/RETAIN qualifier with the PRINT, SUBMIT, or SET ENTRY command.
However, the job retention option you specify for a queue overrides any
job retention option requested by a user for a job in that queue.
/SCHEDULE=[NO]SIZE
Specifies whether pending jobs in an output queue are scheduled for
printing based on the size of the job. When the /SCHEDULE=SIZE
qualifier is in effect, shorter jobs are printed before longer ones.
When the /SCHEDULE=NOSIZE qualifier is in effect, jobs are printed in
the order they were submitted, regardless of size.
If you enter this command while there are pending jobs in any queue,
its effect on future jobs is unpredictable.
/SEARCH="search-string"
Specifies that printing is to resume at the page containing the
specified string. The search for the string moves forward, beginning on
the page following the current page. During the search, consecutive
tabs and spaces are treated as a single space, and character case is
ignored. The string can be from 1 to 63 characters and must be enclosed
in quotation marks (" "). Use this qualifier only when
restarting an output execution queue from a paused state.
/SEPARATE=(option[,...])
/NOSEPARATE
Specifies the mandatory queue options, or job separation options, for
an output execution queue. Job separation options cannot be overridden
by the PRINT command.
You cannot use the /SEPARATE qualifier with the /GENERIC qualifier.
The job separation options are as follows:
|
[NO]BURST
|
Specifies whether two job flag pages with a burst bar between them are
printed at the beginning of each job.
|
|
[NO]FLAG
|
Specifies whether a job flag page is printed at the beginning of each
job.
|
|
[NO]TRAILER
|
Specifies whether a job trailer page is printed at the end of each job.
|
|
[NO]RESET=(module[,...])
|
Specifies one or more device control library modules that contain the
job reset sequence for the queue. The specified modules from the
queue's device control library (by default SYS$LIBRARY:SYSDEVCTL) are
used to reset the device each time a job reset occurs. The RESET
sequence occurs after any file trailer and before any job trailer.
Thus, all job separation pages are printed when the device is in its
RESET state.
|
When you specify /SEPARATE=BURST, the [NO]FLAG separation option does
not add or subtract a flag page from the two flag pages that are
printed preceding the job.
For information on establishing queue options that can be overridden,
see the description of the /DEFAULT qualifier.
For more information on specifying mandatory queue options, refer to
the OpenVMS System Manager's Manual.
/TOP_OF_FILE
Resumes printing at the beginning of the file that was current when the
output execution queue paused. Use this qualifier only when restarting
an output execution queue from a paused state.
/WSDEFAULT=n
Defines for a batch job a working set default, the default number of
physical pages that the job can use. The value set by this qualifier
overrides the value defined in the user authorization file (UAF) of any
user submitting a job to the queue.
You also can specify this qualifier for an output execution queue. Used
in this context, the /WSDEFAULT qualifier establishes the working set
default of the symbiont process for an execution queue when the
symbiont process is created.
Specify the value of n as a number of 512-byte pagelets on
Alpha or 512-byte pages on VAX. Note that the operating systems rounds
up this value to the nearest CPU-specific page so that the actual
amount of physical memory allowed may be larger than the specified
amount on Alpha.
If you specify the value 0 or NONE, the working set default value
defaults to the value specified in the UAF or by the SUBMIT command (if
included).
For more information about the way a working set default affects batch
jobs, see Table DCLII-22.
/WSEXTENT=n
Defines for the batch job a working set extent, the maximum amount of
physical memory that the job can use. The job uses the maximum amount
of physical memory only when the system has excess free pages. The
value set by this qualifier overrides the value defined in the user
authorization file (UAF) of any user submitting a job to the queue.
You also can specify this qualifier for an output execution queue. Used
in this context, the /WSEXTENT qualifier establishes the working set
extent of the symbiont process for an output execution queue when the
symbiont process is created.
Specify the value of n as a number of 512-byte pagelets on
Alpha or 512-byte pages on VAX. Note that the operating system rounds
up this value to the nearest CPU-specific page so that the actual
amount of physical memory allowed may be larger than the specified
amount on Alpha.
If you specify the value 0 or NONE, the working set extent value
defaults to the value specified in the UAF or by the SUBMIT command (if
included).
For more information about the way a working set extent affects batch
jobs, see Table DCLII-22.
/WSQUOTA=n
Defines for a batch job a working set quota, the amount of physical
memory that is guaranteed to the job. The value set by this qualifier
overrides the value defined in the user authorization file (UAF) of any
user submitting a job to the queue.
You also can specify this qualifier for an output execution queue. Used
in this context, the /WSQUOTA qualifier establishes the working set
quota of the symbiont process for an output execution queue when the
symbiont process is created.
Specify the value of n as a number of 512-byte pagelets on
Alpha or 512-byte pages on VAX. Note that the operating system rounds
up this value to the nearest CPU-specific page so that the actual
amount of physical memory allowed may be larger than the specified
amount on Alpha.
If you specify the value 0 or NONE, the working set quota value
defaults to the value specified in the UAF or by the SUBMIT command (if
included).
Working set default, working set quota, and working set extent values
are included in each user record in the system UAF. You can specify
working set values for individual jobs or for all jobs in a given
queue. The decision table (Table DCLII-22) shows the action taken for
different combinations of specifications that involve working set size
and working set quota values.
Examples
| #1 |
$ STOP/QUEUE LPA0
$ START/QUEUE/TOP_OF_FILE LPA0
|
The STOP/QUEUE command in this example suspends the job that is
currently executing on the printer queue LPA0 and places that queue in
the paused state. The START/QUEUE command releases the queue from the
paused state. The /TOP_OF_FILE qualifier causes the job that was
suspended to resume printing at the beginning of the file rather than
at where it was interrupted.
| #2 |
$ INITIALIZE/QUEUE LPA0
.
.
.
$ START/QUEUE/DEFAULT=FLAG LPA0
|
The INITIALIZE/QUEUE command in this example initializes the queue
named LPA0. Later, the START/QUEUE command starts the queue. The
/DEFAULT qualifier requests that a flag page precede each file in each
job.
| #3 |
$ START/QUEUE/DEFAULT=FORM=LN01_PORTRAIT LN01_PRINT
|
The START/QUEUE command in this example restarts the LN01_PRINT queue
with the default form LN01_PORTRAIT.
| #4 |
$ INITIALIZE/QUEUE/START/GENERIC=(A,B) MYQUEUE
.
. [new printers X and Y are brought in at a later date]
.
$ STOP/QUEUE/NEXT MYQUEUE
$ START/QUEUE/GENERIC=(X,Y) MYQUEUE
|
This example changes the list of target nodes for a generic queue. Note
that the queue was previously initialized as a generic queue.
START/QUEUE/MANAGER
Starts the clusterwide queue manager for the queuing system and opens
that queue manager's queue database files. The /QUEUE qualifier is
optional, but the /MANAGER qualifier is required.
By default, the command affects the default queue manager,
SYS$QUEUE_MANAGER. Specify the /NAME_OF_MANAGER qualifier to start a
queue manager other than the default.
For more information, refer to the chapter on the queue manager in the
OpenVMS System Manager's Manual.
Requires OPER (operator) and SYSNAM (system logical name)
privileges.
Format
START/QUEUE/MANAGER [dirspec]
Parameter
dirspec
Specifies the directory location to contain the system queue and
journal files of the queue database. The queue file has a file type of
QMAN$QUEUES and contains queue definitions. The journal file has a file
type of QMAN$JOURNAL and contains job and other information that lets
the queue manager to return to its last known state should a system be
stopped unexpectedly. These files must reside in the same directory.
The default location of the queue and journal files is
SYS$COMMON:[SYSEXE]. The optional dirspec parameter is used
only for specifying an alternate location for the queue and journal
files. The specification must include at least the device and directory
name. The asterisk (*) and the percent sign (%) wildcard characters are
not allowed in the directory specification.
The directory you specify must be available to all nodes that can run
the queue manager. If the directory specification is a concealed
logical name, it must be identically defined on all nodes in the
cluster.
The location of the queue and journal files is stored in the master
file of the queue database. You do not have to respecify the directory
location with subsequent START/QUEUE/MANAGER commands.
For information about changing the location of any of the queue
database files, refer to the chapter on the queue manager in the
OpenVMS System Manager's Manual.
Description
The START/QUEUE/MANAGER command has the following uses:
- Enter the command START/QUEUE/MANAGER/NEW_VERSION to create the
queue database and initially start a queue manager. See the description
of the /NEW_VERSION qualifier for more information. Once the queue
manager has been started, it will remain running unless it is
explicitly stopped with the STOP/QUEUE/MANAGER/CLUSTER command.
- If the STOP/QUEUE/MANAGER/CLUSTER command has been executed, enter
the START/QUEUE/MANAGER command to restart a queue manager.
- In an OpenVMS Cluster, enter the START/QUEUE/MANAGER command with
the /ON qualifier to modify the list of preferred nodes on which a
queue manager can run. See the description of the /ON qualifier for
more information.
- In an OpenVMS Cluster, enter the START/QUEUE/MANAGER command to
ensure that a queue manager process is executing on the most preferred,
available node. If the queue manager is not running on the most
preferred, available node, the queue manager will be moved to that node
without interruption of service. If you are using the default node list
(*), the queue manager will not move. For more information, see the
description of the /ON qualifier.
If the queue manager is in a location other than the default, and in
OpenVMS Cluster environments with multiple system disks, you must
define the logical name QMAN$MASTER. For instructions, refer to the
chapter about the queue manager and queue database in the OpenVMS System Manager's Manual.
If a queue manager does not start when you enter the
START/QUEUE/MANAGER command, you will receive the following message:
%JBC-E-QMANNOTSTARTED, queue manager could not be started
|
If you see this message, search the operator log file
SYS$MANAGER:OPERATOR.LOG (or look on the operator console) for messages
from the facilities QUEUE_MANAGE and JOB_CONTROL for information about
the problem, as follows:
$ SEARCH SYS$MANAGER:OPERATOR.LOG /WINDOW=5 QUEUE_MANAGE,JOB_CONTROL
|
Qualifiers
/ADD
Creates an additional queue manager in the existing queue database. If
the named queue manager already exists, the request will be rejected.
/NAME_OF_MANAGER=name
Creates a non-default queue manager. The required name value may be up
to 31 characters long and may be a logical. The name will serve as the
identifier for the queue manager process and the portion of the
database that it is managing.
/NEW_VERSION
/NONEW_VERSION (default)
Specifies that a new (empty) version of the queue database is to be
created. This qualifier is required when initially creating and
starting the queuing system.
If you specify this qualifier and a queue database already exists, the
new master and queue files of the queue database supersede existing
versions of those files; however, the journal file of the existing
queue database is deleted. Jobs and other information are lost.
/ON=(node[,...])
In an OpenVMS Cluster, specifies the nodes on which a clusterwide queue
manager can run. The default value for the node list is the asterisk
(*) wildcard character, meaning that all nodes in the cluster are
eligible to run the queue manager. If the node on which the queue
manager is running leaves the cluster, the queue manager can
automatically fail over to any available node in the cluster. However,
to specify a preferred order in which the nodes should claim the queue
manager, or to limit the nodes which can run it, you must specify the
/ON qualifier.
The node list you specify is stored in the queue database. Anytime the
START/QUEUE/MANAGER command is entered and neither the /NEW_VERSION nor
/ON qualifier is specified, the /ON list stored in the queue database
remains unchanged.
For highest availability, specify the asterisk (*) wildcard character
as the last node in the node list to indicate that any remaining
unlisted node can claim the queue manager, with no preferred order. If
you do not specify the asterisk (*) wildcard character last in the node
list, the queue manager can only fail over if one of the nodes in the
list is available; however, if you want to exclude certain nodes from
being eligible to run the queue manager, you cannot use the asterisk
(*) wildcard character. You cannot specify the asterisk (*) wildcard
character as part of a node name.
Anytime the START/QUEUE/MANAGER command is entered (with or without the
/ON qualifier), the job controller will check to see if one or more
preferred queue manager nodes was currently or previously specified
with the /ON qualifier. If one or more preferred nodes was specified,
and the queue manager is running on a node other than the first
available node of those specified, the queue manager process is moved
from its current node and restarted on the first available preferred
node. Despite the transition, queues on the running nodes are not
stopped. All requests to the queuing system, for example, PRINT,
SUBMIT, and SHOW ENTRY requests, will complete as expected.
Examples
| #1 |
$ START/QUEUE/MANAGER/NEW_VERSION
$ SHOW QUEUE
%JBC-E-NOSUCHQUE, no such queue
|
The START/QUEUE/MANAGER command in this example starts the queue
manager and creates the queue and journal files in the default
location, SYS$COMMON:[SYSEXE]. Because the asterisk (*) wildcard
character is used as the default value for the list of nodes on which
the queue manager can run, the queue manager will be able to fail over
to any available node in the cluster.
This command starts the default queue manager SYS$QUEUE_MANAGER because
the /NAME_OF_MANAGER qualifier is not specified.
Both the SYS$COMMON:[SYSEXE] location and the asterisk value for the
/ON qualifier are stored in the queue database for future reference.
The newly created queue database contains no queues or jobs. The SHOW
QUEUE command shows that no queues are defined on this cluster.
| #2 |
$ START/QUEUE/MANAGER/NEW_VERSION -
_$ /ON=(SATURN,VENUS,NEPTUN,*) DUA5:[SYSQUE]
|
The START/QUEUE/MANAGER command in this example creates the queue and
journal files on the cluster-accessible disk volume DUA5, in directory
SYSQUE. You must mount the disk before you enter the
START/QUEUE/MANAGER command.
The /ON qualifier specifies that the queue manager should run first on
node SATURN. If SATURN leaves the cluster, the queue manager will
attempt to fail over to VENUS. If VENUS is not available, the queue
manager will attempt to fail over to NEPTUN. If NEPTUN is not
available, the queue manager will fail over to any other available node
in the cluster.
| #3 |
$ START/QUEUE/MANAGER/NEW_VERSION -
_$ /ON=(SATURN,VENUS,NEPTUN,*) DUA5:[SYSQUE])
.
.
.
$ START/QUEUE/MANAGER
|
The START/QUEUE/MANAGER command in this example creates the queue
database as shown in the previous example. Suppose the queue manager
started on node SATURN.
Later, SATURN is removed from the cluster, and the queue manager fails
over to node VENUS. When SATURN rejoins the cluster, the second
START/QUEUE/MANAGER command in the example is entered to move the queue
manager back to node SATURN.
The second START/QUEUE/MANAGER command does not specify the
DUA5:[SYSQUE] parameter value or the /ON qualifier and its node list
because those previously supplied pieces of information are stored in
the queue database. The queue manager continues to use the queue and
journal files found at the location stored in its database. The /ON
list, stored as a result of the previous START/QUEUE/MANAGER command,
also remains unchanged.
| #4 |
$ START/QUEUE/MANAGER DUA4:[SYSQUE]
%JBC-E-QMANNOTSTARTED, queue manager could not be started
$ SEARCH SYS$MANAGER:OPERATOR.LOG /WINDOW=5 QUEUE_MANAGE,JOB_CONTROL
%%%%%%%%%%% OPCOM 14-DEC-2001 18:55:18.23 %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
%QMAN-E-OPENERR, error opening DUA4:[SYSQUE]SYS$QUEUE_MANAGER.QMAN$QUEUES;
%%%%%%%%%%% OPCOM 14-DEC-2001 18:55:18.29 %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
-RMS-F-DEV, error in device name or inappropriate device type for operation
%%%%%%%%%%% OPCOM 14-DEC-2001 18:55:18.31 %%%%%%%%%%%
Message from user QUEUE_MANAGE on QMUNGR
-SYSTEM-W-NOSUCHDEV, no such device available
$ START/QUEUE/MANAGER DUA5:[SYSQUE]
|
In this example, the first START/QUEUE/MANAGER command specifies device
DUA4: as the location of the queue and journal files. The error message
indicates that the queue manager does not start. The SEARCH command
searches the operator log file for relevent messages, and reveals that
device DUA4: does not exist. The second START/QUEUE/MANAGER command
specifies the correct device name, DUA5:.
|
