SYNOPSIS
qsub [-a date_time] [-A account_string] [-b secs] [-c checkpoint_options] [-C directive_prefix] [-d path] [-D path] [-e path] [-f] [-h] [-I] [-j join] [-k keep] [-l resource_list] [-m mail_options] [-M user_list] [-N name] [-o path] [-p priority] [-P proxy_username[:group]] [-q destination] [-r c] [-S path_list] [-t num_jobs] [-T prologue/epilogue script_name] [-u user_list] [-v variable_list] [-V] [-w] path [-W additional_attributes] [-x] [-X] [-z] [script]DESCRIPTION
To create a job is to submit an executable script to a batch server. The batch server will be the default server unless the option is specified. See discussion of PBS_DEFAULT under Environment Variables below. Typically, the script is a shell script which will be executed by a command shell such as sh or csh.Options on the qsub command allow the specification of attributes which affect the behavior of the job.
The qsub command will pass certain environment variables in the
OPTIONS
- -a date_time
-
Declares the time after which the job is eligible for execution.
-
The argument is in the form:
Where CC is the first two digits of the year (the century), YY is the second two digits of the year, MM is the two digits for the month, DD is the day of the month, hh is the hour, mm is the minute, and the optional SS is the seconds.
If the month, is not specified, it will default to the current month if the specified day is in the future. Otherwise, the month will be set to next month. Likewise, if the day, is not specified, it will default to today if the time is in the future. Otherwise, the day will be set to tomorrow. For example, if you submit a job at 11:15am with a time of the job will be eligible to run at 11:10am tomorrow.
-
- -A account_string
- Defines the account string associated with the job. The is an undefined string of characters and is interpreted by the server which executes the job. See section 2.7.1 of the PBS ERS.
- -b seconds
- Defines the maximum number of seconds qsub will block attempting to contact pbs_server. If pbs_server is down, or for a variety of communication failures, qsub will continually retry connecting to pbs_server for job submission. This value overrides the CLIENTRETRY parameter in torque.cfg. This is a non-portable TORQUE extension. Portability-minded users can use the PBS_CLIENTRETRY environmental variable. A negative value is interpreted as infinity. The default is 0.
- -c checkpoint_options
- Defines the options that will apply to the job. If the job executes upon a host which does not support checkpoint, these options will be ignored.
-
Valid checkpoint options are:
-
- none
- No checkpointing is to be performed.
- enabled
- Specify that checkpointing is allowed but must be explicitly invoked by either the qhold or qchkpt commands.
- shutdown
- Specify that checkpointing is to be done on a job at pbs_mom shutdown.
- periodic
- Specify that periodic checkpointing is enabled. The default interval is 10 minutes and can be changed by the $checkpoint_interval option in the mom config file or by specifying an interval when the job is submitted
- interval=minutes
- Checkpointing is to be performed at an interval of which is the integer number of minutes of wall time used by the job. This value must be greater than zero.
- depth=number
- Specify a number (depth) of checkpoint images to be kept in the checkpoint directory.
- dir=path
- Specify a checkpoint directory (default is /var/spool/torque/checkpoint).
-
where is the name of a host to which the file will be returned and is the path name on that host in the syntax recognized by POSIX. The argument will be interpreted as follows:
-
- path_name
job_name.esequence_number
where job_name is the name of the job, see option, and sequence_number is the job number assigned when the job is submitted.
OPERANDS
The qsub command accepts a operand that is the path to the script of the job. If the path is relative, it will be expanded relative to the working directory of the qsub command.If the operand is not provided or the operand is the single character "-", the qsub command reads the script from standard input. When the script is being read from Standard Input, qsub will copy the file to a temporary file. This temporary file is passed to the library interface routine pbs_submit. The temporary file is removed by qsub after pbs_submit returns or upon the receipt of a signal which would cause qsub to terminate.
STANDARD INPUT
The qsub command reads the script for the job from standard input if the operand is missing or is the single character "-".INPUT FILES
The file is read by the qsub command. Qsub acts upon any directives found in the script.When the job is created, a copy of the script file is made and that copy cannot be modified.
STANDARD OUTPUT
Unless the option is set, the job identifier assigned to the job will be written to standard output if the job is successfully created.STANDARD ERROR
The qsub command will write a diagnostic message to standard error for each error occurrence.ENVIRONMENT VARIABLES
The values of some or all of the variables in the qsub command's environment are exported with the job, see the -v and -V options.The environment variable PBS_DEFAULT defines the name of the default server. Typically, it corresponds to the system name of the host on which the server is running. If PBS_DEFAULT is not set, the default is defined by an administrator established file.
The environment variable PBS_DPREFIX determines the prefix string which identifies directives in the script.
The environment variable PBS_CLIENTRETRY defines the maximum number of seconds qsub will block. See the -b option above. Despite the name, currently qsub is the only client that supports this option.
TORQUE.CFG
The torque.cfg file, located in PBS_SERVER_HOME (/var/spool/torque by default) controls the behavior of the qsub command. This file contains a list of parameters and values separated by whitespaceQSUBSLEEP takes an integer operand which specifies time to sleep when running qsub command. Used to prevent users from overwhelming the scheduler.
SUBMITFILTER specifies the path to the submit filter used to pre-process job submission. The default path is $(libexecdir)/qsub_filter, which falls back to /usr/local/sbin/torque_submitfilter for backwards compatibility. This torque.cfg parameter overrides this default.
SERVERHOST specifies the value for the PBS_SERVER environment variable
QSUBHOST specifies the hostname for the jobs QSUB_O_HOST variable
QSUBSENDUID specifies a uid to use for the jobs PBS_O_UID variable
XAUTHPATH specifies the path to xauth
CLIENTRETRY specifies the integer seconds between retry attempts to communicate with pbs_server
VALIDATEGROUP set this parameter to force qsub to verify the submitter's group id
DEFAULTCKPT specifies the default value for the jobs checkpoint attribute. The user overrides this with the -c qsub option.
VALIDATEPATH set this parameter to force qsub to validate local existence of a "-d" working directory
RERUNNABLEBYDEFAULT this parameter specifies if a job is rerunnable by default. The default is true, setting this to false causes the rerunnable attribute value to be false unless the users specifies otherwise with the -r option
FAULT_TOLERANT_BY_DEFAULT this parameter specifies if a job is fault tolerant by default. The default value for the fault_tolerant job attribute is false, setting this parameter to true causes the default value of the attribute to be true. The user can specify their preference with the -f qsub option.
For example:
EXTENDED DESCRIPTION
Script Processing:
A job script may consist of PBS directives, comments and executable statements. A PBS directive provides a way of specifying job attributes in addition to the command line options. For example:
The qsub command scans the lines of the script file for directives. An initial line in the script that begins with the characters "#!" or the character ":" will be ignored and scanning will start with the next line. Scanning will continue until the first executable line, that is a line that is not blank, not a directive line, nor a line whose first non white space character is "#". If directives occur on subsequent lines, they will be ignored.
A line in the script file will be processed as a directive to qsub if and only if the string of characters starting with the first non white space character on the line and of the same length as the directive prefix matches the directive prefix.
The remainder of the directive line consists of the options to qsub in the same syntax as they appear on the command line. The option character is to be preceded with the "-" character.
If an option is present in both a directive and on the command line, that option and its argument, if any, will be ignored in the directive. The command line takes precedence.
If an option is present in a directive and not on the command line, that option and its argument, if any, will be processed as if it had occurred on the command line.
The directive prefix string will be determined in order of preference from:
-
The value of the option argument if the option is specified on the command line.
The value of the environment variable PBS_DPREFIX if it is defined.
The four character string
User Authorization:
When the user submits a job from a system other than the one on which the PBS Server is running, the name under which the job is to be executed is selected according to the rules listed under the -u option. The user submitting the job must be authorized to run the job under the execution user name. This authorization is provided if
-
- (1)
- The host on which qsub is run is trusted by the execution host (see /etc/hosts.equiv),
- (2)
- The execution user has an .rhosts file naming the submitting user on the submitting host.
C-Shell .logout File:
The following warning applies for users of the c-shell, csh.
If the job is executed under the csh and a
.logout
file exists in the home directory in which the job executes,
the exit status of the job is that of the .logout script, not the job script.
This may impact any inter-job dependencies.
To preserve the job exit status, either remove the .logout file or place the
following line as the first line in the .logout file
and the following line as the last executable line in .logout
Interactive Jobs:
If the option is specified on the command line or in a script directive, or if the "interactive" job attribute declared true via the -W option, either on the command line or in a script directive, the job is an interactive job. The script will be processed for directives, but will not be included with the job. When the job begins execution, all input to the job is from the terminal session in which qsub is running.
When an interactive job is submitted, the qsub command will not terminate when the job is submitted. Qsub will remain running until the job terminates, is aborted, or the user interrupts qsub with an SIGINT (the control-C key). If qsub is interrupted prior to job start, it will query if the user wishes to exit. If the user response "yes", qsub exits and the job is aborted.
Once the interactive job has started execution, input to and output from the job pass through qsub. Keyboard generated interrupts are passed to the job. Lines entered that begin with the tilde ('~') character and contain special sequences are escaped by qsub. The recognized escape sequences are:
-
- ~.
- Qsub terminates execution. The batch job is also terminated.
- ~susp
- Suspend the qsub program if running under the C shell. "susp" is the suspend character, usually CNTL-Z.
- ~asusp
- Suspend the input half of qsub (terminal to job), but allow output to continue to be displayed. Only works under the C shell. "asusp" is the auxiliary suspend character, usually CNTL-Y.
EXIT STATUS
Upon successful processing, the qsub exit status will be a value of zero.If the qsub command fails, the command exits with a value greater than zero.