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
13 qsub — submit a script
14
16 qsub [−a date_time] [−A account_string] [−c interval]
17 [−C directive_prefix] [−e path_name] [−h] [−j join_list]
18 [−k keep_list] [−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. A
25 script is submitted by a request to a batch server. The qsub utility is
26 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 vari‐
37 able 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
45 add the following variables with the indicated values to the variable
46 list:
47 PBS_O_WORKDIR The absolute path of the current working directory of the
49 qsub utility process.
50 PBS_O_HOST The name of the host on which the qsub utility is run‐
52 ning.
53
55 The qsub utility shall conform to the Base Definitions volume of
56 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
57 The following options shall be supported by the implementation:
59 −a date_time
61 Define the time at which a batch job becomes eligible for
62 execution.
63 The qsub utility shall accept an option-argument that con‐
65 forms to the syntax of the time operand of the touch utility.
66 Table 4-19: Environment Variable Values (Utilities)
68 ┌──────────────┬───────────────────────────┐
70 │Variable Name │ Value at qsub Time │
71 ├──────────────┼───────────────────────────┤
72 │PBS_O_HOME │ HOME │
73 │PBS_O_HOST │ Client host name │
74 │PBS_O_LANG │ LANG │
75 │PBS_O_LOGNAME │ LOGNAME │
76 │PBS_O_PATH │ PATH │
77 │PBS_O_MAIL │ MAIL │
78 │PBS_O_SHELL │ SHELL │
79 │PBS_O_TZ │ TZ │
80 │PBS_O_WORKDIR │ Current working directory │
81 └──────────────┴───────────────────────────┘
82 Note: The server that initiates execution of the batch
83 job will add other variables to the batch job's
84 environment; see Section 3.2.2.1, Batch Job Execu‐
85 tion.
86 The qsub utility shall set the Execution_Time attribute of
88 the batch job to the number of seconds since the Epoch that
89 is equivalent to the local time expressed by the value of the
90 date_time option-argument. The Epoch is defined in the Base
91 Definitions volume of POSIX.1‐2008, Section 3.150, Epoch.
92 If the −a option is not presented to the qsub utility, the
94 utility shall set the Execution_Time attribute of the batch
95 job to a time (number of seconds since the Epoch) that is
96 earlier than the time at which the utility exits.
97 −A account_string
99 Define the account to which the resource consumption of the
100 batch job should be charged.
101 The syntax of the account_string option-argument is unspeci‐
103 fied.
104 The qsub utility shall set the Account_Name attribute of the
106 batch job to the value of the account_string option-argument.
107 If the −A option is not presented to the qsub utility, the
109 utility shall omit the Account_Name attribute from the
110 attributes of the batch job.
111 −c interval
113 Define whether the batch job should be checkpointed, and if
114 so, how often.
115 The qsub utility shall accept a value for the interval
117 option-argument that is one of the following:
118 n No checkpointing shall be performed on the batch
120 job (NO_CHECKPOINT).
121 s Checkpointing shall be performed only when the
123 batch server is shut down (CHECKPOINT_AT_SHUTDOWN).
124 c Automatic periodic checkpointing shall be performed
126 at the Minimum_Cpu_Interval attribute of the batch
127 queue, in units of CPU minutes (CHECK‐
128 POINT_AT_MIN_CPU_INTERVAL).
129 c=minutes Automatic periodic checkpointing shall be performed
131 every minutes of CPU time, or every Mini‐
132 mum_Cpu_Interval minutes, whichever is greater. The
133 minutes argument shall conform to the syntax for
134 unsigned integers and shall be greater than zero.
135 The qsub utility shall set the Checkpoint attribute of the
137 batch job to the value of the interval option-argument.
138 If the −c option is not presented to the qsub utility, the
140 utility shall set the Checkpoint attribute of the batch job
141 to the single character 'u' (CHECKPOINT_UNSPECIFIED).
142 −C directive_prefix
144 Define the prefix that declares a directive to the qsub util‐
145 ity within the script.
146 The directive_prefix is not a batch job attribute; it affects
148 the behavior of the qsub utility.
149 If the −C option is presented to the qsub utility, and the
151 value of the directive_prefix option-argument is the null
152 string, the utility shall not scan the script file for direc‐
153 tives. If the −C option is not presented to the qsub utility,
154 then the value of the PBS_DPREFIX environment variable is
155 used. If the environment variable is not defined, then #PBS
156 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
160 the batch job.
161 The qsub utility shall accept a path_name option-argument
163 which can be preceded by a host name element of the form
164 hostname:.
165 If the path_name option-argument constitutes an absolute
167 pathname, the qsub utility shall set the Error_Path attribute
168 of the batch job to the value of the path_name option-argu‐
169 ment.
170 If the path_name option-argument constitutes a relative path‐
172 name and no host name element is specified, the qsub utility
173 shall set the Error_Path attribute of the batch job to the
174 value of the absolute pathname derived by expanding the
175 path_name option-argument relative to the current directory
176 of the process executing qsub.
177 If the path_name option-argument constitutes a relative path‐
179 name and a host name element is specified, the qsub utility
180 shall set the Error_Path attribute of the batch job to the
181 value of the path_name option-argument without expansion. The
182 host name element shall be included.
183 If the path_name option-argument does not include a host name
185 element, the qsub utility shall prefix the pathname with
186 hostname:, where hostname is the name of the host upon which
187 the qsub utility is being executed.
188 If the −e option is not presented to the qsub utility, the
190 utility shall set the Error_Path attribute of the batch job
191 to the host name and path of the current directory of the
192 submitting process and the default filename.
193 The default filename for standard error has the following
195 format:
196 job_name.esequence_number
198 −h Specify that a USER hold is applied to the batch job.
200 The qsub utility shall set the value of the Hold_Types
202 attribute of the batch job to the value USER.
203 If the −h option is not presented to the qsub utility, the
205 utility shall set the Hold_Types attribute of the batch job
206 to the value NO_HOLD.
207 −j join_list
209 Define which streams of the batch job are to be merged. The
210 qsub −j option shall accept a value for the join_list option-
211 argument that is a string of alphanumeric characters in the
212 portable character set (see the Base Definitions volume of
213 POSIX.1‐2008, Section 6.1, Portable Character Set).
214 The qsub utility shall accept a join_list option-argument
216 that consists of one or more of the characters 'e' and 'o',
217 or the single character 'n'.
218 All of the other batch job output streams specified will be
220 merged into the output stream represented by the character
221 listed first in the join_list option-argument.
222 For each unique character in the join_list option-argument,
224 the qsub utility shall add a value to the Join_Path attribute
225 of the batch job as follows, each representing a different
226 batch job stream to join:
227 e The standard error of the batch job (JOIN_STD_ERROR).
229 o The standard output of the batch job (JOIN_STD_OUTPUT).
231 An existing Join_Path attribute can be cleared by the follow‐
233 ing join type:
234 n NO_JOIN
236 If 'n' is specified, then no files are joined. The qsub util‐
238 ity shall consider it an error if any join type other than
239 'n' is combined with join type 'n'.
240 Strictly conforming applications shall not repeat any of the
242 characters 'e', 'o', or 'n' within the join_list option-argu‐
243 ment. The qsub utility shall permit the repetition of charac‐
244 ters, but shall not assign additional meaning to the repeated
245 characters.
246 An implementation may define other join types. The confor‐
248 mance document for an implementation shall describe any addi‐
249 tional batch job streams, how they are specified, their
250 internal behavior, and how they affect the behavior of the
251 utility.
252 If the −j option is not presented to the qsub utility, the
254 utility shall set the value of the Join_Path attribute of the
255 batch job to NO_JOIN.
256 −k keep_list
258 Define which output of the batch job to retain on the execu‐
259 tion host.
260 The qsub −k option shall accept a value for the keep_list
262 option-argument that is a string of alphanumeric characters
263 in the portable character set (see the Base Definitions vol‐
264 ume of POSIX.1‐2008, Section 6.1, Portable Character Set).
265 The qsub utility shall accept a keep_list option-argument
267 that consists of one or more of the characters 'e' and 'o',
268 or the single character 'n'.
269 For each unique character in the keep_list option-argument,
271 the qsub utility shall add a value to the Keep_Files
272 attribute of the batch job as follows, each representing a
273 different batch job stream to keep:
274 e The standard error of the batch job (KEEP_STD_ERROR).
276 o The standard output of the batch job (KEEP_STD_OUTPUT).
278 If both 'e' and 'o' are specified, then both files are
280 retained. An existing Keep_Files attribute can be cleared by
281 the following keep type:
282 n NO_KEEP
284 If 'n' is specified, then no files are retained. The qsub
286 utility shall consider it an error if any keep type other
287 than 'n' is combined with keep type 'n'.
288 Strictly conforming applications shall not repeat any of the
290 characters 'e', 'o', or 'n' within the keep_list option-argu‐
291 ment. The qsub utility shall permit the repetition of charac‐
292 ters, but shall not assign additional meaning to the repeated
293 characters.
294 An implementation may define other keep types. The confor‐
296 mance document for an implementation shall describe any addi‐
297 tional keep types, how they are specified, their internal
298 behavior, and how they affect the behavior of the utility. If
299 the −k option is not presented to the qsub utility, the util‐
300 ity shall set the Keep_Files attribute of the batch job to
301 the value NO_KEEP.
302 −m mail_options
304 Define the points in the execution of the batch job at which
305 the batch server that manages the batch job shall send mail
306 about a change in the state of the batch job.
307 The qsub −m option shall accept a value for the mail_options
309 option-argument that is a string of alphanumeric characters
310 in the portable character set (see the Base Definitions vol‐
311 ume of POSIX.1‐2008, Section 6.1, Portable Character Set).
312 The qsub utility shall accept a value for the mail_options
314 option-argument that is a string of one or more of the char‐
315 acters 'e', 'b', and 'a', or the single character 'n'.
316 For each unique character in the mail_options option-argu‐
318 ment, the qsub utility shall add a value to the Mail_Users
319 attribute of the batch job as follows, each representing a
320 different time during the life of a batch job at which to
321 send mail:
322 e MAIL_AT_EXIT
324 b MAIL_AT_BEGINNING
326 a MAIL_AT_ABORT
328 If any of these characters are duplicated in the mail_options
330 option-argument, the duplicates shall be ignored.
331 An existing Mail_Points attribute can be cleared by the fol‐
333 lowing mail type:
334 n NO_MAIL
336 If 'n' is specified, then mail is not sent. The qsub utility
338 shall consider it an error if any mail type other than 'n' is
339 combined with mail type 'n'.
340 Strictly conforming applications shall not repeat any of the
342 characters 'e', 'b', 'a', or 'n' within the mail_options
343 option-argument.
344 The qsub utility shall permit the repetition of characters,
346 but shall not assign additional meaning to the repeated char‐
347 acters. An implementation may define other mail types. The
348 conformance document for an implementation shall describe any
349 additional mail types, how they are specified, their internal
350 behavior, and how they affect the behavior of the utility.
351 If the −m option is not presented to the qsub utility, the
353 utility shall set the Mail_Points attribute to the value
354 MAIL_AT_ABORT.
355 −M mail_list
357 Define the list of users to which a batch server that exe‐
358 cutes the batch job shall send mail, if the server sends mail
359 about the batch job.
360 The syntax of the mail_list option-argument is unspecified.
362 If the implementation of the qsub utility uses a name service
364 to locate users, the utility should accept the syntax used by
365 the name service.
366 If the implementation of the qsub utility does not use a name
368 service to locate users, the implementation should accept the
369 following syntax for user names:
370 mail_address[,,mail_address,, ...]
372 The interpretation of mail_address is implementation-defined.
374 The qsub utility shall set the Mail_Users attribute of the
376 batch job to the value of the mail_list option-argument.
377 If the −M option is not presented to the qsub utility, the
379 utility shall place only the user name and host name for the
380 current process in the Mail_Users attribute of the batch job.
381 −N name Define the name of the batch job.
383 The qsub −N option shall accept a value for the name option-
385 argument that is a string of up to 15 alphanumeric characters
386 in the portable character set (see the Base Definitions vol‐
387 ume of POSIX.1‐2008, Section 6.1, Portable Character Set)
388 where the first character is alphabetic.
389 The qsub utility shall set the value of the Job_Name
391 attribute of the batch job to the value of the name option-
392 argument.
393 If the −N option is not presented to the qsub utility, the
395 utility shall set the Job_Name attribute of the batch job to
396 the name of the script argument from which the directory
397 specification if any, has been removed.
398 If the −N option is not presented to the qsub utility, and
400 the script is read from standard input, the utility shall set
401 the Job_Name attribute of the batch job to the value STDIN.
402 −o path_name
404 Define the path for the standard output of the batch job.
405 The qsub utility shall accept a path_name option-argument
407 that conforms to the syntax of the path_name element defined
408 in the System Interfaces volume of POSIX.1‐2008, which can be
409 preceded by a host name element of the form hostname:.
410 If the path_name option-argument constitutes an absolute
412 pathname, the qsub utility shall set the Output_Path
413 attribute of the batch job to the value of the path_name
414 option-argument without expansion.
415 If the path_name option-argument constitutes a relative path‐
417 name and no host name element is specified, the qsub utility
418 shall set the Output_Path attribute of the batch job to the
419 pathname derived by expanding the value of the path_name
420 option-argument relative to the current directory of the
421 process executing the qsub.
422 If the path_name option-argument constitutes a relative path‐
424 name and a host name element is specified, the qsub utility
425 shall set the Output_Path attribute of the batch job to the
426 value of the path_name option-argument without expansion.
427 If the path_name option-argument does not specify a host name
429 element, the qsub utility shall prefix the pathname with
430 hostname:, where hostname is the name of the host upon which
431 the qsub utility is executing.
432 If the −o option is not presented to the qsub utility, the
434 utility shall set the Output_Path attribute of the batch job
435 to the host name and path of the current directory of the
436 submitting process and the default filename.
437 The default filename for standard output has the following
439 format:
440 job_name.osequence_number
442 −p priority
444 Define the priority the batch job should have relative to
445 other batch jobs owned by the batch server.
446 The qsub utility shall set the Priority attribute of the
448 batch job to the value of the priority option-argument.
449 If the −p option is not presented to the qsub utility, the
451 value of the Priority attribute is implementation-defined.
452 The qsub utility shall accept a value for the priority
454 option-argument that conforms to the syntax for signed deci‐
455 mal integers, and which is not less than −1024 and not
456 greater than 1023.
457 −q destination
459 Define the destination of the batch job.
460 The destination is not a batch job attribute; it determines
462 the batch server, and possibly the batch queue, to which the
463 qsub utility batch queues the batch job.
464 The qsub utility shall submit the script to the batch server
466 named by the destination option-argument or the server that
467 owns the batch queue named in the destination option-argu‐
468 ment.
469 The qsub utility shall accept an option-argument for the −q
471 option that conforms to the syntax for a destination (see
472 Section 3.3.2, Destination).
473 If the −q option is not presented to the qsub utility, the
475 qsub utility shall submit the batch job to the default desti‐
476 nation. The mechanism for determining the default destination
477 is implementation-defined.
478 −r y|n Define whether the batch job is rerunnable.
480 If the value of the option-argument is y, the qsub utility
482 shall set the Rerunable attribute of the batch job to TRUE.
483 If the value of the option-argument is n, the qsub utility
485 shall set the Rerunable attribute of the batch job to FALSE.
486 If the −r option is not presented to the qsub utility, the
488 utility shall set the Rerunable attribute of the batch job to
489 TRUE.
490 −S path_name_list
492 Define the pathname to the shell under which the batch job is
493 to execute.
494 The qsub utility shall accept a path_name_list option-argu‐
496 ment that conforms to the following syntax:
497 pathname[@host][,,pathname[@host],, ...]
499 The qsub utility shall allow only one pathname for a given
501 host name. The qsub utility shall allow only one pathname
502 that is missing a corresponding host name.
503 The qsub utility shall add a value to the Shell_Path_List
505 attribute of the batch job for each entry in the
506 path_name_list option-argument.
507 If the −S option is not presented to the qsub utility, the
509 utility shall set the Shell_Path_List attribute of the batch
510 job to the null string.
511 The conformance document for an implementation shall describe
513 the mechanism used to set the default shell and determine the
514 current value of the default shell. An implementation shall
515 provide a means for the installation to set the default shell
516 to the login shell of the user under which the batch job is
517 to execute. See Section 3.3.3, Multiple Keyword-Value Pairs
518 for a means of removing keyword=value (and value@keyword)
519 pairs and other general rules for list-oriented batch job
520 attributes.
521 −u user_list
523 Define the user name under which the batch job is to execute.
524 The qsub utility shall accept a user_list option-argument
526 that conforms to the following syntax:
527 username[@host][,,username[@host],, ...]
529 The qsub utility shall accept only one user name that is
531 missing a corresponding host name. The qsub utility shall
532 accept only one user name per named host.
533 The qsub utility shall add a value to the User_List attribute
535 of the batch job for each entry in the user_list option-argu‐
536 ment.
537 If the −u option is not presented to the qsub utility, the
539 utility shall set the User_List attribute of the batch job to
540 the user name from which the utility is executing. See Sec‐
541 tion 3.3.3, Multiple Keyword-Value Pairs for a means of
542 removing keyword=value (and value@keyword) pairs and other
543 general rules for list-oriented batch job attributes.
544 −v variable_list
546 Add to the list of variables that are exported to the session
547 leader of the batch job.
548 A variable_list is a set of strings of either the form <vari‐
550 able> or <variable=value>, delimited by <comma> characters.
551 If the −v option is presented to the qsub utility, the util‐
553 ity shall also add, to the environment Variable_List
554 attribute of the batch job, every variable named in the envi‐
555 ronment variable_list option-argument and, optionally, values
556 of specified variables.
557 If a value is not provided on the command line, the qsub
559 utility shall set the value of each variable in the environ‐
560 ment Variable_List attribute of the batch job to the value of
561 the corresponding environment variable for the process in
562 which the utility is executing; see Table 4-19, Environment
563 Variable Values (Utilities).
564 A conforming application shall not repeat a variable in the
566 environment variable_list option-argument.
567 The qsub utility shall not repeat a variable in the environ‐
569 ment Variable_List attribute of the batch job. See Section
570 3.3.3, Multiple Keyword-Value Pairs for a means of removing
571 keyword=value (and value@keyword) pairs and other general
572 rules for list-oriented batch job attributes.
573 −V Specify that all of the environment variables of the process
575 are exported to the context of the batch job.
576 The qsub utility shall place every environment variable in
578 the process in which the utility is executing in the list and
579 shall set the value of each variable in the attribute to the
580 value of that variable in the process.
581 −z Specify that the utility does not write the batch job_identi‐
583 fier of the created batch job to standard output.
584 If the −z option is presented to the qsub utility, the util‐
586 ity shall not write the batch job_identifier of the created
587 batch job to standard output.
588 If the −z option is not presented to the qsub utility, the
590 utility shall write the identifier of the created batch job
591 to standard output.
592
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 vari‐
618 ables that are unset or null. (See the Base Definitions vol‐
619 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
620 ables 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
624 all the other internationalization variables.
625 LC_CTYPE Determine the locale for the interpretation of sequences of
627 bytes of text data as characters (for example, single-byte as
628 opposed to multi-byte characters in arguments).
629 LC_MESSAGES
631 Determine the locale that should be used to affect the format
632 and contents of diagnostic messages written to standard
633 error.
634 LOGNAME Determine the login name of the user.
636 PBS_DPREFIX
638 Determine the default prefix for directives within the
639 script.
640 SHELL Determine the pathname of the preferred command language
642 interpreter of the user.
643 TZ Determine the timezone used to interpret the date-time
645 option-argument. If TZ is unset or null, an unspecified
646 default timezone shall be used.
647
649 Once created, a batch job exists until it exits, aborts, or is deleted.
650 After a batch job is created by the qsub utility, batch servers might
652 route, execute, modify, or delete the batch job.
653
655 The qsub utility writes the batch job_identifier assigned to the batch
656 job to standard output, unless the −z option is specified.
657
659 The standard error shall be used only for diagnostic messages.
660
662 None.
663
665 Script Preservation
666 The qsub utility shall make the script available to the server execut‐
667 ing the batch job in such a way that the server executes the script as
668 it exists at the time of submission.
669 The qsub utility can send a copy of the script to the server with the
671 Queue Job Request or store a temporary copy of the script in a location
672 specified to the server.
673 Option Specification
675 A script can contain directives to the qsub utility.
676 The qsub utility shall scan the lines of the script for directives,
678 skipping blank lines, until the first line that begins with a string
679 other than the directive string; if directives occur on subsequent
680 lines, the utility shall ignore those directives.
681 Lines are separated by a <newline>. If the first line of the script
683 begins with "#!" or a <colon> (':'), then it is skipped. The qsub util‐
684 ity shall process a line in the script as a directive if and only if
685 the string of characters from the first non-white-space character on
686 the line until the first <space> or <tab> on the line match the direc‐
687 tive prefix. If a line in the script contains a directive and the final
688 characters of the line are <backslash> and <newline>, then the next
689 line shall be interpreted as a continuation of that directive.
690 The qsub utility shall process the options and option-arguments con‐
692 tained on the directive prefix line using the same syntax as if the
693 options were input on the qsub utility.
694 The qsub utility shall continue to process a directive prefix line
696 until after a <newline> is encountered. An implementation may ignore
697 lines which, according to the syntax of the shell that will interpret
698 the script, are comments. An implementation shall describe in the con‐
699 formance document the format of any shell comments that it will recog‐
700 nize.
701 If an option is present in both a directive and the arguments to the
703 qsub utility, the utility shall ignore the option and the corresponding
704 option-argument, if any, in the directive.
705 If an option that is present in the directive is not present in the
707 arguments to the qsub utility, the utility shall process the option and
708 the option-argument, if any.
709 In order of preference, the qsub utility shall select the directive
711 prefix from one of the following sources:
712 * If the −C option is presented to the utility, the value of the
714 directive_prefix option-argument
715 * If the environment variable PBS_DPREFIX is defined, the value of
717 that variable
718 * The four-character string "#PBS" encoded in the portable character
720 set
721 If the −C option is present in the script file it shall be ignored.
723
725 The following exit values shall be returned:
726 0 Successful completion.
728 >0 An error occurred.
730
732 Default.
733 The following sections are informative.
735
737 None.
738
740 None.
741
743 The qsub utility allows users to create a batch job that will process
744 the script specified as the operand of the utility.
745 The options of the qsub utility allow users to control many aspects of
747 the queuing and execution of a batch job.
748 The −a option allows users to designate the time after which the batch
750 job will become eligible to run. By specifying an execution time, users
751 can take advantage of resources at off-peak hours, synchronize jobs
752 with chronologically predictable events, and perhaps take advantage of
753 off-peak pricing of computing time. For these reasons and others, a
754 timing option is existing practice on the part of almost every batch
755 system, including NQS.
756 The −A option allows users to specify the account that will be charged
758 for the batch job. Support for account is not mandatory for conforming
759 batch servers.
760 The −C option allows users to prescribe the prefix for directives
762 within the script file. The default prefix "#PBS" may be inappropriate
763 if the script will be interpreted with an alternate shell, as specified
764 by the −S option.
765 The −c option allows users to establish the checkpointing interval for
767 their jobs. A checkpointing system, which is not defined by this volume
768 of POSIX.1‐2008, allows recovery of a batch job at the most recent
769 checkpoint in the event of a crash. Checkpointing is typically used for
770 jobs that consume expensive computing time or must meet a critical
771 schedule. Users should be allowed to make the tradeoff between the
772 overhead of checkpointing and the risk to the timely completion of the
773 batch job; therefore, this volume of POSIX.1‐2008 provides the check‐
774 pointing interval option. Support for checkpointing is optional for
775 batch servers.
776 The −e option allows users to redirect the standard error streams of
778 their jobs to a non-default path. For example, if the submitted script
779 generally produces a great deal of useless error output, a user might
780 redirect the standard error output to the null device. Or, if the file
781 system holding the default location (the home directory of the user)
782 has too little free space, the user might redirect the standard error
783 stream to a file in another file system.
784 The −h option allows users to create a batch job that is held until
786 explicitly released. The ability to create a held job is useful when
787 some external event must complete before the batch job can execute. For
788 example, the user might submit a held job and release it when the sys‐
789 tem load has dropped.
790 The −j option allows users to merge the standard error of a batch job
792 into its standard output stream, which has the advantage of showing the
793 sequential relationship between output and error messages.
794 The −m option allows users to designate those points in the execution
796 of a batch job at which mail will be sent to the submitting user, or to
797 the account(s) indicated by the −M option. By requesting mail notifica‐
798 tion at points of interest in the life of a job, the submitting user,
799 or other designated users, can track the progress of a batch job.
800 The −N option allows users to associate a name with the batch job. The
802 job name in no way affects the processing of the batch job, but rather
803 serves as a mnemonic handle for users. For example, the batch job name
804 can help the user distinguish between multiple jobs listed by the qstat
805 utility.
806 The −o option allows users to redirect the standard output stream. A
808 user might, for example, wish to redirect to the null device the stan‐
809 dard output stream of a job that produces copious yet superfluous out‐
810 put.
811 The −P option allows users to designate the relative priority of a
813 batch job for selection from a queue.
814 The −q option allows users to specify an initial queue for the batch
816 job. If the user specifies a routing queue, the batch server routes the
817 batch job to another queue for execution or further routing. If the
818 user specifies a non-routing queue, the batch server of the queue even‐
819 tually executes the batch job.
820 The −r option allows users to control whether the submitted job will be
822 rerun if the controlling batch node fails during execution of the batch
823 job. The −r option likewise allows users to indicate whether or not
824 the batch job is eligible to be rerun by the qrerun utility. Some jobs
825 cannot be correctly rerun because of changes they make in the state of
826 databases or other aspects of their environment. This volume of
827 POSIX.1‐2008 specifies that the default, if the −r option is not pre‐
828 sented to the utility, will be that the batch job cannot be rerun,
829 since the result of rerunning a non-rerunnable job might be catastroph‐
830 ic.
831 The −S option allows users to specify the program (usually a shell)
833 that will be invoked to process the script of the batch job. This
834 option has been modified to allow a list of shell names and locations
835 associated with different hosts.
836 The −u option is useful when the submitting user is authorized to use
838 more than one account on a given host, in which case the −u option
839 allows the user to select from among those accounts. The option-argu‐
840 ment is a list of user-host pairs, so that the submitting user can pro‐
841 vide different user identifiers for different nodes in the event the
842 batch job is routed. The −u option provides a lot of flexibility to
843 accommodate sites with complex account structures. Users that have the
844 same user identifier on all the hosts they are authorized to use will
845 not need to use the −u option.
846 The −V option allows users to export all their current environment
848 variables, as of the time the batch job is submitted, to the context of
849 the processes of the batch job.
850 The −v option allows users to export specific environment variables
852 from their current process to the processes of the batch job.
853 The −z option allows users to suppress the writing of the batch job
855 identifier to standard output. The −z option is an existing NQS prac‐
856 tice that has been standardized.
857 Historically, the qsub utility has served the batch job-submission
859 function in the NQS system, the existing practice on which it is based.
860 Some changes and additions have been made to the qsub utility in this
861 volume of POSIX.1‐2008, vis-a-vis NQS, as a result of the growing pool
862 of experience with distributed batch systems.
863 The set of features of the qsub utility as defined in this volume of
865 POSIX.1‐2008 appears to incorporate all the common existing practice on
866 potentially conforming platforms.
867
869 The qsub utility may be removed in a future version.
870
872 Chapter 3, Batch Environment Services, qrerun, qstat, touch
873 The Base Definitions volume of POSIX.1‐2008, Section 3.150, Epoch, Sec‐
875 tion 6.1, Portable Character Set, Chapter 8, Environment Variables,
876 Section 12.2, Utility Syntax Guidelines
877
879 Portions of this text are reprinted and reproduced in electronic form
880 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
881 -- Portable Operating System Interface (POSIX), The Open Group Base
882 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
883 cal and Electronics Engineers, Inc and The Open Group. (This is
884 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
885 event of any discrepancy between this version and the original IEEE and
886 The Open Group Standard, the original IEEE and The Open Group Standard
887 is the referee document. The original Standard can be obtained online
888 at http://www.unix.org/online.html .
889 Any typographical or formatting errors that appear in this page are
891 most likely to have been introduced during the conversion of the source
892 files to man page format. To report such errors, see https://www.ker‐
893 nel.org/doc/man-pages/reporting_bugs.html .
894IEEE/The Open Group 2013 QSUB(1P)