Provided by: manpages-posix_2017a-2_all bug

PROLOG

       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

       qsub — submit a script

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 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 NameValue 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

       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

       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 directives 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   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

       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.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

   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

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

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

       The qsub utility may be removed in a future version.

SEE ALSO

       Chapter 3, Batch Environment Services, qrerun, qstat, touch

       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

       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 .