qselect.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd>The value of the <i>Priority</i> attribute of the batch job equals the value of the <i>priority</i> component of the
option-argument.</dd>

<dt><tt>.ge.</tt></dt>

<dd>The value of the <i>Priority</i> attribute of the batch job is greater than or equal to the value of the <i>priority</i>
component option-argument.</dd>

<dt><tt>.gt.</tt></dt>

<dd>The value of the <i>Priority</i> attribute of the batch job is greater than the value of the <i>priority</i> component
option-argument.</dd>

<dt><tt>.lt.</tt></dt>

<dd>The value of the <i>Priority</i> attribute of the batch job is less than the value of the <i>priority</i> component
option-argument.</dd>

<dt><tt>.lt.</tt></dt>

<dd>The value of the <i>Priority</i> attribute of the batch job is less than or equal to the value of the <i>priority</i> component
option-argument.</dd>

<dt><tt>.ne.</tt></dt>

<dd>The value of the <i>Priority</i> attribute of the batch job does not equal the value of the <i>priority</i> component
option-argument.</dd>
</dl>
</dd>

<dt><b>-q&nbsp;</b> <i>destination</i></dt>

<dd><br>
Restrict selection to the specified batch queue or server, or both. 

<p>The <i>qselect</i> utility shall select only batch jobs that are located at the destination indicated by the value of the
<i>destination</i> option-argument.</p>

<p>The destination defines a batch queue, a server, or a batch queue at a server.</p>

<p>The <i>qselect</i> utility shall accept an option-argument for the <b>-q</b> option that conforms to the syntax for a
destination. If the <b>-q</b> option is not presented to the <i>qselect</i> utility, the utility shall select batch jobs from all
batch queues at the default batch server.</p>

<p>If the option-argument describes only a batch queue, the <i>qselect</i> utility shall select only batch jobs from the batch
queue of the specified name at the default batch server. The means by which <i>qselect</i> determines the default server is
implementation-defined.</p>

<p>If the option-argument describes only a batch server, the <i>qselect</i> utility shall select batch jobs from all the batch
queues at that batch server.</p>

<p>If the option-argument describes both a batch queue and a batch server, the <i>qselect</i> utility shall select only batch jobs
from the specified batch queue at the specified server.</p>
</dd>

<dt><b>-r&nbsp;</b> <tt>y</tt>|<tt>n</tt></dt>

<dd>Restrict selection to batch jobs with the specified rerunability status. 

<p>The <i>qselect</i> utility shall select only batch jobs for which the value of the <i>Rerunable</i> attribute of the batch job
matches the value of the option-argument.</p>

<p>The <i>qselect</i> utility shall accept a value for the option-argument that consists of either the single character
<tt>'y'</tt> or the single character <tt>'n'</tt> . The character <tt>'y'</tt> represents the value TRUE, and the character
<tt>'n'</tt> represents the value FALSE.</p>
</dd>

<dt><b>-s&nbsp;</b> <i>states</i></dt>

<dd>Restrict selection to batch jobs in the specified states. 

<p>The <i>qselect</i> utility shall accept an option-argument that consists of any combination of the characters <tt>'e'</tt> ,
<tt>'q'</tt> , <tt>'r'</tt> , <tt>'w'</tt> , <tt>'h'</tt> , and <tt>'t'</tt> .</p>

<p>Conforming applications shall not repeat any character in the option-argument. The <i>qselect</i> utility shall permit the
repetition of characters in the option-argument, but shall not assign additional meaning to repeated characters.</p>

<p>The <i>qselect</i> utility shall interpret the characters in the <i>states</i> option-argument as follows:</p>

<dl compact>
<dt><tt>e</tt></dt>

<dd>Represents the EXITING state.</dd>

<dt><tt>q</tt></dt>

<dd>Represents the QUEUED state.</dd>

<dt><tt>r</tt></dt>

<dd>Represents the RUNNING state.</dd>

<dt><tt>t</tt></dt>

<dd>Represents the TRANSITING state.</dd>

<dt><tt>h</tt></dt>

<dd>Represents the HELD state.</dd>

<dt><tt>w</tt></dt>

<dd>Represents the WAITING state.</dd>
</dl>

<p>For each character in the <i>states</i> option-argument, the <i>qselect</i> utility shall select batch jobs in the corresponding
state.</p>
</dd>

<dt><b>-u&nbsp;</b> <i>user_list</i></dt>

<dd>Restrict selection to batch jobs owned by the specified user names. 

<p>The <i>qselect</i> utility shall select only the batch jobs of those users specified in the <i>user_list</i>
option-argument.</p>

<p>The <i>qselect</i> utility shall accept a <i>user_list</i> option-argument that conforms to the following syntax:</p>

<pre>
<i>username</i><b>[</b><tt>@</tt><i>host</i><b>][</b><tt>,,</tt><i>username</i><b>[</b><tt>@</tt><i>host</i><b>]</b><tt>,, ...</tt><b>]</b>
</pre>

<p>The <i>qselect</i> utility shall accept only one user name that is missing a corresponding host name. The <i>qselect</i> utility
shall accept only one user name per named host.</p>
</dd>
</dl>
</blockquote>

<h4><a name="tag_04_113_05"></a>OPERANDS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_06"></a>STDIN</h4>

<blockquote>
<p>Not used.</p>
</blockquote>

<h4><a name="tag_04_113_07"></a>INPUT FILES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_08"></a>ENVIRONMENT VARIABLES</h4>

