qsub.html

IEEE 1003.1-2003, Single Unix Specification v3

the created batch job to standard output.</p>

<p>If the <b>-z</b> option is not presented to the <i>qsub</i> utility, the utility shall write the identifier of the created batch
job to standard output.</p>
</dd>
</dl>
</blockquote>

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

<blockquote>
<p>The <i>qsub</i> utility shall accept a <i>script</i> operand that indicates the path to the script of the batch job.</p>

<p>If the <i>script</i> operand is not presented to the <i>qsub</i> utility, or if the operand is the single-character string
<tt>'-'</tt> , the utility shall read the script from standard input.</p>

<p>If the script represents a partial path, the <i>qsub</i> utility shall expand the path relative to the current directory of the
process executing the utility.</p>
</blockquote>

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

<blockquote>
<p>The <i>qsub</i> utility reads the script of the batch job from standard input if the script operand is omitted or is the single
character <tt>'-'</tt> .</p>
</blockquote>

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

<blockquote>
<p>In addition to binding the file indicated by the <i>script</i> operand to the batch job, the <i>qsub</i> utility reads the
script file and acts on directives in the script.</p>
</blockquote>

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

<blockquote>
<p>The following environment variables shall affect the execution of <i>qsub</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>PBS_DPREFIX</i></dt>

<dd><br>
Determine the default prefix for directives within the script.</dd>

<dt><i>SHELL</i></dt>

<dd>Determine the pathname of the preferred command language interpreter 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_116_09"></a>ASYNCHRONOUS EVENTS</h4>

<blockquote>
<p>Once created, a batch job exists until it exits, aborts, or is deleted.</p>

<p>After a batch job is created by the <i>qsub</i> utility, batch servers might route, execute, modify, or delete the batch
job.</p>
</blockquote>

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

<blockquote>
<p>The <i>qsub</i> utility writes the batch <i>job_identifier</i> assigned to the batch job to standard output, unless the
<b>-z</b> option is specified.</p>
</blockquote>

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

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

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

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

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

<blockquote>
<h5><a name="tag_04_116_13_01"></a>Script Preservation</h5>

<p>The <i>qsub</i> utility shall make the script available to the server executing the batch job in such a way that the server
executes the script as it exists at the time of submission.</p>

<p>The <i>qsub</i> utility can send a copy of the script to the server with the <i>Queue Job Request</i> or store a temporary copy
of the script in a location specified to the server.</p>

<h5><a name="tag_04_116_13_02"></a>Option Specification</h5>

<p>A script can contain directives to the <i>qsub</i> utility.</p>

<p>The <i>qsub</i> utility shall scan the lines of the script for directives, skipping blank lines, until the first line that
begins with a string other than the directive string; if directives occur on subsequent lines, the utility shall ignore those
directives.</p>

