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 POSIX.1‐2017, 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 POSIX.1‐2017 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 system load has dropped.
The -j 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.
The -m 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 -M 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.
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 standard output stream of a job that produces copious
yet superfluous output.
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 eventually 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 cannot be correctly rerun
because of changes they make in the state of databases or other
aspects of their environment. This volume of POSIX.1‐2017
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
catastrophic.
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-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 -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 identifier to standard output. The -z option is an existing
NQS practice that has been standardized.
Historically, the qsub 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 qsub utility in this volume of POSIX.1‐2017, vis-a-vis NQS,
as a result of the growing pool of experience with distributed
batch systems.
The set of features of the qsub utility as defined in this volume
of POSIX.1‐2017 appears to incorporate all the common existing
practice on potentially conforming platforms.
