xcu_chap03.html

IEEE 1003.1-2003, Single Unix Specification v3

<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Select Batch Job Request</i></p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Move Batch Job Request</i></p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Hold Batch Job Request</i></p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Release Batch Job Request</i></p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Server Shutdown Request</i></p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><i>Locate Batch Job Request</i></p>
</td>
<td align="center">
<p class="tent">e</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
<td align="center">
<p class="tent">O</p>
</td>
</tr>
</table>
</center>

<h5><a name="tag_03_02_02_03"></a>Legend</h5>

<dl compact>
<dt>O</dt>

<dd>OK</dd>

<dt>e</dt>

<dd>Error message</dd>
</dl>

<p>The execution of a batch job by a batch server shall be controlled by job, queue, and server attributes, as defined in this
section.</p>

<h5><a name="tag_03_02_02_04"></a>Account_Name Attribute</h5>

<p>Batch accounting is an optional feature of batch servers. If a batch server implements accounting, the statements in this
section apply and the configuration variable POSIX2_PBS_ACCOUNTING shall be set to 1.</p>

<p>A batch server that executes a batch job shall charge the account named in the <i>Account_Name</i> attribute of the batch job
for resources consumed by the batch job.</p>

<p>If the <i>Account_Name</i> attribute of the batch job is absent from the batch job attribute list or is altered while the batch
job is in execution, the batch server action is implementation-defined.</p>

<h5><a name="tag_03_02_02_05"></a>Checkpoint Attribute</h5>

<p>Batch checkpointing is an optional feature of batch servers. If a batch server implements checkpointing, the statements in this
section apply and the configuration variable POSIX2_PBS_CHECKPOINT shall be set to 1.</p>

<p>There are two attributes associated with the checkpointing feature: <i>Checkpoint</i> and <i>Minimum_Cpu_Interval</i>.
<i>Checkpoint</i> is a batch job attribute, while <i>Minimum_Cpu_Interval</i> is a queue attribute. An implementation that does not
support checkpointing shall support the <i>Checkpoint</i> job attribute to the extent that the batch server shall maintain and pass
this attribute to other servers.</p>

<p>The behavior of a batch server that executes a batch job for which the value of the <i>Checkpoint</i> attribute is
CHECKPOINT_UNSPECIFIED is implementation-defined. A batch server that executes a batch job for which the value of the
<i>Checkpoint</i> attribute is NO_CHECKPOINT shall not checkpoint the batch job.</p>

<p>A batch server that executes a batch job for which the value of the <i>Checkpoint</i> attribute is CHECKPOINT_AT_SHUTDOWN shall
checkpoint the batch job only when the batch server accepts a request to shut down during the time when the batch job is in the
RUNNING state.</p>

<p>A batch server that executes a batch job for which the value of the <i>Checkpoint</i> attribute is
CHECKPOINT_AT_MIN_CPU_INTERVAL shall checkpoint the batch job at the interval specified by the <i>Minimum_Cpu_Interval</i>
attribute of the queue for which the batch job has been selected. The <i>Minimum_Cpu_Interval</i> attribute shall be specified in
units of CPU minutes.</p>

<p>A batch server that executes a batch job for which the value of the <i>Checkpoint</i> attribute is an unsigned integer shall
checkpoint the batch job at an interval that is the value of either the <i>Checkpoint</i> attribute, or the
<i>Minimum_Cpu_Interval</i> attribute of the queue for which the batch job has been selected, whichever is greater. Both intervals
shall be in units of CPU minutes. When the <i>Minimum_Cpu_Interval</i> attribute is greater than the <i>Checkpoint</i> attribute,
the batch job shall write a warning message to the standard error stream of the batch job.</p>

<h5><a name="tag_03_02_02_06"></a>Error_Path Attribute</h5>

<p>The <i>Error_Path</i> attribute of a running job cannot be changed by a <i>Modify Batch Job Request</i>. When the
<i>Join_Path</i> attribute of the batch job is set to the value FALSE and the <i>Keep_Files</i> attribute of the batch job does not
contain the value KEEP_STD_ERROR, a batch server that executes a batch job shall perform one of the following actions:</p>

<ul>
<li>
<p>Set the standard error stream of the session leader of the batch job to the path described by the value of the <i>Error_Path</i>
attribute of the batch job.</p>
</li>

<li>
<p>Buffer the standard error of the session leader of the batch job until completion of the batch job, and when the batch job exits
return the contents to the destination described by the value of the <i>Error_Path</i> attribute of the batch job.</p>
</li>
</ul>

<p>Applications shall not rely on having access to the standard error of a batch job prior to the completion of the batch job.</p>

