2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "QSUB" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" qsub
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
qsub \- submit a script
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fBqsub\fP \fB[\fP\fB-a\fP \fIdate_time\fP\fB][\fP\fB-A\fP
|
|
|
|
\fIaccount_string\fP\fB][\fP\fB-c\fP \fIinterval\fP\fB]
|
|
|
|
.br
|
|
|
|
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-C\fP \fIdirective_prefix\fP\fB][\fP\fB-e\fP
|
|
|
|
\fIpath_name\fP\fB][\fP\fB-h\fP\fB][\fP\fB-j\fP \fIjoin_list\fP\fB][\fP\fB-k\fP
|
|
|
|
\fIkeep_list\fP\fB]
|
|
|
|
.br
|
|
|
|
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-m\fP \fImail_options\fP\fB][\fP\fB-M\fP
|
|
|
|
\fImail_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB]
|
|
|
|
.br
|
|
|
|
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIpath_name\fP\fB][\fP\fB-p\fP
|
|
|
|
\fIpriority\fP\fB][\fP\fB-q\fP \fIdestination\fP\fB][\fP\fB-r\fP \fIy\fP\fB|\fP\fIn\fP\fB]
|
|
|
|
.br
|
|
|
|
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-S\fP \fIpath_name_list\fP\fB][\fP\fB-u\fP
|
|
|
|
\fIuser_list\fP\fB][\fP\fB-v\fP \fIvariable_list\fP\fB][\fP\fB-V\fP\fB]
|
|
|
|
.br
|
|
|
|
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-z\fP\fB][\fP\fIscript\fP\fB]\fP\fB\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
To submit a script is to create a batch job that executes the script.
|
|
|
|
A script is submitted by a request to a batch server. The
|
|
|
|
\fIqsub\fP utility is a user-accessible batch client that submits
|
|
|
|
a script.
|
|
|
|
.LP
|
|
|
|
Upon successful completion, the \fIqsub\fP utility shall have created
|
|
|
|
a batch job that will execute the submitted script.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall submit a script by sending a \fIQueue
|
|
|
|
Job Request\fP to a batch server.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall place the value of the following environment
|
|
|
|
variables in the \fIVariable_List\fP attribute of
|
2007-09-20 06:41:41 +00:00
|
|
|
the batch job: \fIHOME\fP, \fILANG\fP, \fILOGNAME\fP, \fIPATH\fP,
|
|
|
|
\fIMAIL\fP, \fISHELL\fP, and \fITZ\fP. The name of
|
2004-11-03 13:51:07 +00:00
|
|
|
the environment variable shall be the current name prefixed with the
|
|
|
|
string PBS_O_.
|
|
|
|
.TP 7
|
|
|
|
\fBNote:\fP
|
|
|
|
If the current value of the \fIHOME\fP variable in the environment
|
|
|
|
space of the \fIqsub\fP utility is \fB/aa/bb/cc\fP, then
|
|
|
|
\fIqsub\fP shall place \fIPBS_O_HOME =\fP \fB/aa/bb/cc\fP in the \fIVariable_List\fP
|
|
|
|
attribute of the batch job.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
In addition to the variables described above, the \fIqsub\fP utility
|
|
|
|
shall add the following variables with the indicated
|
|
|
|
values to the variable list:
|
|
|
|
.TP 7
|
|
|
|
\fIPBS_O_WORKDIR\fP
|
|
|
|
The absolute path of the current working directory of the \fIqsub\fP
|
|
|
|
utility process.
|
|
|
|
.TP 7
|
|
|
|
\fIPBS_O_HOST\fP
|
|
|
|
The name of the host on which the \fIqsub\fP utility is running.
|
|
|
|
.sp
|
|
|
|
.SH OPTIONS
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall conform to the Base Definitions volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
|
|
.LP
|
|
|
|
The following options shall be supported by the implementation:
|
|
|
|
.TP 7
|
|
|
|
\fB-a\ \fP \fIdate_time\fP
|
|
|
|
Define the time at which a batch job becomes eligible for execution.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept an option-argument that conforms
|
|
|
|
to the syntax of the \fItime\fP operand of the \fItouch\fP utility.
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
.ce 1
|
|
|
|
\fBTable: Environment Variable Values (Utilities)\fP
|
|
|
|
.TS C
|
|
|
|
center; l l.
|
|
|
|
\fBVariable Name\fP \fBValue at qsub Time\fP
|
|
|
|
\fIPBS_O_HOME\fP \fIHOME\fP
|
|
|
|
\fIPBS_O_HOST\fP \fIClient host name\fP
|
|
|
|
\fIPBS_O_LANG\fP \fILANG\fP
|
|
|
|
\fIPBS_O_LOGNAME\fP \fILOGNAME\fP
|
|
|
|
\fIPBS_O_PATH\fP \fIPATH\fP
|
|
|
|
\fIPBS_O_MAIL\fP \fIMAIL\fP
|
|
|
|
\fIPBS_O_SHELL\fP \fISHELL\fP
|
|
|
|
\fIPBS_O_TZ\fP \fITZ\fP
|
|
|
|
\fIPBS_O_WORKDIR\fP \fICurrent working directory\fP
|
|
|
|
.TE
|
|
|
|
.TP 7
|
|
|
|
\fBNote:\fP
|
|
|
|
.RS
|
|
|
|
The server that initiates execution of the batch job will add other
|
|
|
|
variables to the batch job's environment; see \fIBatch Job Execution\fP
|
|
|
|
\&.
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the \fIExecution_Time\fP attribute
|
|
|
|
of the batch job to the number of seconds since the Epoch
|
|
|
|
that is equivalent to the local time expressed by the value of the
|
|
|
|
\fIdate_time\fP option-argument. The Epoch is defined in the
|
|
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.149,
|
|
|
|
Epoch.
|
|
|
|
.LP
|
|
|
|
If the \fB-a\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIExecution_Time\fP attribute
|
|
|
|
of the batch job to a time (number of seconds since the Epoch) that
|
|
|
|
is earlier than the time at which the utility exits.
|
|
|
|
.TP 7
|
|
|
|
\fB-A\ \fP \fIaccount_string\fP
|
|
|
|
.sp
|
|
|
|
Define the account to which the resource consumption of the batch
|
|
|
|
job should be charged.
|
|
|
|
.LP
|
|
|
|
The syntax of the \fIaccount_string\fP option-argument is unspecified.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the \fIAccount_Name\fP attribute
|
|
|
|
of the batch job to the value of the \fIaccount_string\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-A\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall omit the \fIAccount_Name\fP attribute
|
|
|
|
from the attributes of the batch job.
|
|
|
|
.TP 7
|
|
|
|
\fB-c\ \fP \fIinterval\fP
|
|
|
|
Define whether the batch job should be checkpointed, and if so, how
|
|
|
|
often.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a value for the interval option-argument
|
|
|
|
that is one of the following:
|
|
|
|
.TP 7
|
|
|
|
\fBn\fP
|
|
|
|
.RS
|
|
|
|
No checkpointing shall be performed on the batch job (NO_CHECKPOINT).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBs\fP
|
|
|
|
.RS
|
|
|
|
Checkpointing shall be performed only when the batch server is shut
|
|
|
|
down (CHECKPOINT_AT_SHUTDOWN).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBc\fP
|
|
|
|
.RS
|
|
|
|
Automatic periodic checkpointing shall be performed at the \fIMinimum_Cpu_Interval\fP
|
|
|
|
attribute of the batch queue, in units
|
|
|
|
of CPU minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBc\fP=\fIminutes\fP
|
|
|
|
.RS
|
|
|
|
Automatic periodic checkpointing shall be performed every \fIminutes\fP
|
|
|
|
of CPU time, or every \fIMinimum_Cpu_Interval\fP
|
|
|
|
minutes, whichever is greater. The \fIminutes\fP argument shall conform
|
|
|
|
to the syntax for unsigned integers and shall be greater
|
|
|
|
than zero.
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the \fICheckpoint\fP attribute of
|
|
|
|
the batch job to the value of the \fIinterval\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-c\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fICheckpoint\fP attribute of
|
|
|
|
the batch job to the single character \fB'u'\fP (CHECKPOINT_UNSPECIFIED).
|
|
|
|
.TP 7
|
|
|
|
\fB-C\ \fP \fIdirective_prefix\fP
|
|
|
|
.sp
|
|
|
|
Define the prefix that declares a directive to the \fIqsub\fP utility
|
|
|
|
within the script.
|
|
|
|
.LP
|
|
|
|
The \fIdirective_prefix\fP is not a batch job attribute; it affects
|
|
|
|
the behavior of the \fIqsub\fP utility.
|
|
|
|
.LP
|
|
|
|
If the \fB-C\fP option is presented to the \fIqsub\fP utility, and
|
|
|
|
the value of the \fIdirective_prefix\fP option-argument is
|
|
|
|
the null string, the utility shall not scan the script file for directives.
|
|
|
|
If the \fB-C\fP option is not presented to the
|
|
|
|
\fIqsub\fP utility, then the value of the \fIPBS_DPREFIX\fP environment
|
|
|
|
variable is used. If the environment variable is not
|
|
|
|
defined, then #PBS encoded in the portable character set is the default.
|
|
|
|
.TP 7
|
|
|
|
\fB-e\ \fP \fIpath_name\fP
|
|
|
|
Define the path to be used for the standard error stream of the batch
|
|
|
|
job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument
|
|
|
|
which can be preceded by a host name element of the form
|
|
|
|
\fIhostname\fP:.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes an absolute pathname,
|
|
|
|
the \fIqsub\fP utility shall set the
|
|
|
|
\fIError_Path\fP attribute of the batch job to the value of the \fIpath_name\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes a relative pathname
|
|
|
|
and no host name element is specified, the \fIqsub\fP
|
|
|
|
utility shall set the \fIError_Path\fP attribute of the batch job
|
|
|
|
to the value of the absolute pathname derived by expanding the
|
|
|
|
\fIpath_name\fP option-argument relative to the current directory
|
|
|
|
of the process executing \fIqsub\fP.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes a relative pathname
|
|
|
|
and a host name element is specified, the \fIqsub\fP
|
|
|
|
utility shall set the \fIError_Path\fP attribute of the batch job
|
|
|
|
to the value of the \fIpath_name\fP option-argument without
|
|
|
|
expansion. The host name element shall be included.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument does not include a host name
|
|
|
|
element, the \fIqsub\fP utility shall prefix the pathname
|
|
|
|
with \fIhostname\fP:, where \fIhostname\fP is the name of the host
|
|
|
|
upon which the \fIqsub\fP utility is being executed.
|
|
|
|
.LP
|
|
|
|
If the \fB-e\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIError_Path\fP attribute of
|
|
|
|
the batch job to the host name and path of the current directory of
|
|
|
|
the submitting process and the default filename.
|
|
|
|
.LP
|
|
|
|
The default filename for standard error has the following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fIjob_name\fP\fB.e\fP\fIsequence_number\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fB-h\fP
|
|
|
|
Specify that a USER hold is applied to the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the value of the \fIHold_Types\fP
|
|
|
|
attribute of the batch job to the value USER.
|
|
|
|
.LP
|
|
|
|
If the \fB-h\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIHold_Types\fP attribute of
|
|
|
|
the batch job to the value NO_HOLD.
|
|
|
|
.TP 7
|
|
|
|
\fB-j\ \fP \fIjoin_list\fP
|
|
|
|
Define which streams of the batch job are to be merged. The \fIqsub\fP
|
|
|
|
\fB-j\fP option shall accept a value for the
|
|
|
|
\fIjoin_list\fP option-argument that is a string of alphanumeric characters
|
|
|
|
in the portable character set (see the Base
|
|
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable
|
|
|
|
Character Set).
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIjoin_list\fP option-argument
|
|
|
|
that consists of one or more of the characters
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'e'\fP and \fB'o'\fP, or the single character \fB'n'\fP .
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
All of the other batch job output streams specified will be merged
|
|
|
|
into the output stream represented by the character listed
|
|
|
|
first in the \fIjoin_list\fP option-argument.
|
|
|
|
.LP
|
|
|
|
For each unique character in the \fIjoin_list\fP option-argument,
|
|
|
|
the \fIqsub\fP utility shall add a value to the
|
|
|
|
\fIJoin_Path\fP attribute of the batch job as follows, each representing
|
|
|
|
a different batch job stream to join:
|
|
|
|
.TP 7
|
|
|
|
\fBe\fP
|
|
|
|
.RS
|
|
|
|
The standard error of the batch job (JOIN_STD_ERROR).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBo\fP
|
|
|
|
.RS
|
|
|
|
The standard output of the batch job (JOIN_STD_OUTPUT).
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
An existing \fIJoin_Path\fP attribute can be cleared by the following
|
|
|
|
join type:
|
|
|
|
.TP 7
|
|
|
|
\fBn\fP
|
|
|
|
.RS
|
|
|
|
NO_JOIN
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If \fB'n'\fP is specified, then no files are joined. The \fIqsub\fP
|
|
|
|
utility shall consider it an error if any join type
|
|
|
|
other than \fB'n'\fP is combined with join type \fB'n'\fP .
|
|
|
|
.LP
|
|
|
|
Strictly conforming applications shall not repeat any of the characters
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'e'\fP, \fB'o'\fP, or \fB'n'\fP within the
|
2004-11-03 13:51:07 +00:00
|
|
|
\fIjoin_list\fP option-argument. The \fIqsub\fP utility shall permit
|
|
|
|
the repetition of characters, but shall not assign
|
|
|
|
additional meaning to the repeated characters.
|
|
|
|
.LP
|
|
|
|
An implementation may define other join types. The conformance document
|
|
|
|
for an implementation shall describe any additional
|
|
|
|
batch job streams, how they are specified, their internal behavior,
|
|
|
|
and how they affect the behavior of the utility.
|
|
|
|
.LP
|
|
|
|
If the \fB-j\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the value of the \fIJoin_Path\fP
|
|
|
|
attribute of the batch job to NO_JOIN.
|
|
|
|
.TP 7
|
|
|
|
\fB-k\ \fP \fIkeep_list\fP
|
|
|
|
Define which output of the batch job to retain on the execution host.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP \fB-k\fP option shall accept a value for the \fIkeep_list\fP
|
|
|
|
option-argument that is a string of alphanumeric
|
|
|
|
characters in the portable character set (see the Base Definitions
|
|
|
|
volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable Character
|
|
|
|
Set).
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIkeep_list\fP option-argument
|
|
|
|
that consists of one or more of the characters
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'e'\fP and \fB'o'\fP, or the single character \fB'n'\fP .
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
For each unique character in the \fIkeep_list\fP option-argument,
|
|
|
|
the \fIqsub\fP utility shall add a value to the
|
|
|
|
\fIKeep_Files\fP attribute of the batch job as follows, each representing
|
|
|
|
a different batch job stream to keep:
|
|
|
|
.TP 7
|
|
|
|
\fBe\fP
|
|
|
|
.RS
|
|
|
|
The standard error of the batch job (KEEP_STD_ERROR).
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBo\fP
|
|
|
|
.RS
|
|
|
|
The standard output of the batch job (KEEP_STD_OUTPUT).
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If both \fB'e'\fP and \fB'o'\fP are specified, then both files are
|
|
|
|
retained. An existing \fIKeep_Files\fP attribute can
|
|
|
|
be cleared by the following keep type:
|
|
|
|
.TP 7
|
|
|
|
\fBn\fP
|
|
|
|
.RS
|
|
|
|
NO_KEEP
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If \fB'n'\fP is specified, then no files are retained. The \fIqsub\fP
|
|
|
|
utility shall consider it an error if any keep type
|
|
|
|
other than \fB'n'\fP is combined with keep type \fB'n'\fP .
|
|
|
|
.LP
|
|
|
|
Strictly conforming applications shall not repeat any of the characters
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'e'\fP, \fB'o'\fP, or \fB'n'\fP within the
|
2004-11-03 13:51:07 +00:00
|
|
|
\fIkeep_list\fP option-argument. The \fIqsub\fP utility shall permit
|
|
|
|
the repetition of characters, but shall not assign
|
|
|
|
additional meaning to the repeated characters.
|
|
|
|
.LP
|
|
|
|
An implementation may define other keep types. The conformance document
|
|
|
|
for an implementation shall describe any additional keep
|
|
|
|
types, how they are specified, their internal behavior, and how they
|
|
|
|
affect the behavior of the utility. If the \fB-k\fP option is
|
|
|
|
not presented to the \fIqsub\fP utility, the utility shall set the
|
|
|
|
\fIKeep_Files\fP attribute of the batch job to the value
|
|
|
|
NO_KEEP.
|
|
|
|
.TP 7
|
|
|
|
\fB-m\ \fP \fImail_options\fP
|
|
|
|
.sp
|
|
|
|
Define the points in the execution of the batch job at which the batch
|
|
|
|
server that manages the batch job shall send mail about a
|
|
|
|
change in the state of the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP \fB-m\fP option shall accept a value for the \fImail_options\fP
|
|
|
|
option-argument that is a string of
|
|
|
|
alphanumeric characters in the portable character set (see the Base
|
|
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable
|
|
|
|
Character Set).
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a value for the \fImail_options\fP
|
|
|
|
option-argument that is a string of one or more of the
|
2007-09-20 06:36:16 +00:00
|
|
|
characters \fB'e'\fP, \fB'b'\fP, and \fB'a'\fP, or the single character
|
2004-11-03 13:51:07 +00:00
|
|
|
\fB'n'\fP .
|
|
|
|
.LP
|
|
|
|
For each unique character in the \fImail_options\fP option-argument,
|
|
|
|
the \fIqsub\fP utility shall add a value to the
|
|
|
|
\fIMail_Users\fP attribute of the batch job as follows, each representing
|
|
|
|
a different time during the life of a batch job at which
|
|
|
|
to send mail:
|
|
|
|
.TP 7
|
|
|
|
\fBe\fP
|
|
|
|
.RS
|
|
|
|
MAIL_AT_EXIT
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBb\fP
|
|
|
|
.RS
|
|
|
|
MAIL_AT_BEGINNING
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fBa\fP
|
|
|
|
.RS
|
|
|
|
MAIL_AT_ABORT
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If any of these characters are duplicated in the \fImail_options\fP
|
|
|
|
option-argument, the duplicates shall be ignored.
|
|
|
|
.LP
|
|
|
|
An existing \fIMail_Points\fP attribute can be cleared by the following
|
|
|
|
mail type:
|
|
|
|
.TP 7
|
|
|
|
\fBn\fP
|
|
|
|
.RS
|
|
|
|
NO_MAIL
|
|
|
|
.RE
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
If \fB'n'\fP is specified, then mail is not sent. The \fIqsub\fP utility
|
|
|
|
shall consider it an error if any mail type other
|
|
|
|
than \fB'n'\fP is combined with mail type \fB'n'\fP .
|
|
|
|
.LP
|
|
|
|
Strictly conforming applications shall not repeat any of the characters
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'e'\fP, \fB'b'\fP, \fB'a'\fP, or
|
2004-11-03 13:51:07 +00:00
|
|
|
\fB'n'\fP within the \fImail_options\fP option-argument.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall permit the repetition of characters,
|
|
|
|
but shall not assign additional meaning to the repeated
|
|
|
|
characters. An implementation may define other mail types. The conformance
|
|
|
|
document for an implementation shall describe any
|
|
|
|
additional mail types, how they are specified, their internal behavior,
|
|
|
|
and how they affect the behavior of the utility.
|
|
|
|
.LP
|
|
|
|
If the \fB-m\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIMail_Points\fP attribute to
|
|
|
|
the value MAIL_AT_ABORT.
|
|
|
|
.TP 7
|
|
|
|
\fB-M\ \fP \fImail_list\fP
|
|
|
|
Define the list of users to which a batch server that executes the
|
|
|
|
batch job shall send mail, if the server sends mail about
|
|
|
|
the batch job.
|
|
|
|
.LP
|
|
|
|
The syntax of the \fImail_list\fP option-argument is unspecified.
|
|
|
|
.LP
|
|
|
|
If the implementation of the \fIqsub\fP utility uses a name service
|
|
|
|
to locate users, the utility should accept the syntax used
|
|
|
|
by the name service.
|
|
|
|
.LP
|
|
|
|
If the implementation of the \fIqsub\fP utility does not use a name
|
|
|
|
service to locate users, the implementation should accept
|
|
|
|
the following syntax for user names:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fImail_address\fP\fB[\fP\fB,,\fP\fImail_address\fP\fB,, ...\fP\fB]\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The interpretation of \fImail_address\fP is implementation-defined.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the \fIMail_Users\fP attribute of
|
|
|
|
the batch job to the value of the \fImail_list\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-M\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall place only the user name and host name
|
|
|
|
for the current process in the \fIMail_Users\fP attribute of the batch
|
|
|
|
job.
|
|
|
|
.TP 7
|
|
|
|
\fB-N\ \fP \fIname\fP
|
|
|
|
Define the name of the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP \fB-N\fP option shall accept a value for the \fIname\fP
|
|
|
|
option-argument that is a string of up to 15
|
|
|
|
alphanumeric characters in the portable character set (see the Base
|
|
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, Section 6.1, Portable
|
|
|
|
Character Set) where the first character is alphabetic.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the value of the \fIJob_Name\fP attribute
|
|
|
|
of the batch job to the value of the \fIname\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-N\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIJob_Name\fP attribute of the
|
|
|
|
batch job to the name of the \fIscript\fP argument from which the
|
|
|
|
directory specification if any, has been removed.
|
|
|
|
.LP
|
|
|
|
If the \fB-N\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
and the script is read from standard input, the utility
|
|
|
|
shall set the \fIJob_Name\fP attribute of the batch job to the value
|
|
|
|
STDIN.
|
|
|
|
.TP 7
|
|
|
|
\fB-o\ \fP \fIpath_name\fP
|
|
|
|
Define the path for the standard output of the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIpath_name\fP option-argument
|
|
|
|
that conforms to the syntax of the \fIpath_name\fP
|
|
|
|
element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
|
|
|
which can be preceded by a host name element of
|
|
|
|
the form \fIhostname\fP:.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes an absolute pathname,
|
|
|
|
the \fIqsub\fP utility shall set the
|
|
|
|
\fIOutput_Path\fP attribute of the batch job to the value of the \fIpath_name\fP
|
|
|
|
option-argument without expansion.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes a relative pathname
|
|
|
|
and no host name element is specified, the \fIqsub\fP
|
|
|
|
utility shall set the \fIOutput_Path\fP attribute of the batch job
|
|
|
|
to the pathname derived by expanding the value of the
|
|
|
|
\fIpath_name\fP option-argument relative to the current directory
|
|
|
|
of the process executing the \fIqsub\fP.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument constitutes a relative pathname
|
|
|
|
and a host name element is specified, the \fIqsub\fP
|
|
|
|
utility shall set the \fIOutput_Path\fP attribute of the batch job
|
|
|
|
to the value of the \fIpath_name\fP option-argument without
|
|
|
|
expansion.
|
|
|
|
.LP
|
|
|
|
If the \fIpath_name\fP option-argument does not specify a host name
|
|
|
|
element, the \fIqsub\fP utility shall prefix the pathname
|
|
|
|
with \fIhostname\fP:, where \fIhostname\fP is the name of the host
|
|
|
|
upon which the \fIqsub\fP utility is executing.
|
|
|
|
.LP
|
|
|
|
If the \fB-o\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIOutput_Path\fP attribute of
|
|
|
|
the batch job to the host name and path of the current directory of
|
|
|
|
the submitting process and the default filename.
|
|
|
|
.LP
|
|
|
|
The default filename for standard output has the following format:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fIjob_name\fP\fB.o\fP\fIsequence_number\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.TP 7
|
|
|
|
\fB-p\ \fP \fIpriority\fP
|
|
|
|
Define the priority the batch job should have relative to other batch
|
|
|
|
jobs owned by the batch server.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall set the \fIPriority\fP attribute of the
|
|
|
|
batch job to the value of the \fIpriority\fP
|
|
|
|
option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-p\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the value of the \fIPriority\fP attribute is
|
|
|
|
implementation-defined.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a value for the \fIpriority\fP
|
|
|
|
option-argument that conforms to the syntax for signed
|
|
|
|
decimal integers, and which is not less than -1024 and not greater
|
|
|
|
than 1023.
|
|
|
|
.TP 7
|
|
|
|
\fB-q\ \fP \fIdestination\fP
|
|
|
|
.sp
|
|
|
|
Define the destination of the batch job.
|
|
|
|
.LP
|
|
|
|
The destination is not a batch job attribute; it determines the batch
|
|
|
|
server, and possibly the batch queue, to which the
|
|
|
|
\fIqsub\fP utility batch queues the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall submit the script to the batch server
|
|
|
|
named by the \fIdestination\fP option-argument or the
|
|
|
|
server that owns the batch queue named in the \fIdestination\fP option-argument.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept an option-argument for the \fB-q\fP
|
|
|
|
option that conforms to the syntax for a destination
|
|
|
|
(see \fIDestination\fP ).
|
|
|
|
.LP
|
|
|
|
If the \fB-q\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the \fIqsub\fP utility shall submit the batch job to the
|
|
|
|
default destination. The mechanism for determining the default destination
|
|
|
|
is implementation-defined.
|
|
|
|
.TP 7
|
|
|
|
\fB-r\ \fP \fIy\fP|\fIn\fP
|
|
|
|
Define whether the batch job is rerunnable.
|
|
|
|
.LP
|
|
|
|
If the value of the option-argument is \fIy\fP, the \fIqsub\fP utility
|
|
|
|
shall set the \fIRerunable\fP attribute of the batch
|
|
|
|
job to TRUE.
|
|
|
|
.LP
|
|
|
|
If the value of the option-argument is \fIn\fP, the \fIqsub\fP utility
|
|
|
|
shall set the \fIRerunable\fP attribute of the batch
|
|
|
|
job to FALSE.
|
|
|
|
.LP
|
|
|
|
If the \fB-r\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIRerunable\fP attribute of the
|
|
|
|
batch job to TRUE.
|
|
|
|
.TP 7
|
|
|
|
\fB-S\ \fP \fIpath_name_list\fP
|
|
|
|
.sp
|
|
|
|
Define the pathname to the shell under which the batch job is to execute.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIpath_name_list\fP option-argument
|
|
|
|
that conforms to the following syntax:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIpathname\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall allow only one pathname for a given host
|
|
|
|
name. The \fIqsub\fP utility shall allow only one
|
|
|
|
pathname that is missing a corresponding host name.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall add a value to the \fIShell_Path_List\fP
|
|
|
|
attribute of the batch job for each entry in the
|
|
|
|
\fIpath_name_list\fP option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-S\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIShell_Path_List\fP attribute
|
|
|
|
of the batch job to the null string.
|
|
|
|
.LP
|
|
|
|
The conformance document for an implementation shall describe the
|
|
|
|
mechanism used to set the default shell and determine the
|
|
|
|
current value of the default shell. An implementation shall provide
|
|
|
|
a means for the installation to set the default shell to the
|
|
|
|
login shell of the user under which the batch job is to execute. See
|
|
|
|
\fIMultiple
|
|
|
|
Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP
|
|
|
|
(and \fIvalue\fP@ \fIkeyword\fP) pairs and other
|
|
|
|
general rules for list-oriented batch job attributes.
|
|
|
|
.TP 7
|
|
|
|
\fB-u\ \fP \fIuser_list\fP
|
|
|
|
Define the user name under which the batch job is to execute.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIuser_list\fP option-argument
|
|
|
|
that conforms to the following syntax:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB][\fP\fB,,\fP\fIusername\fP\fB[\fP\fB@\fP\fIhost\fP\fB]\fP\fB,, ...\fP\fB]\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept only one user name that is missing
|
|
|
|
a corresponding host name. The \fIqsub\fP utility shall
|
|
|
|
accept only one user name per named host.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall add a value to the \fIUser_List\fP attribute
|
|
|
|
of the batch job for each entry in the
|
|
|
|
\fIuser_list\fP option-argument.
|
|
|
|
.LP
|
|
|
|
If the \fB-u\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall set the \fIUser_List\fP attribute of the
|
|
|
|
batch job to the user name from which the utility is executing. See
|
|
|
|
\fIMultiple
|
|
|
|
Keyword-Value Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP
|
|
|
|
(and \fIvalue\fP@ \fIkeyword\fP) pairs and other
|
|
|
|
general rules for list-oriented batch job attributes.
|
|
|
|
.TP 7
|
|
|
|
\fB-v\ \fP \fIvariable_list\fP
|
|
|
|
.sp
|
|
|
|
Add to the list of variables that are exported to the session leader
|
|
|
|
of the batch job.
|
|
|
|
.LP
|
|
|
|
A \fIvariable_list\fP is a set of strings of either the form < \fIvariable\fP>
|
|
|
|
or < \fIvariable\fP=
|
|
|
|
\fIvalue\fP>, delimited by commas.
|
|
|
|
.LP
|
|
|
|
If the \fB-v\fP option is presented to the \fIqsub\fP utility, the
|
|
|
|
utility shall also add, to the environment
|
|
|
|
\fIVariable_List\fP attribute of the batch job, every variable named
|
|
|
|
in the environment \fIvariable_list\fP option-argument and,
|
|
|
|
optionally, values of specified variables.
|
|
|
|
.LP
|
|
|
|
If a value is not provided on the command line, the \fIqsub\fP utility
|
|
|
|
shall set the value of each variable in the environment
|
|
|
|
\fIVariable_List\fP attribute of the batch job to the value of the
|
|
|
|
corresponding environment variable for the process in which the
|
|
|
|
utility is executing; see Environment Variable Values (Utilities)
|
|
|
|
\&.
|
|
|
|
.LP
|
|
|
|
A conforming application shall not repeat a variable in the environment
|
|
|
|
\fIvariable_list\fP option-argument.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall not repeat a variable in the environment
|
|
|
|
\fIVariable_List\fP attribute of the batch job. See \fIMultiple Keyword-Value
|
|
|
|
Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP
|
|
|
|
(and \fIvalue\fP@ \fIkeyword\fP) pairs and other general rules for
|
|
|
|
list-oriented batch job attributes.
|
|
|
|
.TP 7
|
|
|
|
\fB-V\fP
|
|
|
|
Specify that all of the environment variables of the process are exported
|
|
|
|
to the context of the batch job.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall place every environment variable in the
|
|
|
|
process in which the utility is executing in the list and
|
|
|
|
shall set the value of each variable in the attribute to the value
|
|
|
|
of that variable in the process.
|
|
|
|
.TP 7
|
|
|
|
\fB-z\fP
|
|
|
|
Specify that the utility does not write the batch \fIjob_identifier\fP
|
|
|
|
of the created batch job to standard output.
|
|
|
|
.LP
|
|
|
|
If the \fB-z\fP option is presented to the \fIqsub\fP utility, the
|
|
|
|
utility shall not write the batch \fIjob_identifier\fP of
|
|
|
|
the created batch job to standard output.
|
|
|
|
.LP
|
|
|
|
If the \fB-z\fP option is not presented to the \fIqsub\fP utility,
|
|
|
|
the utility shall write the identifier of the created batch
|
|
|
|
job to standard output.
|
|
|
|
.sp
|
|
|
|
.SH OPERANDS
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall accept a \fIscript\fP operand that indicates
|
|
|
|
the path to the script of the batch job.
|
|
|
|
.LP
|
|
|
|
If the \fIscript\fP operand is not presented to the \fIqsub\fP utility,
|
|
|
|
or if the operand is the single-character string
|
2007-09-20 06:36:16 +00:00
|
|
|
\fB'-'\fP, the utility shall read the script from standard input.
|
2004-11-03 13:51:07 +00:00
|
|
|
.LP
|
|
|
|
If the script represents a partial path, the \fIqsub\fP utility shall
|
|
|
|
expand the path relative to the current directory of the
|
|
|
|
process executing the utility.
|
|
|
|
.SH STDIN
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility reads the script of the batch job from standard
|
|
|
|
input if the script operand is omitted or is the single
|
|
|
|
character \fB'-'\fP .
|
|
|
|
.SH INPUT FILES
|
|
|
|
.LP
|
|
|
|
In addition to binding the file indicated by the \fIscript\fP operand
|
|
|
|
to the batch job, the \fIqsub\fP utility reads the
|
|
|
|
script file and acts on directives in the script.
|
|
|
|
.SH ENVIRONMENT VARIABLES
|
|
|
|
.LP
|
|
|
|
The following environment variables shall affect the execution of
|
|
|
|
\fIqsub\fP:
|
|
|
|
.TP 7
|
|
|
|
\fILANG\fP
|
|
|
|
Provide a default value for the internationalization variables that
|
|
|
|
are unset or null. (See the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
|
|
for
|
|
|
|
the precedence of internationalization variables used to determine
|
|
|
|
the values of locale categories.)
|
|
|
|
.TP 7
|
|
|
|
\fILC_ALL\fP
|
|
|
|
If set to a non-empty string value, override the values of all the
|
|
|
|
other internationalization variables.
|
|
|
|
.TP 7
|
|
|
|
\fILC_CTYPE\fP
|
|
|
|
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).
|
|
|
|
.TP 7
|
|
|
|
\fILC_MESSAGES\fP
|
|
|
|
Determine the locale that should be used to affect the format and
|
|
|
|
contents of diagnostic messages written to standard
|
|
|
|
error.
|
|
|
|
.TP 7
|
|
|
|
\fILOGNAME\fP
|
|
|
|
Determine the login name of the user.
|
|
|
|
.TP 7
|
|
|
|
\fIPBS_DPREFIX\fP
|
|
|
|
.sp
|
|
|
|
Determine the default prefix for directives within the script.
|
|
|
|
.TP 7
|
|
|
|
\fISHELL\fP
|
|
|
|
Determine the pathname of the preferred command language interpreter
|
|
|
|
of the user.
|
|
|
|
.TP 7
|
|
|
|
\fITZ\fP
|
|
|
|
Determine the timezone used to interpret the \fIdate-time\fP option-argument.
|
|
|
|
If \fITZ\fP is unset or null, an unspecified
|
|
|
|
default timezone shall be used.
|
|
|
|
.sp
|
|
|
|
.SH ASYNCHRONOUS EVENTS
|
|
|
|
.LP
|
|
|
|
Once created, a batch job exists until it exits, aborts, or is deleted.
|
|
|
|
.LP
|
|
|
|
After a batch job is created by the \fIqsub\fP utility, batch servers
|
|
|
|
might route, execute, modify, or delete the batch
|
|
|
|
job.
|
|
|
|
.SH STDOUT
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility writes the batch \fIjob_identifier\fP assigned
|
|
|
|
to the batch job to standard output, unless the
|
|
|
|
\fB-z\fP option is specified.
|
|
|
|
.SH STDERR
|
|
|
|
.LP
|
|
|
|
The standard error shall be used only for diagnostic messages.
|
|
|
|
.SH OUTPUT FILES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXTENDED DESCRIPTION
|
|
|
|
.SS Script Preservation
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility can send a copy of the script to the server
|
|
|
|
with the \fIQueue Job Request\fP or store a temporary copy
|
|
|
|
of the script in a location specified to the server.
|
|
|
|
.SS Option Specification
|
|
|
|
.LP
|
|
|
|
A script can contain directives to the \fIqsub\fP utility.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP 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.
|
|
|
|
.LP
|
|
|
|
Lines are separated by a <newline>. If the first line of the script
|
|
|
|
begins with \fB"#!"\fP or a colon ( \fB':'\fP ),
|
|
|
|
then it is skipped. The \fIqsub\fP 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 <space> or <tab> 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 ( \fB'\\'\fP )
|
|
|
|
and <newline>, then the next line shall be interpreted as a continuation
|
|
|
|
of that directive.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP 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 \fIqsub\fP utility.
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility shall continue to process a directive prefix
|
|
|
|
line until after a <newline> 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.
|
|
|
|
.LP
|
|
|
|
If an option is present in both a directive and the arguments to the
|
|
|
|
\fIqsub\fP utility, the utility shall ignore the option
|
|
|
|
and the corresponding option-argument, if any, in the directive.
|
|
|
|
.LP
|
|
|
|
If an option that is present in the directive is not present in the
|
|
|
|
arguments to the \fIqsub\fP utility, the utility shall
|
|
|
|
process the option and the option-argument, if any.
|
|
|
|
.LP
|
|
|
|
In order of preference, the \fIqsub\fP utility shall select the directive
|
|
|
|
prefix from one of the following sources:
|
|
|
|
.IP " *" 3
|
|
|
|
If the \fB-C\fP option is presented to the utility, the value of the
|
|
|
|
\fIdirective_prefix\fP option-argument
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
If the environment variable \fIPBS_DPREFIX\fP is defined, the value
|
|
|
|
of that variable
|
|
|
|
.LP
|
|
|
|
.IP " *" 3
|
|
|
|
The four-character string \fB"#PBS"\fP encoded in the portable character
|
|
|
|
set
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
If the \fB-C\fP option is present in the script file it shall be ignored.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
.LP
|
|
|
|
The following exit values shall be returned:
|
|
|
|
.TP 7
|
|
|
|
\ 0
|
|
|
|
Successful completion.
|
|
|
|
.TP 7
|
|
|
|
>0
|
|
|
|
An error occurred.
|
|
|
|
.sp
|
|
|
|
.SH CONSEQUENCES OF ERRORS
|
|
|
|
.LP
|
|
|
|
Default.
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
The \fIqsub\fP utility allows users to create a batch job that will
|
|
|
|
process the script specified as the operand of the
|
|
|
|
utility.
|
|
|
|
.LP
|
|
|
|
The options of the \fIqsub\fP utility allow users to control many
|
|
|
|
aspects of the queuing and execution of a batch job.
|
|
|
|
.LP
|
|
|
|
The \fB-a\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-A\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-C\fP option allows users to prescribe the prefix for directives
|
|
|
|
within the script file. The default prefix
|
|
|
|
\fB"#PBS"\fP may be inappropriate if the script will be interpreted
|
|
|
|
with an alternate shell, as specified by the \fB-S\fP
|
|
|
|
option.
|
|
|
|
.LP
|
|
|
|
The \fB-c\fP option allows users to establish the checkpointing interval
|
|
|
|
for their jobs. A checkpointing system, which is not
|
|
|
|
defined by this volume of IEEE\ Std\ 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\ Std\ 1003.1-2001 provides the
|
|
|
|
checkpointing interval option. Support for checkpointing
|
|
|
|
is optional for batch servers.
|
|
|
|
.LP
|
|
|
|
The \fB-e\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-h\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-j\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-m\fP 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 \fB-M\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-N\fP 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 \fIqstat\fP utility.
|
|
|
|
.LP
|
|
|
|
The \fB-o\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-P\fP option allows users to designate the relative priority
|
|
|
|
of a batch job for selection from a queue.
|
|
|
|
.LP
|
|
|
|
The \fB-q\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-r\fP 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 \fB-r\fP option likewise allows users
|
|
|
|
to indicate whether or not the batch job is eligible to be
|
|
|
|
rerun by the \fIqrerun\fP 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\ Std\ 1003.1-2001 specifies
|
|
|
|
that the default, if the \fB-r\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-S\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-u\fP option is useful when the submitting user is authorized
|
|
|
|
to use more than one account on a given host, in which
|
|
|
|
case the \fB-u\fP 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
|
|
|
|
\fB-u\fP 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 \fB-u\fP option.
|
|
|
|
.LP
|
|
|
|
The \fB-V\fP 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.
|
|
|
|
.LP
|
|
|
|
The \fB-v\fP option allows users to export specific environment variables
|
|
|
|
from their current process to the processes of the
|
|
|
|
batch job.
|
|
|
|
.LP
|
|
|
|
The \fB-z\fP option allows users to suppress the writing of the batch
|
|
|
|
job identifier to standard output. The \fB-z\fP option
|
|
|
|
is an existing NQS practice that has been standardized.
|
|
|
|
.LP
|
|
|
|
Historically, the \fIqsub\fP 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
|
|
|
|
\fIqsub\fP utility in this volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, \fIvis-a-vis\fP NQS, as a result of the growing
|
|
|
|
pool of experience with distributed batch
|
|
|
|
systems.
|
|
|
|
.LP
|
|
|
|
The set of features of the \fIqsub\fP utility as defined in this volume
|
|
|
|
of IEEE\ Std\ 1003.1-2001 appears to
|
|
|
|
incorporate all the common existing practice on potentially conforming
|
|
|
|
platforms.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:36:16 +00:00
|
|
|
\fIBatch Environment Services\fP, \fIqrerun\fP, \fIqstat\fP, \fItouch\fP
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|