1QALTER(P) POSIX Programmer's Manual QALTER(P)
2
6 qalter - alter batch job
7
9 qalter [-a date_time][-A account_string][-c interval][-e path_name]
10 [-h hold_list][-j join_list][-k keep_list][-l resource_list]
11 [-m mail_options][-M mail_list][-N name][-o path_name]
12 [-p priority][-r y|n][-S path_name_list][-u user_list]
13 job_identifier ...
14
16 The attributes of a batch job are altered by a request to the batch
17 server that manages the batch job. The qalter utility is a user-acces‐
18 sible batch client that requests the alteration of the attributes of
19 one or more batch jobs.
20 The qalter utility shall alter the attributes of those batch jobs, and
22 only those batch jobs, for which a batch job_identifier is presented to
23 the utility.
24 The qalter utility shall alter the attributes of batch jobs in the
26 order in which the batch job_identifiers are presented to the utility.
27 If the qalter utility fails to process a batch job_identifier success‐
29 fully, the utility shall proceed to process the remaining batch
30 job_identifiers, if any.
31 For each batch job_identifier for which the qalter utility succeeds,
33 each attribute of the identified batch job shall be altered as indi‐
34 cated by all the options presented to the utility.
35 For each identified batch job for which the qalter utility fails, the
37 utility shall not alter any attribute of the batch job.
38 For each batch job that the qalter utility processes, the utility shall
40 not modify any attribute other than those required by the options and
41 option-arguments presented to the utility.
42 The qalter utility shall alter batch jobs by sending a Modify Job
44 Request to the batch server that manages each batch job. At the time
45 the qalter utility exits, it shall have modified the batch job corre‐
46 sponding to each successfully processed batch job_identifier. An
47 attempt to alter the attributes of a batch job in the RUNNING state is
48 implementation-defined.
49
51 The qalter utility shall conform to the Base Definitions volume of
52 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
53 The following options shall be supported by the implementation:
55 -a date_time
57 Redefine the time at which the batch job becomes eligible for
58 execution.
59 The date_time argument shall be in the same form and represent the same
61 time as for the touch utility. The time so represented shall be set
62 into the Execution_Time attribute of the batch job. If the time speci‐
63 fied is earlier than the current time, the -a option shall have no
64 effect.
65 -A account_string
67 Redefine the account to which the resource consumption of the
69 batch job should be charged.
70 The syntax of the account_string option-argument is unspecified.
72 The qalter utility shall set the Account_Name attribute of the batch
74 job to the value of the account_string option-argument.
75 -c interval
77 Redefine whether the batch job should be checkpointed, and if
78 so, how often.
79 The qalter utility shall accept a value for the interval option-argu‐
81 ment that is one of the following:
82 n
84 No checkpointing is to be performed on the batch job (NO_CHECK‐
85 POINT).
86 s
88 Checkpointing is to be performed only when the batch server is
89 shut down (CHECKPOINT_AT_SHUTDOWN).
90 c
92 Automatic periodic checkpointing is to be performed at the Mini‐
93 mum_Cpu_Interval attribute of the batch queue, in units of CPU
94 minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
95 c=minutes
97 Automatic periodic checkpointing is to be performed every min‐
98 utes of CPU time, or every Minimum_Cpu_Interval minutes, which‐
99 ever is greater. The minutes argument shall conform to the syn‐
100 tax for unsigned integers and shall be greater than zero.
101 An implementation may define other checkpoint intervals. The confor‐
104 mance document for an implementation shall describe any alternative
105 checkpoint intervals, how they are specified, their internal behavior,
106 and how they affect the behavior of the utility.
107 The qalter utility shall set the Checkpoint attribute of the batch job
109 to the value of the interval option-argument.
110 -e path_name
112 Redefine the path to be used for the standard error stream of
113 the batch job.
114 The qalter utility shall accept a path_name option-argument that con‐
116 forms to the syntax of the path_name element defined in the System
117 Interfaces volume of IEEE Std 1003.1-2001, which can be preceded by a
118 host name element of the form hostname:.
119 If the path_name option-argument constitutes an absolute pathname, the
121 qalter utility shall set the Error_Path attribute of the batch job to
122 the value of the path_name option-argument, including the host name
123 element, if present.
124 If the path_name option-argument constitutes a relative pathname and no
126 host name element is specified, the qalter utility shall set the
127 Error_Path attribute of the batch job to the value of the absolute
128 pathname derived by expanding the path_name option-argument relative to
129 the current directory of the process that executes the qalter utility.
130 If the path_name option-argument constitutes a relative pathname and a
132 host name element is specified, the qalter utility shall set the
133 Error_Path attribute of the batch job to the value of the option-argu‐
134 ment without expansion.
135 If the path_name option-argument does not include a host name element,
137 the qalter utility shall prefix the pathname in the Error_Path
138 attribute with hostname:, where hostname is the name of the host upon
139 which the qalter utility is being executed.
140 -h hold_list
142 Redefine the types of holds, if any, on the batch job. The qal‐
143 ter -h option shall accept a value for the hold_list option-
144 argument that is a string of alphanumeric characters in the por‐
145 table character set.
146 The qalter utility shall accept a value for the hold_list option-argu‐
148 ment that is a string of one or more of the characters 'u' , 's' , or
149 'o' , or the single character 'n' . For each unique character in the
150 hold_list option-argument, the qalter utility shall add a value to the
151 Hold_Types attribute of the batch job as follows, each representing a
152 different hold type:
153 u
155 USER
156 s
158 SYSTEM
159 o
161 OPERATOR
162 If any of these characters are duplicated in the hold_list option-argu‐
165 ment, the duplicates shall be ignored. An existing Hold_Types attribute
166 can be cleared by the hold type:
167 n
169 NO_HOLD
170 The qalter utility shall consider it an error if any hold type other
173 than 'n' is combined with hold type 'n' . Strictly conforming applica‐
174 tions shall not repeat any of the characters 'u' , 's' , 'o' , or 'n'
175 within the hold_list option-argument. The qalter utility shall permit
176 the repetition of characters, but shall not assign additional meaning
177 to the repeated characters. An implementation may define other hold
178 types. The conformance document for an implementation shall describe
179 any additional hold types, how they are specified, their internal
180 behavior, and how they affect the behavior of the utility.
181 -j join_list
183 Redefine which streams of the batch job are to be merged. The
184 qalter -j option shall accept a value for the join_list option-
185 argument that is a string of alphanumeric characters in the por‐
186 table character set.
187 The qalter utility shall accept a join_list option-argument that con‐
189 sists of one or more of the characters 'e' and 'o' , or the single
190 character 'n' .
191 All of the other batch job output streams specified shall be merged
193 into the output stream represented by the character listed first in the
194 join_list option-argument.
195 For each unique character in the join_list option-argument, the qalter
197 utility shall add a value to the Join_Path attribute of the batch job
198 as follows, each representing a different batch job stream to join:
199 e
201 The standard error of the batch job (JOIN_STD_ERROR).
202 o
204 The standard output of the batch job (JOIN_STD_OUTPUT).
205 An existing Join_Path attribute can be cleared by the join type:
208 n
210 NO_JOIN
211 If 'n' is specified, then no files are joined. The qalter utility shall
214 consider it an error if any join type other than 'n' is combined with
215 join type 'n' .
216 Strictly conforming applications shall not repeat any of the characters
218 'e' , 'o' , or 'n' within the join_list option-argument. The qalter
219 utility shall permit the repetition of characters, but shall not assign
220 additional meaning to the repeated characters.
221 An implementation may define other join types. The conformance document
223 for an implementation shall describe any additional batch job streams,
224 how they are specified, their internal behavior, and how they affect
225 the behavior of the utility.
226 -k keep_list
228 Redefine which output of the batch job to retain on the execu‐
229 tion host.
230 The qalter -k option shall accept a value for the keep_list option-
232 argument that is a string of alphanumeric characters in the portable
233 character set.
234 The qalter utility shall accept a keep_list option-argument that con‐
236 sists of one or more of the characters 'e' and 'o' , or the single
237 character 'n' .
238 For each unique character in the keep_list option-argument, the qalter
240 utility shall add a value to the Keep_Files attribute of the batch job
241 as follows, each representing a different batch job stream to keep:
242 e
244 The standard error of the batch job (KEEP_STD_ERROR).
245 o
247 The standard output of the batch job (KEEP_STD_OUTPUT).
248 If both 'e' and 'o' are specified, then both files are retained. An
251 existing Keep_Files attribute can be cleared by the keep type:
252 n
254 NO_KEEP
255 If 'n' is specified, then no files are retained. The qalter utility
258 shall consider it an error if any keep type other than 'n' is combined
259 with keep type 'n' .
260 Strictly conforming applications shall not repeat any of the characters
262 'e' , 'o' , or 'n' within the keep_list option-argument. The qalter
263 utility shall permit the repetition of characters, but shall not assign
264 additional meaning to the repeated characters. An implementation may
265 define other keep types. The conformance document for an implementation
266 shall describe any additional keep types, how they are specified, their
267 internal behavior, and how they affect the behavior of the utility.
268 -l resource_list
270 Redefine the resources that are allowed or required by the batch
272 job.
273 The qalter utility shall accept a resource_list option-argument that
275 conforms to the following syntax:
276 resource=value[,,resource=value,,...]
279 The qalter utility shall set one entry in the value of the
281 Resource_List attribute of the batch job for each resource listed in
282 the resource_list option-argument.
283 Because the list of supported resource names might vary by batch
285 server, the qalter utility shall rely on the batch server to validate
286 the resource names and associated values. See Multiple Keyword-Value
287 Pairs for a means of removing keyword= value (and value@ keyword) pairs
288 and other general rules for list-oriented batch job attributes.
289 -m mail_options
291 Redefine the points in the execution of the batch job at which
293 the batch server is to send mail about a change in the state of
294 the batch job.
295 The qalter -m option shall accept a value for the mail_options option-
297 argument that is a string of alphanumeric characters in the portable
298 character set.
299 The qalter utility shall accept a value for the mail_options option-
301 argument that is a string of one or more of the characters 'e' , 'b' ,
302 and 'a' , or the single character 'n' . For each unique character in
303 the mail_options option-argument, the qalter utility shall add a value
304 to the Mail_Users attribute of the batch job as follows, each repre‐
305 senting a different time during the life of a batch job at which to
306 send mail:
307 e
309 MAIL_AT_EXIT
310 b
312 MAIL_AT_BEGINNING
313 a
315 MAIL_AT_ABORT
316 If any of these characters are duplicated in the mail_options option-
319 argument, the duplicates shall be ignored.
320 An existing Mail_Points attribute can be cleared by the mail type:
322 n
324 NO_MAIL
325 If 'n' is specified, then mail is not sent. The qalter utility shall
328 consider it an error if any mail type other than 'n' is combined with
329 mail type 'n' . Strictly conforming applications shall not repeat any
330 of the characters 'e' , 'b' , 'a' , or 'n' within the mail_options
331 option-argument. The qalter utility shall permit the repetition of
332 characters but shall not assign additional meaning to the repeated
333 characters.
334 An implementation may define other mail types. The conformance document
336 for an implementation shall describe any additional mail types, how
337 they are specified, their internal behavior, and how they affect the
338 behavior of the utility.
339 -M mail_list
341 Redefine the list of users to which the batch server that exe‐
342 cutes the batch job is to send mail, if the batch server sends
343 mail about the batch job.
344 The syntax of the mail_list option-argument is unspecified. If the
346 implementation of the qalter utility uses a name service to locate
347 users, the utility shall accept the syntax used by the name service.
348 If the implementation of the qalter utility does not use a name service
350 to locate users, the implementation shall accept the following syntax
351 for user names:
352 mail_address[,,mail_address,,...]
355 The interpretation of mail_address is implementation-defined.
357 The qalter utility shall set the Mail_Users attribute of the batch job
359 to the value of the mail_list option-argument.
360 -N name
362 Redefine the name of the batch job.
363 The qalter -N option shall accept a value for the name option-argument
365 that is a string of up to 15 alphanumeric characters in the portable
366 character set where the first character is alphabetic.
367 The syntax of the name option-argument is unspecified.
369 The qalter utility shall set the Job_Name attribute of the batch job to
371 the value of the name option-argument.
372 -o path_name
374 Redefine the path for the standard output of the batch job.
375 The qalter utility shall accept a path_name option-argument that con‐
377 forms to the syntax of the path_name element defined in the System
378 Interfaces volume of IEEE Std 1003.1-2001, which can be preceded by a
379 host name element of the form hostname:.
380 If the path_name option-argument constitutes an absolute pathname, the
382 qalter utility shall set the Output_Path attribute of the batch job to
383 the value of the path_name option-argument.
384 If the path_name option-argument constitutes a relative pathname and no
386 host name element is specified, the qalter utility shall set the Out‐
387 put_Path attribute of the batch job to the absolute pathname derived by
388 expanding the path_name option-argument relative to the current direc‐
389 tory of the process that executes the qalter utility.
390 If the path_name option-argument constitutes a relative pathname and a
392 host name element is specified, the qalter utility shall set the Out‐
393 put_Path attribute of the batch job to the value of the path_name
394 option-argument without any expansion of the pathname.
395 If the path_name option-argument does not include a host name element,
397 the qalter utility shall prefix the pathname in the Output_Path
398 attribute with hostname:, where hostname is the name of the host upon
399 which the qalter utility is being executed.
400 -p priority
402 Redefine the priority of the batch job.
403 The qalter utility shall accept a value for the priority option-argu‐
405 ment that conforms to the syntax for signed decimal integers, and which
406 is not less than -1024 and not greater than 1023.
407 The qalter utility shall set the Priority attribute of the batch job to
409 the value of the priority option-argument.
410 -r y|n
412 Redefine whether the batch job is rerunnable.
413 If the value of the option-argument is 'y' , the qalter utility shall
415 set the Rerunable attribute of the batch job to TRUE.
416 If the value of the option-argument is 'n' , the qalter utility shall
418 set the Rerunable attribute of the batch job to FALSE.
419 The qalter utility shall consider it an error if any character other
421 than 'y' or 'n' is specified in the option-argument.
422 -S path_name_list
424 Redefine the shell that interprets the script at the destination
426 system.
427 The qalter utility shall accept a path_name_list option-argument that
429 conforms to the following syntax:
430 pathname[@host][,pathname[@host],...]
433 The qalter utility shall accept only one pathname that is missing a
435 corresponding host name. The qalter utility shall allow only one path‐
436 name per named host.
437 The qalter utility shall add a value to the Shell_Path_List attribute
439 of the batch job for each entry in the path_name_list option-argument.
440 See Multiple Keyword-Value Pairs for a means of removing keyword= value
441 (and value@ keyword) pairs and other general rules for list-oriented
442 batch job attributes.
443 -u user_list
445 Redefine the user name under which the batch job is to run at
446 the destination system.
447 The qalter utility shall accept a user_list option-argument that con‐
449 forms to the following syntax:
450 username[@host][,,username[@host],,...]
453 The qalter utility shall accept only one user name that is missing a
455 corresponding host name. The qalter utility shall accept only one user
456 name per named host.
457 The qalter utility shall add a value to the User_List attribute of the
459 batch job for each entry in the user_list option-argument. See Multiple
460 Keyword-Value Pairs for a means of removing keyword= value (and value@
461 keyword) pairs and other general rules for list-oriented batch job
462 attributes.
463
466 The qalter utility shall accept one or more operands that conform to
467 the syntax for a batch job_identifier (see Batch Job Identifier ).
468
470 Not used.
471
473 None.
474
476 The following environment variables shall affect the execution of qal‐
477 ter:
478 LANG Provide a default value for the internationalization variables
480 that are unset or null. (See the Base Definitions volume of
481 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
482 ables for the precedence of internationalization variables used
483 to determine the values of locale categories.)
484 LC_ALL If set to a non-empty string value, override the values of all
486 the other internationalization variables.
487 LC_CTYPE
489 Determine the locale for the interpretation of sequences of
490 bytes of text data as characters (for example, single-byte as
491 opposed to multi-byte characters in arguments).
492 LC_MESSAGES
494 Determine the locale that should be used to affect the format
495 and contents of diagnostic messages written to standard error.
496 LOGNAME
498 Determine the login name of the user.
499 TZ Determine the timezone used to interpret the date-time option-
501 argument. If TZ is unset or null, an unspecified default time‐
502 zone shall be used.
503
506 Default.
507
509 None.
510
512 The standard error shall be used only for diagnostic messages.
513
515 None.
516
518 None.
519
521 The following exit values shall be returned:
522 0 Successful completion.
524 >0 An error occurred.
526
529 In addition to the default behavior, the qalter utility shall not be
530 required to write a diagnostic message to standard error when the error
531 reply received from a batch server indicates that the batch job_identi‐
532 fier does not exist on the server. Whether or not the qalter utility
533 attempts to locate the batch job on other batch servers is implementa‐
534 tion-defined.
535 The following sections are informative.
537
539 None.
540
542 None.
543
545 The qalter utility allows users to change the attributes of a batch
546 job.
547 As a means of altering a queued job, the qalter utility is superior to
549 deleting and requeuing the batch job insofar as an altered job retains
550 its place in the queue with some traditional selection algorithms. In
551 addition, the qalter utility is both shorter and simpler than a
552 sequence of qdel and qsub utilities.
553 The result of an attempt on the part of a user to alter a batch job in
555 a RUNNING state is implementation-defined because a batch job in the
556 RUNNING state will already have opened its output files and otherwise
557 performed any actions indicated by the options in effect at the time
558 the batch job began execution.
559 The options processed by the qalter utility are identical to those of
561 the qsub utility, with a few exceptions: -V, -v, and -q. The -V and -v
562 are inappropriate for the qalter utility, since they capture poten‐
563 tially transient environment information from the submitting process.
564 The -q option would specify a new queue, which would largely negate the
565 previously stated advantage of using qalter; furthermore, the qmove
566 utility provides a superior means of moving jobs.
567 Each of the following paragraphs provides the rationale for a qalter
569 option.
570 Additional rationale concerning these options can be found in the
572 rationale for the qsub utility.
573 The -a option allows users to alter the date and time at which a batch
575 job becomes eligible to run.
576 The -A option allows users to change the account that will be charged
578 for the resources consumed by the batch job. Support for the -A option
579 is mandatory for conforming implementations of qalter, even though sup‐
580 port of accounting is optional for servers. Whether or not to support
581 accounting is left to the implementor of the server, but mandatory sup‐
582 port of the -A option assures users of a consistent interface and
583 allows them to control accounting on servers that support accounting.
584 The -c option allows users to alter the checkpointing interval of a
586 batch job. A checkpointing system, which is not defined by
587 IEEE Std 1003.1-2001, allows recovery of a batch job at the most recent
588 checkpoint in the event of a crash. Checkpointing is typically used
589 for jobs that consume expensive computing time or must meet a critical
590 schedule. Users should be allowed to make the tradeoff between the
591 overhead of checkpointing and the risk to the timely completion of the
592 batch job; therefore, this volume of IEEE Std 1003.1-2001 provides the
593 checkpointing interval option. Support for checkpointing is optional
594 for servers.
595 The -e option allows users to alter the name and location of the stan‐
597 dard error stream written by a batch job. However, the path of the
598 standard error stream is meaningless if the value of the Join_Path
599 attribute of the batch job is TRUE.
600 The -h option allows users to set the hold type in the Hold_Types
602 attribute of a batch job. The qhold and qrls utilities add or remove
603 hold types to the Hold_Types attribute, respectively. The -h option has
604 been modified to allow for implementation-defined hold types.
605 The -j option allows users to alter the decision to join (merge) the
607 standard error stream of the batch job with the standard output stream
608 of the batch job.
609 The -l option allows users to change the resource limits imposed on a
611 batch job.
612 The -m option allows users to modify the list of points in the life of
614 a batch job at which the designated users will receive mail notifica‐
615 tion.
616 The -M option allows users to alter the list of users who will receive
618 notification about events in the life of a batch job.
619 The -N option allows users to change the name of a batch job.
621 The -o option allows users to alter the name and path to which the
623 standard output stream of the batch job will be written.
624 The -P option allows users to modify the priority of a batch job. Sup‐
626 port for priority is optional for batch servers.
627 The -r option allows users to alter the rerunability status of a batch
629 job.
630 The -S option allows users to change the name and location of the shell
632 image that will be invoked to interpret the script of the batch job.
633 This option has been modified to allow a list of shell name and loca‐
634 tions associated with different hosts.
635 The -u option allows users to change the user identifier under which
637 the batch job will execute.
638 The job_identifier operand syntax is provided so that the user can dif‐
640 ferentiate between the originating and destination (or executing) batch
641 server. These may or may not be the same. The . server_name portion
642 identifies the originating batch server, while the @ server portion
643 identifies the destination batch server.
644 Historically, the qalter utility has been a component of the Network
646 Queuing System (NQS), the existing practice from which this utility has
647 been derived.
648
650 None.
651
653 Batch Environment Services , qdel , qhold , qmove , qrls , qsub , touch
654
656 Portions of this text are reprinted and reproduced in electronic form
657 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
658 -- Portable Operating System Interface (POSIX), The Open Group Base
659 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
660 Electrical and Electronics Engineers, Inc and The Open Group. In the
661 event of any discrepancy between this version and the original IEEE and
662 The Open Group Standard, the original IEEE and The Open Group Standard
663 is the referee document. The original Standard can be obtained online
664 at http://www.opengroup.org/unix/online.html .
665IEEE/The Open Group 2003 QALTER(P)