1QALTER(1P) POSIX Programmer's Manual QALTER(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 qalter — alter batch job
13
15 qalter [-a date_time] [-A account_string] [-c interval] [-e path_name]
16 [-h hold_list] [-j join_list] [-k keep_list] [-l resource_list]
17 [-m mail_options] [-M mail_list] [-N name] [-o path_name]
18 [-p priority] [-r y|n] [-S path_name_list] [-u user_list]
19 job_identifier...
20
22 The attributes of a batch job are altered by a request to the batch
23 server that manages the batch job. The qalter utility is a user-acces‐
24 sible batch client that requests the alteration of the attributes of
25 one or more batch jobs.
26 The qalter utility shall alter the attributes of those batch jobs, and
28 only those batch jobs, for which a batch job_identifier is presented to
29 the utility.
30 The qalter utility shall alter the attributes of batch jobs in the
32 order in which the batch job_identifiers are presented to the utility.
33 If the qalter utility fails to process a batch job_identifier success‐
35 fully, the utility shall proceed to process the remaining batch
36 job_identifiers, if any.
37 For each batch job_identifier for which the qalter utility succeeds,
39 each attribute of the identified batch job shall be altered as indi‐
40 cated by all the options presented to the utility.
41 For each identified batch job for which the qalter utility fails, the
43 utility shall not alter any attribute of the batch job.
44 For each batch job that the qalter utility processes, the utility shall
46 not modify any attribute other than those required by the options and
47 option-arguments presented to the utility.
48 The qalter utility shall alter batch jobs by sending a Modify Job
50 Request to the batch server that manages each batch job. At the time
51 the qalter utility exits, it shall have modified the batch job corre‐
52 sponding to each successfully processed batch job_identifier. An
53 attempt to alter the attributes of a batch job in the RUNNING state is
54 implementation-defined.
55
57 The qalter utility shall conform to the Base Definitions volume of
58 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
59 The following options shall be supported by the implementation:
61 -a date_time
63 Redefine the time at which the batch job becomes eligible for
64 execution.
65 The date_time argument shall be in the same form and repre‐
67 sent the same time as for the touch utility. The time so rep‐
68 resented shall be set into the Execution_Time attribute of
69 the batch job. If the time specified is earlier than the cur‐
70 rent time, the -a option shall have no effect.
71 -A account_string
73 Redefine the account to which the resource consumption of the
74 batch job should be charged.
75 The syntax of the account_string option-argument is unspeci‐
77 fied.
78 The qalter utility shall set the Account_Name attribute of
80 the batch job to the value of the account_string option-argu‐
81 ment.
82 -c interval
84 Redefine whether the batch job should be checkpointed, and if
85 so, how often.
86 The qalter utility shall accept a value for the interval
88 option-argument that is one of the following:
89 n No checkpointing is to be performed on the batch
91 job (NO_CHECKPOINT).
92 s Checkpointing is to be performed only when the
94 batch server is shut down (CHECKPOINT_AT_SHUTDOWN).
95 c Automatic periodic checkpointing is to be performed
97 at the Minimum_Cpu_Interval attribute of the batch
98 queue, in units of CPU minutes (CHECK‐
99 POINT_AT_MIN_CPU_INTERVAL).
100 c=minutes Automatic periodic checkpointing is to be performed
102 every minutes of CPU time, or every Mini‐
103 mum_Cpu_Interval minutes, whichever is greater. The
104 minutes argument shall conform to the syntax for
105 unsigned integers and shall be greater than zero.
106 An implementation may define other checkpoint intervals. The
108 conformance document for an implementation shall describe any
109 alternative checkpoint intervals, how they are specified,
110 their internal behavior, and how they affect the behavior of
111 the utility.
112 The qalter utility shall set the Checkpoint attribute of the
114 batch job to the value of the interval option-argument.
115 -e path_name
117 Redefine the path to be used for the standard error stream of
118 the batch job.
119 The qalter utility shall accept a path_name option-argument
121 that conforms to the syntax of the path_name element defined
122 in the System Interfaces volume of POSIX.1‐2017, which can be
123 preceded by a host name element of the form hostname:.
124 If the path_name option-argument constitutes an absolute
126 pathname, the qalter utility shall set the Error_Path
127 attribute of the batch job to the value of the path_name
128 option-argument, including the host name element, if present.
129 If the path_name option-argument constitutes a relative path‐
131 name and no host name element is specified, the qalter util‐
132 ity shall set the Error_Path attribute of the batch job to
133 the value of the absolute pathname derived by expanding the
134 path_name option-argument relative to the current directory
135 of the process that executes the qalter utility.
136 If the path_name option-argument constitutes a relative path‐
138 name and a host name element is specified, the qalter utility
139 shall set the Error_Path attribute of the batch job to the
140 value of the option-argument without expansion.
141 If the path_name option-argument does not include a host name
143 element, the qalter utility shall prefix the pathname in the
144 Error_Path attribute with hostname:, where hostname is the
145 name of the host upon which the qalter utility is being exe‐
146 cuted.
147 -h hold_list
149 Redefine the types of holds, if any, on the batch job. The
150 qalter -h option shall accept a value for the hold_list
151 option-argument that is a string of alphanumeric characters
152 in the portable character set.
153 The qalter utility shall accept a value for the hold_list
155 option-argument that is a string of one or more of the char‐
156 acters 'u', 's', or 'o', or the single character 'n'. For
157 each unique character in the hold_list option-argument, the
158 qalter utility shall add a value to the Hold_Types attribute
159 of the batch job as follows, each representing a different
160 hold type:
161 u USER
163 s SYSTEM
165 o OPERATOR
167 If any of these characters are duplicated in the hold_list
169 option-argument, the duplicates shall be ignored. An existing
170 Hold_Types attribute can be cleared by the hold type:
171 n NO_HOLD
173 The qalter utility shall consider it an error if any hold
175 type other than 'n' is combined with hold type 'n'. Strictly
176 conforming applications shall not repeat any of the charac‐
177 ters 'u', 's', 'o', or 'n' within the hold_list option-argu‐
178 ment. The qalter utility shall permit the repetition of char‐
179 acters, but shall not assign additional meaning to the
180 repeated characters. An implementation may define other hold
181 types. The conformance document for an implementation shall
182 describe any additional hold types, how they are specified,
183 their internal behavior, and how they affect the behavior of
184 the utility.
185 -j join_list
187 Redefine which streams of the batch job are to be merged. The
188 qalter -j option shall accept a value for the join_list
189 option-argument that is a string of alphanumeric characters
190 in the portable character set.
191 The qalter utility shall accept a join_list option-argument
193 that consists of one or more of the characters 'e' and 'o',
194 or the single character 'n'.
195 All of the other batch job output streams specified shall be
197 merged into the output stream represented by the character
198 listed first in the join_list option-argument.
199 For each unique character in the join_list option-argument,
201 the qalter utility shall add a value to the Join_Path
202 attribute of the batch job as follows, each representing a
203 different batch job stream to join:
204 e The standard error of the batch job (JOIN_STD_ERROR).
206 o The standard output of the batch job (JOIN_STD_OUTPUT).
208 An existing Join_Path attribute can be cleared by the join
210 type:
211 n NO_JOIN
213 If 'n' is specified, then no files are joined. The qalter
215 utility shall consider it an error if any join type other
216 than 'n' is combined with join type 'n'.
217 Strictly conforming applications shall not repeat any of the
219 characters 'e', 'o', or 'n' within the join_list option-argu‐
220 ment. The qalter utility shall permit the repetition of char‐
221 acters, but shall not assign additional meaning to the
222 repeated characters.
223 An implementation may define other join types. The confor‐
225 mance document for an implementation shall describe any addi‐
226 tional batch job streams, how they are specified, their
227 internal behavior, and how they affect the behavior of the
228 utility.
229 -k keep_list
231 Redefine which output of the batch job to retain on the exe‐
232 cution host.
233 The qalter -k option shall accept a value for the keep_list
235 option-argument that is a string of alphanumeric characters
236 in the portable character set.
237 The qalter utility shall accept a keep_list option-argument
239 that consists of one or more of the characters 'e' and 'o',
240 or the single character 'n'.
241 For each unique character in the keep_list option-argument,
243 the qalter utility shall add a value to the Keep_Files
244 attribute of the batch job as follows, each representing a
245 different batch job stream to keep:
246 e The standard error of the batch job (KEEP_STD_ERROR).
248 o The standard output of the batch job (KEEP_STD_OUTPUT).
250 If both 'e' and 'o' are specified, then both files are
252 retained. An existing Keep_Files attribute can be cleared by
253 the keep type:
254 n NO_KEEP
256 If 'n' is specified, then no files are retained. The qalter
258 utility shall consider it an error if any keep type other
259 than 'n' is combined with keep type 'n'.
260 Strictly conforming applications shall not repeat any of the
262 characters 'e', 'o', or 'n' within the keep_list option-argu‐
263 ment. The qalter utility shall permit the repetition of char‐
264 acters, but shall not assign additional meaning to the
265 repeated characters. An implementation may define other keep
266 types. The conformance document for an implementation shall
267 describe any additional keep types, how they are specified,
268 their internal behavior, and how they affect the behavior of
269 the utility.
270 -l resource_list
272 Redefine the resources that are allowed or required by the
273 batch job.
274 The qalter utility shall accept a resource_list option-argu‐
276 ment that conforms to the following syntax:
277 resource=value[,,resource=value,,...]
280 The qalter utility shall set one entry in the value of the
282 Resource_List attribute of the batch job for each resource
283 listed in the resource_list option-argument.
284 Because the list of supported resource names might vary by
286 batch server, the qalter utility shall rely on the batch
287 server to validate the resource names and associated values.
288 See Section 3.3.3, Multiple Keyword-Value Pairs for a means
289 of removing keyword=value (and value@keyword) pairs and other
290 general rules for list-oriented batch job attributes.
291 -m mail_options
293 Redefine the points in the execution of the batch job at
294 which the batch server is to send mail about a change in the
295 state of the batch job.
296 The qalter -m option shall accept a value for the
298 mail_options option-argument that is a string of alphanumeric
299 characters in the portable character set.
300 The qalter utility shall accept a value for the mail_options
302 option-argument that is a string of one or more of the char‐
303 acters 'e', 'b', and 'a', or the single character 'n'. For
304 each unique character in the mail_options option-argument,
305 the qalter utility shall add a value to the Mail_Users
306 attribute of the batch job as follows, each representing a
307 different time during the life of a batch job at which to
308 send mail:
309 e MAIL_AT_EXIT
311 b MAIL_AT_BEGINNING
313 a MAIL_AT_ABORT
315 If any of these characters are duplicated in the mail_options
317 option-argument, the duplicates shall be ignored.
318 An existing Mail_Points attribute can be cleared by the mail
320 type:
321 n NO_MAIL
323 If 'n' is specified, then mail is not sent. The qalter util‐
325 ity shall consider it an error if any mail type other than
326 'n' is combined with mail type 'n'. Strictly conforming
327 applications shall not repeat any of the characters 'e', 'b',
328 'a', or 'n' within the mail_options option-argument. The qal‐
329 ter utility shall permit the repetition of characters but
330 shall not assign additional meaning to the repeated charac‐
331 ters.
332 An implementation may define other mail types. The confor‐
334 mance document for an implementation shall describe any addi‐
335 tional mail types, how they are specified, their internal
336 behavior, and how they affect the behavior of the utility.
337 -M mail_list
339 Redefine the list of users to which the batch server that
340 executes the batch job is to send mail, if the batch server
341 sends mail about the batch job.
342 The syntax of the mail_list option-argument is unspecified.
344 If the implementation of the qalter utility uses a name ser‐
345 vice to locate users, the utility shall accept the syntax
346 used by the name service.
347 If the implementation of the qalter utility does not use a
349 name service to locate users, the implementation shall accept
350 the following syntax for user names:
351 mail_address[,,mail_address,,...]
354 The interpretation of mail_address is implementation-defined.
356 The qalter utility shall set the Mail_Users attribute of the
358 batch job to the value of the mail_list option-argument.
359 -N name Redefine the name of the batch job.
361 The qalter -N option shall accept a value for the name
363 option-argument that is a string of up to 15 alphanumeric
364 characters in the portable character set where the first
365 character is alphabetic.
366 The syntax of the name option-argument is unspecified.
368 The qalter utility shall set the Job_Name attribute of the
370 batch job to the value of the name option-argument.
371 -o path_name
373 Redefine the path for the standard output of the batch job.
374 The qalter utility shall accept a path_name option-argument
376 that conforms to the syntax of the path_name element defined
377 in the System Interfaces volume of POSIX.1‐2017, which can be
378 preceded by a host name element of the form hostname:.
379 If the path_name option-argument constitutes an absolute
381 pathname, the qalter utility shall set the Output_Path
382 attribute of the batch job to the value of the path_name
383 option-argument.
384 If the path_name option-argument constitutes a relative path‐
386 name and no host name element is specified, the qalter util‐
387 ity shall set the Output_Path attribute of the batch job to
388 the absolute pathname derived by expanding the path_name
389 option-argument relative to the current directory of the
390 process that executes the qalter utility.
391 If the path_name option-argument constitutes a relative path‐
393 name and a host name element is specified, the qalter utility
394 shall set the Output_Path attribute of the batch job to the
395 value of the path_name option-argument without any expansion
396 of the pathname.
397 If the path_name option-argument does not include a host name
399 element, the qalter utility shall prefix the pathname in the
400 Output_Path attribute with hostname:, where hostname is the
401 name of the host upon which the qalter utility is being exe‐
402 cuted.
403 -p priority
405 Redefine the priority of the batch job.
406 The qalter utility shall accept a value for the priority
408 option-argument that conforms to the syntax for signed deci‐
409 mal integers, and which is not less than -1024 and not
410 greater than 1023.
411 The qalter utility shall set the Priority attribute of the
413 batch job to the value of the priority option-argument.
414 -r y|n Redefine whether the batch job is rerunnable.
416 If the value of the option-argument is 'y', the qalter util‐
418 ity shall set the Rerunable attribute of the batch job to
419 TRUE.
420 If the value of the option-argument is 'n', the qalter util‐
422 ity shall set the Rerunable attribute of the batch job to
423 FALSE.
424 The qalter utility shall consider it an error if any charac‐
426 ter other than 'y' or 'n' is specified in the option-argu‐
427 ment.
428 -S path_name_list
430 Redefine the shell that interprets the script at the destina‐
431 tion system.
432 The qalter utility shall accept a path_name_list option-argu‐
434 ment that conforms to the following syntax:
435 pathname[@host][,pathname[@host],...]
438 The qalter utility shall accept only one pathname that is
440 missing a corresponding host name. The qalter utility shall
441 allow only one pathname per named host.
442 The qalter utility shall add a value to the Shell_Path_List
444 attribute of the batch job for each entry in the
445 path_name_list option-argument. See Section 3.3.3, Multiple
446 Keyword-Value Pairs for a means of removing keyword=value
447 (and value@keyword) pairs and other general rules for list-
448 oriented batch job attributes.
449 -u user_list
451 Redefine the user name under which the batch job is to run at
452 the destination system.
453 The qalter utility shall accept a user_list option-argument
455 that conforms to the following syntax:
456 username[@host][,,username[@host],,...]
459 The qalter utility shall accept only one user name that is
461 missing a corresponding host name. The qalter utility shall
462 accept only one user name per named host.
463 The qalter utility shall add a value to the User_List
465 attribute of the batch job for each entry in the user_list
466 option-argument. See Section 3.3.3, Multiple Keyword-Value
467 Pairs for a means of removing keyword=value (and value@key‐
468 word) pairs and other general rules for list-oriented batch
469 job attributes.
470
472 The qalter utility shall accept one or more operands that conform to
473 the syntax for a batch job_identifier (see Section 3.3.1, Batch Job
474 Identifier).
475
477 Not used.
478
480 None.
481
483 The following environment variables shall affect the execution of qal‐
484 ter:
485 LANG Provide a default value for the internationalization vari‐
487 ables that are unset or null. (See the Base Definitions vol‐
488 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
489 ables the precedence of internationalization variables used
490 to determine the values of locale categories.)
491 LC_ALL If set to a non-empty string value, override the values of
493 all the other internationalization variables.
494 LC_CTYPE Determine the locale for the interpretation of sequences of
496 bytes of text data as characters (for example, single-byte as
497 opposed to multi-byte characters in arguments).
498 LC_MESSAGES
500 Determine the locale that should be used to affect the format
501 and contents of diagnostic messages written to standard
502 error.
503 LOGNAME Determine the login name of the user.
505 TZ Determine the timezone used to interpret the date-time
507 option-argument. If TZ is unset or null, an unspecified
508 default timezone shall be used.
509
511 Default.
512
514 None.
515
517 The standard error shall be used only for diagnostic messages.
518
520 None.
521
523 None.
524
526 The following exit values shall be returned:
527 0 Successful completion.
529 >0 An error occurred.
531
533 In addition to the default behavior, the qalter utility shall not be
534 required to write a diagnostic message to standard error when the error
535 reply received from a batch server indicates that the batch job_identi‐
536 fier does not exist on the server. Whether or not the qalter utility
537 attempts to locate the batch job on other batch servers is implementa‐
538 tion-defined.
539 The following sections are informative.
541
543 None.
544
546 None.
547
549 The qalter utility allows users to change the attributes of a batch
550 job.
551 As a means of altering a queued job, the qalter utility is superior to
553 deleting and requeuing the batch job insofar as an altered job retains
554 its place in the queue with some traditional selection algorithms. In
555 addition, the qalter utility is both shorter and simpler than a
556 sequence of qdel and qsub utilities.
557 The result of an attempt on the part of a user to alter a batch job in
559 a RUNNING state is implementation-defined because a batch job in the
560 RUNNING state will already have opened its output files and otherwise
561 performed any actions indicated by the options in effect at the time
562 the batch job began execution.
563 The options processed by the qalter utility are identical to those of
565 the qsub utility, with a few exceptions: -V, -v, and -q. The -V and -v
566 are inappropriate for the qalter utility, since they capture poten‐
567 tially transient environment information from the submitting process.
568 The -q option would specify a new queue, which would largely negate the
569 previously stated advantage of using qalter; furthermore, the qmove
570 utility provides a superior means of moving jobs.
571 Each of the following paragraphs provides the rationale for a qalter
573 option.
574 Additional rationale concerning these options can be found in the
576 rationale for the qsub utility.
577 The -a option allows users to alter the date and time at which a batch
579 job becomes eligible to run.
580 The -A option allows users to change the account that will be charged
582 for the resources consumed by the batch job. Support for the -A option
583 is mandatory for conforming implementations of qalter, even though sup‐
584 port of accounting is optional for servers. Whether or not to support
585 accounting is left to the implementor of the server, but mandatory sup‐
586 port of the -A option assures users of a consistent interface and
587 allows them to control accounting on servers that support accounting.
588 The -c option allows users to alter the checkpointing interval of a
590 batch job. A checkpointing system, which is not defined by
591 POSIX.1‐2008, allows recovery of a batch job at the most recent check‐
592 point in the event of a crash. Checkpointing is typically used for jobs
593 that consume expensive computing time or must meet a critical schedule.
594 Users should be allowed to make the tradeoff between the overhead of
595 checkpointing and the risk to the timely completion of the batch job;
596 therefore, this volume of POSIX.1‐2017 provides the checkpointing
597 interval option. Support for checkpointing is optional for servers.
598 The -e option allows users to alter the name and location of the stan‐
600 dard error stream written by a batch job. However, the path of the
601 standard error stream is meaningless if the value of the Join_Path
602 attribute of the batch job is TRUE.
603 The -h option allows users to set the hold type in the Hold_Types
605 attribute of a batch job. The qhold and qrls utilities add or remove
606 hold types to the Hold_Types attribute, respectively. The -h option has
607 been modified to allow for implementation-defined hold types.
608 The -j option allows users to alter the decision to join (merge) the
610 standard error stream of the batch job with the standard output stream
611 of the batch job.
612 The -l option allows users to change the resource limits imposed on a
614 batch job.
615 The -m option allows users to modify the list of points in the life of
617 a batch job at which the designated users will receive mail notifica‐
618 tion.
619 The -M option allows users to alter the list of users who will receive
621 notification about events in the life of a batch job.
622 The -N option allows users to change the name of a batch job.
624 The -o option allows users to alter the name and path to which the
626 standard output stream of the batch job will be written.
627 The -P option allows users to modify the priority of a batch job. Sup‐
629 port for priority is optional for batch servers.
630 The -r option allows users to alter the rerunability status of a batch
632 job.
633 The -S option allows users to change the name and location of the shell
635 image that will be invoked to interpret the script of the batch job.
636 This option has been modified to allow a list of shell name and loca‐
637 tions associated with different hosts.
638 The -u option allows users to change the user identifier under which
640 the batch job will execute.
641 The job_identifier operand syntax is provided so that the user can dif‐
643 ferentiate between the originating and destination (or executing) batch
644 server. These may or may not be the same. The .server_name portion
645 identifies the originating batch server, while the @server portion
646 identifies the destination batch server.
647 Historically, the qalter utility has been a component of the Network
649 Queuing System (NQS), the existing practice from which this utility has
650 been derived.
651
653 The qalter utility may be removed in a future version.
654
656 Chapter 3, Batch Environment Services, qdel, qhold, qmove, qrls, qsub,
657 touch
658 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
660 Variables, Section 12.2, Utility Syntax Guidelines
661
663 Portions of this text are reprinted and reproduced in electronic form
664 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
665 table Operating System Interface (POSIX), The Open Group Base Specifi‐
666 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
667 Electrical and Electronics Engineers, Inc and The Open Group. In the
668 event of any discrepancy between this version and the original IEEE and
669 The Open Group Standard, the original IEEE and The Open Group Standard
670 is the referee document. The original Standard can be obtained online
671 at http://www.opengroup.org/unix/online.html .
672 Any typographical or formatting errors that appear in this page are
674 most likely to have been introduced during the conversion of the source
675 files to man page format. To report such errors, see https://www.ker‐
676 nel.org/doc/man-pages/reporting_bugs.html .
677IEEE/The Open Group 2017 QALTER(1P)