qstat(1B) PBS qstat(1B)
NAME
qstat - show status of pbs batch jobs
SYNOPSIS
qstat [-f][-W site_specific] [job_identifier... |
destination...]
qstat [-a|-i|-r] [-n] [-s] [-G|-M] [-R] [-u user_list]
[job_identifier... | destination...]
qstat -Q [-f][-W site_specific] [destination...]
qstat -q [-G|-M] [destination...]
qstat -B [-f][-W site_specific] [server_name...]
DESCRIPTION
The qstat command is used to request the status of jobs,
queues, or a batch server. The requested status is writ
ten to standard out.
When requesting job status, synopsis format 1 or 2, qstat
will output information about each job_identifier or all
jobs at each destination. Jobs for which the user does
not have status privilege are not displayed.
When requesting queue or server status, synopsis format 3
through 5, qstat will output information about each desti
nation.
OPTIONS
-f Specifies that a full status display be written
to standard out.
-a "All" jobs are displayed in the alternative for
mat, see the Standard Output section. If the
operand is a destination id, all jobs at that
destination are displayed. If the operand is a
job id, information about that job is displayed.
-i Job status is displayed in the alternative for
mat. For a destination id operand, status for
jobs at that destination which are not running
are displayed. This includeds jobs which are
queued, held or waiting. If an operand is a job
id, status for that job is displayed regardless
of its state.
-r If an operand is a job id, status for that job
is displayed. For a destination id operand,
status for jobs at that destination which are
running are displayed, this includeds jobs
which are suspended. If an operand is a job id,
status for that job is displayed.
Local 1
qstat(1B) PBS qstat(1B)
-n In addition to the basic information, nodes
allocated to a job are listed.
-s In addition to the basic information, any com
ment provided by the batch administrator or
scheduler is shown.
-G Show size information in giga-bytes.
-M Show size information, disk or memory in mega-
words. A word is considered to be 8 bytes.
-R In addition to other information, disk reserva
tion information is shown. Not applicable to
all systems.
-u Job status is displayed in the alternative for
mat. If an operand is a job id, status for that
job is displayed. For a destination id operand,
status for jobs at that destination which are
owned by the user(s) listed in user_list are
displayed. The syntax of the user_list is:
user_name[@host][,user_name[@host],...]
Host names may be wild carded on the left end,
e.g. "*.nasa.gov". User_name without a "@host"
is equivalent to "user_name@*", that is at any
host.
-Q Specifies that the request is for queue status
and that the operands are destination identi
fiers.
-q Specifies that the request is for queue status
which should be shown in the alternative format.
-B Specifies that the request is for batch server
status and that the operands are the names of
servers.
OPERANDS
If neither the -Q nor the -B option is given, the operands
on the qstat command must be either job identifiers or
destinations identifiers.
If the operand is a job identifier, it must be in the fol
lowing form:
sequence_number[.server_name][@server]
where sequence_number.server_name is the job identifier
assigned at submittal time, see qsub. If the .server_name
is omitted, the name of the default server will be used.
If @server is supplied, the request will be for the job
identifier currently at that Server.
Local 2
qstat(1B) PBS qstat(1B)
If the operand is a destination identifier, it is one of
the following three forms:
queue
@server
queue@server
If queue is specified, the request is for status of all
jobs in that queue at the default server. If the @server
form is given, the request is for status of all jobs at
that server. If a full destination identifier,
queue@server, is given, the request is for status of all
jobs in the named queue at the named server.
If the -Q option is given, the operands are destination
identifiers as specified above. If queue is specified,
the status of that queue at the default server will be
given. If queue@server is specified, the status of the
named queue at the named server will be given. If @server
is specified, the status of all queues at the named server
will be given. If no destination is specified, the status
of all queues at the default server will be given.
If the -B option is given, the operand is the name of a
server.
STANDARD OUTPUT
Displaying Job Status
If job status is being displayed in the default format and
the -f option is not specified, the following items are
displayed on a single line, in the specified order, sepa
rated by white space:
- the job identifier assigned by PBS.
- the job name given by the submitter.
- the job owner
- the CPU time used
- the job state:
E - Job is exiting after having run.
H - Job is held.
Q - job is queued, eligable to run or routed.
R - job is running.
T - job is being moved to new location.
W - job is waiting for its execution time
(-a option) to be reached.
S - (Unicos only) job is suspend.
- the queue in which the job resides
If job status is being displayed and the -f option is
specified, the output will depend on whether qstat was
Local 3
qstat(1B) PBS qstat(1B)
compiled to use a Tcl interpreter. See the configuration
section for details. If Tcl is not being used, full dis
play for each job consists of the header line:
Job Id: job identifier
Followed by one line per job attribute of the form:
attribute_name = value
If any of the options -a, -i, -r, -u, -n, -s, -G or -M are
provided, the alternative display format for jobs is used.
The following items are displayed on a single line, in the
specified order, separated by white space:
- the job identifier assigned by PBS.
- the job owner.
- The queue in which the job currently resides.
- The job name given by the submitter.
- The session id (if the job is running).
- The number of nodes requested by the job.
- The number of cpus or tasks requested by the
job.
- The amount of memory requested by the job.
- Either the cpu time, if specified, or wall time
requested by the job, (hh:mm).
- The job's current state.
- The amount of cpu time or wall time used by the
job (hh:mm).
If the -R option is provied, the line contains:
- the job identifier assigned by PBS.
- the job owner.
- The queue in which the job currently resides.
- The number of nodes requested by the job.
- The number of cpus or tasks requested by the
job.
- The amount of memory requested by the job.
- Either the cpu time or wall time requested by
the job.
Local 4
qstat(1B) PBS qstat(1B)
- The job's current state.
- The amount of cpu time or wall time used by the
job.
- The amount of SRFS space requested on the big
file sysstem.
- The amount of SRFS space requested on the fast
file sysstem.
- The amount of space requested on the parallel
I/O file system.
The last three fields may not contain useful information
at all sites or on all systems.
Displaying Queue Status
If queue status is being displayed and the -f option was
not specified, the following items are displayed on a sin
gle line, in the specified order, separated by white
space:
- the queue name
- the maximum number of jobs that may be run in
the queue concurrently
- the total number of jobs in the queue
- the enable or disabled status of the queue
- the started or stopped status of the queue
- for each job state, the name of the state and
the number of jobs in the queue in that state.
- the type of queue, execution or routing.
If queue status is being displayed and the -f option is
specified, the output will depend on whether qstat was
compiled to use a Tcl interpreter. See the configuration
section for details. If Tcl is not being used, the full
display for each queue consists of the header line:
Queue: queue_name
Followed by one line per queue attribute of the form:
attribute_name = value
If the -q option is specified, queue information is dis
played in the alternative format: The following informa
tion is displayed on a single line:
- the queue name
Local 5
qstat(1B) PBS qstat(1B)
- the maximum amount of memory a job in the queue
may request
- the maximum amount of cpu time a job in the
queue may request
- the maximum amount of wall time a job in the
queue may request
- the maximum amount of nodes a job in the queue
may request
- the number of jobs in the queue in the running
state
- the number of jobs in the queue in the queued
state
- the maximum number (limit) of jobs that may be
run in the queue concurrently
- the state of the queue given by a pair of let
ters:
- either the letter E if the queue is Enabled or
D if Disabled, and
- either the letter R if the queue is Running
(started) or S if Stopped.
Displaying Server Status
If batch server status is being displayed and the -f
option is not specified, the following items are displayed
on a single line, in the specified order, separated by
white space:
- the server name
- the maximum number of jobs that the server may
run concurrently
- the total number of jobs currently managed by
the server
- the status of the server
- for each job state, the name of the state and
the number of jobs in the server in that state
If server status is being displayed and the -f option is
specified, the output will depend on whether qstat was
compiled to use a Tcl interpreter. See the configuration
section for details. If Tcl is not being used, the full
display for the server consist of the header line:
Local 6
qstat(1B) PBS qstat(1B)
Server: server name
Followed by one line per server attribute of the form:
attribute_name = value
STANDARD ERROR
The qstat command will write a diagnostic message to stan
dard error for each error occurrence.
CONFIGURATION
If qstat is compiled with an option to include a Tcl
interpreter, using the -f flag to get a full display
causes a check to be made for a script file to use to out
put the requested information. The first location checked
is $HOME/.qstatrc. If this does not exist, the next loca
tion checked is administrator configured. If one of these
is found, a Tcl interpreter is started and the script file
is passed to it along with three global variables. The
command line arguments are split into two variable named
flags and operands . The status information is passed in
a variable named objects . All of these variables are Tcl
lists. The flags list contains the name of the command
(usually "qstat") as its first element. Any other ele
ments are command line option flags with any options they
use, presented in the order given on the command line.
They are broken up individually so that if two flags are
given together on the command line, they are separated in
the list. For example, if the user typed
qstat -QfWbigdisplay
the flags list would contain
qstat -Q -f -W bigdisplay
The operands list contains all other command line argu
ments following the flags. There will always be at least
one element in operands because if no operands are typed
by the user, the default destination or server name is
used. The objects list contains all the information
retrieved from the server(s) so the Tcl interpreter can
run once to format the entire output. This list has the
same number of elements as the operands list. Each ele
ment is another list with two elements. The first element
is a string giving the type of objects to be found in the
second. The string can take the values "server", "queue",
"job" or "error". The second element will be a list in
which each element is a single batch status object of the
type given by the string discussed above. In the case of
"error", the list will be empty. Each object is again a
list. The first element is the name of the object. The
second is a list of attributes. The third element will be
the object text. All three of these object elements core
spond with fields in the structure batch_status which is
Local 7
qstat(1B) PBS qstat(1B)
described in detail for each type of object by the man
pages for pbs_statjob(3), pbs_statque(3), and pbs_stat--
server(3). Each attribute in the second element list
whose elements correspond with the attrl structure. Each
will be a list with two elements. The first will be the
attribute name and the second will be the attribute value.
EXIT STATUS
Upon successful processing of all the operands presented
to the qstat command, the exit status will be a value of
zero.
If the qstat command fails to process any operand, the
command exits with a value greater than zero.
SEE ALSO
qalter(1B), qsub(1B), pbs_alterjob(3B), pbs_statjob(3B),
pbs_statque(3B), pbs_statserver(3B), pbs_submit(3B),
pbs_job_attributes(7B), pbs_queue_attributes(7B),
pbs_server_attributes(7B), pbs_resources_*(7B) where * is
system type, and the PBS ERS.
Local 8