openpbs/doc/man1/qselect.1B

.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\" FOR A PARTICULAR PURPOSE.
.\" See the GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH qselect 1B "11 January 2018" Local "PBS Professional"
.SH NAME
.B qselect 
- select specified PBS jobs
.SH SYNOPSIS
.B qselect
[-a [<op>] <date and time>] [-A <account string>] 
.RS 8
[-c [<op>] <interval>] [-h <hold list>] [-H] [-J] 
.br
[-l <resource list>] [-N <name>] [-p [<op>] <priority>] 
.br
[-P <project>] [-q <destination>] [-r <rerun>] [-s <states>] 
.br
[-t <time option> [<comparison>] <specified time>] [-T] 
.br
[-u <user list>] [-x]
.RE
.br
.B qselect
--version

.SH DESCRIPTION
The
.B qselect
command lists those jobs that meet the specified selection criteria.
You can compare certain job attribute values to specified values using
a comparison operator shown as 
.I op 
in the option description.

You can select jobs, job arrays, or subjobs.  You can select jobs from
one server per call to the command.

Each option acts as a filter restricting which jobs are listed.  

You can select jobs according to the values of some of the resources
in the 
.I Resource_List 
job attribute.  You can also select jobs
according the selection directive (although because this is a string,
you can only check for equality or inequality.)

Jobs that are finished or moved are listed only when the 
.I -x 
or 
.I -H
options are used.  Otherwise, job selection is limited to queued and
running jobs.

.B Comparison Operations
.br
You can select jobs by comparing the values of certain job attributes
to values you specify.  The following table lists the comparison 
operations you can use:

.B Operation \ \ Type of Comparison
.br
-----------------------------------------------------------------------
.IP .eq. 12
The value of the attribute of the job is equal to the value of the
option argument.
.IP .ne. 12
The value of the attribute of the job is not equal to the value of the
option argument.
.IP .ge. 12
The value of the attribute of the job is greater than or equal to the
value of the option argument.
.IP .gt. 12	
The value of the attribute of the job is greater than the value of the
option argument.
.IP .le. 12
The value of the attribute of the job is less than or equal to the
value of the option argument.
.IP .lt. 12
The value of the attribute of the job is less than the
value of the option argument.
.LP

For example, to select jobs whose 
.I Priority 
attribute has a value greater than 
.I 5:
.br
.B \ \ \ qselect -p.gt.5

Where an optional comparison is not specified, the comparison
operation defaults to 
.I .eq, 
meaning PBS checks whether the value of the
attribute is equal to the option argument.

.B Required Permissions
.br
When selecting jobs according to resource values, users without
Operator or Manager privilege cannot specify custom resources which
were created to be invisible to unprivileged users.

.SH Options to qselect
.IP "(no options)" 8
Lists all jobs at the server which the user is authorized to list
(query status of).

.IP "-a [<op>] <date and time>" 8
.B Deprecated.  
Restricts selection to those jobs whose 
.I Execution_Time
attribute qualifies when compared to the 
.I date and time
argument.  You can select a range of execution times by using this
option twice, to compare to a minimum time and a maximum time.

The 
.I date and time
argument has the format:
.br
.I [[CC]YY]MMDDhhmm[.SS]
.br
where the 
.I MM 
is the two digits for the month, 
.I DD 
is the day of the month, 
.I hh 
is the hour, 
.I mm 
is the minute, and the optional 
.I SS 
is the seconds.  
.I CC 
is the century and 
.I YY 
the year.

.IP "-A <account string>" 8
Restricts selection to jobs whose 
.I Account_Name
attribute matches the specified
.I account string.

.IP "-c [<op>] <interval>" 8
Restricts selection to jobs whose 
.I Checkpoint
interval attribute meets the comparison criteria.

