path: root/man1p/qsub.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "QSUB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" qsub 
.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
the batch job: \fIHOME ,\fP \fILANG ,\fP \fILOGNAME ,\fP \fIPATH ,\fP
\fIMAIL ,\fP \fISHELL ,\fP and \fITZ .\fP The name of
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
\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP .
.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
\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the
\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
\fB'e'\fP and \fB'o'\fP , or the single character \fB'n'\fP .
.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
\fB'e'\fP , \fB'o'\fP , or \fB'n'\fP within the
\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
characters \fB'e'\fP , \fB'b'\fP , and \fB'a'\fP , or the single character
\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
\fB'e'\fP , \fB'b'\fP , \fB'a'\fP , or
\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
\fB'-'\fP , the utility shall read the script from standard input.
.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
\fIBatch Environment Services\fP , \fIqrerun\fP , \fIqstat\fP , \fItouch\fP
.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 .