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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       qsub -- submit a script

SSYYNNOOPPSSIISS
       qsub [[-a _d_a_t_e___t_i_m_e]] [[-A _a_c_c_o_u_n_t___s_t_r_i_n_g]] [[-c _i_n_t_e_r_v_a_l]]
           [[-C _d_i_r_e_c_t_i_v_e___p_r_e_f_i_x]] [[-e _p_a_t_h___n_a_m_e]] [[-h]] [[-j _j_o_i_n___l_i_s_t]]
           [[-k _k_e_e_p___l_i_s_t]] [[-m _m_a_i_l___o_p_t_i_o_n_s]] [[-M _m_a_i_l___l_i_s_t]] [[-N _n_a_m_e]]
           [[-o _p_a_t_h___n_a_m_e]] [[-p _p_r_i_o_r_i_t_y]] [[-q _d_e_s_t_i_n_a_t_i_o_n]] [[-r _y|_n]]
           [[-S _p_a_t_h___n_a_m_e___l_i_s_t]] [[-u _u_s_e_r___l_i_s_t]] [[-v _v_a_r_i_a_b_l_e___l_i_s_t]] [[-V]]
           [[-z]] [[_s_c_r_i_p_t]]

DDEESSCCRRIIPPTTIIOONN
       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 _q_s_u_b utility is
       a user-accessible batch client that submits a script.

       Upon successful completion, the _q_s_u_b utility shall have created a batch
       job that will execute the submitted script.

       The _q_s_u_b utility shall submit a script by sending a _Q_u_e_u_e _J_o_b _R_e_q_u_e_s_t
       to a batch server.

       The _q_s_u_b utility shall place the value of the following environment
       variables in the _V_a_r_i_a_b_l_e___L_i_s_t attribute of the batch job: _H_O_M_E, _L_A_N_G,
       _L_O_G_N_A_M_E, _P_A_T_H, _M_A_I_L, _S_H_E_L_L, and _T_Z.  The name of the environment
       variable shall be the current name prefixed with the string PBS_O_.

       NNoottee::     If the current value of the _H_O_M_E variable in the environment
                 space of the _q_s_u_b utility is //aaaa//bbbb//cccc, then _q_s_u_b shall place
                 _P_B_S___O___H_O_M_E=//aaaa//bbbb//cccc in the _V_a_r_i_a_b_l_e___L_i_s_t attribute of the
                 batch job.

       In addition to the variables described above, the _q_s_u_b utility shall
       add the following variables with the indicated values to the variable
       list:

       _P_B_S___O___W_O_R_K_D_I_R The absolute path of the current working directory of the
                     _q_s_u_b utility process.

       _P_B_S___O___H_O_S_T    The name of the host on which the _q_s_u_b utility is
                     running.

