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]
17 [-k keep_list] [-m mail_options] [-M mail_list] [-N name]
18 [-o path_name] [-p priority] [-q destination] [-r y|n]
19 [-S path_name_list] [-u user_list] [-v variable_list] [-V]
20 [-z] [script]
21
23 To submit a script is to create a batch job that executes the script. A
24 script is submitted by a request to a batch server. The qsub utility is
25 a user-accessible batch client that submits a script.
26 Upon successful completion, the qsub utility shall have created a batch
28 job that will execute the submitted script.
29 The qsub utility shall submit a script by sending a Queue Job Request
31 to a batch server.
32 The qsub utility shall place the value of the following environment
34 variables in the Variable_List attribute of the batch job: HOME, LANG,
35 LOGNAME, PATH, MAIL, SHELL, and TZ. The name of the environment vari‐
36 able shall be the current name prefixed with the string PBS_O_.
37 Note: If the current value of the HOME variable in the environment
39 space of the qsub utility is /aa/bb/cc, then qsub shall place
40 PBS_O_HOME=/aa/bb/cc in the Variable_List attribute of the
41 batch job.
42 In addition to the variables described above, the qsub utility shall
44 add the following variables with the indicated values to the variable
45 list:
46 PBS_O_WORKDIR The absolute path of the current working directory of the
48 qsub utility process.
49 PBS_O_HOST The name of the host on which the qsub utility is run‐
51 ning.
52
54 The qsub utility shall conform to the Base Definitions volume of
55 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
56 The following options shall be supported by the implementation:
58 -a date_time
60 Define the time at which a batch job becomes eligible for
61 execution.
62 The qsub utility shall accept an option-argument that con‐
64 forms to the syntax of the time operand of the touch utility.
65 Table 4-19: Environment Variable Values (Utilities)
67 ┌──────────────┬───────────────────────────┐
69 │Variable Name │ Value at qsub Time │
70 ├──────────────┼───────────────────────────┤
71 │PBS_O_HOME │ HOME │
72 │PBS_O_HOST │ Client host name │
73 │PBS_O_LANG │ LANG │
74 │PBS_O_LOGNAME │ LOGNAME │
75 │PBS_O_PATH │ PATH │
76 │PBS_O_MAIL │ MAIL │
77 │PBS_O_SHELL │ SHELL │
78 │PBS_O_TZ │ TZ │
79 │PBS_O_WORKDIR │ Current working directory │
80 └──────────────┴───────────────────────────┘
81 Note: The server that initiates execution of the batch
82 job will add other variables to the batch job's
83 environment; see Section 3.2.2.1, Batch Job Execu‐
84 tion.
85 The qsub utility shall set the Execution_Time attribute of
87 the batch job to the number of seconds since the Epoch that
88 is equivalent to the local time expressed by the value of the
89 date_time option-argument. The Epoch is defined in the Base
90 Definitions volume of POSIX.1‐2017, Section 3.150, Epoch.
91 If the -a option is not presented to the qsub utility, the
93 utility shall set the Execution_Time attribute of the batch
94 job to a time (number of seconds since the Epoch) that is
95 earlier than the time at which the utility exits.
96 -A account_string
98 Define the account to which the resource consumption of the
99 batch job should be charged.
100 The syntax of the account_string option-argument is unspeci‐
102 fied.
103 The qsub utility shall set the Account_Name attribute of the
105 batch job to the value of the account_string option-argument.
106 If the -A option is not presented to the qsub utility, the
108 utility shall omit the Account_Name attribute from the
109 attributes of the batch job.
110 -c interval
112 Define whether the batch job should be checkpointed, and if
113 so, how often.
114 The qsub utility shall accept a value for the interval
116 option-argument that is one of the following:
117 n No checkpointing shall be performed on the batch
119 job (NO_CHECKPOINT).
120 s Checkpointing shall be performed only when the
122 batch server is shut down (CHECKPOINT_AT_SHUTDOWN).
123 c Automatic periodic checkpointing shall be performed
125 at the Minimum_Cpu_Interval attribute of the batch
126 queue, in units of CPU minutes (CHECK‐
127 POINT_AT_MIN_CPU_INTERVAL).
128 c=minutes Automatic periodic checkpointing shall be performed
130 every minutes of CPU time, or every Mini‐
131 mum_Cpu_Interval minutes, whichever is greater. The
132 minutes argument shall conform to the syntax for
133 unsigned integers and shall be greater than zero.
134 The qsub utility shall set the Checkpoint attribute of the
136 batch job to the value of the interval option-argument.
137 If the -c option is not presented to the qsub utility, the
139 utility shall set the Checkpoint attribute of the batch job
140 to the single character 'u' (CHECKPOINT_UNSPECIFIED).
141 -C directive_prefix
143 Define the prefix that declares a directive to the qsub util‐
144 ity within the script.
145 The directive_prefix is not a batch job attribute; it affects
147 the behavior of the qsub utility.
148 If the -C option is presented to the qsub utility, and the
150 value of the directive_prefix option-argument is the null
151 string, the utility shall not scan the script file for direc‐
152 tives. If the -C option is not presented to the qsub utility,
153 then the value of the PBS_DPREFIX environment variable is
154 used. If the environment variable is not defined, then #PBS
155 encoded in the portable character set is the default.
156 -e path_name
158 Define the path to be used for the standard error stream of
159 the batch job.
160 The qsub utility shall accept a path_name option-argument
162 which can be preceded by a host name element of the form
163 hostname:.
164 If the path_name option-argument constitutes an absolute
166 pathname, the qsub utility shall set the Error_Path attribute
167 of the batch job to the value of the path_name option-argu‐
168 ment.
169 If the path_name option-argument constitutes a relative path‐
171 name and no host name element is specified, the qsub utility
172 shall set the Error_Path attribute of the batch job to the
173 value of the absolute pathname derived by expanding the
174 path_name option-argument relative to the current directory
175 of the process executing qsub.
176 If the path_name option-argument constitutes a relative path‐
178 name and a host name element is specified, the qsub utility
179 shall set the Error_Path attribute of the batch job to the
180 value of the path_name option-argument without expansion. The
181 host name element shall be included.
182 If the path_name option-argument does not include a host name
184 element, the qsub utility shall prefix the pathname with
185 hostname:, where hostname is the name of the host upon which
186 the qsub utility is being executed.
187 If the -e option is not presented to the qsub utility, the
189 utility shall set the Error_Path attribute of the batch job
190 to the host name and path of the current directory of the
191 submitting process and the default filename.
192 The default filename for standard error has the following
194 format:
195 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‐2017, 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‐2017, 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‐2017, 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,, ...]
373 The interpretation of mail_address is implementation-defined.
375 The qsub utility shall set the Mail_Users attribute of the
377 batch job to the value of the mail_list option-argument.
378 If the -M option is not presented to the qsub utility, the
380 utility shall place only the user name and host name for the
381 current process in the Mail_Users attribute of the batch job.
382 -N name Define the name of the batch job.
384 The qsub -N option shall accept a value for the name option-
386 argument that is a string of up to 15 alphanumeric characters
387 in the portable character set (see the Base Definitions vol‐
388 ume of POSIX.1‐2017, Section 6.1, Portable Character Set)
389 where the first character is alphabetic.
390 The qsub utility shall set the value of the Job_Name
392 attribute of the batch job to the value of the name option-
393 argument.
394 If the -N option is not presented to the qsub utility, the
396 utility shall set the Job_Name attribute of the batch job to
397 the name of the script argument from which the directory
398 specification if any, has been removed.
399 If the -N option is not presented to the qsub utility, and
401 the script is read from standard input, the utility shall set
402 the Job_Name attribute of the batch job to the value STDIN.
403 -o path_name
405 Define the path for the standard output of the batch job.
406 The qsub utility shall accept a path_name option-argument
408 that conforms to the syntax of the path_name element defined
409 in the System Interfaces volume of POSIX.1‐2017, which can be
410 preceded by a host name element of the form hostname:.
411 If the path_name option-argument constitutes an absolute
413 pathname, the qsub utility shall set the Output_Path
414 attribute of the batch job to the value of the path_name
415 option-argument without expansion.
416 If the path_name option-argument constitutes a relative path‐
418 name and no host name element is specified, the qsub utility
419 shall set the Output_Path attribute of the batch job to the
420 pathname derived by expanding the value of the path_name
421 option-argument relative to the current directory of the
422 process executing the qsub.
423 If the path_name option-argument constitutes a relative path‐
425 name and a host name element is specified, the qsub utility
426 shall set the Output_Path attribute of the batch job to the
427 value of the path_name option-argument without expansion.
428 If the path_name option-argument does not specify a host name
430 element, the qsub utility shall prefix the pathname with
431 hostname:, where hostname is the name of the host upon which
432 the qsub utility is executing.
433 If the -o option is not presented to the qsub utility, the
435 utility shall set the Output_Path attribute of the batch job
436 to the host name and path of the current directory of the
437 submitting process and the default filename.
438 The default filename for standard output has the following
440 format:
441 job_name.osequence_number
444 -p priority
446 Define the priority the batch job should have relative to
447 other batch jobs owned by the batch server.
448 The qsub utility shall set the Priority attribute of the
450 batch job to the value of the priority option-argument.
451 If the -p option is not presented to the qsub utility, the
453 value of the Priority attribute is implementation-defined.
454 The qsub utility shall accept a value for the priority
456 option-argument that conforms to the syntax for signed deci‐
457 mal integers, and which is not less than -1024 and not
458 greater than 1023.
459 -q destination
461 Define the destination of the batch job.
462 The destination is not a batch job attribute; it determines
464 the batch server, and possibly the batch queue, to which the
465 qsub utility batch queues the batch job.
466 The qsub utility shall submit the script to the batch server
468 named by the destination option-argument or the server that
469 owns the batch queue named in the destination option-argu‐
470 ment.
471 The qsub utility shall accept an option-argument for the -q
473 option that conforms to the syntax for a destination (see
474 Section 3.3.2, Destination).
475 If the -q option is not presented to the qsub utility, the
477 qsub utility shall submit the batch job to the default desti‐
478 nation. The mechanism for determining the default destination
479 is implementation-defined.
480 -r y|n Define whether the batch job is rerunnable.
482 If the value of the option-argument is y, the qsub utility
484 shall set the Rerunable attribute of the batch job to TRUE.
485 If the value of the option-argument is n, the qsub utility
487 shall set the Rerunable attribute of the batch job to FALSE.
488 If the -r option is not presented to the qsub utility, the
490 utility shall set the Rerunable attribute of the batch job to
491 TRUE.
492 -S path_name_list
494 Define the pathname to the shell under which the batch job is
495 to execute.
496 The qsub utility shall accept a path_name_list option-argu‐
498 ment that conforms to the following syntax:
499 pathname[@host][,,pathname[@host],, ...]
502 The qsub utility shall allow only one pathname for a given
504 host name. The qsub utility shall allow only one pathname
505 that is missing a corresponding host name.
506 The qsub utility shall add a value to the Shell_Path_List
508 attribute of the batch job for each entry in the
509 path_name_list option-argument.
510 If the -S option is not presented to the qsub utility, the
512 utility shall set the Shell_Path_List attribute of the batch
513 job to the null string.
514 The conformance document for an implementation shall describe
516 the mechanism used to set the default shell and determine the
517 current value of the default shell. An implementation shall
518 provide a means for the installation to set the default shell
519 to the login shell of the user under which the batch job is
520 to execute. See Section 3.3.3, Multiple Keyword-Value Pairs
521 for a means of removing keyword=value (and value@keyword)
522 pairs and other general rules for list-oriented batch job
523 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
529 that conforms to the following syntax:
530 username[@host][,,username[@host],, ...]
533 The qsub utility shall accept only one user name that is
535 missing a corresponding host name. The qsub utility shall
536 accept only one user name per named host.
537 The qsub utility shall add a value to the User_List attribute
539 of the batch job for each entry in the user_list option-argu‐
540 ment.
541 If the -u option is not presented to the qsub utility, the
543 utility shall set the User_List attribute of the batch job to
544 the user name from which the utility is executing. See Sec‐
545 tion 3.3.3, Multiple Keyword-Value Pairs for a means of
546 removing keyword=value (and value@keyword) pairs and other
547 general rules for list-oriented batch job attributes.
548 -v variable_list
550 Add to the list of variables that are exported to the session
551 leader of the batch job.
552 A variable_list is a set of strings of either the form <vari‐
554 able> or <variable=value>, delimited by <comma> characters.
555 If the -v option is presented to the qsub utility, the util‐
557 ity shall also add, to the environment Variable_List
558 attribute of the batch job, every variable named in the envi‐
559 ronment variable_list option-argument and, optionally, values
560 of specified variables.
561 If a value is not provided on the command line, the qsub
563 utility shall set the value of each variable in the environ‐
564 ment Variable_List attribute of the batch job to the value of
565 the corresponding environment variable for the process in
566 which the utility is executing; see Table 4-19, Environment
567 Variable Values (Utilities).
568 A conforming application shall not repeat a variable in the
570 environment variable_list option-argument.
571 The qsub utility shall not repeat a variable in the environ‐
573 ment Variable_List attribute of the batch job. See Section
574 3.3.3, Multiple Keyword-Value Pairs for a means of removing
575 keyword=value (and value@keyword) pairs and other general
576 rules for list-oriented batch job attributes.
577 -V Specify that all of the environment variables of the process
579 are exported to the context of the batch job.
580 The qsub utility shall place every environment variable in
582 the process in which the utility is executing in the list and
583 shall set the value of each variable in the attribute to the
584 value of that variable in the process.
585 -z Specify that the utility does not write the batch job_identi‐
587 fier of the created batch job to standard output.
588 If the -z option is presented to the qsub utility, the util‐
590 ity shall not write the batch job_identifier of the created
591 batch job to standard output.
592 If the -z option is not presented to the qsub utility, the
594 utility shall write the identifier of the created batch job
595 to standard output.
596
598 The qsub utility shall accept a script operand that indicates the path
599 to the script of the batch job.
600 If the script operand is not presented to the qsub utility, or if the
602 operand is the single-character string '-', the utility shall read the
603 script from standard input.
604 If the script represents a partial path, the qsub utility shall expand
606 the path relative to the current directory of the process executing the
607 utility.
608
610 The qsub utility reads the script of the batch job from standard input
611 if the script operand is omitted or is the single character '-'.
612
614 In addition to binding the file indicated by the script operand to the
615 batch job, the qsub utility reads the script file and acts on direc‐
616 tives in the script.
617
619 The following environment variables shall affect the execution of qsub:
620 LANG Provide a default value for the internationalization vari‐
622 ables that are unset or null. (See the Base Definitions vol‐
623 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
624 ables the precedence of internationalization variables used
625 to determine the values of locale categories.)
626 LC_ALL If set to a non-empty string value, override the values of
628 all the other internationalization variables.
629 LC_CTYPE Determine the locale for the interpretation of sequences of
631 bytes of text data as characters (for example, single-byte as
632 opposed to multi-byte characters in arguments).
633 LC_MESSAGES
635 Determine the locale that should be used to affect the format
636 and contents of diagnostic messages written to standard
637 error.
638 LOGNAME Determine the login name of the user.
640 PBS_DPREFIX
642 Determine the default prefix for directives within the
643 script.
644 SHELL Determine the pathname of the preferred command language
646 interpreter of the user.
647 TZ Determine the timezone used to interpret the date-time
649 option-argument. If TZ is unset or null, an unspecified
650 default timezone shall be used.
651
653 Once created, a batch job exists until it exits, aborts, or is deleted.
654 After a batch job is created by the qsub utility, batch servers might
656 route, execute, modify, or delete the batch job.
657
659 The qsub utility writes the batch job_identifier assigned to the batch
660 job to standard output, unless the -z option is specified.
661
663 The standard error shall be used only for diagnostic messages.
664
666 None.
667
669 Script Preservation
670 The qsub utility shall make the script available to the server execut‐
671 ing the batch job in such a way that the server executes the script as
672 it exists at the time of submission.
673 The qsub utility can send a copy of the script to the server with the
675 Queue Job Request or store a temporary copy of the script in a location
676 specified to the server.
677 Option Specification
679 A script can contain directives to the qsub utility.
680 The qsub utility shall scan the lines of the script for directives,
682 skipping blank lines, until the first line that begins with a string
683 other than the directive string; if directives occur on subsequent
684 lines, the utility shall ignore those directives.
685 Lines are separated by a <newline>. If the first line of the script
687 begins with "#!" or a <colon> (':'), then it is skipped. The qsub util‐
688 ity shall process a line in the script as a directive if and only if
689 the string of characters from the first non-white-space character on
690 the line until the first <space> or <tab> on the line match the direc‐
691 tive prefix. If a line in the script contains a directive and the final
692 characters of the line are <backslash> and <newline>, then the next
693 line shall be interpreted as a continuation of that directive.
694 The qsub utility shall process the options and option-arguments con‐
696 tained on the directive prefix line using the same syntax as if the
697 options were input on the qsub utility.
698 The qsub utility shall continue to process a directive prefix line
700 until after a <newline> is encountered. An implementation may ignore
701 lines which, according to the syntax of the shell that will interpret
702 the script, are comments. An implementation shall describe in the con‐
703 formance document the format of any shell comments that it will recog‐
704 nize.
705 If an option is present in both a directive and the arguments to the
707 qsub utility, the utility shall ignore the option and the corresponding
708 option-argument, if any, in the directive.
709 If an option that is present in the directive is not present in the
711 arguments to the qsub utility, the utility shall process the option and
712 the option-argument, if any.
713 In order of preference, the qsub utility shall select the directive
715 prefix from one of the following sources:
716 * If the -C option is presented to the utility, the value of the
718 directive_prefix option-argument
719 * If the environment variable PBS_DPREFIX is defined, the value of
721 that variable
722 * The four-character string "#PBS" encoded in the portable character
724 set
725 If the -C option is present in the script file it shall be ignored.
727
729 The following exit values shall be returned:
730 0 Successful completion.
732 >0 An error occurred.
734
736 Default.
737 The following sections are informative.
739
741 None.
742
744 None.
745
747 The qsub utility allows users to create a batch job that will process
748 the script specified as the operand of the utility.
749 The options of the qsub utility allow users to control many aspects of
751 the queuing and execution of a batch job.
752 The -a option allows users to designate the time after which the batch
754 job will become eligible to run. By specifying an execution time, users
755 can take advantage of resources at off-peak hours, synchronize jobs
756 with chronologically predictable events, and perhaps take advantage of
757 off-peak pricing of computing time. For these reasons and others, a
758 timing option is existing practice on the part of almost every batch
759 system, including NQS.
760 The -A option allows users to specify the account that will be charged
762 for the batch job. Support for account is not mandatory for conforming
763 batch servers.
764 The -C option allows users to prescribe the prefix for directives
766 within the script file. The default prefix "#PBS" may be inappropriate
767 if the script will be interpreted with an alternate shell, as specified
768 by the -S option.
769 The -c option allows users to establish the checkpointing interval for
771 their jobs. A checkpointing system, which is not defined by this volume
772 of POSIX.1‐2017, allows recovery of a batch job at the most recent
773 checkpoint in the event of a crash. Checkpointing is typically used for
774 jobs that consume expensive computing time or must meet a critical
775 schedule. Users should be allowed to make the tradeoff between the
776 overhead of checkpointing and the risk to the timely completion of the
777 batch job; therefore, this volume of POSIX.1‐2017 provides the check‐
778 pointing interval option. Support for checkpointing is optional for
779 batch servers.
780 The -e option allows users to redirect the standard error streams of
782 their jobs to a non-default path. For example, if the submitted script
783 generally produces a great deal of useless error output, a user might
784 redirect the standard error output to the null device. Or, if the file
785 system holding the default location (the home directory of the user)
786 has too little free space, the user might redirect the standard error
787 stream to a file in another file system.
788 The -h option allows users to create a batch job that is held until
790 explicitly released. The ability to create a held job is useful when
791 some external event must complete before the batch job can execute. For
792 example, the user might submit a held job and release it when the sys‐
793 tem load has dropped.
794 The -j option allows users to merge the standard error of a batch job
796 into its standard output stream, which has the advantage of showing the
797 sequential relationship between output and error messages.
798 The -m option allows users to designate those points in the execution
800 of a batch job at which mail will be sent to the submitting user, or to
801 the account(s) indicated by the -M option. By requesting mail notifica‐
802 tion at points of interest in the life of a job, the submitting user,
803 or other designated users, can track the progress of a batch job.
804 The -N option allows users to associate a name with the batch job. The
806 job name in no way affects the processing of the batch job, but rather
807 serves as a mnemonic handle for users. For example, the batch job name
808 can help the user distinguish between multiple jobs listed by the qstat
809 utility.
810 The -o option allows users to redirect the standard output stream. A
812 user might, for example, wish to redirect to the null device the stan‐
813 dard output stream of a job that produces copious yet superfluous out‐
814 put.
815 The -P option allows users to designate the relative priority of a
817 batch job for selection from a queue.
818 The -q option allows users to specify an initial queue for the batch
820 job. If the user specifies a routing queue, the batch server routes the
821 batch job to another queue for execution or further routing. If the
822 user specifies a non-routing queue, the batch server of the queue even‐
823 tually executes the batch job.
824 The -r option allows users to control whether the submitted job will be
826 rerun if the controlling batch node fails during execution of the batch
827 job. The -r option likewise allows users to indicate whether or not
828 the batch job is eligible to be rerun by the qrerun utility. Some jobs
829 cannot be correctly rerun because of changes they make in the state of
830 databases or other aspects of their environment. This volume of
831 POSIX.1‐2017 specifies that the default, if the -r option is not pre‐
832 sented to the utility, will be that the batch job cannot be rerun,
833 since the result of rerunning a non-rerunnable job might be catastroph‐
834 ic.
835 The -S option allows users to specify the program (usually a shell)
837 that will be invoked to process the script of the batch job. This
838 option has been modified to allow a list of shell names and locations
839 associated with different hosts.
840 The -u option is useful when the submitting user is authorized to use
842 more than one account on a given host, in which case the -u option
843 allows the user to select from among those accounts. The option-argu‐
844 ment is a list of user-host pairs, so that the submitting user can pro‐
845 vide different user identifiers for different nodes in the event the
846 batch job is routed. The -u option provides a lot of flexibility to
847 accommodate sites with complex account structures. Users that have the
848 same user identifier on all the hosts they are authorized to use will
849 not need to use the -u option.
850 The -V option allows users to export all their current environment
852 variables, as of the time the batch job is submitted, to the context of
853 the processes of the batch job.
854 The -v option allows users to export specific environment variables
856 from their current process to the processes of the batch job.
857 The -z option allows users to suppress the writing of the batch job
859 identifier to standard output. The -z option is an existing NQS prac‐
860 tice that has been standardized.
861 Historically, the qsub utility has served the batch job-submission
863 function in the NQS system, the existing practice on which it is based.
864 Some changes and additions have been made to the qsub utility in this
865 volume of POSIX.1‐2017, vis-a-vis NQS, as a result of the growing pool
866 of experience with distributed batch systems.
867 The set of features of the qsub utility as defined in this volume of
869 POSIX.1‐2017 appears to incorporate all the common existing practice on
870 potentially conforming platforms.
871
873 The qsub utility may be removed in a future version.
874
876 Chapter 3, Batch Environment Services, qrerun, qstat, touch
877 The Base Definitions volume of POSIX.1‐2017, Section 3.150, Epoch, Sec‐
879 tion 6.1, Portable Character Set, Chapter 8, Environment Variables,
880 Section 12.2, Utility Syntax Guidelines
881
883 Portions of this text are reprinted and reproduced in electronic form
884 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
885 table Operating System Interface (POSIX), The Open Group Base Specifi‐
886 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
887 Electrical and Electronics Engineers, Inc and The Open Group. In the
888 event of any discrepancy between this version and the original IEEE and
889 The Open Group Standard, the original IEEE and The Open Group Standard
890 is the referee document. The original Standard can be obtained online
891 at http://www.opengroup.org/unix/online.html .
892 Any typographical or formatting errors that appear in this page are
894 most likely to have been introduced during the conversion of the source
895 files to man page format. To report such errors, see https://www.ker‐
896 nel.org/doc/man-pages/reporting_bugs.html .
897IEEE/The Open Group 2017 QSUB(1P)