1QSUB(P) POSIX Programmer's Manual QSUB(P)
2
6 qsub - submit a script
7
9 qsub [-a date_time][-A account_string][-c interval]
10 [-C directive_prefix][-e path_name][-h][-j join_list][-k
11 keep_list]
12 [-m mail_options][-M mail_list][-N name]
13 [-o path_name][-p priority][-q destination][-r y|n]
14 [-S path_name_list][-u user_list][-v variable_list][-V]
15 [-z][script]
16
18 To submit a script is to create a batch job that executes the script.
19 A script is submitted by a request to a batch server. The qsub utility
20 is a user-accessible batch client that submits a script.
21 Upon successful completion, the qsub utility shall have created a batch
23 job that will execute the submitted script.
24 The qsub utility shall submit a script by sending a Queue Job Request
26 to a batch server.
27 The qsub utility shall place the value of the following environment
29 variables in the Variable_List attribute of the batch job: HOME , LANG
30 , LOGNAME , PATH , MAIL , SHELL , and TZ . The name of the environment
31 variable shall be the current name prefixed with the string PBS_O_.
32 Note: If the current value of the HOME variable in the environment
34 space of the qsub utility is /aa/bb/cc, then qsub shall place
35 PBS_O_HOME = /aa/bb/cc in the Variable_List attribute of the
36 batch job.
37 In addition to the variables described above, the qsub utility shall
40 add the following variables with the indicated values to the variable
41 list:
42 PBS_O_WORKDIR
44 The absolute path of the current working directory of the qsub
45 utility process.
46 PBS_O_HOST
48 The name of the host on which the qsub utility is running.
49
52 The qsub utility shall conform to the Base Definitions volume of
53 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
54 The following options shall be supported by the implementation:
56 -a date_time
58 Define the time at which a batch job becomes eligible for execu‐
59 tion.
60 The qsub utility shall accept an option-argument that conforms to the
62 syntax of the time operand of the touch utility.
63 Table: Environment Variable Values (Utilities)
65 Variable Name Value at qsub Time
68 PBS_O_HOME HOME
69 PBS_O_HOST Client host name
70 PBS_O_LANG LANG
71 PBS_O_LOGNAME LOGNAME
72 PBS_O_PATH PATH
73 PBS_O_MAIL MAIL
74 PBS_O_SHELL SHELL
75 PBS_O_TZ TZ
76 PBS_O_WORKDIR Current working directory
77 Note:
79 The server that initiates execution of the batch job will add
80 other variables to the batch job's environment; see Batch Job
81 Execution .
82 The qsub utility shall set the Execution_Time attribute of the batch
85 job to the number of seconds since the Epoch that is equivalent to the
86 local time expressed by the value of the date_time option-argument. The
87 Epoch is defined in the Base Definitions volume of
88 IEEE Std 1003.1-2001, Section 3.149, Epoch.
89 If the -a option is not presented to the qsub utility, the utility
91 shall set the Execution_Time attribute of the batch job to a time (num‐
92 ber of seconds since the Epoch) that is earlier than the time at which
93 the utility exits.
94 -A account_string
96 Define the account to which the resource consumption of the
98 batch job should be charged.
99 The syntax of the account_string option-argument is unspecified.
101 The qsub utility shall set the Account_Name attribute of the batch job
103 to the value of the account_string option-argument.
104 If the -A option is not presented to the qsub utility, the utility
106 shall omit the Account_Name attribute from the attributes of the batch
107 job.
108 -c interval
110 Define whether the batch job should be checkpointed, and if so,
111 how often.
112 The qsub utility shall accept a value for the interval option-argument
114 that is one of the following:
115 n
117 No checkpointing shall be performed on the batch job (NO_CHECK‐
118 POINT).
119 s
121 Checkpointing shall be performed only when the batch server is
122 shut down (CHECKPOINT_AT_SHUTDOWN).
123 c
125 Automatic periodic checkpointing shall be performed at the Mini‐
126 mum_Cpu_Interval attribute of the batch queue, in units of CPU
127 minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
128 c=minutes
130 Automatic periodic checkpointing shall be performed every min‐
131 utes of CPU time, or every Minimum_Cpu_Interval minutes, which‐
132 ever is greater. The minutes argument shall conform to the syn‐
133 tax for unsigned integers and shall be greater than zero.
134 The qsub utility shall set the Checkpoint attribute of the batch job to
137 the value of the interval option-argument.
138 If the -c option is not presented to the qsub utility, the utility
140 shall set the Checkpoint attribute of the batch job to the single char‐
141 acter 'u' (CHECKPOINT_UNSPECIFIED).
142 -C directive_prefix
144 Define the prefix that declares a directive to the qsub utility
146 within the script.
147 The directive_prefix is not a batch job attribute; it affects the
149 behavior of the qsub utility.
150 If the -C option is presented to the qsub utility, and the value of the
152 directive_prefix option-argument is the null string, the utility shall
153 not scan the script file for directives. If the -C option is not pre‐
154 sented to the qsub utility, then the value of the PBS_DPREFIX environ‐
155 ment variable is used. If the environment variable is not defined, then
156 #PBS encoded in the portable character set is the default.
157 -e path_name
159 Define the path to be used for the standard error stream of the
160 batch job.
161 The qsub utility shall accept a path_name option-argument which can be
163 preceded by a host name element of the form hostname:.
164 If the path_name option-argument constitutes an absolute pathname, the
166 qsub utility shall set the Error_Path attribute of the batch job to the
167 value of the path_name option-argument.
168 If the path_name option-argument constitutes a relative pathname and no
170 host name element is specified, the qsub utility shall set the
171 Error_Path attribute of the batch job to the value of the absolute
172 pathname derived by expanding the path_name option-argument relative to
173 the current directory of the process executing qsub.
174 If the path_name option-argument constitutes a relative pathname and a
176 host name element is specified, the qsub utility shall set the
177 Error_Path attribute of the batch job to the value of the path_name
178 option-argument without expansion. The host name element shall be
179 included.
180 If the path_name option-argument does not include a host name element,
182 the qsub utility shall prefix the pathname with hostname:, where host‐
183 name is the name of the host upon which the qsub utility is being exe‐
184 cuted.
185 If the -e option is not presented to the qsub utility, the utility
187 shall set the Error_Path attribute of the batch job to the host name
188 and path of the current directory of the submitting process and the
189 default filename.
190 The default filename for standard error has the following format:
192 job_name.esequence_number
195 -h Specify that a USER hold is applied to the batch job.
197 The qsub utility shall set the value of the Hold_Types attribute of the
199 batch job to the value USER.
200 If the -h option is not presented to the qsub utility, the utility
202 shall set the Hold_Types attribute of the batch job to the value
203 NO_HOLD.
204 -j join_list
206 Define which streams of the batch job are to be merged. The qsub
207 -j option shall accept a value for the join_list option-argument
208 that is a string of alphanumeric characters in the portable
209 character set (see the Base Definitions volume of
210 IEEE Std 1003.1-2001, Section 6.1, Portable Character Set).
211 The qsub utility shall accept a join_list option-argument that consists
213 of one or more of the characters 'e' and 'o' , or the single character
214 'n' .
215 All of the other batch job output streams specified will be merged into
217 the output stream represented by the character listed first in the
218 join_list option-argument.
219 For each unique character in the join_list option-argument, the qsub
221 utility shall add a value to the Join_Path attribute of the batch job
222 as follows, each representing a different batch job stream to join:
223 e
225 The standard error of the batch job (JOIN_STD_ERROR).
226 o
228 The standard output of the batch job (JOIN_STD_OUTPUT).
229 An existing Join_Path attribute can be cleared by the following join
232 type:
233 n
235 NO_JOIN
236 If 'n' is specified, then no files are joined. The qsub utility shall
239 consider it an error if any join type other than 'n' is combined with
240 join type 'n' .
241 Strictly conforming applications shall not repeat any of the characters
243 'e' , 'o' , or 'n' within the join_list option-argument. The qsub util‐
244 ity shall permit the repetition of characters, but shall not assign
245 additional meaning to the repeated characters.
246 An implementation may define other join types. The conformance document
248 for an implementation shall describe any additional batch job streams,
249 how they are specified, their internal behavior, and how they affect
250 the behavior of the utility.
251 If the -j option is not presented to the qsub utility, the utility
253 shall set the value of the Join_Path attribute of the batch job to
254 NO_JOIN.
255 -k keep_list
257 Define which output of the batch job to retain on the execution
258 host.
259 The qsub -k option shall accept a value for the keep_list option-argu‐
261 ment that is a string of alphanumeric characters in the portable char‐
262 acter set (see the Base Definitions volume of IEEE Std 1003.1-2001,
263 Section 6.1, Portable Character Set).
264 The qsub utility shall accept a keep_list option-argument that consists
266 of one or more of the characters 'e' and 'o' , or the single character
267 'n' .
268 For each unique character in the keep_list option-argument, the qsub
270 utility shall add a value to the Keep_Files attribute of the batch job
271 as follows, each representing a different batch job stream to keep:
272 e
274 The standard error of the batch job (KEEP_STD_ERROR).
275 o
277 The standard output of the batch job (KEEP_STD_OUTPUT).
278 If both 'e' and 'o' are specified, then both files are retained. An
281 existing Keep_Files attribute can be cleared by the following keep
282 type:
283 n
285 NO_KEEP
286 If 'n' is specified, then no files are retained. The qsub utility shall
289 consider it an error if any keep type other than 'n' is combined with
290 keep type 'n' .
291 Strictly conforming applications shall not repeat any of the characters
293 'e' , 'o' , or 'n' within the keep_list option-argument. The qsub util‐
294 ity shall permit the repetition of characters, but shall not assign
295 additional meaning to the repeated characters.
296 An implementation may define other keep types. The conformance document
298 for an implementation shall describe any additional keep types, how
299 they are specified, their internal behavior, and how they affect the
300 behavior of the utility. If the -k option is not presented to the qsub
301 utility, the utility shall set the Keep_Files attribute of the batch
302 job to the value NO_KEEP.
303 -m mail_options
305 Define the points in the execution of the batch job at which the
307 batch server that manages the batch job shall send mail about a
308 change in the state of the batch job.
309 The qsub -m option shall accept a value for the mail_options option-
311 argument that is a string of alphanumeric characters in the portable
312 character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
313 Section 6.1, Portable Character Set).
314 The qsub utility shall accept a value for the mail_options option-argu‐
316 ment that is a string of one or more of the characters 'e' , 'b' , and
317 'a' , or the single character 'n' .
318 For each unique character in the mail_options option-argument, the qsub
320 utility shall add a value to the Mail_Users attribute of the batch job
321 as follows, each representing a different time during the life of a
322 batch job at which to send mail:
323 e
325 MAIL_AT_EXIT
326 b
328 MAIL_AT_BEGINNING
329 a
331 MAIL_AT_ABORT
332 If any of these characters are duplicated in the mail_options option-
335 argument, the duplicates shall be ignored.
336 An existing Mail_Points attribute can be cleared by the following mail
338 type:
339 n
341 NO_MAIL
342 If 'n' is specified, then mail is not sent. The qsub utility shall con‐
345 sider it an error if any mail type other than 'n' is combined with mail
346 type 'n' .
347 Strictly conforming applications shall not repeat any of the characters
349 'e' , 'b' , 'a' , or 'n' within the mail_options option-argument.
350 The qsub utility shall permit the repetition of characters, but shall
352 not assign additional meaning to the repeated characters. An implemen‐
353 tation may define other mail types. The conformance document for an
354 implementation shall describe any additional mail types, how they are
355 specified, their internal behavior, and how they affect the behavior of
356 the utility.
357 If the -m option is not presented to the qsub utility, the utility
359 shall set the Mail_Points attribute to the value MAIL_AT_ABORT.
360 -M mail_list
362 Define the list of users to which a batch server that executes
363 the batch job shall send mail, if the server sends mail about
364 the batch job.
365 The syntax of the mail_list option-argument is unspecified.
367 If the implementation of the qsub utility uses a name service to locate
369 users, the utility should accept the syntax used by the name service.
370 If the implementation of the qsub utility does not use a name service
372 to locate users, the implementation should accept the following syntax
373 for user names:
374 mail_address[,,mail_address,, ...]
377 The interpretation of mail_address is implementation-defined.
379 The qsub utility shall set the Mail_Users attribute of the batch job to
381 the value of the mail_list option-argument.
382 If the -M option is not presented to the qsub utility, the utility
384 shall place only the user name and host name for the current process in
385 the Mail_Users attribute of the batch job.
386 -N name
388 Define the name of the batch job.
389 The qsub -N option shall accept a value for the name option-argument
391 that is a string of up to 15 alphanumeric characters in the portable
392 character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
393 Section 6.1, Portable Character Set) where the first character is
394 alphabetic.
395 The qsub utility shall set the value of the Job_Name attribute of the
397 batch job to the value of the name option-argument.
398 If the -N option is not presented to the qsub utility, the utility
400 shall set the Job_Name attribute of the batch job to the name of the
401 script argument from which the directory specification if any, has been
402 removed.
403 If the -N option is not presented to the qsub utility, and the script
405 is read from standard input, the utility shall set the Job_Name
406 attribute of the batch job to the value STDIN.
407 -o path_name
409 Define the path for the standard output of the batch job.
410 The qsub utility shall accept a path_name option-argument that conforms
412 to the syntax of the path_name element defined in the System Interfaces
413 volume of IEEE Std 1003.1-2001, which can be preceded by a host name
414 element of the form hostname:.
415 If the path_name option-argument constitutes an absolute pathname, the
417 qsub utility shall set the Output_Path attribute of the batch job to
418 the value of the path_name option-argument without expansion.
419 If the path_name option-argument constitutes a relative pathname and no
421 host name element is specified, the qsub utility shall set the Out‐
422 put_Path attribute of the batch job to the pathname derived by expand‐
423 ing the value of the path_name option-argument relative to the current
424 directory of the process executing the qsub.
425 If the path_name option-argument constitutes a relative pathname and a
427 host name element is specified, the qsub utility shall set the Out‐
428 put_Path attribute of the batch job to the value of the path_name
429 option-argument without expansion.
430 If the path_name option-argument does not specify a host name element,
432 the qsub utility shall prefix the pathname with hostname:, where host‐
433 name is the name of the host upon which the qsub utility is executing.
434 If the -o option is not presented to the qsub utility, the utility
436 shall set the Output_Path attribute of the batch job to the host name
437 and path of the current directory of the submitting process and the
438 default filename.
439 The default filename for standard output has the following format:
441 job_name.osequence_number
444 -p priority
446 Define the priority the batch job should have relative to other
447 batch jobs owned by the batch server.
448 The qsub utility shall set the Priority attribute of the batch job to
450 the value of the priority option-argument.
451 If the -p option is not presented to the qsub utility, the value of the
453 Priority attribute is implementation-defined.
454 The qsub utility shall accept a value for the priority option-argument
456 that conforms to the syntax for signed decimal integers, and which is
457 not less than -1024 and not greater than 1023.
458 -q destination
460 Define the destination of the batch job.
462 The destination is not a batch job attribute; it determines the batch
464 server, and possibly the batch queue, to which the qsub utility batch
465 queues the batch job.
466 The qsub utility shall submit the script to the batch server named by
468 the destination option-argument or the server that owns the batch queue
469 named in the destination option-argument.
470 The qsub utility shall accept an option-argument for the -q option that
472 conforms to the syntax for a destination (see Destination ).
473 If the -q option is not presented to the qsub utility, the qsub utility
475 shall submit the batch job to the default destination. The mechanism
476 for determining the default destination is implementation-defined.
477 -r y|n
479 Define whether the batch job is rerunnable.
480 If the value of the option-argument is y, the qsub utility shall set
482 the Rerunable attribute of the batch job to TRUE.
483 If the value of the option-argument is n, the qsub utility shall set
485 the Rerunable attribute of the batch job to FALSE.
486 If the -r option is not presented to the qsub utility, the utility
488 shall set the Rerunable attribute of the batch job to TRUE.
489 -S path_name_list
491 Define the pathname to the shell under which the batch job is to
493 execute.
494 The qsub utility shall accept a path_name_list option-argument that
496 conforms to the following syntax:
497 pathname[@host][,,pathname[@host],, ...]
500 The qsub utility shall allow only one pathname for a given host name.
502 The qsub utility shall allow only one pathname that is missing a corre‐
503 sponding host name.
504 The qsub utility shall add a value to the Shell_Path_List attribute of
506 the batch job for each entry in the path_name_list option-argument.
507 If the -S option is not presented to the qsub utility, the utility
509 shall set the Shell_Path_List attribute of the batch job to the null
510 string.
511 The conformance document for an implementation shall describe the mech‐
513 anism used to set the default shell and determine the current value of
514 the default shell. An implementation shall provide a means for the
515 installation to set the default shell to the login shell of the user
516 under which the batch job is to execute. See Multiple Keyword-Value
517 Pairs for a means of removing keyword= value (and value@ keyword) pairs
518 and other general rules for list-oriented batch job attributes.
519 -u user_list
521 Define the user name under which the batch job is to execute.
522 The qsub utility shall accept a user_list option-argument that conforms
524 to the following syntax:
525 username[@host][,,username[@host],, ...]
528 The qsub utility shall accept only one user name that is missing a cor‐
530 responding host name. The qsub utility shall accept only one user name
531 per named host.
532 The qsub utility shall add a value to the User_List attribute of the
534 batch job for each entry in the user_list option-argument.
535 If the -u option is not presented to the qsub utility, the utility
537 shall set the User_List attribute of the batch job to the user name
538 from which the utility is executing. See Multiple Keyword-Value Pairs
539 for a means of removing keyword= value (and value@ keyword) pairs and
540 other general rules for list-oriented batch job attributes.
541 -v variable_list
543 Add to the list of variables that are exported to the session
545 leader of the batch job.
546 A variable_list is a set of strings of either the form < variable> or <
548 variable= value>, delimited by commas.
549 If the -v option is presented to the qsub utility, the utility shall
551 also add, to the environment Variable_List attribute of the batch job,
552 every variable named in the environment variable_list option-argument
553 and, optionally, values of specified variables.
554 If a value is not provided on the command line, the qsub utility shall
556 set the value of each variable in the environment Variable_List
557 attribute of the batch job to the value of the corresponding environ‐
558 ment variable for the process in which the utility is executing; see
559 Environment Variable Values (Utilities) .
560 A conforming application shall not repeat a variable in the environment
562 variable_list option-argument.
563 The qsub utility shall not repeat a variable in the environment Vari‐
565 able_List attribute of the batch job. See Multiple Keyword-Value Pairs
566 for a means of removing keyword= value (and value@ keyword) pairs and
567 other general rules for list-oriented batch job attributes.
568 -V Specify that all of the environment variables of the process are
570 exported to the context of the batch job.
571 The qsub utility shall place every environment variable in the process
573 in which the utility is executing in the list and shall set the value
574 of each variable in the attribute to the value of that variable in the
575 process.
576 -z Specify that the utility does not write the batch job_identifier
578 of the created batch job to standard output.
579 If the -z option is presented to the qsub utility, the utility shall
581 not write the batch job_identifier of the created batch job to standard
582 output.
583 If the -z option is not presented to the qsub utility, the utility
585 shall write the identifier of the created batch job to standard output.
586
589 The qsub utility shall accept a script operand that indicates the path
590 to the script of the batch job.
591 If the script operand is not presented to the qsub utility, or if the
593 operand is the single-character string '-' , the utility shall read the
594 script from standard input.
595 If the script represents a partial path, the qsub utility shall expand
597 the path relative to the current directory of the process executing the
598 utility.
599
601 The qsub utility reads the script of the batch job from standard input
602 if the script operand is omitted or is the single character '-' .
603
605 In addition to binding the file indicated by the script operand to the
606 batch job, the qsub utility reads the script file and acts on direc‐
607 tives in the script.
608
610 The following environment variables shall affect the execution of qsub:
611 LANG Provide a default value for the internationalization variables
613 that are unset or null. (See the Base Definitions volume of
614 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
615 ables for the precedence of internationalization variables used
616 to determine the values of locale categories.)
617 LC_ALL If set to a non-empty string value, override the values of all
619 the other internationalization variables.
620 LC_CTYPE
622 Determine the locale for the interpretation of sequences of
623 bytes of text data as characters (for example, single-byte as
624 opposed to multi-byte characters in arguments).
625 LC_MESSAGES
627 Determine the locale that should be used to affect the format
628 and contents of diagnostic messages written to standard error.
629 LOGNAME
631 Determine the login name of the user.
632 PBS_DPREFIX
634 Determine the default prefix for directives within the script.
636 SHELL Determine the pathname of the preferred command language inter‐
638 preter of the user.
639 TZ Determine the timezone used to interpret the date-time option-
641 argument. If TZ is unset or null, an unspecified default time‐
642 zone shall be used.
643
646 Once created, a batch job exists until it exits, aborts, or is deleted.
647 After a batch job is created by the qsub utility, batch servers might
649 route, execute, modify, or delete the batch job.
650
652 The qsub utility writes the batch job_identifier assigned to the batch
653 job to standard output, unless the -z option is specified.
654
656 The standard error shall be used only for diagnostic messages.
657
659 None.
660
662 Script Preservation
663 The qsub utility shall make the script available to the server execut‐
664 ing the batch job in such a way that the server executes the script as
665 it exists at the time of submission.
666 The qsub utility can send a copy of the script to the server with the
668 Queue Job Request or store a temporary copy of the script in a location
669 specified to the server.
670 Option Specification
672 A script can contain directives to the qsub utility.
673 The qsub utility shall scan the lines of the script for directives,
675 skipping blank lines, until the first line that begins with a string
676 other than the directive string; if directives occur on subsequent
677 lines, the utility shall ignore those directives.
678 Lines are separated by a <newline>. If the first line of the script
680 begins with "#!" or a colon ( ':' ), then it is skipped. The qsub util‐
681 ity shall process a line in the script as a directive if and only if
682 the string of characters from the first non-white-space character on
683 the line until the first <space> or <tab> on the line match the direc‐
684 tive prefix. If a line in the script contains a directive and the final
685 characters of the line are backslash ( '\' ) and <newline>, then the
686 next line shall be interpreted as a continuation of that directive.
687 The qsub utility shall process the options and option-arguments con‐
689 tained on the directive prefix line using the same syntax as if the
690 options were input on the qsub utility.
691 The qsub utility shall continue to process a directive prefix line
693 until after a <newline> is encountered. An implementation may ignore
694 lines which, according to the syntax of the shell that will interpret
695 the script, are comments. An implementation shall describe in the con‐
696 formance document the format of any shell comments that it will recog‐
697 nize.
698 If an option is present in both a directive and the arguments to the
700 qsub utility, the utility shall ignore the option and the corresponding
701 option-argument, if any, in the directive.
702 If an option that is present in the directive is not present in the
704 arguments to the qsub utility, the utility shall process the option and
705 the option-argument, if any.
706 In order of preference, the qsub utility shall select the directive
708 prefix from one of the following sources:
709 * If the -C option is presented to the utility, the value of the
711 directive_prefix option-argument
712 * If the environment variable PBS_DPREFIX is defined, the value of
714 that variable
715 * The four-character string "#PBS" encoded in the portable character
717 set
718 If the -C option is present in the script file it shall be ignored.
720
722 The following exit values shall be returned:
723 0 Successful completion.
725 >0 An error occurred.
727
730 Default.
731 The following sections are informative.
733
735 None.
736
738 None.
739
741 The qsub utility allows users to create a batch job that will process
742 the script specified as the operand of the utility.
743 The options of the qsub utility allow users to control many aspects of
745 the queuing and execution of a batch job.
746 The -a option allows users to designate the time after which the batch
748 job will become eligible to run. By specifying an execution time, users
749 can take advantage of resources at off-peak hours, synchronize jobs
750 with chronologically predictable events, and perhaps take advantage of
751 off-peak pricing of computing time. For these reasons and others, a
752 timing option is existing practice on the part of almost every batch
753 system, including NQS.
754 The -A option allows users to specify the account that will be charged
756 for the batch job. Support for account is not mandatory for conforming
757 batch servers.
758 The -C option allows users to prescribe the prefix for directives
760 within the script file. The default prefix "#PBS" may be inappropriate
761 if the script will be interpreted with an alternate shell, as specified
762 by the -S option.
763 The -c option allows users to establish the checkpointing interval for
765 their jobs. A checkpointing system, which is not defined by this volume
766 of IEEE Std 1003.1-2001, allows recovery of a batch job at the most
767 recent checkpoint in the event of a crash. Checkpointing is typically
768 used for jobs that consume expensive computing time or must meet a
769 critical schedule. Users should be allowed to make the tradeoff between
770 the overhead of checkpointing and the risk to the timely completion of
771 the batch job; therefore, this volume of IEEE Std 1003.1-2001 provides
772 the checkpointing interval option. Support for checkpointing is
773 optional for batch servers.
774 The -e option allows users to redirect the standard error streams of
776 their jobs to a non-default path. For example, if the submitted script
777 generally produces a great deal of useless error output, a user might
778 redirect the standard error output to the null device. Or, if the file
779 system holding the default location (the home directory of the user)
780 has too little free space, the user might redirect the standard error
781 stream to a file in another file system.
782 The -h option allows users to create a batch job that is held until
784 explicitly released. The ability to create a held job is useful when
785 some external event must complete before the batch job can execute. For
786 example, the user might submit a held job and release it when the sys‐
787 tem load has dropped.
788 The -j option allows users to merge the standard error of a batch job
790 into its standard output stream, which has the advantage of showing the
791 sequential relationship between output and error messages.
792 The -m option allows users to designate those points in the execution
794 of a batch job at which mail will be sent to the submitting user, or to
795 the account(s) indicated by the -M option. By requesting mail notifi‐
796 cation at points of interest in the life of a job, the submitting user,
797 or other designated users, can track the progress of a batch job.
798 The -N option allows users to associate a name with the batch job. The
800 job name in no way affects the processing of the batch job, but rather
801 serves as a mnemonic handle for users. For example, the batch job name
802 can help the user distinguish between multiple jobs listed by the qstat
803 utility.
804 The -o option allows users to redirect the standard output stream. A
806 user might, for example, wish to redirect to the null device the stan‐
807 dard output stream of a job that produces copious yet superfluous out‐
808 put.
809 The -P option allows users to designate the relative priority of a
811 batch job for selection from a queue.
812 The -q option allows users to specify an initial queue for the batch
814 job. If the user specifies a routing queue, the batch server routes the
815 batch job to another queue for execution or further routing. If the
816 user specifies a non-routing queue, the batch server of the queue even‐
817 tually executes the batch job.
818 The -r option allows users to control whether the submitted job will be
820 rerun if the controlling batch node fails during execution of the batch
821 job. The -r option likewise allows users to indicate whether or not the
822 batch job is eligible to be rerun by the qrerun utility. Some jobs can‐
823 not be correctly rerun because of changes they make in the state of
824 databases or other aspects of their environment. This volume of
825 IEEE Std 1003.1-2001 specifies that the default, if the -r option is
826 not presented to the utility, will be that the batch job cannot be
827 rerun, since the result of rerunning a non-rerunnable job might be cat‐
828 astrophic.
829 The -S option allows users to specify the program (usually a shell)
831 that will be invoked to process the script of the batch job. This
832 option has been modified to allow a list of shell names and locations
833 associated with different hosts.
834 The -u option is useful when the submitting user is authorized to use
836 more than one account on a given host, in which case the -u option
837 allows the user to select from among those accounts. The option-argu‐
838 ment is a list of user-host pairs, so that the submitting user can pro‐
839 vide different user identifiers for different nodes in the event the
840 batch job is routed. The -u option provides a lot of flexibility to
841 accommodate sites with complex account structures. Users that have the
842 same user identifier on all the hosts they are authorized to use will
843 not need to use the -u option.
844 The -V option allows users to export all their current environment
846 variables, as of the time the batch job is submitted, to the context of
847 the processes of the batch job.
848 The -v option allows users to export specific environment variables
850 from their current process to the processes of the batch job.
851 The -z option allows users to suppress the writing of the batch job
853 identifier to standard output. The -z option is an existing NQS prac‐
854 tice that has been standardized.
855 Historically, the qsub utility has served the batch job-submission
857 function in the NQS system, the existing practice on which it is based.
858 Some changes and additions have been made to the qsub utility in this
859 volume of IEEE Std 1003.1-2001, vis-a-vis NQS, as a result of the grow‐
860 ing pool of experience with distributed batch systems.
861 The set of features of the qsub utility as defined in this volume of
863 IEEE Std 1003.1-2001 appears to incorporate all the common existing
864 practice on potentially conforming platforms.
865
867 None.
868
870 Batch Environment Services , qrerun , qstat , touch
871
873 Portions of this text are reprinted and reproduced in electronic form
874 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
875 -- Portable Operating System Interface (POSIX), The Open Group Base
876 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
877 Electrical and Electronics Engineers, Inc and The Open Group. In the
878 event of any discrepancy between this version and the original IEEE and
879 The Open Group Standard, the original IEEE and The Open Group Standard
880 is the referee document. The original Standard can be obtained online
881 at http://www.opengroup.org/unix/online.html .
882IEEE/The Open Group 2003 QSUB(P)