1QSUB(1P) POSIX Programmer's Manual QSUB(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 qsub - submit a script
13
15 qsub [-a date_time][-A account_string][-c interval]
16 [-C directive_prefix][-e path_name][-h][-j join_list][-k
17 keep_list]
18 [-m mail_options][-M mail_list][-N name]
19 [-o path_name][-p priority][-q destination][-r y|n]
20 [-S path_name_list][-u user_list][-v variable_list][-V]
21 [-z][script]
22
24 To submit a script is to create a batch job that executes the script.
25 A script is submitted by a request to a batch server. The qsub utility
26 is a user-accessible batch client that submits a script.
27 Upon successful completion, the qsub utility shall have created a batch
29 job that will execute the submitted script.
30 The qsub utility shall submit a script by sending a Queue Job Request
32 to a batch server.
33 The qsub utility shall place the value of the following environment
35 variables in the Variable_List attribute of the batch job: HOME, LANG,
36 LOGNAME, PATH, MAIL, SHELL, and TZ. The name of the environment
37 variable shall be the current name prefixed with the string PBS_O_.
38 Note: If the current value of the HOME variable in the environment
40 space of the qsub utility is /aa/bb/cc, then qsub shall place
41 PBS_O_HOME = /aa/bb/cc in the Variable_List attribute of the
42 batch job.
43 In addition to the variables described above, the qsub utility shall
46 add the following variables with the indicated values to the variable
47 list:
48 PBS_O_WORKDIR
50 The absolute path of the current working directory of the qsub
51 utility process.
52 PBS_O_HOST
54 The name of the host on which the qsub utility is running.
55
58 The qsub utility shall conform to the Base Definitions volume of
59 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
60 The following options shall be supported by the implementation:
62 -a date_time
64 Define the time at which a batch job becomes eligible for execu‐
65 tion.
66 The qsub utility shall accept an option-argument that conforms to the
68 syntax of the time operand of the touch utility.
69 Table: Environment Variable Values (Utilities)
71 Variable Name Value at qsub Time
73 PBS_O_HOME HOME
74 PBS_O_HOST Client host name
75 PBS_O_LANG LANG
76 PBS_O_LOGNAME LOGNAME
77 PBS_O_PATH PATH
78 PBS_O_MAIL MAIL
79 PBS_O_SHELL SHELL
80 PBS_O_TZ TZ
81 PBS_O_WORKDIR Current working directory
82 Note:
84 The server that initiates execution of the batch job will add
85 other variables to the batch job's environment; see Batch Job
86 Execution .
87 The qsub utility shall set the Execution_Time attribute of the batch
90 job to the number of seconds since the Epoch that is equivalent to the
91 local time expressed by the value of the date_time option-argument. The
92 Epoch is defined in the Base Definitions volume of
93 IEEE Std 1003.1-2001, Section 3.149, Epoch.
94 If the -a option is not presented to the qsub utility, the utility
96 shall set the Execution_Time attribute of the batch job to a time (num‐
97 ber of seconds since the Epoch) that is earlier than the time at which
98 the utility exits.
99 -A account_string
101 Define the account to which the resource consumption of the
103 batch job should be charged.
104 The syntax of the account_string option-argument is unspecified.
106 The qsub utility shall set the Account_Name attribute of the batch job
108 to the value of the account_string option-argument.
109 If the -A option is not presented to the qsub utility, the utility
111 shall omit the Account_Name attribute from the attributes of the batch
112 job.
113 -c interval
115 Define whether the batch job should be checkpointed, and if so,
116 how often.
117 The qsub utility shall accept a value for the interval option-argument
119 that is one of the following:
120 n
122 No checkpointing shall be performed on the batch job (NO_CHECK‐
123 POINT).
124 s
126 Checkpointing shall be performed only when the batch server is
127 shut down (CHECKPOINT_AT_SHUTDOWN).
128 c
130 Automatic periodic checkpointing shall be performed at the Mini‐
131 mum_Cpu_Interval attribute of the batch queue, in units of CPU
132 minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
133 c=minutes
135 Automatic periodic checkpointing shall be performed every min‐
136 utes of CPU time, or every Minimum_Cpu_Interval minutes, which‐
137 ever is greater. The minutes argument shall conform to the syn‐
138 tax for unsigned integers and shall be greater than zero.
139 The qsub utility shall set the Checkpoint attribute of the batch job to
142 the value of the interval option-argument.
143 If the -c option is not presented to the qsub utility, the utility
145 shall set the Checkpoint attribute of the batch job to the single char‐
146 acter 'u' (CHECKPOINT_UNSPECIFIED).
147 -C directive_prefix
149 Define the prefix that declares a directive to the qsub utility
151 within the script.
152 The directive_prefix is not a batch job attribute; it affects the
154 behavior of the qsub utility.
155 If the -C option is presented to the qsub utility, and the value of the
157 directive_prefix option-argument is the null string, the utility shall
158 not scan the script file for directives. If the -C option is not pre‐
159 sented to the qsub utility, then the value of the PBS_DPREFIX environ‐
160 ment variable is used. If the environment variable is not defined, then
161 #PBS encoded in the portable character set is the default.
162 -e path_name
164 Define the path to be used for the standard error stream of the
165 batch job.
166 The qsub utility shall accept a path_name option-argument which can be
168 preceded by a host name element of the form hostname:.
169 If the path_name option-argument constitutes an absolute pathname, the
171 qsub utility shall set the Error_Path attribute of the batch job to the
172 value of the path_name option-argument.
173 If the path_name option-argument constitutes a relative pathname and no
175 host name element is specified, the qsub utility shall set the
176 Error_Path attribute of the batch job to the value of the absolute
177 pathname derived by expanding the path_name option-argument relative to
178 the current directory of the process executing qsub.
179 If the path_name option-argument constitutes a relative pathname and a
181 host name element is specified, the qsub utility shall set the
182 Error_Path attribute of the batch job to the value of the path_name
183 option-argument without expansion. The host name element shall be
184 included.
185 If the path_name option-argument does not include a host name element,
187 the qsub utility shall prefix the pathname with hostname:, where host‐
188 name is the name of the host upon which the qsub utility is being exe‐
189 cuted.
190 If the -e option is not presented to the qsub utility, the utility
192 shall set the Error_Path attribute of the batch job to the host name
193 and path of the current directory of the submitting process and the
194 default filename.
195 The default filename for standard error has the following format:
197 job_name.esequence_number
200 -h Specify that a USER hold is applied to the batch job.
202 The qsub utility shall set the value of the Hold_Types attribute of the
204 batch job to the value USER.
205 If the -h option is not presented to the qsub utility, the utility
207 shall set the Hold_Types attribute of the batch job to the value
208 NO_HOLD.
209 -j join_list
211 Define which streams of the batch job are to be merged. The qsub
212 -j option shall accept a value for the join_list option-argument
213 that is a string of alphanumeric characters in the portable
214 character set (see the Base Definitions volume of
215 IEEE Std 1003.1-2001, Section 6.1, Portable Character Set).
216 The qsub utility shall accept a join_list option-argument that consists
218 of one or more of the characters 'e' and 'o', or the single character
219 'n' .
220 All of the other batch job output streams specified will be merged into
222 the output stream represented by the character listed first in the
223 join_list option-argument.
224 For each unique character in the join_list option-argument, the qsub
226 utility shall add a value to the Join_Path attribute of the batch job
227 as follows, each representing a different batch job stream to join:
228 e
230 The standard error of the batch job (JOIN_STD_ERROR).
231 o
233 The standard output of the batch job (JOIN_STD_OUTPUT).
234 An existing Join_Path attribute can be cleared by the following join
237 type:
238 n
240 NO_JOIN
241 If 'n' is specified, then no files are joined. The qsub utility shall
244 consider it an error if any join type other than 'n' is combined with
245 join type 'n' .
246 Strictly conforming applications shall not repeat any of the characters
248 'e', 'o', or 'n' within the join_list option-argument. The qsub utility
249 shall permit the repetition of characters, but shall not assign addi‐
250 tional meaning to the repeated characters.
251 An implementation may define other join types. The conformance document
253 for an implementation shall describe any additional batch job streams,
254 how they are specified, their internal behavior, and how they affect
255 the behavior of the utility.
256 If the -j option is not presented to the qsub utility, the utility
258 shall set the value of the Join_Path attribute of the batch job to
259 NO_JOIN.
260 -k keep_list
262 Define which output of the batch job to retain on the execution
263 host.
264 The qsub -k option shall accept a value for the keep_list option-argu‐
266 ment that is a string of alphanumeric characters in the portable char‐
267 acter set (see the Base Definitions volume of IEEE Std 1003.1-2001,
268 Section 6.1, Portable Character Set).
269 The qsub utility shall accept a keep_list option-argument that consists
271 of one or more of the characters 'e' and 'o', or the single character
272 'n' .
273 For each unique character in the keep_list option-argument, the qsub
275 utility shall add a value to the Keep_Files attribute of the batch job
276 as follows, each representing a different batch job stream to keep:
277 e
279 The standard error of the batch job (KEEP_STD_ERROR).
280 o
282 The standard output of the batch job (KEEP_STD_OUTPUT).
283 If both 'e' and 'o' are specified, then both files are retained. An
286 existing Keep_Files attribute can be cleared by the following keep
287 type:
288 n
290 NO_KEEP
291 If 'n' is specified, then no files are retained. The qsub utility shall
294 consider it an error if any keep type other than 'n' is combined with
295 keep type 'n' .
296 Strictly conforming applications shall not repeat any of the characters
298 'e', 'o', or 'n' within the keep_list option-argument. The qsub utility
299 shall permit the repetition of characters, but shall not assign addi‐
300 tional meaning to the repeated characters.
301 An implementation may define other keep types. The conformance document
303 for an implementation shall describe any additional keep types, how
304 they are specified, their internal behavior, and how they affect the
305 behavior of the utility. If the -k option is not presented to the qsub
306 utility, the utility shall set the Keep_Files attribute of the batch
307 job to the value NO_KEEP.
308 -m mail_options
310 Define the points in the execution of the batch job at which the
312 batch server that manages the batch job shall send mail about a
313 change in the state of the batch job.
314 The qsub -m option shall accept a value for the mail_options option-
316 argument that is a string of alphanumeric characters in the portable
317 character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
318 Section 6.1, Portable Character Set).
319 The qsub utility shall accept a value for the mail_options option-argu‐
321 ment that is a string of one or more of the characters 'e', 'b', and
322 'a', or the single character 'n' .
323 For each unique character in the mail_options option-argument, the qsub
325 utility shall add a value to the Mail_Users attribute of the batch job
326 as follows, each representing a different time during the life of a
327 batch job at which to send mail:
328 e
330 MAIL_AT_EXIT
331 b
333 MAIL_AT_BEGINNING
334 a
336 MAIL_AT_ABORT
337 If any of these characters are duplicated in the mail_options option-
340 argument, the duplicates shall be ignored.
341 An existing Mail_Points attribute can be cleared by the following mail
343 type:
344 n
346 NO_MAIL
347 If 'n' is specified, then mail is not sent. The qsub utility shall con‐
350 sider it an error if any mail type other than 'n' is combined with mail
351 type 'n' .
352 Strictly conforming applications shall not repeat any of the characters
354 'e', 'b', 'a', or 'n' within the mail_options option-argument.
355 The qsub utility shall permit the repetition of characters, but shall
357 not assign additional meaning to the repeated characters. An implemen‐
358 tation may define other mail types. The conformance document for an
359 implementation shall describe any additional mail types, how they are
360 specified, their internal behavior, and how they affect the behavior of
361 the utility.
362 If the -m option is not presented to the qsub utility, the utility
364 shall set the Mail_Points attribute to the value MAIL_AT_ABORT.
365 -M mail_list
367 Define the list of users to which a batch server that executes
368 the batch job shall send mail, if the server sends mail about
369 the batch job.
370 The syntax of the mail_list option-argument is unspecified.
372 If the implementation of the qsub utility uses a name service to locate
374 users, the utility should accept the syntax used by the name service.
375 If the implementation of the qsub utility does not use a name service
377 to locate users, the implementation should accept the following syntax
378 for user names:
379 mail_address[,,mail_address,, ...]
382 The interpretation of mail_address is implementation-defined.
384 The qsub utility shall set the Mail_Users attribute of the batch job to
386 the value of the mail_list option-argument.
387 If the -M option is not presented to the qsub utility, the utility
389 shall place only the user name and host name for the current process in
390 the Mail_Users attribute of the batch job.
391 -N name
393 Define the name of the batch job.
394 The qsub -N option shall accept a value for the name option-argument
396 that is a string of up to 15 alphanumeric characters in the portable
397 character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
398 Section 6.1, Portable Character Set) where the first character is
399 alphabetic.
400 The qsub utility shall set the value of the Job_Name attribute of the
402 batch job to the value of the name option-argument.
403 If the -N option is not presented to the qsub utility, the utility
405 shall set the Job_Name attribute of the batch job to the name of the
406 script argument from which the directory specification if any, has been
407 removed.
408 If the -N option is not presented to the qsub utility, and the script
410 is read from standard input, the utility shall set the Job_Name
411 attribute of the batch job to the value STDIN.
412 -o path_name
414 Define the path for the standard output of the batch job.
415 The qsub utility shall accept a path_name option-argument that conforms
417 to the syntax of the path_name element defined in the System Interfaces
418 volume of IEEE Std 1003.1-2001, which can be preceded by a host name
419 element of the form hostname:.
420 If the path_name option-argument constitutes an absolute pathname, the
422 qsub utility shall set the Output_Path attribute of the batch job to
423 the value of the path_name option-argument without expansion.
424 If the path_name option-argument constitutes a relative pathname and no
426 host name element is specified, the qsub utility shall set the Out‐
427 put_Path attribute of the batch job to the pathname derived by expand‐
428 ing the value of the path_name option-argument relative to the current
429 directory of the process executing the qsub.
430 If the path_name option-argument constitutes a relative pathname and a
432 host name element is specified, the qsub utility shall set the Out‐
433 put_Path attribute of the batch job to the value of the path_name
434 option-argument without expansion.
435 If the path_name option-argument does not specify a host name element,
437 the qsub utility shall prefix the pathname with hostname:, where host‐
438 name is the name of the host upon which the qsub utility is executing.
439 If the -o option is not presented to the qsub utility, the utility
441 shall set the Output_Path attribute of the batch job to the host name
442 and path of the current directory of the submitting process and the
443 default filename.
444 The default filename for standard output has the following format:
446 job_name.osequence_number
449 -p priority
451 Define the priority the batch job should have relative to other
452 batch jobs owned by the batch server.
453 The qsub utility shall set the Priority attribute of the batch job to
455 the value of the priority option-argument.
456 If the -p option is not presented to the qsub utility, the value of the
458 Priority attribute is implementation-defined.
459 The qsub utility shall accept a value for the priority option-argument
461 that conforms to the syntax for signed decimal integers, and which is
462 not less than -1024 and not greater than 1023.
463 -q destination
465 Define the destination of the batch job.
467 The destination is not a batch job attribute; it determines the batch
469 server, and possibly the batch queue, to which the qsub utility batch
470 queues the batch job.
471 The qsub utility shall submit the script to the batch server named by
473 the destination option-argument or the server that owns the batch queue
474 named in the destination option-argument.
475 The qsub utility shall accept an option-argument for the -q option that
477 conforms to the syntax for a destination (see Destination ).
478 If the -q option is not presented to the qsub utility, the qsub utility
480 shall submit the batch job to the default destination. The mechanism
481 for determining the default destination is implementation-defined.
482 -r y|n
484 Define whether the batch job is rerunnable.
485 If the value of the option-argument is y, the qsub utility shall set
487 the Rerunable attribute of the batch job to TRUE.
488 If the value of the option-argument is n, the qsub utility shall set
490 the Rerunable attribute of the batch job to FALSE.
491 If the -r option is not presented to the qsub utility, the utility
493 shall set the Rerunable attribute of the batch job to TRUE.
494 -S path_name_list
496 Define the pathname to the shell under which the batch job is to
498 execute.
499 The qsub utility shall accept a path_name_list option-argument that
501 conforms to the following syntax:
502 pathname[@host][,,pathname[@host],, ...]
505 The qsub utility shall allow only one pathname for a given host name.
507 The qsub utility shall allow only one pathname that is missing a corre‐
508 sponding host name.
509 The qsub utility shall add a value to the Shell_Path_List attribute of
511 the batch job for each entry in the path_name_list option-argument.
512 If the -S option is not presented to the qsub utility, the utility
514 shall set the Shell_Path_List attribute of the batch job to the null
515 string.
516 The conformance document for an implementation shall describe the mech‐
518 anism used to set the default shell and determine the current value of
519 the default shell. An implementation shall provide a means for the
520 installation to set the default shell to the login shell of the user
521 under which the batch job is to execute. See Multiple Keyword-Value
522 Pairs for a means of removing keyword= value (and value@ keyword) pairs
523 and other general rules for list-oriented batch job attributes.
524 -u user_list
526 Define the user name under which the batch job is to execute.
527 The qsub utility shall accept a user_list option-argument that conforms
529 to the following syntax:
530 username[@host][,,username[@host],, ...]
533 The qsub utility shall accept only one user name that is missing a cor‐
535 responding host name. The qsub utility shall accept only one user name
536 per named host.
537 The qsub utility shall add a value to the User_List attribute of the
539 batch job for each entry in the user_list option-argument.
540 If the -u option is not presented to the qsub utility, the utility
542 shall set the User_List attribute of the batch job to the user name
543 from which the utility is executing. See Multiple Keyword-Value Pairs
544 for a means of removing keyword= value (and value@ keyword) pairs and
545 other general rules for list-oriented batch job attributes.
546 -v variable_list
548 Add to the list of variables that are exported to the session
550 leader of the batch job.
551 A variable_list is a set of strings of either the form < variable> or <
553 variable= value>, delimited by commas.
554 If the -v option is presented to the qsub utility, the utility shall
556 also add, to the environment Variable_List attribute of the batch job,
557 every variable named in the environment variable_list option-argument
558 and, optionally, values of specified variables.
559 If a value is not provided on the command line, the qsub utility shall
561 set the value of each variable in the environment Variable_List
562 attribute of the batch job to the value of the corresponding environ‐
563 ment variable for the process in which the utility is executing; see
564 Environment Variable Values (Utilities) .
565 A conforming application shall not repeat a variable in the environment
567 variable_list option-argument.
568 The qsub utility shall not repeat a variable in the environment Vari‐
570 able_List attribute of the batch job. See Multiple Keyword-Value Pairs
571 for a means of removing keyword= value (and value@ keyword) pairs and
572 other general rules for list-oriented batch job attributes.
573 -V Specify that all of the environment variables of the process are
575 exported to the context of the batch job.
576 The qsub utility shall place every environment variable in the process
578 in which the utility is executing in the list and shall set the value
579 of each variable in the attribute to the value of that variable in the
580 process.
581 -z Specify that the utility does not write the batch job_identifier
583 of the created batch job to standard output.
584 If the -z option is presented to the qsub utility, the utility shall
586 not write the batch job_identifier of the created batch job to standard
587 output.
588 If the -z option is not presented to the qsub utility, the utility
590 shall write the identifier of the created batch job to standard output.
591
594 The qsub utility shall accept a script operand that indicates the path
595 to the script of the batch job.
596 If the script operand is not presented to the qsub utility, or if the
598 operand is the single-character string '-', the utility shall read the
599 script from standard input.
600 If the script represents a partial path, the qsub utility shall expand
602 the path relative to the current directory of the process executing the
603 utility.
604
606 The qsub utility reads the script of the batch job from standard input
607 if the script operand is omitted or is the single character '-' .
608
610 In addition to binding the file indicated by the script operand to the
611 batch job, the qsub utility reads the script file and acts on direc‐
612 tives in the script.
613
615 The following environment variables shall affect the execution of qsub:
616 LANG Provide a default value for the internationalization variables
618 that are unset or null. (See the Base Definitions volume of
619 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
620 ables for the precedence of internationalization variables used
621 to determine the values of locale categories.)
622 LC_ALL If set to a non-empty string value, override the values of all
624 the other internationalization variables.
625 LC_CTYPE
627 Determine the locale for the interpretation of sequences of
628 bytes of text data as characters (for example, single-byte as
629 opposed to multi-byte characters in arguments).
630 LC_MESSAGES
632 Determine the locale that should be used to affect the format
633 and contents of diagnostic messages written to standard error.
634 LOGNAME
636 Determine the login name of the user.
637 PBS_DPREFIX
639 Determine the default prefix for directives within the script.
641 SHELL Determine the pathname of the preferred command language inter‐
643 preter of the user.
644 TZ Determine the timezone used to interpret the date-time option-
646 argument. If TZ is unset or null, an unspecified default time‐
647 zone shall be used.
648
651 Once created, a batch job exists until it exits, aborts, or is deleted.
652 After a batch job is created by the qsub utility, batch servers might
654 route, execute, modify, or delete the batch job.
655
657 The qsub utility writes the batch job_identifier assigned to the batch
658 job to standard output, unless the -z option is specified.
659
661 The standard error shall be used only for diagnostic messages.
662
664 None.
665
667 Script Preservation
668 The qsub utility shall make the script available to the server execut‐
669 ing the batch job in such a way that the server executes the script as
670 it exists at the time of submission.
671 The qsub utility can send a copy of the script to the server with the
673 Queue Job Request or store a temporary copy of the script in a location
674 specified to the server.
675 Option Specification
677 A script can contain directives to the qsub utility.
678 The qsub utility shall scan the lines of the script for directives,
680 skipping blank lines, until the first line that begins with a string
681 other than the directive string; if directives occur on subsequent
682 lines, the utility shall ignore those directives.
683 Lines are separated by a <newline>. If the first line of the script
685 begins with "#!" or a colon ( ':' ), then it is skipped. The qsub util‐
686 ity shall process a line in the script as a directive if and only if
687 the string of characters from the first non-white-space character on
688 the line until the first <space> or <tab> on the line match the direc‐
689 tive prefix. If a line in the script contains a directive and the final
690 characters of the line are backslash ( '\' ) and <newline>, then the
691 next line shall be interpreted as a continuation of that directive.
692 The qsub utility shall process the options and option-arguments con‐
694 tained on the directive prefix line using the same syntax as if the
695 options were input on the qsub utility.
696 The qsub utility shall continue to process a directive prefix line
698 until after a <newline> is encountered. An implementation may ignore
699 lines which, according to the syntax of the shell that will interpret
700 the script, are comments. An implementation shall describe in the con‐
701 formance document the format of any shell comments that it will recog‐
702 nize.
703 If an option is present in both a directive and the arguments to the
705 qsub utility, the utility shall ignore the option and the corresponding
706 option-argument, if any, in the directive.
707 If an option that is present in the directive is not present in the
709 arguments to the qsub utility, the utility shall process the option and
710 the option-argument, if any.
711 In order of preference, the qsub utility shall select the directive
713 prefix from one of the following sources:
714 * If the -C option is presented to the utility, the value of the
716 directive_prefix option-argument
717 * If the environment variable PBS_DPREFIX is defined, the value of
719 that variable
720 * The four-character string "#PBS" encoded in the portable character
722 set
723 If the -C option is present in the script file it shall be ignored.
725
727 The following exit values shall be returned:
728 0 Successful completion.
730 >0 An error occurred.
732
735 Default.
736 The following sections are informative.
738
740 None.
741
743 None.
744
746 The qsub utility allows users to create a batch job that will process
747 the script specified as the operand of the utility.
748 The options of the qsub utility allow users to control many aspects of
750 the queuing and execution of a batch job.
751 The -a option allows users to designate the time after which the batch
753 job will become eligible to run. By specifying an execution time, users
754 can take advantage of resources at off-peak hours, synchronize jobs
755 with chronologically predictable events, and perhaps take advantage of
756 off-peak pricing of computing time. For these reasons and others, a
757 timing option is existing practice on the part of almost every batch
758 system, including NQS.
759 The -A option allows users to specify the account that will be charged
761 for the batch job. Support for account is not mandatory for conforming
762 batch servers.
763 The -C option allows users to prescribe the prefix for directives
765 within the script file. The default prefix "#PBS" may be inappropriate
766 if the script will be interpreted with an alternate shell, as specified
767 by the -S option.
768 The -c option allows users to establish the checkpointing interval for
770 their jobs. A checkpointing system, which is not defined by this volume
771 of IEEE Std 1003.1-2001, allows recovery of a batch job at the most
772 recent checkpoint in the event of a crash. Checkpointing is typically
773 used for jobs that consume expensive computing time or must meet a
774 critical schedule. Users should be allowed to make the tradeoff between
775 the overhead of checkpointing and the risk to the timely completion of
776 the batch job; therefore, this volume of IEEE Std 1003.1-2001 provides
777 the checkpointing interval option. Support for checkpointing is
778 optional for batch servers.
779 The -e option allows users to redirect the standard error streams of
781 their jobs to a non-default path. For example, if the submitted script
782 generally produces a great deal of useless error output, a user might
783 redirect the standard error output to the null device. Or, if the file
784 system holding the default location (the home directory of the user)
785 has too little free space, the user might redirect the standard error
786 stream to a file in another file system.
787 The -h option allows users to create a batch job that is held until
789 explicitly released. The ability to create a held job is useful when
790 some external event must complete before the batch job can execute. For
791 example, the user might submit a held job and release it when the sys‐
792 tem load has dropped.
793 The -j option allows users to merge the standard error of a batch job
795 into its standard output stream, which has the advantage of showing the
796 sequential relationship between output and error messages.
797 The -m option allows users to designate those points in the execution
799 of a batch job at which mail will be sent to the submitting user, or to
800 the account(s) indicated by the -M option. By requesting mail notifi‐
801 cation at points of interest in the life of a job, the submitting user,
802 or other designated users, can track the progress of a batch job.
803 The -N option allows users to associate a name with the batch job. The
805 job name in no way affects the processing of the batch job, but rather
806 serves as a mnemonic handle for users. For example, the batch job name
807 can help the user distinguish between multiple jobs listed by the qstat
808 utility.
809 The -o option allows users to redirect the standard output stream. A
811 user might, for example, wish to redirect to the null device the stan‐
812 dard output stream of a job that produces copious yet superfluous out‐
813 put.
814 The -P option allows users to designate the relative priority of a
816 batch job for selection from a queue.
817 The -q option allows users to specify an initial queue for the batch
819 job. If the user specifies a routing queue, the batch server routes the
820 batch job to another queue for execution or further routing. If the
821 user specifies a non-routing queue, the batch server of the queue even‐
822 tually executes the batch job.
823 The -r option allows users to control whether the submitted job will be
825 rerun if the controlling batch node fails during execution of the batch
826 job. The -r option likewise allows users to indicate whether or not the
827 batch job is eligible to be rerun by the qrerun utility. Some jobs can‐
828 not be correctly rerun because of changes they make in the state of
829 databases or other aspects of their environment. This volume of
830 IEEE Std 1003.1-2001 specifies that the default, if the -r option is
831 not presented to the utility, will be that the batch job cannot be
832 rerun, since the result of rerunning a non-rerunnable job might be cat‐
833 astrophic.
834 The -S option allows users to specify the program (usually a shell)
836 that will be invoked to process the script of the batch job. This
837 option has been modified to allow a list of shell names and locations
838 associated with different hosts.
839 The -u option is useful when the submitting user is authorized to use
841 more than one account on a given host, in which case the -u option
842 allows the user to select from among those accounts. The option-argu‐
843 ment is a list of user-host pairs, so that the submitting user can pro‐
844 vide different user identifiers for different nodes in the event the
845 batch job is routed. The -u option provides a lot of flexibility to
846 accommodate sites with complex account structures. Users that have the
847 same user identifier on all the hosts they are authorized to use will
848 not need to use the -u option.
849 The -V option allows users to export all their current environment
851 variables, as of the time the batch job is submitted, to the context of
852 the processes of the batch job.
853 The -v option allows users to export specific environment variables
855 from their current process to the processes of the batch job.
856 The -z option allows users to suppress the writing of the batch job
858 identifier to standard output. The -z option is an existing NQS prac‐
859 tice that has been standardized.
860 Historically, the qsub utility has served the batch job-submission
862 function in the NQS system, the existing practice on which it is based.
863 Some changes and additions have been made to the qsub utility in this
864 volume of IEEE Std 1003.1-2001, vis-a-vis NQS, as a result of the grow‐
865 ing pool of experience with distributed batch systems.
866 The set of features of the qsub utility as defined in this volume of
868 IEEE Std 1003.1-2001 appears to incorporate all the common existing
869 practice on potentially conforming platforms.
870
872 None.
873
875 Batch Environment Services, qrerun, qstat, touch
876
878 Portions of this text are reprinted and reproduced in electronic form
879 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
880 -- Portable Operating System Interface (POSIX), The Open Group Base
881 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
882 Electrical and Electronics Engineers, Inc and The Open Group. In the
883 event of any discrepancy between this version and the original IEEE and
884 The Open Group Standard, the original IEEE and The Open Group Standard
885 is the referee document. The original Standard can be obtained online
886 at http://www.opengroup.org/unix/online.html .
887IEEE/The Open Group 2003 QSUB(1P)