The 
.I interval
argument can take one of the following values:
.RS 11
.I c
.br
.I c=<minutes>
.br
.I n
.br
.I s
.br
.I w
.br
.I w=<minutes>
.RE
.IP " "  8
We give the range of interval  values for the 
.I Checkpoint
attribute the following ordered relationship:
.br
.I  n\ >\ s\ >\ c=minutes\ >\ c\ >\ u

(Information about 
.I w
and 
.I w=<minutes>
is not available.)

For an interval value of 
"u", only ".eq" and ".ne" are valid.

.IP "-h <hold list>" 8
Restricts the selection of jobs to those with a specific set of hold types.
The holds in the 
.I Hold_Types
job attribute must be the same as those in the 
.I hold list
argument, but can be in a different order.

The
.I hold list
argument is a string consisting of the single letter
.I n,
or one or more of the letters
.I u,
.I o,
.I p,
or 
.I s 
in any combination.  If letters are duplicated, they are treated as if they
occurred once.
The letters represent the hold types:

.B Letter \ \ Hold Type
.br
---------------------------------------------------------------
.nf
n        None
u        User
o        Other
p        Bad password
s        System
.fi

.IP "-H" 8
Restricts selection to finished and moved jobs.

.IP "-J" 8
Limits selection to job arrays only.

.IP "-l <resource list>" 8
Restricts selection of jobs to those with specified resource amounts.
Resource must be job-wide, or be 
.I mem, ncpus, 
or 
.I vmem.

The 
.I resource list
is in the following format:
.br
.I <resource name> <op> <value>[,<resource name> <op> <value> ...]

You must specify
.I op,
and you can use any of the comparison operators.

Because resource specifications for chunks using the select statement,
and placement using the place statement, are stored as strings, the
only useful operators for these are 
.I .eq.  
and 
.I .ne.

Unprivileged users cannot specify custom resources
which were created to be invisible to unprivileged users.

.IP "-N <name>" 8
Restricts selection of jobs to those with the specified value for the
.I Job_Name
attribute.

.IP "-p [<op>] <priority>" 8
Restricts selection of jobs to those with the specified 
.I Priority 
value(s).

.IP "-P <project>" 8
Restricts selection of jobs to those matching the specified value for the 
.I project
attribute.

Format: 
.I Project Name;
see the 
.I PBS Professional Reference Guide.

.IP "-q <destination>" 8
Restricts selection to those jobs at the specified 
.I destination.

The
.I destination
may take of one of the following forms:
.RS 11
.I <queue name>
.br
Restricts selection to the specified queue at the default server.
.br
.I @<server name>
.br
Restricts selection to the specified server.
.br
.I <queue name>@<server name>
.br
Restricts selection to the specified queue at the specified server. 
.RE
.IP " " 8
If the -q option is not specified, jobs are selected from the default server.

.IP "-r <rerun>" 8
Restricts selection of jobs to those with the specified value for the 
.I Rerunable
attribute.  The option argument 
.I rerun
must be a single character, either
.I y
or 
.I n.

.IP "-s <states>" 8
Restricts job selection to those whose
.I job_state
attribute has the specified value(s).

The
.I states
argument is a character string consisting of any combination of these
characters:
.I B
, 
.I E
, 
.I F
,
.I H
,
.I M
,
.I Q
,
.I R
,
.I S
,
.I T
,
.I U
,
.I W
, and
.I X.
(A repeated character is accepted, but no additional meaning is
assigned to it.)

.nf
.B State \ \ Meaning
---------------------------------------------------------------
B       Job array has started execution
E       The Exiting state
F       The Finished state
H       The Held state
M       The Moved state
Q       The Queued state
R       The Running state
S       The Suspended state
T       The Transiting state
U       Job suspended due to workstation user activity
W       The Waiting state
X       The eXited state.  Subjobs only
.fi

.IP
Jobs in any of the specified states are selected.

Job arrays are never in states 
.I R, S, T, 
or 
.I U.  
Subjobs may be in those states.

