qsub
SYNOPSIS
qsub [-a date_time][-A account_string][-c interval]
[-C directive_prefix][-e path_name][-h][-j join_list][-k
keep_list]
[-m mail_options][-M mail_list][-N name]
[-o path_name][-p priority][-q destination][-r y|n]
[-S path_name_list][-u user_list][-v variable_list][-V]
[-z][script]
DESCRIPTION
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 qsub utility
is a user-accessible batch client that submits a script.
Upon successful completion, the qsub utility shall have created a batch
job that will execute the submitted script.
The qsub utility shall submit a script by sending a Queue Job Request
to a batch server.
The qsub utility shall place the value of the following environment
variables in the Variable_List attribute of the batch job: HOME , LANG
, LOGNAME , PATH , MAIL , SHELL , and TZ . The name of the environment
variable shall be the current name prefixed with the string PBS_O_.
Note: If the current value of the HOME variable in the environment
space of the qsub utility is /aa/bb/cc, then qsub shall place
PBS_O_HOME = /aa/bb/cc in the Variable_List attribute of the
batch job.
In addition to the variables described above, the qsub utility shall
add the following variables with the indicated values to the variable
list:
PBS_O_WORKDIR
The absolute path of the current working directory of the qsub
utility process.
PBS_O_HOST
The name of the host on which the qsub utility is running.
OPTIONS
The qsub utility shall conform to the Base Definitions volume of
IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The following options shall be supported by the implementation:
-a date_time
Define the time at which a batch job becomes eligible for execu-
tion.
PBS_O_MAIL MAIL
PBS_O_SHELL SHELL
PBS_O_TZ TZ
PBS_O_WORKDIR Current working directory
Note:
The server that initiates execution of the batch job will add
other variables to the batch job's environment; see Batch Job
Execution .
The qsub utility shall set the Execution_Time 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 date_time option-argument. The
Epoch is defined in the Base Definitions volume of
IEEE Std 1003.1-2001, Section 3.149, Epoch.
If the -a option is not presented to the qsub utility, the utility
shall set the Execution_Time attribute of the batch job to a time (num-
ber of seconds since the Epoch) that is earlier than the time at which
the utility exits.
-A account_string
Define the account to which the resource consumption of the
batch job should be charged.
The syntax of the account_string option-argument is unspecified.
The qsub utility shall set the Account_Name attribute of the batch job
to the value of the account_string option-argument.
If the -A option is not presented to the qsub utility, the utility
shall omit the Account_Name attribute from the attributes of the batch
job.
-c interval
Define whether the batch job should be checkpointed, and if so,
how often.
The qsub utility shall accept a value for the interval option-argument
that is one of the following:
n
No checkpointing shall be performed on the batch job (NO_CHECK-
POINT).
s
Checkpointing shall be performed only when the batch server is
shut down (CHECKPOINT_AT_SHUTDOWN).
c
Automatic periodic checkpointing shall be performed at the Mini-
mum_Cpu_Interval attribute of the batch queue, in units of CPU
If the -c option is not presented to the qsub utility, the utility
shall set the Checkpoint attribute of the batch job to the single char-
acter 'u' (CHECKPOINT_UNSPECIFIED).
-C directive_prefix
Define the prefix that declares a directive to the qsub utility
within the script.
The directive_prefix is not a batch job attribute; it affects the
behavior of the qsub utility.
If the -C option is presented to the qsub utility, and the value of the
directive_prefix option-argument is the null string, the utility shall
not scan the script file for directives. If the -C option is not pre-
sented to the qsub utility, then the value of the PBS_DPREFIX environ-
ment variable is used. If the environment variable is not defined, then
#PBS encoded in the portable character set is the default.
-e path_name
Define the path to be used for the standard error stream of the
batch job.
The qsub utility shall accept a path_name option-argument which can be
preceded by a host name element of the form hostname:.
If the path_name option-argument constitutes an absolute pathname, the
qsub utility shall set the Error_Path attribute of the batch job to the
value of the path_name option-argument.
If the path_name option-argument constitutes a relative pathname and no
host name element is specified, the qsub utility shall set the
Error_Path attribute of the batch job to the value of the absolute
pathname derived by expanding the path_name option-argument relative to
the current directory of the process executing qsub.
If the path_name option-argument constitutes a relative pathname and a
host name element is specified, the qsub utility shall set the
Error_Path attribute of the batch job to the value of the path_name
option-argument without expansion. The host name element shall be
included.
If the path_name option-argument does not include a host name element,
the qsub utility shall prefix the pathname with hostname:, where host-
name is the name of the host upon which the qsub utility is being exe-
cuted.
If the -e option is not presented to the qsub utility, the utility
shall set the Error_Path attribute of the batch job to the host name
and path of the current directory of the submitting process and the
default filename.
The default filename for standard error has the following format:
-j join_list
Define which streams of the batch job are to be merged. The qsub
-j option shall accept a value for the join_list 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).
The qsub utility shall accept a join_list option-argument that consists
of one or more of the characters 'e' and 'o' , or the single character
'n' .
All of the other batch job output streams specified will be merged into
the output stream represented by the character listed first in the
join_list option-argument.
For each unique character in the join_list option-argument, the qsub
utility shall add a value to the Join_Path attribute of the batch job
as follows, each representing a different batch job stream to join:
e
The standard error of the batch job (JOIN_STD_ERROR).
o
The standard output of the batch job (JOIN_STD_OUTPUT).
An existing Join_Path attribute can be cleared by the following join
type:
n
NO_JOIN
If 'n' is specified, then no files are joined. The qsub utility shall
consider it an error if any join type other than 'n' is combined with
join type 'n' .
Strictly conforming applications shall not repeat any of the characters
'e' , 'o' , or 'n' within the join_list option-argument. The qsub util-
ity shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.
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.
If the -j option is not presented to the qsub utility, the utility
shall set the value of the Join_Path attribute of the batch job to
NO_JOIN.
-k keep_list
Define which output of the batch job to retain on the execution
host.
as follows, each representing a different batch job stream to keep:
e
The standard error of the batch job (KEEP_STD_ERROR).
o
The standard output of the batch job (KEEP_STD_OUTPUT).
If both 'e' and 'o' are specified, then both files are retained. An
existing Keep_Files attribute can be cleared by the following keep
type:
n
NO_KEEP
If 'n' is specified, then no files are retained. The qsub utility shall
consider it an error if any keep type other than 'n' is combined with
keep type 'n' .
Strictly conforming applications shall not repeat any of the characters
'e' , 'o' , or 'n' within the keep_list option-argument. The qsub util-
ity shall permit the repetition of characters, but shall not assign
additional meaning to the repeated characters.
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 -k option is not presented to the qsub
utility, the utility shall set the Keep_Files attribute of the batch
job to the value NO_KEEP.
-m mail_options
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.
The qsub -m option shall accept a value for the mail_options 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).
The qsub utility shall accept a value for the mail_options option-argu-
ment that is a string of one or more of the characters 'e' , 'b' , and
'a' , or the single character 'n' .
For each unique character in the mail_options option-argument, the qsub
utility shall add a value to the Mail_Users attribute of the batch job
as follows, each representing a different time during the life of a
batch job at which to send mail:
e
An existing Mail_Points attribute can be cleared by the following mail
type:
n
NO_MAIL
If 'n' is specified, then mail is not sent. The qsub utility shall con-
sider it an error if any mail type other than 'n' is combined with mail
type 'n' .
Strictly conforming applications shall not repeat any of the characters
'e' , 'b' , 'a' , or 'n' within the mail_options option-argument.
The qsub utility shall permit the repetition of characters, but shall
not assign additional meaning to the repeated characters. An implemen-
tation 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.
If the -m option is not presented to the qsub utility, the utility
shall set the Mail_Points attribute to the value MAIL_AT_ABORT.
-M mail_list
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.
The syntax of the mail_list option-argument is unspecified.
If the implementation of the qsub utility uses a name service to locate
users, the utility should accept the syntax used by the name service.
If the implementation of the qsub utility does not use a name service
to locate users, the implementation should accept the following syntax
for user names:
mail_address[,,mail_address,, ...]
The interpretation of mail_address is implementation-defined.
The qsub utility shall set the Mail_Users attribute of the batch job to
the value of the mail_list option-argument.
If the -M option is not presented to the qsub utility, the utility
shall place only the user name and host name for the current process in
the Mail_Users attribute of the batch job.
-N name
Define the name of the batch job.
The qsub -N option shall accept a value for the name option-argument
If the -N option is not presented to the qsub utility, and the script
is read from standard input, the utility shall set the Job_Name
attribute of the batch job to the value STDIN.
-o path_name
Define the path for the standard output of the batch job.
The qsub utility shall accept a path_name option-argument that conforms
to the syntax of the path_name 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 hostname:.
If the path_name option-argument constitutes an absolute pathname, the
qsub utility shall set the Output_Path attribute of the batch job to
the value of the path_name option-argument without expansion.
If the path_name option-argument constitutes a relative pathname and no
host name element is specified, the qsub utility shall set the Out-
put_Path attribute of the batch job to the pathname derived by expand-
ing the value of the path_name option-argument relative to the current
directory of the process executing the qsub.
If the path_name option-argument constitutes a relative pathname and a
host name element is specified, the qsub utility shall set the Out-
put_Path attribute of the batch job to the value of the path_name
option-argument without expansion.
If the path_name option-argument does not specify a host name element,
the qsub utility shall prefix the pathname with hostname:, where host-
name is the name of the host upon which the qsub utility is executing.
If the -o option is not presented to the qsub utility, the utility
shall set the Output_Path attribute of the batch job to the host name
and path of the current directory of the submitting process and the
default filename.
The default filename for standard output has the following format:
job_name.osequence_number
-p priority
Define the priority the batch job should have relative to other
batch jobs owned by the batch server.
The qsub utility shall set the Priority attribute of the batch job to
the value of the priority option-argument.
If the -p option is not presented to the qsub utility, the value of the
Priority attribute is implementation-defined.
The qsub utility shall accept a value for the priority option-argument
that conforms to the syntax for signed decimal integers, and which is
named in the destination option-argument.
The qsub utility shall accept an option-argument for the -q option that
conforms to the syntax for a destination (see Destination ).
If the -q option is not presented to the qsub utility, the qsub utility
shall submit the batch job to the default destination. The mechanism
for determining the default destination is implementation-defined.
-r y|n
Define whether the batch job is rerunnable.
If the value of the option-argument is y, the qsub utility shall set
the Rerunable attribute of the batch job to TRUE.
If the value of the option-argument is n, the qsub utility shall set
the Rerunable attribute of the batch job to FALSE.
If the -r option is not presented to the qsub utility, the utility
shall set the Rerunable attribute of the batch job to TRUE.
-S path_name_list
Define the pathname to the shell under which the batch job is to
execute.
The qsub utility shall accept a path_name_list option-argument that
conforms to the following syntax:
pathname[@host][,,pathname[@host],, ...]
The qsub utility shall allow only one pathname for a given host name.
The qsub utility shall allow only one pathname that is missing a corre-
sponding host name.
The qsub utility shall add a value to the Shell_Path_List attribute of
the batch job for each entry in the path_name_list option-argument.
If the -S option is not presented to the qsub utility, the utility
shall set the Shell_Path_List attribute of the batch job to the null
string.
The conformance document for an implementation shall describe the mech-
anism 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 Multiple Keyword-Value
Pairs for a means of removing keyword= value (and value@ keyword) pairs
and other general rules for list-oriented batch job attributes.
-u user_list
Define the user name under which the batch job is to execute.
If the -u option is not presented to the qsub utility, the utility
shall set the User_List attribute of the batch job to the user name
from which the utility is executing. See Multiple Keyword-Value Pairs
for a means of removing keyword= value (and value@ keyword) pairs and
other general rules for list-oriented batch job attributes.
-v variable_list
Add to the list of variables that are exported to the session
leader of the batch job.
A variable_list is a set of strings of either the form < variable> or <
variable= value>, delimited by commas.
If the -v option is presented to the qsub utility, the utility shall
also add, to the environment Variable_List attribute of the batch job,
every variable named in the environment variable_list option-argument
and, optionally, values of specified variables.
If a value is not provided on the command line, the qsub utility shall
set the value of each variable in the environment Variable_List
attribute of the batch job to the value of the corresponding environ-
ment variable for the process in which the utility is executing; see
Environment Variable Values (Utilities) .
A conforming application shall not repeat a variable in the environment
variable_list option-argument.
The qsub utility shall not repeat a variable in the environment Vari-
able_List attribute of the batch job. See Multiple Keyword-Value Pairs
for a means of removing keyword= value (and value@ keyword) pairs and
other general rules for list-oriented batch job attributes.
-V Specify that all of the environment variables of the process are
exported to the context of the batch job.
The qsub 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.
-z Specify that the utility does not write the batch job_identifier
of the created batch job to standard output.
If the -z option is presented to the qsub utility, the utility shall
not write the batch job_identifier of the created batch job to standard
output.
If the -z option is not presented to the qsub utility, the utility
shall write the identifier of the created batch job to standard output.
OPERANDS
The qsub utility reads the script of the batch job from standard input
if the script operand is omitted or is the single character '-' .
INPUT FILES
In addition to binding the file indicated by the script operand to the
batch job, the qsub utility reads the script file and acts on direc-
tives in the script.
ENVIRONMENT VARIABLES
The following environment variables shall affect the execution of qsub:
LANG 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 Vari-
ables for the precedence of internationalization variables used
to determine the values of locale categories.)
LC_ALL If set to a non-empty string value, override the values of all
the other internationalization variables.
LC_CTYPE
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).
LC_MESSAGES
Determine the locale that should be used to affect the format
and contents of diagnostic messages written to standard error.
LOGNAME
Determine the login name of the user.
PBS_DPREFIX
Determine the default prefix for directives within the script.
SHELL Determine the pathname of the preferred command language inter-
preter of the user.
TZ Determine the timezone used to interpret the date-time option-
argument. If TZ is unset or null, an unspecified default time-
zone shall be used.
ASYNCHRONOUS EVENTS
Once created, a batch job exists until it exits, aborts, or is deleted.
After a batch job is created by the qsub utility, batch servers might
route, execute, modify, or delete the batch job.
STDOUT
The qsub utility writes the batch job_identifier assigned to the batch
job to standard output, unless the -z option is specified.
The qsub utility can send a copy of the script to the server with the
Queue Job Request or store a temporary copy of the script in a location
specified to the server.
Option Specification
A script can contain directives to the qsub utility.
The qsub 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.
Lines are separated by a <newline>. If the first line of the script
begins with "#!" or a colon ( ':' ), then it is skipped. The qsub util-
ity 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 direc-
tive prefix. If a line in the script contains a directive and the final
characters of the line are backslash ( '\' ) and <newline>, then the
next line shall be interpreted as a continuation of that directive.
The qsub utility shall process the options and option-arguments con-
tained on the directive prefix line using the same syntax as if the
options were input on the qsub utility.
The qsub 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 con-
formance document the format of any shell comments that it will recog-
nize.
If an option is present in both a directive and the arguments to the
qsub utility, the utility shall ignore the option and the corresponding
option-argument, if any, in the directive.
If an option that is present in the directive is not present in the
arguments to the qsub utility, the utility shall process the option and
the option-argument, if any.
In order of preference, the qsub utility shall select the directive
prefix from one of the following sources:
* If the -C option is presented to the utility, the value of the
directive_prefix option-argument
* If the environment variable PBS_DPREFIX is defined, the value of
that variable
* The four-character string "#PBS" encoded in the portable character
set
If the -C option is present in the script file it shall be ignored.
APPLICATION USAGE
None.
EXAMPLES
None.
RATIONALE
The qsub utility allows users to create a batch job that will process
the script specified as the operand of the utility.
The options of the qsub utility allow users to control many aspects of
the queuing and execution of a batch job.
The -a 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.
The -A 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.
The -C option allows users to prescribe the prefix for directives
within the script file. The default prefix "#PBS" may be inappropriate
if the script will be interpreted with an alternate shell, as specified
by the -S option.
The -c 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.
The -e 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.
The -h 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 sys-
The -N 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 qstat
utility.
The -o option allows users to redirect the standard output stream. A
user might, for example, wish to redirect to the null device the stan-
dard output stream of a job that produces copious yet superfluous out-
put.
The -P option allows users to designate the relative priority of a
batch job for selection from a queue.
The -q 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 even-
tually executes the batch job.
The -r 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 -r option likewise allows users to indicate whether or not the
batch job is eligible to be rerun by the qrerun utility. Some jobs can-
not 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 -r 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 cat-
astrophic.
The -S 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.
The -u option is useful when the submitting user is authorized to use
more than one account on a given host, in which case the -u option
allows the user to select from among those accounts. The option-argu-
ment is a list of user-host pairs, so that the submitting user can pro-
vide different user identifiers for different nodes in the event the
batch job is routed. The -u 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 -u option.
The -V 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.
The -v option allows users to export specific environment variables
from their current process to the processes of the batch job.
The -z option allows users to suppress the writing of the batch job
FUTURE DIRECTIONS
None.
SEE ALSO
Batch Environment Services , qrerun , qstat , touch
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 .
IEEE/The Open Group 2003 QSUB(P)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2012
Hurricane Electric.
All Rights Reserved.