OOPPTTIIOONNSS
       The _q_s_u_b utility shall conform to the Base Definitions volume of
       POSIX.1-2008, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The following options shall be supported by the implementation:

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

                 The _q_s_u_b utility shall accept an option-argument that
                 conforms to the syntax of the _t_i_m_e operand of the _t_o_u_c_h
                 utility.

                      TTaabbllee 44--1199:: EEnnvviirroonnmmeenntt VVaarriiaabbllee VVaalluueess ((UUttiilliittiieess))

                          +--------------+---------------------------+
                          |VVaarriiaabbllee NNaammee |    VVaalluuee aatt qqssuubb TTiimmee     |
                          +--------------+---------------------------+
                          |_P_B_S___O___H_O_M_E    | _H_O_M_E                      |
                          |_P_B_S___O___H_O_S_T    | Client host name          |
                          |_P_B_S___O___L_A_N_G    | _L_A_N_G                      |
                          |_P_B_S___O___L_O_G_N_A_M_E | _L_O_G_N_A_M_E                   |
                          |_P_B_S___O___P_A_T_H    | _P_A_T_H                      |
                          |_P_B_S___O___M_A_I_L    | _M_A_I_L                      |
                          |_P_B_S___O___S_H_E_L_L   | _S_H_E_L_L                     |
                          |_P_B_S___O___T_Z      | _T_Z                        |
                          |_P_B_S___O___W_O_R_K_D_I_R | Current working directory |
                          +--------------+---------------------------+
                 NNoottee::     The server that initiates execution of the batch
                           job will add other variables to the batch job's
                           environment; see _S_e_c_t_i_o_n _3_._2_._2_._1, _B_a_t_c_h _J_o_b
                           _E_x_e_c_u_t_i_o_n.

                 The _q_s_u_b utility shall set the _E_x_e_c_u_t_i_o_n___T_i_m_e 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
                 _d_a_t_e___t_i_m_e option-argument. The Epoch is defined in the Base
                 Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _3_._1_5_0, _E_p_o_c_h.

                 If the --aa option is not presented to the _q_s_u_b utility, the
                 utility shall set the _E_x_e_c_u_t_i_o_n___T_i_m_e 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.

       --AA _a_c_c_o_u_n_t___s_t_r_i_n_g
                 Define the account to which the resource consumption of the
                 batch job should be charged.

                 The syntax of the _a_c_c_o_u_n_t___s_t_r_i_n_g option-argument is
                 unspecified.

                 The _q_s_u_b utility shall set the _A_c_c_o_u_n_t___N_a_m_e attribute of the
                 batch job to the value of the _a_c_c_o_u_n_t___s_t_r_i_n_g option-argument.

                 If the --AA option is not presented to the _q_s_u_b utility, the
                 utility shall omit the _A_c_c_o_u_n_t___N_a_m_e attribute from the
                 attributes of the batch job.

       --cc _i_n_t_e_r_v_a_l
                 Define whether the batch job should be checkpointed, and if
                 so, how often.

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

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

                 The _q_s_u_b utility shall set the _C_h_e_c_k_p_o_i_n_t attribute of the
                 batch job to the value of the _i_n_t_e_r_v_a_l option-argument.

                 If the --cc option is not presented to the _q_s_u_b utility, the
                 utility shall set the _C_h_e_c_k_p_o_i_n_t attribute of the batch job
                 to the single character ''uu'' (CHECKPOINT_UNSPECIFIED).

       --CC _d_i_r_e_c_t_i_v_e___p_r_e_f_i_x
                 Define the prefix that declares a directive to the _q_s_u_b
                 utility within the script.

                 The _d_i_r_e_c_t_i_v_e___p_r_e_f_i_x is not a batch job attribute; it affects
                 the behavior of the _q_s_u_b utility.

                 If the --CC option is presented to the _q_s_u_b utility, and the
                 value of the _d_i_r_e_c_t_i_v_e___p_r_e_f_i_x option-argument is the null
                 string, the utility shall not scan the script file for
                 directives. If the --CC option is not presented to the _q_s_u_b
                 utility, then the value of the _P_B_S___D_P_R_E_F_I_X environment
                 variable is used. If the environment variable is not defined,
                 then #PBS encoded in the portable character set is the
                 default.

       --ee _p_a_t_h___n_a_m_e
                 Define the path to be used for the standard error stream of
                 the batch job.

                 The _q_s_u_b utility shall accept a _p_a_t_h___n_a_m_e option-argument
                 which can be preceded by a host name element of the form
                 _h_o_s_t_n_a_m_e:.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes an absolute
                 pathname, the _q_s_u_b utility shall set the _E_r_r_o_r___P_a_t_h attribute
                 of the batch job to the value of the _p_a_t_h___n_a_m_e option-
                 argument.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes a relative
                 pathname and no host name element is specified, the _q_s_u_b
                 utility shall set the _E_r_r_o_r___P_a_t_h attribute of the batch job
                 to the value of the absolute pathname derived by expanding
                 the _p_a_t_h___n_a_m_e option-argument relative to the current
                 directory of the process executing _q_s_u_b.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes a relative
                 pathname and a host name element is specified, the _q_s_u_b
                 utility shall set the _E_r_r_o_r___P_a_t_h attribute of the batch job
                 to the value of the _p_a_t_h___n_a_m_e option-argument without
                 expansion. The host name element shall be included.

                 If the _p_a_t_h___n_a_m_e option-argument does not include a host name
                 element, the _q_s_u_b utility shall prefix the pathname with
                 _h_o_s_t_n_a_m_e:, where _h_o_s_t_n_a_m_e is the name of the host upon which
                 the _q_s_u_b utility is being executed.

                 If the --ee option is not presented to the _q_s_u_b utility, the
                 utility shall set the _E_r_r_o_r___P_a_t_h 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:

                     _j_o_b___n_a_m_e.e_s_e_q_u_e_n_c_e___n_u_m_b_e_r

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

                 The _q_s_u_b utility shall set the value of the _H_o_l_d___T_y_p_e_s
                 attribute of the batch job to the value USER.

                 If the --hh option is not presented to the _q_s_u_b utility, the
                 utility shall set the _H_o_l_d___T_y_p_e_s attribute of the batch job
                 to the value NO_HOLD.

       --jj _j_o_i_n___l_i_s_t
                 Define which streams of the batch job are to be merged. The
                 _q_s_u_b --jj option shall accept a value for the _j_o_i_n___l_i_s_t option-
                 argument that is a string of alphanumeric characters in the
                 portable character set (see the Base Definitions volume of
                 POSIX.1-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t).

                 The _q_s_u_b utility shall accept a _j_o_i_n___l_i_s_t option-argument
                 that consists of one or more of the characters ''ee'' and ''oo'',
                 or the single character ''nn''.

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

                 For each unique character in the _j_o_i_n___l_i_s_t option-argument,
                 the _q_s_u_b utility shall add a value to the _J_o_i_n___P_a_t_h 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 _J_o_i_n___P_a_t_h attribute can be cleared by the
                 following join type:

                 n     NO_JOIN

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

                 Strictly conforming applications shall not repeat any of the
                 characters ''ee'', ''oo'', or ''nn'' within the _j_o_i_n___l_i_s_t option-
                 argument. The _q_s_u_b 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 --jj option is not presented to the _q_s_u_b utility, the
                 utility shall set the value of the _J_o_i_n___P_a_t_h attribute of the
                 batch job to NO_JOIN.

       --kk _k_e_e_p___l_i_s_t
                 Define which output of the batch job to retain on the
                 execution host.

                 The _q_s_u_b --kk option shall accept a value for the _k_e_e_p___l_i_s_t
                 option-argument that is a string of alphanumeric characters
                 in the portable character set (see the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t).

                 The _q_s_u_b utility shall accept a _k_e_e_p___l_i_s_t option-argument
                 that consists of one or more of the characters ''ee'' and ''oo'',
                 or the single character ''nn''.

                 For each unique character in the _k_e_e_p___l_i_s_t option-argument,
                 the _q_s_u_b utility shall add a value to the _K_e_e_p___F_i_l_e_s
                 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 ''ee'' and ''oo'' are specified, then both files are
                 retained. An existing _K_e_e_p___F_i_l_e_s attribute can be cleared by
                 the following keep type:

                 n     NO_KEEP

                 If ''nn'' is specified, then no files are retained. The _q_s_u_b
                 utility shall consider it an error if any keep type other
                 than ''nn'' is combined with keep type ''nn''.

                 Strictly conforming applications shall not repeat any of the
                 characters ''ee'', ''oo'', or ''nn'' within the _k_e_e_p___l_i_s_t option-
                 argument. The _q_s_u_b 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 --kk option is not presented to the _q_s_u_b utility, the
                 utility shall set the _K_e_e_p___F_i_l_e_s attribute of the batch job
                 to the value NO_KEEP.

       --mm _m_a_i_l___o_p_t_i_o_n_s
                 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 _q_s_u_b --mm option shall accept a value for the _m_a_i_l___o_p_t_i_o_n_s
                 option-argument that is a string of alphanumeric characters
                 in the portable character set (see the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t).

                 The _q_s_u_b utility shall accept a value for the _m_a_i_l___o_p_t_i_o_n_s
                 option-argument that is a string of one or more of the
                 characters ''ee'', ''bb'', and ''aa'', or the single character ''nn''.

                 For each unique character in the _m_a_i_l___o_p_t_i_o_n_s option-
                 argument, the _q_s_u_b utility shall add a value to the
                 _M_a_i_l___U_s_e_r_s 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 _m_a_i_l___o_p_t_i_o_n_s
                 option-argument, the duplicates shall be ignored.

                 An existing _M_a_i_l___P_o_i_n_t_s attribute can be cleared by the
                 following mail type:

                 n     NO_MAIL

                 If ''nn'' is specified, then mail is not sent. The _q_s_u_b utility
                 shall consider it an error if any mail type other than ''nn'' is
                 combined with mail type ''nn''.

                 Strictly conforming applications shall not repeat any of the
                 characters ''ee'', ''bb'', ''aa'', or ''nn'' within the _m_a_i_l___o_p_t_i_o_n_s
                 option-argument.

                 The _q_s_u_b 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 --mm option is not presented to the _q_s_u_b utility, the
                 utility shall set the _M_a_i_l___P_o_i_n_t_s attribute to the value
                 MAIL_AT_ABORT.

       --MM _m_a_i_l___l_i_s_t
                 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 _m_a_i_l___l_i_s_t option-argument is unspecified.

                 If the implementation of the _q_s_u_b utility uses a name service
                 to locate users, the utility should accept the syntax used by
                 the name service.

                 If the implementation of the _q_s_u_b utility does not use a name
                 service to locate users, the implementation should accept the
                 following syntax for user names:

                     _m_a_i_l___a_d_d_r_e_s_s[[,,_m_a_i_l___a_d_d_r_e_s_s,, ...]]

                 The interpretation of _m_a_i_l___a_d_d_r_e_s_s is implementation-defined.

                 The _q_s_u_b utility shall set the _M_a_i_l___U_s_e_r_s attribute of the
                 batch job to the value of the _m_a_i_l___l_i_s_t option-argument.

                 If the --MM option is not presented to the _q_s_u_b utility, the
                 utility shall place only the user name and host name for the
                 current process in the _M_a_i_l___U_s_e_r_s attribute of the batch job.

       --NN _n_a_m_e   Define the name of the batch job.

                 The _q_s_u_b --NN option shall accept a value for the _n_a_m_e 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-2008, _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t)
                 where the first character is alphabetic.

                 The _q_s_u_b utility shall set the value of the _J_o_b___N_a_m_e
                 attribute of the batch job to the value of the _n_a_m_e option-
                 argument.

                 If the --NN option is not presented to the _q_s_u_b utility, the
                 utility shall set the _J_o_b___N_a_m_e attribute of the batch job to
                 the name of the _s_c_r_i_p_t argument from which the directory
                 specification if any, has been removed.

                 If the --NN option is not presented to the _q_s_u_b utility, and
                 the script is read from standard input, the utility shall set
                 the _J_o_b___N_a_m_e attribute of the batch job to the value STDIN.

       --oo _p_a_t_h___n_a_m_e
                 Define the path for the standard output of the batch job.

                 The _q_s_u_b utility shall accept a _p_a_t_h___n_a_m_e option-argument
                 that conforms to the syntax of the _p_a_t_h___n_a_m_e element defined
                 in the System Interfaces volume of POSIX.1-2008, which can be
                 preceded by a host name element of the form _h_o_s_t_n_a_m_e:.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes an absolute
                 pathname, the _q_s_u_b utility shall set the _O_u_t_p_u_t___P_a_t_h
                 attribute of the batch job to the value of the _p_a_t_h___n_a_m_e
                 option-argument without expansion.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes a relative
                 pathname and no host name element is specified, the _q_s_u_b
                 utility shall set the _O_u_t_p_u_t___P_a_t_h attribute of the batch job
                 to the pathname derived by expanding the value of the
                 _p_a_t_h___n_a_m_e option-argument relative to the current directory
                 of the process executing the _q_s_u_b.

                 If the _p_a_t_h___n_a_m_e option-argument constitutes a relative
                 pathname and a host name element is specified, the _q_s_u_b
                 utility shall set the _O_u_t_p_u_t___P_a_t_h attribute of the batch job
                 to the value of the _p_a_t_h___n_a_m_e option-argument without
                 expansion.

                 If the _p_a_t_h___n_a_m_e option-argument does not specify a host name
                 element, the _q_s_u_b utility shall prefix the pathname with
                 _h_o_s_t_n_a_m_e:, where _h_o_s_t_n_a_m_e is the name of the host upon which
                 the _q_s_u_b utility is executing.

                 If the --oo option is not presented to the _q_s_u_b utility, the
                 utility shall set the _O_u_t_p_u_t___P_a_t_h 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:

                     _j_o_b___n_a_m_e.o_s_e_q_u_e_n_c_e___n_u_m_b_e_r

       --pp _p_r_i_o_r_i_t_y
                 Define the priority the batch job should have relative to
                 other batch jobs owned by the batch server.

                 The _q_s_u_b utility shall set the _P_r_i_o_r_i_t_y attribute of the
                 batch job to the value of the _p_r_i_o_r_i_t_y option-argument.

                 If the --pp option is not presented to the _q_s_u_b utility, the
                 value of the _P_r_i_o_r_i_t_y attribute is implementation-defined.

                 The _q_s_u_b utility shall accept a value for the _p_r_i_o_r_i_t_y
                 option-argument that conforms to the syntax for signed
                 decimal integers, and which is not less than -1024 and not
                 greater than 1023.

       --qq _d_e_s_t_i_n_a_t_i_o_n
                 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
                 _q_s_u_b utility batch queues the batch job.

                 The _q_s_u_b utility shall submit the script to the batch server
                 named by the _d_e_s_t_i_n_a_t_i_o_n option-argument or the server that
                 owns the batch queue named in the _d_e_s_t_i_n_a_t_i_o_n option-
                 argument.

                 The _q_s_u_b utility shall accept an option-argument for the --qq
                 option that conforms to the syntax for a destination (see
                 _S_e_c_t_i_o_n _3_._3_._2, _D_e_s_t_i_n_a_t_i_o_n).

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

       --rr _y|_n    Define whether the batch job is rerunnable.

                 If the value of the option-argument is _y, the _q_s_u_b utility
                 shall set the _R_e_r_u_n_a_b_l_e attribute of the batch job to TRUE.

                 If the value of the option-argument is _n, the _q_s_u_b utility
                 shall set the _R_e_r_u_n_a_b_l_e attribute of the batch job to FALSE.

                 If the --rr option is not presented to the _q_s_u_b utility, the
                 utility shall set the _R_e_r_u_n_a_b_l_e attribute of the batch job to
                 TRUE.

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

                 The _q_s_u_b utility shall accept a _p_a_t_h___n_a_m_e___l_i_s_t option-
                 argument that conforms to the following syntax:

                     _p_a_t_h_n_a_m_e[[@_h_o_s_t]][[,,_p_a_t_h_n_a_m_e[[@_h_o_s_t]],, ...]]

                 The _q_s_u_b utility shall allow only one pathname for a given
                 host name. The _q_s_u_b utility shall allow only one pathname
                 that is missing a corresponding host name.

                 The _q_s_u_b utility shall add a value to the _S_h_e_l_l___P_a_t_h___L_i_s_t
                 attribute of the batch job for each entry in the
                 _p_a_t_h___n_a_m_e___l_i_s_t option-argument.

                 If the --SS option is not presented to the _q_s_u_b utility, the
                 utility shall set the _S_h_e_l_l___P_a_t_h___L_i_s_t 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 _S_e_c_t_i_o_n _3_._3_._3, _M_u_l_t_i_p_l_e _K_e_y_w_o_r_d_-_V_a_l_u_e _P_a_i_r_s
                 for a means of removing _k_e_y_w_o_r_d=_v_a_l_u_e (and _v_a_l_u_e@_k_e_y_w_o_r_d)
                 pairs and other general rules for list-oriented batch job
                 attributes.

       --uu _u_s_e_r___l_i_s_t
                 Define the user name under which the batch job is to execute.

                 The _q_s_u_b utility shall accept a _u_s_e_r___l_i_s_t option-argument
                 that conforms to the following syntax:

                     _u_s_e_r_n_a_m_e[[@_h_o_s_t]][[,,_u_s_e_r_n_a_m_e[[@_h_o_s_t]],, ...]]

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

                 The _q_s_u_b utility shall add a value to the _U_s_e_r___L_i_s_t attribute
                 of the batch job for each entry in the _u_s_e_r___l_i_s_t option-
                 argument.

                 If the --uu option is not presented to the _q_s_u_b utility, the
                 utility shall set the _U_s_e_r___L_i_s_t attribute of the batch job to
                 the user name from which the utility is executing. See
                 _S_e_c_t_i_o_n _3_._3_._3, _M_u_l_t_i_p_l_e _K_e_y_w_o_r_d_-_V_a_l_u_e _P_a_i_r_s for a means of
                 removing _k_e_y_w_o_r_d=_v_a_l_u_e (and _v_a_l_u_e@_k_e_y_w_o_r_d) pairs and other
                 general rules for list-oriented batch job attributes.

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

                 A _v_a_r_i_a_b_l_e___l_i_s_t is a set of strings of either the form
                 <_v_a_r_i_a_b_l_e> or <_v_a_r_i_a_b_l_e=_v_a_l_u_e>, delimited by <comma>
                 characters.

                 If the --vv option is presented to the _q_s_u_b utility, the
                 utility shall also add, to the environment _V_a_r_i_a_b_l_e___L_i_s_t
                 attribute of the batch job, every variable named in the
                 environment _v_a_r_i_a_b_l_e___l_i_s_t option-argument and, optionally,
                 values of specified variables.

                 If a value is not provided on the command line, the _q_s_u_b
                 utility shall set the value of each variable in the
                 environment _V_a_r_i_a_b_l_e___L_i_s_t attribute of the batch job to the
                 value of the corresponding environment variable for the
                 process in which the utility is executing; see _T_a_b_l_e _4_-_1_9_,
                 _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e _V_a_l_u_e_s _(_U_t_i_l_i_t_i_e_s_).

                 A conforming application shall not repeat a variable in the
                 environment _v_a_r_i_a_b_l_e___l_i_s_t option-argument.

                 The _q_s_u_b utility shall not repeat a variable in the
                 environment _V_a_r_i_a_b_l_e___L_i_s_t attribute of the batch job. See
                 _S_e_c_t_i_o_n _3_._3_._3, _M_u_l_t_i_p_l_e _K_e_y_w_o_r_d_-_V_a_l_u_e _P_a_i_r_s for a means of
                 removing _k_e_y_w_o_r_d=_v_a_l_u_e (and _v_a_l_u_e@_k_e_y_w_o_r_d) pairs and other
                 general rules for list-oriented batch job attributes.

       --VV        Specify that all of the environment variables of the process
                 are exported to the context of the batch job.

                 The _q_s_u_b 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.

       --zz        Specify that the utility does not write the batch
                 _j_o_b___i_d_e_n_t_i_f_i_e_r of the created batch job to standard output.

                 If the --zz option is presented to the _q_s_u_b utility, the
                 utility shall not write the batch _j_o_b___i_d_e_n_t_i_f_i_e_r of the
                 created batch job to standard output.

                 If the --zz option is not presented to the _q_s_u_b utility, the
                 utility shall write the identifier of the created batch job
                 to standard output.

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

       If the _s_c_r_i_p_t operand is not presented to the _q_s_u_b 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 _q_s_u_b utility shall expand
       the path relative to the current directory of the process executing the
       utility.