.IP "-t <time option> [<op>] <specified time>" 8
Jobs are selected according to one of their time-based attributes.  The 
.I time option
specifies which time-based attribute is tested.  You give the 
.I specified time
in 
.I datetime
format.  See the 
.I PBS Professional Reference Guide.

The 
.I time option 
is one of the following:

.nf
.B Time 
.B Option \ Time Attribute \ Attribute Description
---------------------------------------------------------------
a       Execution_Time  Timestamp.  Time the job is eligible 
                        for execution.  Specified in datetime 
                        format.

c       ctime           Timestamp; time at which the job was
                        created.  Printed by qstat in 
                        human-readable format.  Output in hooks
                        as seconds since epoch.

e       etime           Timestamp; time when job became 
                        eligible to run, i.e. was enqueued in 
                        an execution queue and was in the "Q" 
                        state.  Reset when a job moves queues, 
                        or is held then released.  Not affected 
                        by qaltering.  Printed by qstat in 
                        human-readable format.  Output in hooks 
                        as seconds since epoch.

g       eligible_time   Amount of eligible time job accrued 
                        waiting to run.  Specified as duration.

m       mtime           Timestamp; the time that the job was 
                        last modified, changed state, or 
                        changed locations.  Printed by qstat in 
                        human-readable format.  Output in hooks 
                        as seconds since epoch.

q       qtime           Timestamp; the time that the job 
                        entered the current queue.  Printed by 
                        qstat in human-readable format.  Output 
                        in hooks as seconds since epoch.

s       stime           Timestamp; time the job started.  
                        Updated when job is restarted.  Printed 
                        by qstat in human-readable format.  
                        Output in hooks as seconds since epoch.

t       estimated.      Job's estimated start time.  Specified 
        start_time      in datetime format.  Printed by qstat in 
                        human-readable format.  Output in hooks 
                        as seconds since epoch.
.fi

To bracket a time period, use the 
.I -t
option twice.
.br
For example, to select jobs using 
.I stime 
between noon and 3 p.m.:
.br
.B \ \ \ qselect -ts.gt.09251200 -ts.lt.09251500

.IP "-T" 8
Limits selection to jobs and subjobs.

.IP "-u <user list>" 8
Restricts selection to jobs owned by the specified usernames.

Syntax of
.I user_list:
.br
.I <username>[@<hostname>][,<username>[@<hostname>],...]

Selects jobs which are owned by the listed users at the corresponding hosts. 
Hostnames may be wildcarded on the left end, e.g. "*.nasa.gov".  A username
without a "@<hostname>" is equivalent to "<username>@*", meaning that it is 
valid at any host.

.IP "-x" 8
Selects finished and moved jobs in addition to queued and running jobs.

.IP "-X" 8
Selects completed or deleted subjobs (subjobs in 
.I X 
state).

.IP "--version" 8
The 
.B qselect
command returns its PBS version information and exits.
This option can only be used alone.

.SH STANDARD OUTPUT
PBS writes a list of the selected job IDs to standard output.  Each
job ID is separated by white space.  A job ID can represent a job, a
job array, or a subjob.  Each job ID has one of the forms:
.br
.I <sequence number>.<server name>[@<server name>]
.br
.I <sequence number>[].<server name>[@<server name>]   
.br
.I <sequence number>[<index>].<server name>[@<server name>]
.br
.I @<server name> 
identifies the server which currently owns the job.

.SH STANDARD ERROR
The 
.B qselect 
command writes a diagnostic message to standard error for
each error occurrence.

.SH EXIT STATUS
.IP Zero 8
Upon successful processing of all options presented to the
.B qselect 
command
.IP "Greater than zero" 8
If the 
.B qselect 
command fails to process any option

.SH SEE ALSO
The
.I PBS Professional User's Guide,
the
.I PBS Professional Administrator's Guide,
.br
qstat(1B),
qsub(1B), 
pbs_job_attributes(7B),
pbs_resources(7B)