qstat(1)
qstat - display status of NQS queue(s)
SYNOPSIS
qstat [-a] [-d] [-l] [-m] [-o] [-s] [-u user-name ] [-v] [
queue-name@host-name ... ]
qstat [-x] [-b] [-l] [ queue-name ... ]
qstat [-c] [-b] [-l] [ complex-name ... ]
DESCRIPTION
Qstat displays the status of Network Queueing System (NQS)
queues.
If no queues are specified, then the current state of all
NQS queues on the local host are displayed. Otherwise,
information is displayed for the specified queues only.
Queues may be specified either as queue-name or queue-
name@host-name. In the absence of a host-name specifier,
the local host is assumed.
The various qstat switches are separated into several groups
according to which jobs are selected and how the output is
formatted:
Jobs selected by owner:
Default
Shows only the current user's jobs.
-a Shows all requests.
-u user-name
Shows only those requests belonging to user-name.
Jobs selected by machine:
Default
Shows only jobs on the current machine.
-d Shows all jobs in machines within the local NQS domain.
queue
Shows jobs in a particular queue.
@machine
Shows jobs on a specific machine.
queue@machine
Shows jobs on a specific queue on a particular machine.
Jobs selected by origin:
Shows jobs which originated from anywhere.
-o Shows jobs that originated from the current machine.
The format of the output is determined by other switches:
Default
Shows jobs in the Monsanto summary format.
-m Synonym for the default (Monsanto summary format).
-l Standard NQS format with further detail.
-s Standard NQS format.
The -x switch gives greater detail on the queue header, and
is modified by the -b or -l switches which give lesser or
greater detail, respectively, of the queue header. The
queue header always includes the queue-name, queue type,
queue status (see below), an indication of whether or not
the queue is pipeonly (accepts requests from pipe queues
only), and the number of requests in the queue. An extended
queue header goes on to display the priority and run limit
of a queue, as well as the access restrictions, cumulative
use statistics, server and destinations (if a pipe queue),
queue to device mappings (if a device queue), and resource
limits (if a batch queue).
The -c switch gives information about queue complexes and
the display is modified by the -b and -l switches to give
lesser or greater detail, respectively. The display for the
-b switch gives only the complex name. The default is to
print the complex name and the run limit of that complex.
The -l switch causes the name, the queue run limit, and the
members of that complex to be printed.
By default, qstat displays the following information about a
request: the request-name, the request-id, the owner, the
queuename, the start time, the per-process request time, the
total time the request has been running, and the status of
the request. The -m switch also gives this format.
Qstat -s shows the request-name, the request-id, the owner,
the relative request priority, and the current request state
(see below). For running requests, the process group is
also shown, as soon as this information becomes available to
the local NQS daemon.
Qstat -l shows the time at which the request was created, an
indication of whether or not mail will be sent, where mail
will be sent, and the username on the originating machine.
disposition of stderr and stdout, any advice concerning the
command interpreter, and the umask value are shown. If a
device queue is being examined, the requested forms are
shown.
It must be understood that the relative ordering of requests
within a queue does not always determine the order in which
the requests will be run. The NQS request scheduler is
allowed to make exceptions to the request ordering for the
sake of efficient machine resource usage. However, requests
appearing near the beginning of the queue have higher
priority than requests appearing later, and will usually be
run before requests appearing later on in the queue.
Qstat -d first checks the user's default directory for a
file called .qstat, which is a list of machines to be polled
for the NQS status. If this file is not present, then the
system-wide file in /usr/lib/nqs/nqs-domain is used. In this
manner one may override the system default and choose to get
the status of a different list of machines. The format of
these files is a list of machines with a single machine name
on each line. Lines with a # in the first column are
considered comments and ignored.
QUEUE STATE
The general state of a queue is defined by two principal
properties of the queue.
The first property determines whether or not requests can be
submitted to the queue. If they can, then the queue is said
to be enabled. Otherwise the queue is said to be disabled.
One of the words CLOSED, ENABLED, or DISABLED will appear in
the queue status field to indicate the respective queue
states of: enabled (with no local NQS daemon), enabled (and
local NQS daemon is present), and disabled. Requests can
only be submitted to the queue if the queue is enabled, and
the local NQS daemon is present.
The second principal property of a queue determines if
requests which are ready to run, but are not now presently
running, will be allowed to run upon the completion of any
currently running requests, and whether any requests are
presently running in the queue.
If queued requests not already running are blocked from
running, and no requests are presently executing in the
queue, then the queue is said to be stopped. If the same
situation exists with the difference that at least one
request is running, then the queue is said to be stopping,
where the requests presently executing will be allowed to
complete execution, but no new requests will be spawned.
doing so by the NQS request scheduler, and one or more
requests are presently running in the queue, then the queue
is said to be running. If the same circumstances prevail
with the exception that no requests are presently running in
the queue, then the queue is said to be inactive. Finally,
if the NQS daemon for the local host upon which the queue
resides is not running, but the queue would otherwise be in
the state of running or inactive, then the queue is said to
be shutdown. The queue states describing the second
principal property of a queue are therefore respectively
displayed as STOPPED, STOPPING, RUNNING, INACTIVE, and
SHUTDOWN.
REQUEST STATE
The state of a request may be arriving, holding, waiting,
queued, staging, routing, running, departing, or exiting. A
request is said to be arriving if it is being enqueued from
a remote host. Holding indicates that the request is
presently prevented from entering any other state (including
the running state), because a hold has been placed on the
request. A request is said to be waiting if it was
submitted with the constraint that it not run before a
certain date and time, and that date and time have not yet
arrived. Queued requests are eligible to proceed (by
routing or running). When a request reaches the head of a
pipe queue and receives service there, it is routing. A
request is departing from the time the pipe queue turns to
other work until the request has arrived intact at its
destination. Staging denotes a batch request that has not
yet begun execution, but for which input files are being
brought on to the execution machine. A running request has
reached its final destination queue, and is actually
executing. Finally, exiting describes a batch request that
has completed execution, and will exit from the system after
the required output files have been returned (to possibly
remote machines).
Imagine a batch request originating on a workstation,
destined for the batch queue of a computation engine, to be
run immediately. That request would first go through the
states queued, routing, and departing in a local pipe queue.
Then it would disappear from the pipe queue. From the point
of view of a queue on the computation engine, the request
would first be arriving, then queued, staging (if required
by the batch request), running, and finally exiting. Upon
completion of the exiting phase of execution, the batch
request would disappear from the batch queue.
CAVEATS
NQS is not finished, and continues to undergo development.
Some of the request states shown above may or may not be
EXAMPLES
$ qstat -x
batch@beaker.monsanto.com; type=BATCH; [ENABLED, INACTIVE]; pri=16 lim=1
0 exit; 0 run; 0 stage; 0 queued; 0 wait; 0 hold; 0 arrive;
User run limit= 1
cray@beaker.monsanto.com; type=PIPE; [ENABLED, INACTIVE]; pri=16 lim=1
0 depart; 0 route; 0 queued; 0 wait; 0 hold; 0 arrive;
Destset = {batch@cray};
$ qstat -xl
batch@beaker.monsanto.com; type=BATCH; [ENABLED, INACTIVE]; pri=16 lim=1
0 exit; 0 run; 0 stage; 0 queued; 0 wait; 0 hold; 0 arrive;
User run limit= 1
Cumulative system space time = 1.98 seconds
Cumulative user space time = 0.80 seconds
Unrestricted access
Per-process core file size limit = 32 megabytes <DEFAULT>
Per-process data size limit = 32 megabytes <DEFAULT>
Per-process permanent file size limit = 500 megabytes <DEFAULT>
Queue nondegrading priority = 0
Per-process execution nice value = 0 <DEFAULT>
Per-process stack size limit = 32 megabytes <DEFAULT>
Per-process CPU time limit = 360000.0 <DEFAULT>
Per-process working set limit = 32 megabytes <DEFAULT>
cray@beaker.monsanto.com; type=PIPE; [ENABLED, INACTIVE]; pri=16 lim=1
0 depart; 0 route; 0 queued; 0 wait; 0 hold; 0 arrive;
Cumulative system space time = 0.00 seconds
Cumulative user space time = 0.00 seconds
Unrestricted access
Queue server: /usr/lib/nqs/pipeclient
Destset = {batch@cray};
$ qsub -eo -q batch -r example idle.nqs
$ qstat
Request I.D. Owner Queue Start Time Time Limit Total Time St
-------------- ------ -------- -------- ----------- ---------- ---------- --
example 130 jrroma batch 4/30 11:40 4 04:00:00 0 00:00:00 R
$ qstat -s
batch@beaker.monsanto.com; type=BATCH; [ENABLED, RUNNING]; pri=16 lim=1
0 exit; 1 run; 0 stage; 0 queued; 0 wait; 0 hold; 0 arrive;
User run limit= 1
REQUEST NAME REQUEST ID USER PRI STATE PGRP
1: example 130.beaker jrroma 31 RUNNING 8022
cray@beaker.monsanto.com; type=PIPE; [ENABLED, INACTIVE]; pri=16 lim=1
$ qstat -l
batch@beaker.monsanto.com; type=BATCH; [ENABLED, RUNNING]; pri=16 lim=1
0 exit; 1 run; 0 stage; 0 queued; 0 wait; 0 hold; 0 arrive;
User run limit= 1
Request 1: Name=example
Id=130.beaker Owner=jrroma Priority=31 RUNNING Pgrp=8022
Created at Thu Apr 30 11:39:57 CDT 1992
Mail = [NONE]
Mail address = jrroma@beaker
Owner user name at originating machine = jrroma
Request is notrestartable, notrecoverable.
Broadcast = [NONE]
Per-proc. core file size limit= [32 megabytes, 32 megabytes]<DEFAULT>
Per-proc. data size limit= [32 megabytes, 32 megabytes]<DEFAULT>
Per-proc. permanent file size limit= [500 megabytes, 500 megabytes]<DEFAULT>
Per-proc. execution nice priority = 0 <DEFAULT>
Per-proc. stack size limit= [32 megabytes, 32 megabytes]<DEFAULT>
Per-proc. CPU time limit= [360000.0, 360000.0]<DEFAULT>
Per-proc. working set limit= [32 megabytes, 32 megabytes]<DEFAULT>
Standard-error access mode = EO
Standard-output access mode = SPOOL
Standard-output name = beaker:/usr2/jrroma/tmp/example.o130
Shell = DEFAULT
Umask = 22
cray@beaker.monsanto.com; type=PIPE; [ENABLED, INACTIVE]; pri=16 lim=1
0 depart; 0 route; 0 queued; 0 wait; 0 hold; 0 arrive;
BUGS
One cannot yet get information on a remote queue complex.
SEE ALSO
qdel(1), qdev(1), qlimit(1), qpr(1), and qsub(1)
in the NPSN UNIX System Programmer Reference Manual.
qmgr(1M) in the NPSN UNIX System Administrator Reference
Manual.
NPSN HISTORY
Origin: Sterling Software Incorporated
August 1985 - Brent Kingsbury, Sterling Software
Original release.
May 1986
Second release.
August 1994 - John Roman, Monsanto Company
Release 3.36