SSTTDDIINN
       The _q_s_u_b utility reads the script of the batch job from standard input
       if the script operand is omitted or is the single character ''--''.

IINNPPUUTT FFIILLEESS
       In addition to binding the file indicated by the _s_c_r_i_p_t operand to the
       batch job, the _q_s_u_b utility reads the script file and acts on
       directives in the script.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _q_s_u_b:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2008, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s the precedence of internationalization variables
                 used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _L_O_G_N_A_M_E   Determine the login name of the user.

       _P_B_S___D_P_R_E_F_I_X
                 Determine the default prefix for directives within the
                 script.

       _S_H_E_L_L     Determine the pathname of the preferred command language
                 interpreter of the user.

       _T_Z        Determine the timezone used to interpret the _d_a_t_e_-_t_i_m_e
                 option-argument. If _T_Z is unset or null, an unspecified
                 default timezone shall be used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Once created, a batch job exists until it exits, aborts, or is deleted.

       After a batch job is created by the _q_s_u_b utility, batch servers might
       route, execute, modify, or delete the batch job.

SSTTDDOOUUTT
       The _q_s_u_b utility writes the batch _j_o_b___i_d_e_n_t_i_f_i_e_r assigned to the batch
       job to standard output, unless the --zz option is specified.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
   SSccrriipptt PPrreesseerrvvaattiioonn
       The _q_s_u_b 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 _q_s_u_b utility can send a copy of the script to the server with the
       _Q_u_e_u_e _J_o_b _R_e_q_u_e_s_t or store a temporary copy of the script in a location
       specified to the server.

   OOppttiioonn SSppeecciiffiiccaattiioonn
       A script can contain directives to the _q_s_u_b utility.

       The _q_s_u_b 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 _q_s_u_b
       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 _q_s_u_b 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 _q_s_u_b utility.

       The _q_s_u_b 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
       _q_s_u_b 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 _q_s_u_b utility, the utility shall process the option and
       the option-argument, if any.

       In order of preference, the _q_s_u_b utility shall select the directive
       prefix from one of the following sources:

        *  If the --CC option is presented to the utility, the value of the
           _d_i_r_e_c_t_i_v_e___p_r_e_f_i_x option-argument

        *  If the environment variable _P_B_S___D_P_R_E_F_I_X is defined, the value of
           that variable

        *  The four-character string ""##PPBBSS"" encoded in the portable character
           set

       If the --CC option is present in the script file it shall be ignored.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       The _q_s_u_b utility allows users to create a batch job that will process
       the script specified as the operand of the utility.

       The options of the _q_s_u_b utility allow users to control many aspects of
       the queuing and execution of a batch job.

       The --aa 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 --AA 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 --CC option allows users to prescribe the prefix for directives
       within the script file. The default prefix ""##PPBBSS"" may be inappropriate
       if the script will be interpreted with an alternate shell, as specified
       by the --SS option.

       The --cc option allows users to establish the checkpointing interval for
       their jobs. A checkpointing system, which is not defined by this volume
       of POSIX.1-2008, 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-2008 provides the
       checkpointing interval option. Support for checkpointing is optional
       for batch servers.

       The --ee 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 --hh 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 --jj 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 --mm 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 --MM 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 --NN 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 _q_s_t_a_t
       utility.

       The --oo 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 --PP option allows users to designate the relative priority of a
       batch job for selection from a queue.

       The --qq 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 --rr 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 --rr option likewise allows users to indicate whether or not
       the batch job is eligible to be rerun by the _q_r_e_r_u_n 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-2008 specifies that the default, if the --rr 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 --SS 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 --uu option is useful when the submitting user is authorized to use
       more than one account on a given host, in which case the --uu 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 --uu 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 --uu option.

       The --VV 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 --vv option allows users to export specific environment variables
       from their current process to the processes of the batch job.

       The --zz option allows users to suppress the writing of the batch job
       identifier to standard output. The --zz option is an existing NQS
       practice that has been standardized.

       Historically, the _q_s_u_b 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 _q_s_u_b utility in this
       volume of POSIX.1-2008, _v_i_s_-_a_-_v_i_s NQS, as a result of the growing pool
       of experience with distributed batch systems.

       The set of features of the _q_s_u_b utility as defined in this volume of
       POSIX.1-2008 appears to incorporate all the common existing practice on
       potentially conforming platforms.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       The _q_s_u_b utility may be removed in a future version.

SSEEEE AALLSSOO
       _C_h_a_p_t_e_r _3, _B_a_t_c_h _E_n_v_i_r_o_n_m_e_n_t _S_e_r_v_i_c_e_s, _q_r_e_r_u_n, _q_s_t_a_t, _t_o_u_c_h

       The Base Definitions volume of POSIX.1-2008, _S_e_c_t_i_o_n _3_._1_5_0, _E_p_o_c_h,
       _S_e_c_t_i_o_n _6_._1, _P_o_r_t_a_b_l_e _C_h_a_r_a_c_t_e_r _S_e_t, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t _V_a_r_i_a_b_l_e_s,
       _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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                  2013                              QSUB(1)
