.\" OpenPBS (Portable Batch System) v2.3 Software License .\" .\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc. .\" All rights reserved. .\" .\" --------------------------------------------------------------------------- .\" For a license to use or redistribute the OpenPBS software under conditions .\" other than those described below, or to purchase support for this software, .\" please contact Veridian Systems, PBS Products Department ("Licensor") at: .\" .\" www.OpenPBS.org +1 650 967-4675 sales@OpenPBS.org .\" 877 902-4PBS (US toll-free) .\" --------------------------------------------------------------------------- .\" .\" This license covers use of the OpenPBS v2.3 software (the "Software") at .\" your site or location, and, for certain users, redistribution of the .\" Software to other sites and locations. Use and redistribution of .\" OpenPBS v2.3 in source and binary forms, with or without modification, .\" are permitted provided that all of the following conditions are met. .\" After December 31, 2001, only conditions 3-6 must be met: .\" .\" 1. Commercial and/or non-commercial use of the Software is permitted .\" provided a current software registration is on file at www.OpenPBS.org. .\" If use of this software contributes to a publication, product, or service .\" proper attribution must be given; see www.OpenPBS.org/credit.html .\" .\" 2. Redistribution in any form is only permitted for non-commercial, .\" non-profit purposes. There can be no charge for the Software or any .\" software incorporating the Software. Further, there can be no .\" expectation of revenue generated as a consequence of redistributing .\" the Software. .\" .\" 3. Any Redistribution of source code must retain the above copyright notice .\" and the acknowledgment contained in paragraph 6, this list of conditions .\" and the disclaimer contained in paragraph 7. .\" .\" 4. Any Redistribution in binary form must reproduce the above copyright .\" notice and the acknowledgment contained in paragraph 6, this list of .\" conditions and the disclaimer contained in paragraph 7 in the .\" documentation and/or other materials provided with the distribution. .\" .\" 5. Redistributions in any form must be accompanied by information on how to .\" obtain complete source code for the OpenPBS software and any .\" modifications and/or additions to the OpenPBS software. The source code .\" must either be included in the distribution or be available for no more .\" than the cost of distribution plus a nominal fee, and all modifications .\" and additions to the Software must be freely redistributable by any party .\" (including Licensor) without restriction. .\" .\" 6. All advertising materials mentioning features or use of the Software must .\" display the following acknowledgment: .\" .\" "This product includes software developed by NASA Ames Research Center, .\" Lawrence Livermore National Laboratory, and Veridian Information .\" Solutions, Inc. .\" Visit www.OpenPBS.org for OpenPBS software support, .\" products, and information." .\" .\" 7. DISCLAIMER OF WARRANTY .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT .\" ARE EXPRESSLY DISCLAIMED. .\" .\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE .\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" This license will be governed by the laws of the Commonwealth of Virginia, .\" without reference to its choice of law rules. .if \n(Pb .ig Iq .TH qselect 1B "" Local PBS .\" OpenPBS (Portable Batch System) v2.3 Software License .\" .\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc. .\" All rights reserved. .\" .\" --------------------------------------------------------------------------- .\" For a license to use or redistribute the OpenPBS software under conditions .\" other than those described below, or to purchase support for this software, .\" please contact Veridian Systems, PBS Products Department ("Licensor") at: .\" .\" www.OpenPBS.org +1 650 967-4675 sales@OpenPBS.org .\" 877 902-4PBS (US toll-free) .\" --------------------------------------------------------------------------- .\" .\" This license covers use of the OpenPBS v2.3 software (the "Software") at .\" your site or location, and, for certain users, redistribution of the .\" Software to other sites and locations. Use and redistribution of .\" OpenPBS v2.3 in source and binary forms, with or without modification, .\" are permitted provided that all of the following conditions are met. .\" After December 31, 2001, only conditions 3-6 must be met: .\" .\" 1. Commercial and/or non-commercial use of the Software is permitted .\" provided a current software registration is on file at www.OpenPBS.org. .\" If use of this software contributes to a publication, product, or service .\" proper attribution must be given; see www.OpenPBS.org/credit.html .\" .\" 2. Redistribution in any form is only permitted for non-commercial, .\" non-profit purposes. There can be no charge for the Software or any .\" software incorporating the Software. Further, there can be no .\" expectation of revenue generated as a consequence of redistributing .\" the Software. .\" .\" 3. Any Redistribution of source code must retain the above copyright notice .\" and the acknowledgment contained in paragraph 6, this list of conditions .\" and the disclaimer contained in paragraph 7. .\" .\" 4. Any Redistribution in binary form must reproduce the above copyright .\" notice and the acknowledgment contained in paragraph 6, this list of .\" conditions and the disclaimer contained in paragraph 7 in the .\" documentation and/or other materials provided with the distribution. .\" .\" 5. Redistributions in any form must be accompanied by information on how to .\" obtain complete source code for the OpenPBS software and any .\" modifications and/or additions to the OpenPBS software. The source code .\" must either be included in the distribution or be available for no more .\" than the cost of distribution plus a nominal fee, and all modifications .\" and additions to the Software must be freely redistributable by any party .\" (including Licensor) without restriction. .\" .\" 6. All advertising materials mentioning features or use of the Software must .\" display the following acknowledgment: .\" .\" "This product includes software developed by NASA Ames Research Center, .\" Lawrence Livermore National Laboratory, and Veridian Information .\" Solutions, Inc. .\" Visit www.OpenPBS.org for OpenPBS software support, .\" products, and information." .\" .\" 7. DISCLAIMER OF WARRANTY .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT .\" ARE EXPRESSLY DISCLAIMED. .\" .\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE .\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" This license will be governed by the laws of the Commonwealth of Virginia, .\" without reference to its choice of law rules. .\" The following macros defination, Sh and Sx, are used to allow .\" PBS man pages to be formatted with either -man macros or .\" be included in the PBS ERS which is formatted with -ms. .\" .\" The presence of the register Pb defined as non zero will trigger .\" the use of the Sx alternate form. Otherwise the standard -man .\" SH is used. .\" .de Sh .ie \n(Pb .Sx \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 .el .SH \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 .. .\" .de Sx .RE .sp .B \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 .br .RS .R .. .\" .\" end of special PBS man/ERS macros .\" -- .\" The following macros are style for object names and values. .de Ar \" command/function arguments and operands (italic) .ft 2 .if \\n(.$>0 \&\\$1\f1\\$2 .. .de Av \" data item values (Helv) .if \n(Pb .ft 6 .if !\n(Pb .ft 3 .ps -1 .if \\n(.$>0 \&\\$1\s+1\f1\\$2 .. .de At \" attribute and data item names (Helv Bold) .if \n(Pb .ft 6 .if !\n(Pb .ft 2 .ps -1 .if \\n(.$>0 \&\\$1\s+1\f1\\$2 .. .de Ty \" Type-ins and examples (typewritter) .if \n(Pb .ft 5 .if !\n(Pb .ft 3 .if \\n(.$>0 \&\\$1\f1\\$2 .. .de Er \" Error values ( [Helv] ) .if \n(Pb .ft 6 .if !\n(Pb .ft 3 \&\s-1[\^\\$1\^]\s+1\f1\\$2 .. .de Sc \" Symbolic constants ( {Helv} ) .if \n(Pb .ft 6 .if !\n(Pb .ft 3 \&\s-1{\^\\$1\^}\s+1\f1\\$2 .. .de Al \" Attribute list item, like .IP but set font and size .if !\n(Pb .ig Ig .ft 6 .IP "\&\s-1\\$1\s+1\f1" .Ig .if \n(Pb .ig Ig .ft 2 .IP "\&\\$1\s+1\f1" .Ig .. .\" the following pair of macros are used to bracket sections of code .de Cs .ft 5 .nf .. .de Ce .sp .fi .ft 1 .. .if !\n(Pb .ig Ig .\" define sting Ji as section heading for Job Ids .ds Ji 2.7.6 .\" define sting Di as section heading for Destination Ids .ds Di 2.7.3 .\" define sting Si as section heading for Default Server .ds Si 2.7.4 .Ig .\" End of macros .Iq .SH NAME qselect \- select pbs batch jobs .SH SYNOPSIS qselect [\-a [op]date_time] [\-A account_string] [\-e] [\-c [op]interval] [\-h hold_list] [\-l resource_list] [\-N name] [\-p [op]priority] [\-q destination] [\-r rerun] [\-s states] [\-u user_list] .SH DESCRIPTION The .B qselect command provides a method to list the job identifier of those jobs which meet a list of selection criteria. .if !\n(Pb .ig Ig The selection is accomplished by sending a .I "Select Jobs" batch request to the default server or the server specified by the .Ar \-q option. .Ig Jobs are selected from those owned by a single server. .LP When qselect successfully completes, it will have written to standard output a list of zero or more jobs which meet the criteria specified by the options. Each option acts as a filter restricting the number of jobs which might be listed. With no options, the qselect command will list all jobs at the server which the user is authorized to list (query status of). The \-u option may be used to limit the selection to jobs owned by this user or other specified users. .if !\n(Pb .ig Ig Operators and system administrators have the privilege to select all jobs. Other uses access depends on the setting of the server attribute .At query_other_jobs . .Ig .SH OPTIONS When an option is specified with a optional .Ar op component to the option argument, then .Ar op specifies a relation between the value of a certain job attribute and the value component of the option argument. If an .Ar op is allowable on an option, then the description of the option letter will indicate the .Ar op is allowable. The only acceptable strings for the .Ar op component, and the relation the string indicates, are shown in the following list: .RS 5 .IP .eq. 6 the value represented by the attribute of the job is equal to the value represented by the option argument. .IP .ne. 6 the value represented by the attribute of the job is not equal to the value represented by the option argument. .IP .ge. 6 the value represented by the attribute of the job is greater than or equal to the value represented by the option argument. .IP .gt. 6 the value represented by the attribute of the job is greater than the value represented by the option argument. .IP .le. 6 the value represented by the attribute of the job is less than or equal to the value represented by the option argument. .IP .lt. 6 the value represented by the attribute of the job is less than the value represented by the option argument. .RE .IP "\-a [op]\^date_time " 10 Restricts selection to a specific time, or a range of times. .IP The qselect command selects only jobs for which the value of the .At Execution_Time attribute is related to the .Ar date_time argument by the optional .Ar op operator. The .Ar date_time argument is in the form of the date_time operand of the \fBtouch\fP(1) command: .Ty "[[CC]YY]MMDDhhmm[.SS]" .br where the MM is the two digits for the month, DD is the day of the month, hh is the hour, mm is the minute, and the optional SS is the seconds. CC is the century and YY the year. .IP If .Ar op is not specified, jobs will be selected for which the .At Execution_Time and .Ar date_time values are equal. If .Ar op is specified, jobs will be selected according to the following definitions: .RS .IP .eq. .At Execution_Time attribute is equal to the .Ar date_time argument. .IP .ne. .At Execution_Time attribute is not equal to the .Ar date_time argument. .IP .ge. .At execution_Time attribute is greater than (after) or equal to the .Ar date_time argument. .IP .gt. .At Execution_Time attribute is greater than (after) the .Ar date_time argument. .IP .le. .At Execution_Time attribute is less than (before) or equal to the .Ar date_time argument. .IP .lt. .At Execution_Time attribute is less than (before) the .Ar date_time argument. .RE .IP "\-e" 10 Restricts selection to jobs in execution queues. .IP "\-A account_string" 10 Restricts selection to jobs whose .At Account_Name attribute matches the specified .Ar account_string . .IP "\-c [\^op\^]\^interval" 10 Restricts selection to jobs whose .At Checkpoint interval attribute matches the specified relationship. .IP The values of the .At Checkpoint attribute are defined to have the following ordered relationship: .br \ \ \ \ n\ >\ s\ >\ c=minutes\ >\ c\ >\ u .br If the optional .Ar op is not specified, jobs will be selected whose .At Checkpoint attribute is equal to the .Ar interval argument. If .Ar op is specified, jobs will be selected according to: .RS .IP .eq. .At Checkpoint attribute of the job is equal to the .Ar interval argument. .IP .ne. .At Checkpoint attribute of the job is not equal to the .Ar interval argument. .IP .ge. .At Checkpoint attribute of the job is greater than or equal to the .Ar interval argument. .IP .gt. .At Checkpoint attribute of the job is greater than the .Ar interval argument. .IP .le. .At Checkpoint attribute of the job is less than or equal to the .Ar interval argument. .IP .lt. .At Checkpoint attribute of the job is less than the .Ar interval argument. .RE .IP For an interval value of "u", only ".eq." and ".ne." are valid. .IP "\-h hold_list" 10 Restricts the selection of jobs to those with a specific set of hold types. Only those jobs will be selected whose .At Hold_Types attribute exactly match the value of the .Ar hold_list argument. .RS .LP The .Ar hold_list argument is a string consisting of one or more occurrences the single letter .Ty n , or one or more of the letters .Ty u , .Ty o , or .Ty s in any combination. If letters are duplicated, they are treated as if they occurred once. The letters represent the hold types: .nf \fBn\fP \- none \fBu\fP \- user \fBo\fP \- other \fBs\fP \- system .fi .RE .IP "\-l resource_list" 10 Restricts selection of jobs to those with specified resource amounts. .RS .LP Only those jobs will be selected whose .At Resource_List attribute matches the specified relation with each resource and value listed in the .Ar resource_list argument. The .Ar resource_list is in the following format: .br resource_name\fBop\fPvalue[,resource_name\fBop\fPval,...] .br The relation operator .Ar op must be present. .LP When comparing the values of resources, the following definitions for the operator apply: .IP .eq. the resource value in the .At Resource_List attribute of the job equals the value specified in .Ar resource_list . .IP .ne. the resource value in the .At Resource_List attribute of the job is not equal to the value specified in .Ar resource_list . .IP .ge. the resource value in the .At Resource_List attribute of the job is greater than or equal to the value specified in .Ar resource_list . .IP .gt. the resource value in the .At Resource_List attribute of the job is greater than the value specified in .Ar resource_list . .IP .le. the resource value in the .At Resource_List attribute of the job is less than or equal to the value specified in .Ar resource_list . .IP .lt. the resource value in the .At Resource_List attribute of the job is less than the value specified in .Ar resource_list . .RE .IP "\-N name" 10 Restricts selection of jobs to those with a specific name. .IP "\-p [op]priority" 10 Restricts selection of jobs to those with a priority that matches the specified relationship. If .Ar op is not specified, jobs are selected for which the job .At Priority attribute is equal to the .Ar priority .RS .LP If the .Ar op is specified, the relationship is defined as: .IP .eq. .At Priority attribute is equal to the value of the .Ar priority argument. .IP .ne. .At Priority attribute is not equal to the value of the .Ar priority argument. .IP .ge. .At Priority attribute is greater than or equal to the value of the .Ar priority argument. .IP .gt. .At Priority attribute is greater than the value of the .Ar priority argument. .IP .le. .At Priority attribute is less than or equal to the value of the .Ar priority argument. .IP .lt. .At Priority attribute is less than the value of the .Ar priority argument. .RE .IP "\-q destination" 10 Restricts selection to those jobs residing at the specified destination. .RS .LP The .Ar destination may be of one of the following three forms: .br .Ty "\ \ \ \ queue" .br .Ty "\ \ \ \ @server" .br .Ty "\ \ \ \ queue@server" .LP If the .Ar \-q option is not specified, jobs will be selected from the default server. .if !\n(Pb .ig Ig See the ERS section \*(Si for a definition of the default server. .Ig .LP If the .Ar destination describes only a queue, only jobs in that queue on the default batch server will be selected. .LP If the .Ar destination describes only a server, then jobs in all queues on that server will be selected. .LP If the .Ar destination describes both a queue and a server, then only jobs in the named queue on the named server will be selected. .RE .IP \-r\ rerun Restricts selection of jobs to those with the specified .At Rerunable attribute. The option argument must be a single character. The following two characters are supported by PBS: .Ty y and .Ty n . .IP "\-s states" 10 Restricts job selection to those in the specified states. .RS .LP The .Ar states argument is a character string which consists of any combination of the characters: .Ty E , .Ty H , .Ty Q , .Ty R , .Ty T , and .Ty W . .if !\n(Pb .ig Ig .SM This set of state letters does not conform to the POSIX 1003.2d standard. It requires the sames letters, but in lower case. .NL A repeated character will be accepted, but no additional meaning is assigned to it. .Ig .LP The characters in the .Ar states argument have the following interpretation: .IP \fBE\fP 5 the Exiting state. .IP \fBH\fP 5 the Held state. .IP \fBQ\fP 5 the Queued state. .IP \fBR\fP 5 the Running state. .IP \fBT\fP 5 the Transiting state. .IP \fBW\fP 5 the Waiting state. .LP Jobs will be selected which are in any of the specified states. .RE .IP "\-u user_list" 10 Restricts selection to jobs owned by the specified user names. .RS .LP This provides a means of limiting the selection to jobs owned by one or more users. .if !\n(Pb .ig Ig The ability to select jobs owned by others is controllable by the server attribute .At query_other_jobs . Mapping between user names on different hosts and validation of privilege to access the specified user name is discussed under the server. This option may also be used by batch operators and batch administrators to select jobs belonging to other users. .Ig .LP The syntax of the .Ar user_list is: .br .Ty "\ \ \ \ user_name[@host][,user_name[@host],...]" .br 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. Jobs will be selected which are owned by the listed users at the corresponding hosts. .RE .SH STANDARD OUTPUT The list of job identifiers of selected jobs is written to standard output. Each job identifier is separated by white space. Each job identifier is of the form: .br .Ty "\ \ \ \ sequence_number.server_name@server" .br Where .Ty "sequence_number.server" is the identifier assigned at submission time, see .BR qsub . .Ty @server identifies the server which currently owns the job. .SH STANDARD ERROR The qselect command will write a diagnostic message to standard error for each error occurrence. .SH EXIT STATUS Upon successful processing of all options presented to the qselect command, the exit status will be a value of zero. .LP If the qselect command fails to process any option, the command exits with a value greater than zero. .SH SEE ALSO qsub(1B), qstat(1B), pbs_selectjob(3B), pbs_selstat(3B), pbs_statjob(3B) \" turn off any extra indent left by the Sh macro .RE