<blockquote>
<p>The following environment variables shall affect the execution of <i>qselect</i>:</p>

<dl compact>
<dt><i>LANG</i></dt>

<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
the precedence of internationalization variables used to determine the values of locale categories.)</dd>

<dt><i>LC_ALL</i></dt>

<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>

<dt><i>LC_CTYPE</i></dt>

<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments).</dd>

<dt><i>LC_MESSAGES</i></dt>

<dd>Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard
error.</dd>

<dt><i>LOGNAME</i></dt>

<dd>Determine the login name of the user.</dd>

<dt><i>TZ</i></dt>

<dd>Determine the timezone used to interpret the <i>date-time</i> option-argument. If <i>TZ</i> is unset or null, an unspecified
default timezone shall be used.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_113_09"></a>ASYNCHRONOUS EVENTS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<h4><a name="tag_04_113_10"></a>STDOUT</h4>

<blockquote>
<p>The <i>qselect</i> utility shall write zero or more batch <i>job_identifier</i>s to standard output.</p>

<p>The <i>qselect</i> utility shall separate the batch <i>job_identifier</i>s written to standard output by white space.</p>

<p>The <i>qselect</i> utility shall write batch <i>job_identifier</i>s in the following format:</p>

<pre>
<i>sequence_number.server_name</i><tt>@</tt><i>server</i>
</pre>
</blockquote>

<h4><a name="tag_04_113_11"></a>STDERR</h4>

<blockquote>
<p>The standard error shall be used only for diagnostic messages.</p>
</blockquote>

<h4><a name="tag_04_113_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>Successful completion.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_113_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_113_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_17"></a>EXAMPLES</h4>

<blockquote>
<p>The following example shows how a user might use the <i>qselect</i> utility in conjunction with the <a href=
"../utilities/qdel.html"><i>qdel</i></a> utility to delete all of his or her jobs in the queued state without affecting any jobs
that are already running:</p>

<pre>
<tt>qdel $(qselect -s q)
</tt>
</pre>

<p>or:</p>

<pre>
<tt>qselect -s q || xargs qdel
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_113_18"></a>RATIONALE</h4>

<blockquote>
<p>The <i>qselect</i> utility allows users to acquire a list of job identifiers that match user-specified selection criteria. The
list of identifiers returned by the <i>qselect</i> utility conforms to the syntax of the batch job identifier list processed by a
utility such as <a href="../utilities/qmove.html"><i>qmove</i></a>, <a href="../utilities/qdel.html"><i>qdel</i></a>, and <a href=
"../utilities/qrls.html"><i>qrls</i></a>. The <i>qselect</i> utility is thus a powerful tool for causing another batch system
utility to act upon a set of jobs that match a list of selection criteria.</p>

<p>The options of the <i>qselect</i> utility let the user apply a number of useful filters for selecting jobs. Each option further
restricts the selection of jobs. Many of the selection options allow the specification of a relational operator. The FORTRAN-like
syntax of the operator-that is, <tt>".lt."</tt> - was chosen rather than the C-like <tt>"&lt;="</tt> meta-characters.</p>

<p>The <b>-a</b> option allows users to restrict the selected jobs to those that have been submitted (or altered) to wait until a
particular time. The time period is determined by the argument of this option, which includes both a time and an operator-it is
thus possible to select jobs waiting until a specific time, jobs waiting until after a certain time, or those waiting for a time
before the specified time.</p>

<p>The <b>-A</b> option allows users to restrict the selected jobs to those that have been submitted (or altered) to charge a
particular account.</p>

<p>The <b>-c</b> option allows users to restrict the selected jobs to those whose checkpointing interval falls within the specified
range.</p>

<p>The <b>-l</b> option allows users to select those jobs whose resource limits fall within the range indicated by the value of the
option. For example, a user could select those jobs for which the CPU time limit is greater than two hours.</p>

<p>The <b>-N</b> option allows users to select jobs by job name. For instance, all the parts of a task that have been divided in
parallel jobs might be given the same name, and thus manipulated as a group by means of this option.</p>

<p>The <b>-q</b> option allows users to select jobs in a specified queue.</p>

<p>The <b>-r</b> option allows users to select only those jobs with a specified rerun criteria. For instance, a user might select
only those jobs that can be rerun for use with the <a href="../utilities/qrerun.html"><i>qrerun</i></a> utility.</p>

<p>The <b>-s</b> option allows users to select only those jobs that are in a certain state.</p>

<p>The <b>-u</b> option allows users to select jobs that have been submitted to execute under a particular account.</p>

<p>The selection criteria provided by the options of the <i>qselect</i> utility allow users to select jobs based on all the
appropriate attributes that can be assigned to jobs by the <a href="../utilities/qsub.html"><i>qsub</i></a> utility.</p>

<p>Historically, the <i>qselect</i> utility has not been a part of existing practice; it is an improvement that has been introduced
in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>
</blockquote>

<h4><a name="tag_04_113_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_113_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="qdel.html"><i>qdel</i></a> , <a href="qrerun.html"><i>qrerun</i></a> , <a href="qrls.html"><i>qrls</i></a> , <a href=
"#">qselect</a> , <a href="qsub.html"><i>qsub</i></a> , <a href="touch.html"><i>touch</i></a> , <a href=
"xcu_chap03.html#tag_03"><i>Batch Environment Services</i></a></p>
</blockquote>

<h4><a name="tag_04_113_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>Derived from IEEE&nbsp;Std&nbsp;1003.2d-1994.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>