<p>When the <i>Error_Path</i> attribute does not specify a host name, then the batch server shall retain the standard error of the
batch job on the host of execution.</p>

<p>When the <i>Error_Path</i> attribute does specify a host name and the <i>Keep_Files</i> attribute does not contain the value
KEEP_STD_ERROR, then the final destination of the standard error of the batch job shall be on the host whose host name is
specified.</p>

<p>If the path indicated by the value of the <i>Error_Path</i> attribute of the batch job is a relative path, the batch server
shall expand the path relative to the home directory of the user on the host to which the file is being returned.</p>

<p>When the batch server buffers the standard error of the batch job and the file cannot be opened for write upon completion of the
batch job, then the server shall place the standard error in an implementation-defined location and notify the user of the location
via mail. It shall be possible for the user to process this mail using the <a href="../utilities/mailx.html"><i>mailx</i></a>
utility.</p>

<p>If a batch server that does not buffer the standard error cannot open the standard error path of the batch job for write access,
then the batch server shall abort the batch job.</p>

<h5><a name="tag_03_02_02_07"></a>Execution_Time Attribute</h5>

<p>A batch server shall not execute a batch job before the time represented by the value of the <i>Execution_Time</i> attribute of
the batch job. The <i>Execution_Time</i> attribute is defined in seconds since the Epoch.</p>

<h5><a name="tag_03_02_02_08"></a>Hold_Types Attribute</h5>

<p>A batch server shall support the following hold types:</p>

<dl compact>
<dt><tt>s</tt></dt>

<dd>Can be set or released by a user with at least a privilege level of batch administrator (SYSTEM).</dd>

<dt><tt>o</tt></dt>

<dd>Can be set or released by a user with at least a privilege level of batch operator (OPERATOR).</dd>

<dt><tt>u</tt></dt>

<dd>Can be set or released by the user with at least a privilege level of user, where the user is defined in the <i>Job_Owner</i>
attribute (USER).</dd>

<dt><tt>n</tt></dt>

<dd>Indicates that none of the <i>Hold_Types</i> attributes are set (NO_HOLD).</dd>
</dl>

<p>An implementation may define other hold types. Any additional hold types, how they are specified, their internal representation,
their behavior, and how they affect the behavior of other utilities are implementation-defined.</p>

<p>The value of the <i>Hold_Types</i> attribute shall be the union of the valid hold types ( <tt>'s'</tt> , <tt>'o'</tt> ,
<tt>'u'</tt> , and any implementation-defined hold types), or <tt>'n'</tt> .</p>

<p>A batch server shall not execute a batch job if the <i>Hold_Types</i> attribute of the batch job has a value other than NO_HOLD.
If the <i>Hold_Types</i> attribute of the batch job has a value other than NO_HOLD, the batch job shall be in the HELD state.</p>

<h5><a name="tag_03_02_02_09"></a>Job_Owner Attribute</h5>

<p>The <i>Job_Owner</i> attribute consists of a pair of user name and host name values of the form:</p>

<blockquote>
<pre>
<tt>username@hostname
</tt>
</pre>
</blockquote>

<p>A batch server that accepts a <i>Queue Batch Job Request</i> shall set the <i>Job_Owner</i> attribute to a string that is the
<i>username</i>@ <i>hostname</i> of the user who submitted the job.</p>

<h5><a name="tag_03_02_02_10"></a>Join_Path Attribute</h5>

<p>A batch server that executes a batch job for which the value of the <i>Join_Path</i> attribute is TRUE shall ignore the value of
the <i>Error_Path</i> attribute and merge the standard error of the batch job with the standard output of the batch job.</p>

<h5><a name="tag_03_02_02_11"></a>Keep_Files Attribute</h5>

<p>A batch server that executes a batch job for which the value of the <i>Keep_Files</i> attribute includes the value
KEEP_STD_OUTPUT shall retain the standard output of the batch job on the host where execution occurs. The standard output shall be
retained in the home directory of the user under whose user ID the batch job is executed and the filename shall be the default
filename for the standard output as defined under the <b>-o</b> option of the <a href="../utilities/qsub.html"><i>qsub</i></a>
utility. The <i>Output_Path</i> attribute is not modified.</p>

<p>A batch server that executes a batch job for which the value of the <i>Keep_Files</i> attribute includes the value
KEEP_STD_ERROR shall retain the standard error of the batch job on the host where execution occurs. The standard error shall be
retained in the home directory of the user under whose user ID the batch job is executed and the filename shall be the default
filename for standard error as defined under the <b>-e</b> option of the <a href="../utilities/qsub.html"><i>qsub</i></a> utility.
The <i>Error_Path</i> attribute is not modified.</p>

