1QSUB(1P)                   POSIX Programmer's Manual                  QSUB(1P)
2
3
4

PROLOG

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
11

NAME

13       qsub — submit a script
14

SYNOPSIS

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

DESCRIPTION

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
28       Upon successful completion, the qsub utility shall have created a batch
29       job that will execute the submitted script.
30
31       The  qsub  utility shall submit a script by sending a Queue Job Request
32       to a batch server.
33
34       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
39       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
44       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
48       PBS_O_WORKDIR The absolute path of the current working directory of the
49                     qsub utility process.
50
51       PBS_O_HOST    The  name  of  the host on which the qsub utility is run‐
52                     ning.
53

OPTIONS

55       The qsub utility shall  conform  to  the  Base  Definitions  volume  of
56       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
57
58       The following options shall be supported by the implementation:
59
60       −a date_time
61                 Define  the  time  at  which a batch job becomes eligible for
62                 execution.
63
64                 The qsub utility shall accept an  option-argument  that  con‐
65                 forms to the syntax of the time operand of the touch utility.
66
67                      Table 4-19: Environment Variable Values (Utilities)
68
69                          ┌──────────────┬───────────────────────────┐
70Variable Name Value at qsub Time     
71                          ├──────────────┼───────────────────────────┤
72PBS_O_HOMEHOME
73PBS_O_HOST    │ Client host name          │
74PBS_O_LANGLANG
75PBS_O_LOGNAMELOGNAME
76PBS_O_PATHPATH
77PBS_O_MAILMAIL
78PBS_O_SHELLSHELL
79PBS_O_TZTZ
80PBS_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
87                 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
93                 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
98       −A account_string
99                 Define  the  account to which the resource consumption of the
100                 batch job should be charged.
101
102                 The syntax of the account_string option-argument is  unspeci‐
103                 fied.
104
105                 The  qsub utility shall set the Account_Name attribute of the
106                 batch job to the value of the account_string option-argument.
107
108                 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
112       −c interval
113                 Define whether the batch job should be checkpointed,  and  if
114                 so, how often.
115
116                 The  qsub  utility  shall  accept  a  value  for the interval
117                 option-argument that is one of the following:
118
119                 n         No checkpointing shall be performed  on  the  batch
120                           job (NO_CHECKPOINT).
121
122                 s         Checkpointing  shall  be  performed  only  when the
123                           batch server is shut down (CHECKPOINT_AT_SHUTDOWN).
124
125                 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
130                 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
136                 The  qsub  utility  shall set the Checkpoint attribute of the
137                 batch job to the value of the interval option-argument.
138
139                 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
143       −C directive_prefix
144                 Define the prefix that declares a directive to the qsub util‐
145                 ity within the script.
146
147                 The directive_prefix is not a batch job attribute; it affects
148                 the behavior of the qsub utility.
149
150                 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
158       −e path_name
159                 Define the path to be used for the standard error  stream  of
160                 the batch job.
161
162                 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
166                 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
171                 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
178                 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
184                 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
189                 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
194                 The  default  filename  for  standard error has the following
195                 format:
196
197                     job_name.esequence_number
198
199       −h        Specify that a USER hold is applied to the batch job.
200
201                 The qsub utility  shall  set  the  value  of  the  Hold_Types
202                 attribute of the batch job to the value USER.
203
204                 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
208       −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
215                 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
219                 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
223                 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
228                 e     The standard error of the batch job (JOIN_STD_ERROR).
229
230                 o     The standard output of the batch job (JOIN_STD_OUTPUT).
231
232                 An existing Join_Path attribute can be cleared by the follow‐
233                 ing join type:
234
235                 n     NO_JOIN
236
237                 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
241                 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
247                 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
253                 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
257       −k keep_list
258                 Define  which output of the batch job to retain on the execu‐
259                 tion host.
260
261                 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
266                 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
270                 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
275                 e     The standard error of the batch job (KEEP_STD_ERROR).
276
277                 o     The standard output of the batch job (KEEP_STD_OUTPUT).
278
279                 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
283                 n     NO_KEEP
284
285                 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
289                 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
295                 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
303       −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
308                 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
313                 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
317                 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
323                 e     MAIL_AT_EXIT
324
325                 b     MAIL_AT_BEGINNING
326
327                 a     MAIL_AT_ABORT
328
329                 If any of these characters are duplicated in the mail_options
330                 option-argument, the duplicates shall be ignored.
331
332                 An existing Mail_Points attribute can be cleared by the  fol‐
333                 lowing mail type:
334
335                 n     NO_MAIL
336
337                 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
341                 Strictly  conforming applications shall not repeat any of the
342                 characters 'e', 'b', 'a',  or  'n'  within  the  mail_options
343                 option-argument.
344
345                 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
352                 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
356       −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
361                 The syntax of the mail_list option-argument is unspecified.
362
363                 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
367                 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
371                     mail_address[,,mail_address,, ...]
372
373                 The interpretation of mail_address is implementation-defined.
374
375                 The qsub utility shall set the Mail_Users  attribute  of  the
376                 batch job to the value of the mail_list option-argument.
377
378                 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
382       −N name   Define the name of the batch job.
383
384                 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
390                 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
394                 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
399                 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
403       −o path_name
404                 Define the path for the standard output of the batch job.
405
406                 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
411                 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
416                 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
423                 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
428                 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
433                 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
438                 The default filename for standard output  has  the  following
439                 format:
440
441                     job_name.osequence_number
442
443       −p priority
444                 Define  the  priority  the  batch job should have relative to
445                 other batch jobs owned by the batch server.
446
447                 The qsub utility shall set  the  Priority  attribute  of  the
448                 batch job to the value of the priority option-argument.
449
450                 If  the  −p  option is not presented to the qsub utility, the
451                 value of the Priority attribute is implementation-defined.
452
453                 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
458       −q destination
459                 Define the destination of the batch job.
460
461                 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
465                 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
470                 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
474                 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
479       −r y|n    Define whether the batch job is rerunnable.
480
481                 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
484                 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
487                 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
491       −S path_name_list
492                 Define the pathname to the shell under which the batch job is
493                 to execute.
494
495                 The qsub utility shall accept a  path_name_list  option-argu‐
496                 ment that conforms to the following syntax:
497
498                     pathname[@host][,,pathname[@host],, ...]
499
500                 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
504                 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
508                 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
512                 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
522       −u user_list
523                 Define the user name under which the batch job is to execute.
524
525                 The  qsub  utility  shall  accept a user_list option-argument
526                 that conforms to the following syntax:
527
528                     username[@host][,,username[@host],, ...]
529
530                 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
534                 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
538                 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
545       −v variable_list
546                 Add to the list of variables that are exported to the session
547                 leader of the batch job.
548
549                 A variable_list is a set of strings of either the form <vari‐
550                 able> or <variable=value>, delimited by <comma> characters.
551
552                 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
558                 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
565                 A conforming application shall not repeat a variable  in  the
566                 environment variable_list option-argument.
567
568                 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
574       −V        Specify  that all of the environment variables of the process
575                 are exported to the context of the batch job.
576
577                 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
582       −z        Specify that the utility does not write the batch job_identi‐
583                 fier of the created batch job to standard output.
584
585                 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
589                 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

