Man Pages

qsub(1p) - phpMan qsub(1p) - phpMan

Command: man perldoc info search(apropos)  


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



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (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 indi-
       cated values to the variable list:

       PBS_O_WORKDIR
              The absolute path of the current working directory of the qsub utility process.

       PBS_O_HOST
              The name of the host on which the qsub utility is running.


OPTIONS
       The  qsub  utility  shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility
       Syntax Guidelines.

       The following options shall be supported by the implementation:

       -a  date_time
              Define the time at which a batch job becomes eligible for execution.

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

                                       Table: Environment Variable Values (Utilities)

                                          Variable Name   Value at qsub Time
                                          PBS_O_HOME      HOME
                                          PBS_O_HOST      Client host name
                                          PBS_O_LANG      LANG

                                          PBS_O_LOGNAME   LOGNAME
                                          PBS_O_PATH      PATH
                                          PBS_O_MAIL      MAIL
                                          PBS_O_SHELL     SHELL
                                          PBS_O_TZ        TZ
                                          PBS_O_WORKDIR   Current working directory

       Note:
              The  server  that initiates execution of the batch job will add other variables to the batch job's envi-
              ronment; see Batch Job Execution .


       The qsub utility shall set the Execution_Time attribute of the batch job to the number  of  seconds  since  the
       Epoch  that  is equivalent to the local time expressed by the value of the date_time option-argument. The Epoch
       is defined in the Base Definitions volume of IEEE Std 1003.1-2001, Section 3.149, Epoch.

       If the -a option is not presented to the qsub utility, the utility shall set the  Execution_Time  attribute  of
       the  batch job to a time (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 Mini-
              mum_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-argu-
       ment.

       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 with-
       out 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  path-
       name 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  file-
       name.

       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 IEEE Std 1003.1-2001, Section 6.1, Portable Character Set).

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

       All  of  the  other batch job output streams specified will be merged into the output stream represented by the
       character listed first in the join_list option-argument.

       For each unique character in the join_list option-argument, the qsub utility shall add a value to the Join_Path
       attribute of the batch job as follows, each representing a different batch job stream to join:

       e
              The standard error of the batch job (JOIN_STD_ERROR).

       o
              The standard output of the batch job (JOIN_STD_OUTPUT).


       An existing Join_Path attribute can be cleared by the following join type:

       n
              NO_JOIN


       If  'n'  is  specified,  then no files are joined. The qsub utility shall consider it an error if any join type
       other than 'n' is combined with join type 'n' .

       Strictly conforming applications shall not repeat any of the characters 'e', 'o', or 'n' within  the  join_list
       option-argument.  The  qsub  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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, 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 implementa-
       tion  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-argu-
       ment.

       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 IEEE Std 1003.1-2001, 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 IEEE Std 1003.1-2001, which can be preceded by a host  name  element
       of the form hostname:.

       If  the  path_name option-argument constitutes an absolute pathname, the qsub utility shall set the Output_Path
       attribute of the batch job to the value of the path_name option-argument without expansion.

       If the path_name option-argument constitutes a relative pathname and no host name  element  is  specified,  the
       qsub  utility  shall  set  the  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  path-
       name 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  file-
       name.

       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-argu-
       ment.

       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  destina-
       tion (see Destination ).

       If  the  -q  option  is  not  presented to the qsub utility, the qsub utility shall submit the batch job to the
       default destination. The mechanism for determining the default destination is implementation-defined.

       -r  y|n
              Define whether the batch job is rerunnable.

       If the value of the option-argument is y, the qsub utility shall set the Rerunable attribute of the  batch  job
       to TRUE.

       If  the  value of the option-argument is n, the qsub utility shall set the Rerunable attribute of the batch job
       to FALSE.

       If the -r option is not presented to the qsub utility, the utility shall set the  Rerunable  attribute  of  the
       batch job to TRUE.

       -S  path_name_list

              Define the pathname to the shell under which the batch job is to execute.

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


              pathname[@host][,,pathname[@host],, ...]

       The  qsub  utility  shall  allow only one pathname for a given host name. The qsub utility shall allow only one
       pathname that is missing a 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  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 Multiple Keyword-Value Pairs for a means of
       removing keyword= value (and value@ keyword)  pairs  and  other  general  rules  for  list-oriented  batch  job
       attributes.

       -v  variable_list

              Add to the list of variables that are exported to the session leader of the batch job.

       A  variable_list is a set of strings of either the form < variable> or < variable= value>, delimited by commas.

       If the -v option is presented to the qsub utility, the utility shall also add, to the environment Variable_List
       attribute  of the batch job, every variable named in the environment variable_list option-argument and, option-
       ally, 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 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
       Multiple  Keyword-Value  Pairs for a means of removing keyword= value (and value@ keyword) pairs and other gen-
       eral 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  direc-
       tory 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 IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for  the  prece-
              dence 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  exam-
              ple, 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 writ-
              ten 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 direc-
       tive.

       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 IEEE Std 1003.1-2001, allows recovery of a batch job at the most  recent
       checkpoint  in  the event of a crash. Checkpointing is typically used for jobs that consume expensive computing
       time or must meet a critical schedule. Users should be allowed to make the tradeoff  between  the  overhead  of
       checkpointing   and  the  risk  to  the  timely  completion  of  the  batch  job;  therefore,  this  volume  of
       IEEE Std 1003.1-2001 provides the checkpointing interval option. Support  for  checkpointing  is  optional  for
       batch servers.

       The  -e  option  allows  users  to redirect the standard error streams of their jobs to a non-default path. For
       example, if the submitted script generally produces a great deal of useless error output, a user might redirect
       the  standard  error  output  to the null device. Or, if the file system holding the default location (the home
       directory of the user) has too little free space, the user might redirect the standard error stream to  a  file
       in another file system.

       The  -h option allows users to create a batch job that is held until explicitly released. The ability to create
       a held job is useful when some external event must complete before the batch job can execute. For example,  the
       user might submit a held job and release it when the 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 process-
       ing 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 IEEE Std 1003.1-2001
       specifies that the default, if the -r option is not presented to the utility, will be that the batch job cannot
       be rerun, since the result of rerunning a non-rerunnable job might be 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
       IEEE Std 1003.1-2001,  vis-a-vis NQS, as a result of the growing pool of experience with distributed batch sys-
       tems.

       The set of features of the qsub utility as defined in this volume of IEEE Std 1003.1-2001 appears  to  incorpo-
       rate all the common existing practice on potentially conforming platforms.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Batch Environment Services, qrerun, qstat, touch

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  Issue  6,  Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The
       Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Stan-
       dard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                             QSUB(1P)