QSTAT(1)

NAME
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:

Default
    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. If a batch queue is being examined, resource limits, planned 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.

If queued requests ready to run are only prevented from 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 supported in your version of NQS.

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
  0 depart;   0 route;   0 queued;   0 wait;   0 hold;   0 arrive;
$ 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