<p>A batch server that executes a batch job for which the value of the <i>Keep_Files</i> attribute includes values other than
KEEP_STD_OUTPUT and KEEP_STD_ERROR shall retain these other files on the host where execution occurs. These files (with
implementation-defined names) shall be retained in the home directory of the user under whose user identifier the batch job is
executed.</p>

<h5><a name="tag_03_02_02_12"></a>Mail_Points and Mail_Users Attributes</h5>

<p>A batch server that executes a batch job for which one of the values of the <i>Mail_Points</i> attribute is the value
MAIL_AT_BEGINNING shall send a mail message to each user account listed in the <i>Mail_Users</i> attribute of the batch job.</p>

<p>The mail message shall contain at least the batch job identifier, queue, and server at which the batch job currently resides,
and the <i>Job_Owner</i> attribute.</p>

<h5><a name="tag_03_02_02_13"></a>Output_Path Attribute</h5>

<p>The <i>Output_Path</i> attribute of a running job cannot be changed by a <i>Modify Batch Job Request</i>. When the
<i>Keep_Files</i> attribute of the batch job does not contain the value KEEP_STD_OUTPUT, a batch server that executes a batch job
shall either:</p>

<ul>
<li>
<p>Set the standard output stream of the session leader of the batch job to the destination described by the value of the
<i>Output_Path</i> attribute of the batch job.</p>

<p>or:</p>
</li>

<li>
<p>Buffer the standard output of the session leader of the batch job until completion of the batch job, and when the batch job
exits return the contents to the destination described by the value of the <i>Output_Path</i> attribute of the batch job.</p>
</li>
</ul>

<p>When the <i>Output_Path</i> attribute does not specify a host name, then the batch server shall retain the standard output of
the batch job on the host of execution.</p>

<p>When the <i>Keep_Files</i> attribute does not contain the value KEEP_STD_OUTPUT and the <i>Output_Path</i> attribute does
specify a host name, then the final destination of the standard output of the batch job shall be on the host specified.</p>

<p>If the path specified in the <i>Output_Path</i> attribute of the batch job is a relative path, the batch server shall expand the
path relative to the home directory of the user on the host to which the file is being returned.</p>

<p>Whether or not the batch server buffers the standard output of the batch job until completion of the batch job is
implementation-defined. Applications shall not rely on having access to the standard output of a batch job prior to the completion
of the batch job.</p>

<p>When the batch server does buffer the standard output of the batch job and the file cannot be opened for write upon completion
of the batch job, then the batch server shall place the standard output in an implementation-defined location and notify the user
of the location via mail. It shall be possible for the user to process this mail using the <a href=
"../utilities/mailx.html"><i>mailx</i></a> utility.</p>

<p>If a batch server that does not buffer the standard output cannot open the standard output path of the batch job for write
access, then the batch server shall abort the batch job.</p>

<h5><a name="tag_03_02_02_14"></a>Priority Attribute</h5>

<p>A batch server implementation may choose to preferentially execute a batch job based on the <i>Priority</i> attribute. The
interpretation of the batch job <i>Priority</i> attribute by a batch server is implementation-defined. If an implementation uses
the <i>Priority</i> attribute, it shall interpret larger values of the <i>Priority</i> attribute to mean the batch job shall be
preferentially selected for execution.</p>

<h5><a name="tag_03_02_02_15"></a>Rerunable Attribute</h5>

<p>A batch job that began execution but did not complete, because the batch server either shut down or terminated abnormally, shall
be requeued if the <i>Rerunable</i> attribute of the batch job has the value TRUE.</p>

<p>If a batch job, which was requeued after beginning execution but prior to completion, has a valid checkpoint file and the batch
server supports checkpointing, then the batch job shall be restarted from the last valid checkpoint.</p>

<p>If the batch job cannot be restarted from a checkpoint, then when a batch job has a <i>Rerunable</i> attribute value of TRUE and
was requeued after beginning execution but prior to completion, the batch server shall place the batch job into execution at the
beginning of the job.</p>

<p>When a batch job has a <i>Rerunable</i> attribute value other than TRUE and was requeued after beginning execution but prior to
completion, and the batch job cannot be restarted from a checkpoint, then the batch server shall abort the batch job.</p>

<h5><a name="tag_03_02_02_16"></a>Resource_List Attribute</h5>

<p>A batch server that executes a batch job shall establish the resource limits of the session leader of the batch job according to
the values of the <i>Resource_List</i> attribute of the batch job. Resource limits shall be enforced by an implementation-defined
method.</p>