OPERANDS

594       The qsub utility shall accept a script operand that indicates the  path
595       to the script of the batch job.
596
597       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
601       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

STDIN

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

INPUT FILES

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

ENVIRONMENT VARIABLES

615       The following environment variables shall affect the execution of qsub:
616
617       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
623       LC_ALL    If set to a non-empty string value, override  the  values  of
624                 all the other internationalization variables.
625
626       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
630       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
635       LOGNAME   Determine the login name of the user.
636
637       PBS_DPREFIX
638                 Determine  the  default  prefix  for  directives  within  the
639                 script.
640
641       SHELL     Determine the pathname  of  the  preferred  command  language
642                 interpreter of the user.
643
644       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

ASYNCHRONOUS EVENTS

649       Once created, a batch job exists until it exits, aborts, or is deleted.
650
651       After  a  batch job is created by the qsub utility, batch servers might
652       route, execute, modify, or delete the batch job.
653

STDOUT

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

STDERR

659       The standard error shall be used only for diagnostic messages.
660

OUTPUT FILES

662       None.
663

EXTENDED DESCRIPTION

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
670       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
674   Option Specification
675       A script can contain directives to the qsub utility.
676
677       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
682       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
691       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
695       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
702       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
706       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
710       In order of preference, the qsub utility  shall  select  the  directive
711       prefix from one of the following sources:
712
713        *  If  the  −C  option  is  presented to the utility, the value of the
714           directive_prefix option-argument
715
716        *  If the environment variable PBS_DPREFIX is defined,  the  value  of
717           that variable
718
719        *  The  four-character string "#PBS" encoded in the portable character
720           set
721
722       If the −C option is present in the script file it shall be ignored.
723

EXIT STATUS

725       The following exit values shall be returned:
726
727        0    Successful completion.
728
729       >0    An error occurred.
730

CONSEQUENCES OF ERRORS

732       Default.
733
734       The following sections are informative.
735

APPLICATION USAGE

737       None.
738

EXAMPLES

740       None.
741

RATIONALE

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
746       The  options of the qsub utility allow users to control many aspects of
747       the queuing and execution of a batch job.
748
749       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
757       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
761       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
766       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
777       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
785       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
791       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
795       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
801       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
807       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
812       The  −P  option  allows  users  to designate the relative priority of a
813       batch job for selection from a queue.
814
815       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
821       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
832       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
837       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
847       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
851       The −v option allows users to  export  specific  environment  variables
852       from their current process to the processes of the batch job.
853
854       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
858       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
864       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

FUTURE DIRECTIONS

869       The qsub utility may be removed in a future version.
870

SEE ALSO

872       Chapter 3, Batch Environment Services, qrerun, qstat, touch
873
874       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
890       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 .
894
895
896
897IEEE/The Open Group                  2013                             QSUB(1P)
Impressum