<p>Lines are separated by a &lt;newline&gt;. If the first line of the script begins with <tt>"#!"</tt> or a colon ( <tt>':'</tt> ),
then it is skipped. The <i>qsub</i> utility shall process a line in the script as a directive if and only if the string of
characters from the first non-white-space character on the line until the first &lt;space&gt; or &lt;tab&gt; on the line match the
directive prefix. If a line in the script contains a directive and the final characters of the line are backslash ( <tt>'\'</tt> )
and &lt;newline&gt;, then the next line shall be interpreted as a continuation of that directive.</p>

<p>The <i>qsub</i> utility shall process the options and option-arguments contained on the directive prefix line using the same
syntax as if the options were input on the <i>qsub</i> utility.</p>

<p>The <i>qsub</i> utility shall continue to process a directive prefix line until after a &lt;newline&gt; is encountered. An
implementation may ignore lines which, according to the syntax of the shell that will interpret the script, are comments. An
implementation shall describe in the conformance document the format of any shell comments that it will recognize.</p>

<p>If an option is present in both a directive and the arguments to the <i>qsub</i> utility, the utility shall ignore the option
and the corresponding option-argument, if any, in the directive.</p>

<p>If an option that is present in the directive is not present in the arguments to the <i>qsub</i> utility, the utility shall
process the option and the option-argument, if any.</p>

<p>In order of preference, the <i>qsub</i> utility shall select the directive prefix from one of the following sources:</p>

<ul>
<li>
<p>If the <b>-C</b> option is presented to the utility, the value of the <i>directive_prefix</i> option-argument</p>
</li>

<li>
<p>If the environment variable <i>PBS_DPREFIX</i> is defined, the value of that variable</p>
</li>

<li>
<p>The four-character string <tt>"#PBS"</tt> encoded in the portable character set</p>
</li>
</ul>

<p>If the <b>-C</b> option is present in the script file it shall be ignored.</p>
</blockquote>

<h4><a name="tag_04_116_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_116_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_116_16"></a>APPLICATION USAGE</h4>

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

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

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

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

<blockquote>
<p>The <i>qsub</i> utility allows users to create a batch job that will process the script specified as the operand of the
utility.</p>

<p>The options of the <i>qsub</i> utility allow users to control many aspects of the queuing and execution of a batch job.</p>

<p>The <b>-a</b> option allows users to designate the time after which the batch job will become eligible to run. By specifying an
execution time, users can take advantage of resources at off-peak hours, synchronize jobs with chronologically predictable events,
and perhaps take advantage of off-peak pricing of computing time. For these reasons and others, a timing option is existing
practice on the part of almost every batch system, including NQS.</p>

<p>The <b>-A</b> option allows users to specify the account that will be charged for the batch job. Support for account is not
mandatory for conforming batch servers.</p>

<p>The <b>-C</b> option allows users to prescribe the prefix for directives within the script file. The default prefix
<tt>"#PBS"</tt> may be inappropriate if the script will be interpreted with an alternate shell, as specified by the <b>-S</b>
option.</p>

<p>The <b>-c</b> option allows users to establish the checkpointing interval for their jobs. A checkpointing system, which is not
defined by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, allows recovery of a batch job at the most recent checkpoint in the event
of a crash. Checkpointing is typically used for jobs that consume expensive computing time or must meet a critical schedule. Users
should be allowed to make the tradeoff between the overhead of checkpointing and the risk to the timely completion of the batch
job; therefore, this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 provides the checkpointing interval option. Support for checkpointing
is optional for batch servers.</p>

<p>The <b>-e</b> option allows users to redirect the standard error streams of their jobs to a non-default path. For example, if
the submitted script generally produces a great deal of useless error output, a user might redirect the standard error output to
the null device. Or, if the file system holding the default location (the home directory of the user) has too little free space,
the user might redirect the standard error stream to a file in another file system.</p>

<p>The <b>-h</b> option allows users to create a batch job that is held until explicitly released. The ability to create a held job
is useful when some external event must complete before the batch job can execute. For example, the user might submit a held job
and release it when the system load has dropped.</p>

<p>The <b>-j</b> option allows users to merge the standard error of a batch job into its standard output stream, which has the
advantage of showing the sequential relationship between output and error messages.</p>

<p>The <b>-m</b> option allows users to designate those points in the execution of a batch job at which mail will be sent to the
submitting user, or to the account(s) indicated by the <b>-M</b> option. By requesting mail notification at points of interest in
the life of a job, the submitting user, or other designated users, can track the progress of a batch job.</p>

<p>The <b>-N</b> option allows users to associate a name with the batch job. The job name in no way affects the processing of the
batch job, but rather serves as a mnemonic handle for users. For example, the batch job name can help the user distinguish between
multiple jobs listed by the <a href="../utilities/qstat.html"><i>qstat</i></a> utility.</p>

<p>The <b>-o</b> option allows users to redirect the standard output stream. A user might, for example, wish to redirect to the
null device the standard output stream of a job that produces copious yet superfluous output.</p>

<p>The <b>-P</b> option allows users to designate the relative priority of a batch job for selection from a queue.</p>

<p>The <b>-q</b> option allows users to specify an initial queue for the batch job. If the user specifies a routing queue, the
batch server routes the batch job to another queue for execution or further routing. If the user specifies a non-routing queue, the
batch server of the queue eventually executes the batch job.</p>

<p>The <b>-r</b> option allows users to control whether the submitted job will be rerun if the controlling batch node fails during
execution of the batch job. The <b>-r</b> option likewise allows users to indicate whether or not the batch job is eligible to be
rerun by the <a href="../utilities/qrerun.html"><i>qrerun</i></a> utility. Some jobs cannot be correctly rerun because of changes
they make in the state of databases or other aspects of their environment. This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 specifies
that the default, if the <b>-r</b> option is not presented to the utility, will be that the batch job cannot be rerun, since the
result of rerunning a non-rerunnable job might be catastrophic.</p>

<p>The <b>-S</b> option allows users to specify the program (usually a shell) that will be invoked to process the script of the
batch job. This option has been modified to allow a list of shell names and locations associated with different hosts.</p>

<p>The <b>-u</b> option is useful when the submitting user is authorized to use more than one account on a given host, in which
case the <b>-u</b> option allows the user to select from among those accounts. The option-argument is a list of user-host pairs, so
that the submitting user can provide different user identifiers for different nodes in the event the batch job is routed. The
<b>-u</b> option provides a lot of flexibility to accommodate sites with complex account structures. Users that have the same user
identifier on all the hosts they are authorized to use will not need to use the <b>-u</b> option.</p>

<p>The <b>-V</b> option allows users to export all their current environment variables, as of the time the batch job is submitted,
to the context of the processes of the batch job.</p>

<p>The <b>-v</b> option allows users to export specific environment variables from their current process to the processes of the
batch job.</p>

<p>The <b>-z</b> option allows users to suppress the writing of the batch job identifier to standard output. The <b>-z</b> option
is an existing NQS practice that has been standardized.</p>

<p>Historically, the <i>qsub</i> utility has served the batch job-submission function in the NQS system, the existing practice on
which it is based. Some changes and additions have been made to the <i>qsub</i> utility in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <i>vis-a-vis</i> NQS, as a result of the growing pool of experience with distributed batch
systems.</p>

<p>The set of features of the <i>qsub</i> utility as defined in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 appears to
incorporate all the common existing practice on potentially conforming platforms.</p>
</blockquote>

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

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

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

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

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

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

<h4><a name="tag_04_116_22"></a>Issue 6</h4>

<blockquote>
<p>The <b>-l</b> option has been removed as there is no portable description of the resources that are allowed or required by the
batch job.</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>