qsub(1p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

QSUB(1P)                POSIX Programmer's Manual               QSUB(1P)

PROLOG         top

       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.

NAME         top

       qsub — submit a script

SYNOPSIS         top

       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         top

       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         top

       The qsub utility shall conform to the Base Definitions volume of
       POSIX.1‐2017, 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 execution.

                 The qsub utility shall accept an option-argument that
                 conforms to the syntax of the time operand of the touch
                 utility.

                   Table 4-19: Environment Variable Values (Utilities)
                     ┌───────────────┬───────────────────────────┐
                     │ Variable Name Value at qsub Time     │
                     ├───────────────┼───────────────────────────┤
                     │ PBS_O_HOMEHOME                      │
                     │ PBS_O_HOST    │ Client host name          │
                     │ PBS_O_LANGLANG                      │
                     │ PBS_O_LOGNAMELOGNAME                   │
                     │ PBS_O_PATHPATH                      │
                     │ PBS_O_MAILMAIL                      │
                     │ PBS_O_SHELLSHELL                     │
                     │ PBS_O_TZTZ                        │
                     │ 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 Section 3.2.2.1, 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
                 POSIX.1‐2017, Section 3.150, 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 (number 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_CHECKPOINT).

                 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 Minimum_Cpu_Interval
                           attribute of the batch queue, in units of CPU
                           minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).

                 c=minutes Automatic periodic checkpointing shall be
                           performed every minutes of CPU time, or every
                           Minimum_Cpu_Interval minutes, whichever is
                           greater. The minutes argument shall conform
                           to the syntax for unsigned integers and shall
                           be greater than zero.

                 The qsub utility shall set the Checkpoint attribute of
                 the batch job to the value of the interval option-
                 argument.

                 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 character '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 presented
                 to the qsub utility, then the value of the PBS_DPREFIX
                 environment 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 hostname is the name of
                 the host upon which the qsub utility is being executed.

                 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:

                     job_name.esequence_number

       -h        Specify that a USER hold is applied to the batch job.

                 The qsub utility shall set the value of the Hold_Types
                 attribute of the batch job to the value USER.

                 If the -h option is not presented to the qsub utility,
                 the utility shall set the Hold_Types attribute of the
                 batch job to the value NO_HOLD.

       -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 POSIX.1‐2017,
                 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 utility 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.

                 The qsub -k option shall accept a value for the
                 keep_list option-argument that is a string of
                 alphanumeric characters in the portable character set
                 (see the Base Definitions volume of POSIX.1‐2017,
                 Section 6.1, Portable Character Set).

                 The qsub utility shall accept a keep_list option-
                 argument that consists of one or more of the characters
                 'e' and 'o', or the single character 'n'.

                 For each unique character in the keep_list option-
                 argument, the qsub utility shall add a value to the
                 Keep_Files attribute of the batch job 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 utility 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 POSIX.1‐2017,
                 Section 6.1, Portable Character Set).

                 The qsub utility shall accept a value for the
                 mail_options option-argument 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     MAIL_AT_EXIT

                 b     MAIL_AT_BEGINNING

                 a     MAIL_AT_ABORT

                 If any of these characters are duplicated in the
                 mail_options option-argument, the duplicates shall be
                 ignored.

                 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 consider 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 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.

                 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 that is a string of up to 15
                 alphanumeric characters in the portable character set
                 (see the Base Definitions volume of POSIX.1‐2017,
                 Section 6.1, Portable Character Set) where the first
                 character is alphabetic.

                 The qsub utility shall set the value of the Job_Name
                 attribute of the batch job to the value of the name
                 option-argument.

                 If the -N option is not presented to the qsub utility,
                 the utility shall set the Job_Name attribute of the
                 batch job to the name of the script argument from which
                 the directory specification if any, has been removed.

                 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
                 POSIX.1‐2017, 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 Output_Path attribute of the
                 batch job to the pathname derived by expanding 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 Output_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 hostname 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 not less than -1024 and
                 not greater than 1023.

       -q destination
                 Define the destination of the batch job.

                 The destination is not a batch job attribute; it
                 determines the batch server, and possibly the batch
                 queue, to which the qsub utility batch queues the batch
                 job.

                 The qsub utility shall submit the script to the batch
                 server named by the destination option-argument or the
                 server that owns the batch queue 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 Section 3.3.2, 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 corresponding 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 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 Section 3.3.3, 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.

                 The qsub utility shall accept a user_list option-
                 argument that conforms to the following syntax:

                     username[@host][,,username[@host],, ...]

                 The qsub utility shall accept only one user name that
                 is missing a corresponding host name. The qsub utility
                 shall accept only one user name per named host.

                 The qsub utility shall add a value to the User_List
                 attribute of the batch job for each entry in the
                 user_list option-argument.

                 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 Section 3.3.3, 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 <comma>
                 characters.

                 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 environment
                 variable for the process in which the utility is
                 executing; see Table 4-19, 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 Variable_List attribute of the batch job.
                 See Section 3.3.3, 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         top

       The qsub utility shall accept a script operand that indicates the
       path to the script of the batch job.

       If the script operand is not presented to the qsub utility, or if
       the operand is the single-character string '-', the utility shall
       read the script from standard input.

       If the script represents a partial path, the qsub utility shall
       expand the path relative to the current directory of the process
       executing the utility.

STDIN         top

       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         top

       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 directives in the script.

ENVIRONMENT VARIABLES         top

       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 POSIX.1‐2017, Section 8.2,
                 Internationalization Variables 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 interpreter of the user.

       TZ        Determine the timezone used to interpret the date-time
                 option-argument. If TZ is unset or null, an unspecified
                 default timezone shall be used.

ASYNCHRONOUS EVENTS         top

       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         top

       The qsub utility writes the batch job_identifier assigned to the
       batch job to standard output, unless the -z option is specified.

STDERR         top

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES         top

       None.

EXTENDED DESCRIPTION         top

   Script Preservation
       The qsub 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.

       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 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> 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
       contained 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 conformance document the format of any shell
       comments that it will recognize.

       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.

EXIT STATUS         top

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       Default.

       The following sections are informative.

APPLICATION USAGE         top

       None.

EXAMPLES         top

       None.

RATIONALE         top

       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.

FUTURE DIRECTIONS         top

       The qsub utility may be removed in a future version.

SEE ALSO         top

       Chapter 3, Batch Environment Services, qrerun(1p), qstat(1p),
       touch(1p)

       The Base Definitions volume of POSIX.1‐2017, Section 3.150,
       Epoch, Section 6.1, Portable Character Set, Chapter 8,
       Environment Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic
       form from IEEE Std 1003.1-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 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 .

       Any typographical or formatting errors that appear in this page
       are most likely to have been introduced during the conversion of
       the source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group               2017                          QSUB(1P)

Pages that refer to this page: qalter(1p)qselect(1p)