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