qmgr(8) CLIX qmgr(8)
NAME
qmgr - Runs the Network Queuing System (NQS) queue manager
SYNOPSIS
qmgr
DESCRIPTION
The qmgr command is used by the system administrator or system operator to
control NQS requests, queues, devices, and general NQS configuration at
the local machine.
Definitions
An NQS request is a request by a user or user program to perform a
function that requires a delay in servicing (after a certain time).
Examples of such functions are the scheduling of a shared serial-access
resource (such as a printer) and batch job requests. An NQS manager
identifies a user capable of changing any NQS characteristic on the local
machine. An NQS operator identifies a user who can execute only the
operator commands as a proper subset of all commands provided by the qmgr
utility.
NQS supports three queue types: batch, device, and pipe.
Batch queues can be used only to execute NQS batch requests. Only NQS
batch requests created by the qsub command can be placed in a batch queue.
Device queues can be used only to execute NQS device requests. Only NQS
device requests created by the qpr command can be placed in a device
queue.
Pipe queues are used to send NQS requests to other pipe queues or request
destination batch or device queues appropriate for the request type. In
general, pipe queues combine with network queues to become the mechanism
that NQS uses to transport both batch and device requests to queues on
remote machines. It is also legal for a pipe queue to transport requests
to queues on the same machine.
When a pipe queue is defined, it is given a set of possible destination
queues for requests entered in that pipe queue. In this manner, it is
possible for a batch or device request to pass through many pipe queues on
its way to its ultimate destination, which must eventually be a batch or
device queue (matching the request type).
Each pipe queue has an associated server. For each request handled by a
pipe queue, the associated server that must select a queue destination for
the request being handled is spawned. The selection is based on the
characteristics of the request and on the characteristics of each queue in
2/94 - Intergraph Corporation 1
qmgr(8) CLIX qmgr(8)
the set of destination queues defined for the pipe queue.
Since a different server can be configured for each pipe queue, and batch
and device queues can have the pipeonly attribute that will admit requests
queued only through another pipe queue, respective NQS installations may
use pipe queues as a request class mechanism. This places requests that
ask for different resource allocations in different queues. Each of these
queues can have different associated limits and priorities.
It is also completely possible for a pipe-client (pipe queue server) when
handling a request to discover that a destination queue will not accept
the request for various reasons, including insufficient resource limits to
execute the request, or a lack of a corresponding account or privilege for
queuing at a remote queue. In such circumstances, the request will be
deleted and the user will be notified by mail (see mail).
NQS has queue access restrictions. For each queue with a queue type other
than network, access may be either unrestricted or restricted. If access
is unrestricted, any request may enter the queue. If access is
restricted, a request can enter the queue only if the requester or the
requester's login group has access to that queue. Requests submitted by
the superuser are an exception; they are always queued, even if the
superuser has not explicitly been given access. The qstat command may be
used to determine who has access to a particular queue.
The qmgr command recognizes commands regardless of uppercase or lowercase
characters. The qmgr command will also recognize shortened versions of
commands. The user must enter only enough of the command to make it
unique.
The qmgr command will support command line editing and recall in both vi
and emacs modes. Upon initialization, qmgr determines which editing
command set it will use. It does this by checking the following
environmental variables, in order:
VISUAL
EDITOR
FCEDIT
If none of these variables are set to vi, emacs, or gmacs, the vi mode
will be used.
The environmental variable EDIT_RECALL may be set to indicate a preference
for having the cursor be at the beginning or end of recalled lines. If
this variable is not set, the default is to put the cursor at the end of
the recalled line for emacs, and at the beginning of the line for vi. If
it is set to the value REVERSE_LINE, it will reverse this convention.
The editor commands are a subset of the vi and emacs editor commands, and
are very similar to the ones used in ksh.
2 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
General Commands
The following commands are available to all users:
exit Exits qmgr.
help [command]
Displays help information. Without an argument, help displays
information about the available commands. With an argument, help
displays information about the specified command. The command may
be partially specified as long as it is unique. A more complete
help request yields more detailed information.
The help command provides information that is often more extensive
than the manual page descriptions.
show all
Displays information about the devices, forms, limits, managers,
parameters, and queues on the local machine (see the show commands
below).
show complex [complex-name]
Displays the status of all NQS queue complexes on this host. If a
complex-name is specified, output is limited to that queue complex.
show device [device-name]
Displays the status of all NQS devices on this host. If a device-
name is specified, output is limited to that device.
show forms
Displays the list of valid forms.
show limits_supported
Displays the list of meaningful NQS resource limits on this
machine. If a limit is meaningful on a machine, the corresponding
qmgr commands allow the association of a limit with any batch queue
on that machine. Note that users may request resource limits that
are not meaningful on the machine where qsub is invoked. If the
request is to be executed on a remote machine where the limit is
meaningful, NQS honors it. Otherwise, the unsupported limit is
ignored.
show long queue [queue-name [username]]
Displays in long format the status of all NQS queues on this host.
If a queue-name is specified, output will be limited to that queue.
If a username is specified, output will be limited to requests
owned by username.
show managers
Displays the list of NQS managers.
2/94 - Intergraph Corporation 3
qmgr(8) CLIX qmgr(8)
show parameters
Displays the general NQS parameters.
show queue [queue-name [username]]
Displays the status of all NQS queues on this host. If a queue-
name is specified, output will be limited to that queue. If a
username is specified, output will be limited to requests owned by
username.
Operator Commands
The following commands require the user to have NQS operator privileges:
abort queue queue [seconds]
Aborts all running requests in the queue. A SIGTERM (see the
signal() function) signal is sent to each process of each running
request. After the specified number of seconds of real time have
elapsed, a SIGKILL (see the signal() function) signal is sent to
all remaining processes for each of the running requests. The
default number of seconds is 60. All requests aborted by this
command are deleted and all output files associated with the
requests are returned to the appropriate destination.
delete request request-id ...
Deletes the requests named by request-ids. This command can delete
both running and nonrunning requests. If a request is running, all
processes of the request are sent a SIGKILL signal.
disable device device
Completes the current request. After that, the device is prevented
from handling any more requests until it is enabled. If the
disabled device was the last enabled device in a queue-to-device
mapping, the device queue is effectively stopped.
disable queue queue
Prevents any more requests from being placed in this queue.
enable device device
Makes the device available to handle requests.
enable queue queue
Make the queue now available to accept new requests.
hold request ...
Places a queued or waiting request in the operator hold state. The
request will remain in the hold state until it is unheld or
released by an operator.
lock local_daemon
Locks the NQS local daemon into memory (see the plock command).
4 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
modify request request priority = n
Modifies the scheduling priority of the request. If the request is
running, the new scheduling priority will not take effect unless
the request returns to a waiting state.
move queue from-queue to-queue
Moves all requests in the queue specified by from-queue to the
queue specified by to-queue.
move request request-id queue
Moves the request specified by request-id from its current queue to
the queue specified by queue.
purge queue queue
Purges all queued requests from the queue. The purged queues are
irretrievably lost. Running requests in the queue are allowed to
complete.
release request ...
Removes the request from any held or waiting state and place it in
the queued state ready to run. This command will release any
operator or user hold.
restart queue queue [seconds]
Sends all running requests in the queue specified by queue a
SIGTERM signal. After a grace period of seconds has passed, a
SIGKILL signal is sent to the requests. The requests are then
immediately rescheduled for execution. If queue was put in a
stopping state before the restart was performed, the requests
remain queued. If seconds is not specified, a default value of 20
seconds is used.
set complex run_limit = run-limit complex
Changes the run-limit of an NQS queue complex. The run-limit
determines the maximum number of requests allowed to run in the
queue complex at any given time.
set done_limit = done_limit_queue
Changes the done_limit of an NQS device queue. The done_limit
determines the maximum number of jobs allowed in the done state at
one time. The default status is zero, which indicates that no jobs
will be put in the done state after printing. If the done_limit is
set to a value that is lower than the current value and there are
more than done_limit requests already in the done state, the limit
will be enforced at the current number of requests until an
operator removes the ``extra'' requests. Once the number of
requests in the done state is equal to or lower than the
done_limit, the new limit is enforced. This prevents accidental
deletion of requests.
set run_limit = run-limit queue
2/94 - Intergraph Corporation 5
qmgr(8) CLIX qmgr(8)
Changes the run-limit of an NQS batch or pipe queue. The run-limit
determines the maximum number of requests allowed to run in the
queue at any given time.
shutdown [seconds]
Shuts down NQS on the local host. A SIGTERM signal is sent to each
process of each running request. After the specified number of
seconds of real time have elapsed, a SIGKILL signal is sent to all
remaining processes for each running request. If a seconds value
is not specified, the delay is 60 seconds. Unlike the abort queue
command, shutdown re-queues all of the requests it kills if the
initial SIGTERM signal is caught or ignored by the running request.
start queue queue
Starts the queue and make requests in the queue eligible for
selection.
stop queue queue
Allows any running requests in the queue to complete. All other
requests in the queue are frozen. New requests can still be
submitted to the queue but are also frozen.
unhold request ...
Removes the request from an operator hold state. If the request is
also in a user hold, the request will remain in the hold state. If
the request is waiting for a certain time, the request will go into
the waiting state. Otherwise, the request returns to the queued
state.
unlock local_daemon
Removes a lock that has been retaining the NQS local daemon in
memory (see plock).
Manager Commands
The following commands require the user to have NQS manager privileges.
add destination = destination queue
add destination = (destination[, destination ... ]) queue
Adds the specified destinations as valid destinations for a pipe
queue named queue.
add device = device queue
add device = (device[, device ... ]) queue
Adds the specified devices as resources to service requests from
queue. The devices must exist (see create device below).
add forms form-name ...
Adds the specified form-names to the list of valid forms.
add groups = group queue
6 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
add groups = (group[, group ... ]) queue
Adds the specified groups to the access list for queue. There
are two ways to specify a group:
group-name
[group-id]
add queues = queue complex
add queues = (queue[, queue ... ]) complex
Adds the specified queues to the queue complex named complex.
add managers manager ...
Add the specified managers to the list of authorized NQS
managers with privileges as specified. A manager specification
consists of an account name specification followed by either :m
or :o. There are four ways to specify an account name:
local-account-name
[local-user-id]
[remote-user-id]@remote-machine-name
[remote-user-id]@[remote-machine-id]
If the account-name specification is followed by :m, the account
is designated as an NQS manager account capable of using all
qmgr commands. If the account name specification is followed by
:o, the account is designated as an NQS operator account capable
of using commands only appropriate for an NQS operator.
add users = user queue
add users = (user[, user ... ]) queue
Adds the specified users to the access list for queue. There
are two ways to specify a user:
username
[user-id]
create batch_queue queue priority = n [pipeonly] [run_limit = n]
Defines a batch queue named queue with interqueue priority n
(0-63). If pipeonly is specified, requests may enter this queue
only if their source is a pipe queue. The specification of a
run_limit limits the maximum number of requests allowed to run
in the batch queue at any given time. The default run limit is
1.
create complex = queue complex
create complex = (queue[, queue ... ]) complex
Creates a queue complex consisting of the specified set of batch
and device queues. Queue complexes provide for the grouping of
a set of batch and device queues into a queue complex, which can
2/94 - Intergraph Corporation 7
qmgr(8) CLIX qmgr(8)
have an associated run limit.
create device device forms = forms fullname = filename server = (server)
Defines a device with the specified forms and associate it with
a server. This is done by specifying an absolute pathname to
the program binary server and any arguments required by the
program. The filename is the absolute pathname of the device
(special file) and is typically /dev/device.
create device_queue queue priority = n [device = device] [device = (device
Defines a device queue named queue with interqueue priority n
(0-63). If pipeonly is specified, requests may enter this queue
only if their source is a pipe queue. If sizeorder is
specified, requests will be sorted by size (smallest job first)
instead of arrival time in the queue. Following device, a list
of one or more devices that may service this queue appears.
(destination[, destination ... ]]
create pipe_queue queue priority = n server = (server) [destination =
[pipeonly] [run_limit = n]
Defines a pipe queue named queue with interqueue priority n (0-
63) and associate it with a server. This is done by specifying
an absolute pathname to the program binary server and any
arguments required by the program. Following destination is a
list of one or more destination queues that may receive requests
from this pipe queue. If pipeonly is specified, requests may
enter this queue only if their source is a pipe queue. The
run_limit option limits the maximum number of requests allowed
to run in the pipe queue at any given time. The default run
limit is 1.
delete complex complex
Deletes the queue complex.
delete destination = destination queue
delete destination = (destination[, destination ... ]) queue
Deletes the mappings from the pipe queue to the destination
queues. All requests from the named queue being transferred to
a deleted destination complete normally. If all destinations
for a pipe queue are deleted in this manner, the pipe queue is
effectively stopped.
delete device device
Deletes the specified device. A device must be disabled to
delete it from the device set (see disable device below).
delete device = device queue
delete device = (device[, device ... ]) queue
Deletes the mappings from the device queue queue to the devices.
All requests from the named device queue running on any of the
named devices are allowed to complete normally. If all queue-
8 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
to-device mappings for the named device queue are removed by
this command, the queue is effectively stopped.
delete forms form-name ...
Deletes the specified form-names from the list of valid forms.
delete groups = group queue
delete groups = (group[, group ... ]) queue
Deletes the specified groups from the access list for queue.
There are two ways to specify a group:
group-name
[group-id]
delete managers manager ...
Deletes the specified managers from the list of authorized NQS
managers. A manager specification consists of an account name
specification followed by either :m or :o. There are four ways
to specify an account name:
local-account-name
[local-user-id]
[remote-user-id]@remote-machine-name
[remote-user-id]@[remote-machine-id]
If the account name specification is followed by :m, the account
is currently permitted to use all qmgr commands. If the account
name specification is followed by :o, the account is currently
permitted to use only the commands appropriate for an operator
to use. The superuser always has full privileges.
delete queue queue
Deletes the queue. To delete a queue, requests may not be in
the queue and the queue must be disabled. Any queue-to-device
mappings are updated accordingly.
delete users = user queue
delete users = (user [, user ... ]) queue
Deletes the specified users from the access list for queue.
There are two ways to specify a user:
username
[user-id]
remove queue = queue complex
remove queue = (queue[, queue ... ]) complex
Removes the specified queues from the queue complex named
complex. If the queue is the last queue in the queue complex,
the queue complex is deleted.
2/94 - Intergraph Corporation 9
qmgr(8) CLIX qmgr(8)
set debug level
Sets the debug level. The following values are valid:
0 No debug
1 Minimum debug
2 Maximum debug
set default batch_request priority priority
Sets the default intra-batch-queue priority. This is not the
CLIX execution time priority. This is the priority used if the
user does not specify an intra-batch-queue priority parameter on
the qsub command.
set default batch_request queue queue
Sets the default batch queue. This queue is used if the user
does not specify a queue parameter on the qsub command.
set default destination_retry time retry-time
Sets the default number of hours that can elapse during which a
pipe queue destination can be unreachable before being marked as
completely failed.
set default destination_retry wait interval
Sets the default number of minutes to wait before retrying a
pipe queue destination that was unreachable at the last attempt.
set default device_request priority priority
Sets the default intra-device-queue priority. This is the
priority used if the user does not specify an intraqueue
priority parameter on the qpr command.
set default print_request forms form-name
Sets the default print forms to form-name. This is the form
used if the user does not specify a forms parameter on the qpr
command.
set default print_request queue queue
Sets the default print queue. This is the queue used if the
user does not specify a queue parameter on the qpr command.
set destination = destination queue
set destination = (destination[, destination ... ]) queue
Associates one or more destination queues with a particular pipe
queue.
set device = device queue
set device = (device[, device ... ]) queue
Associates one or more devices with a particular queue.
10 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
set device_server = (server) device
Associates a server with a device. The server consists of the
absolute pathname to the program binary followed by any
arguments required by the program.
set forms form-name ...
Specifies the valid form-names. Other valid forms may be added
to this list (see add forms above).
set forms = form-name device
Sets the form-name for a device.
set lifetime lifetime
Sets pipe queue request lifetime in hours.
set log_file filename
Specifies the name of the log file for NQS messages.
set mail user-id
Specifies the user-id used to send NQS mail.
set managers manager ...
Sets the list of authorized NQS managers to the specified
managers. A manager specification consists of an account name
specification followed by either :m or :o. There are four ways
to specify an account name:
local-account-name
[local-user-id]
[remote-user-id]@remote-machine-name
[remote-user-id]@[remote-machine-id]
If the account name specification is followed by :m, the account
is designated as an NQS manager account capable of using all
qmgr commands. If the account name specification is followed by
:o, the account is designated as an NQS operator account capable
of using only those commands appropriate for an NQS operator.
The superuser always has full privileges.
set maximum copies copies
Sets the maximum number of print copies.
set maximum open_retries retries
Specifies the maximum number of retries for a failed device
open.
set maximum print_size size
Specifies the maximum size of an NQS print file in bytes.
set network client = (client)
Specifies the network client to be used. The client consists of
2/94 - Intergraph Corporation 11
qmgr(8) CLIX qmgr(8)
the absolute pathname of the client followed by any arguments
required by the client.
set network daemon = (daemon)
Specifies the network daemon to be used. The daemon parameter
consists of the absolute pathname of the daemon followed by any
arguments required by the daemon.
set network server = (server)
Specifies the network server to be used. The server consists of
the absolute pathname of the server followed by any arguments
required by the server.
set nice_value_limit = nice-value queue
Sets the limit for the nice value of requests in a batch queue.
If a request already in the queue has requested treatment more
favorable than the new nice value, it will not change the new
value. A request specifying a nice value may enter a batch
queue only if the queue's nice-value is numerically less than
(more willing to allow access to the CPU) or equal to the
request's nice value. The nice-value is an integer preceded by
an optional negative sign.
set no_access queue
Specifies that no one will be allowed to place requests in the
queue. The superuser is an exception; requests submitted by the
superuser are always allowed in a queue, even if the superuser
is not explicitly given access.
set no_default batch_request queue
Indicates that a default batch request queue will not exist.
set no_default print_request forms
Indicates that default print request forms will not exist.
set no_default print_request queue
Indicates that a default print request queue will not exist.
set no_network_daemon
Indicates that a network daemon will not exist.
set open_wait interval
Specifies the number of seconds to wait between failed device
opens.
set per_process permfile_limit = (limit) queue
Sets a per-process maximum file size limit for a batch queue to
which the per-process maximum file size limit for a request may
be compared. If the local host does not support per-process
file size limits, this command will report an error. Otherwise,
every batch queue on the local host will have a per-process
12 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
maximum file size limit associated with it at all times. If a
request already in the queue has requested more than the new
limit, it will be given a grandfather clause. A request
specifying a per-process maximum file size limit may enter a
batch queue only if the queue's limit is greater than or equal
to the request's limit.
The format for limit is either .fraction[units] or
integer[.fraction][units] when the limit is a finite limit. If
an infinite limit is needed, the limit may be specified as
unlimited or any initial substring. The integer and fraction
portions of a finite limit may be specified as strings of up to
eight decimal digits. The units may be specified as one of the
following case-sensitive strings:
b Bytes
w Words
kb Kilobytes (2^10 bytes)
kw Kilowords (2^10 words)
mb Megabytes (2^20 bytes)
mw Megawords (2^20 words)
gb Gigabytes (2^30 bytes)
gw Gigawords (2^30 words)
When units are not specified, bytes are assumed. If the limit
is set to unlimited, the only limitations imposed are those of
the physical hardware involved.
set pipe_client = (client) queue
Associates a pipe client with a pipe queue. The client consists
of the absolute pathname to the program binary followed by any
arguments required by the program.
set priority = priority queue
Specifies the interqueue priority of a queue.
set shell_strategy fixed = (shell)
Specifies that shell should be used to execute all batch
requests. The shell variable must be the absolute pathname of a
command interpreter.
set shell_strategy free
Specifies that the free shell strategy should be used to execute
all batch requests. The free shell strategy duplicates the
2/94 - Intergraph Corporation 13
qmgr(8) CLIX qmgr(8)
shell choice that would have been made if the batch request
script had been executed interactively. Under this strategy,
the user's login shell is allowed to determine the shell to be
used to execute the batch request. The user's login shell is
the shell named within the user's entry in the password file
(see the passwd file).
set shell_strategy login
Specifies that the login shell strategy should be used to
execute all batch requests. Under the login shell strategy, the
user's login shell is used to execute the batch request. The
login shell is the shell named in the password file (see the
passwd file).
set unrestricted_access queue
Specifies that requests will not be refused from queue because
of queue access restrictions.
EXAMPLES
1. The following command invokes qmgr in interactive mode, with command
line editing:
qmgr
2. The following command invokes qmgr without editing commands, and will
exit when end-of-file is reached:
echo shutdown | qmgr
DIAGNOSTICS
Unexpected characters past end of otherwise valid command.
Invalid command verb.
Incomplete command specified.
Invalid command verb modifier.
The command syntax was not correct; use the help command to
determine correct syntax.
[parameter] out of bounds.
One of the parameters given for a command was out of bounds; use
the show parameters command to review most limits.
Multiple [parameter] specified
Two or more values were given for a command that was expecting only
one.
EXIT VALUES
14 Intergraph Corporation - 2/94
qmgr(8) CLIX qmgr(8)
The qmgr command exits with a value of 0 if successful. If unsuccessful,
qmgr returns one of the following values:
1 Could not determine the local network address. The workstation has
no Internet address.
2-12 Could not open one of the critical NQS files. NQS may not be
installed on this system, or the NQS configuration was corrupted.
13 Could not access pipe to the local NQS daemon. NQS has not been
installed on this system.
RELATED INFORMATION
Commands: qdel(1), qdev(1), qlimit(1), qpr(1), qstat(1), and qsub(1)
Functions: plock(2)
2/94 - Intergraph Corporation 15