1qalter(1B) PBS qalter(1B)
2
6 qalter - alter pbs batch job
7
9 qalter [-a date_time] [-A account_string] [-c interval] [-e path] [-h
10 hold_list] [-j join] [-k keep] [-l resource_list] [-L numa_list] [-m
11 mail_options] [-M user_list] [-n node exclusive] [-N name] [-o path]
12 [-p priority] [-q] [-r c] [-S path] [-t array_range] [-u user_list]
13 [-v variable_list] [-W additional_attributes] [-x exec_host] job_iden‐
14 tifier...
15
17 The qalter command modifies the attributes of the job or jobs specified
18 by job_identifier on the command line. Only those attributes listed as
19 options on the command will be modified. If any of the specified at‐
20 tributes cannot be modified for a job for any reason, none of that
21 job's attributes will be modified.
22 The qalter command accomplishes the modifications by sending a Modify
24 Job batch request to the batch server which owns each job.
25
27 -a date_time
28 Replaces the time at which the job becomes eligible for execu‐
29 tion. The date_time argument syntax is:
30 [[[[CC]YY]MM]DD]hhmm[.SS].
31 If the month, MM, is not specified, it will default to the cur‐
33 rent month if the specified day DD, is in the future. Other‐
34 wise, the month will be set to next month. Likewise, if the
35 day, DD, is not specified, it will default to today if the time
36 hhmm is in the future. Otherwise, the day will be set to to‐
37 morrow.
38 This attribute can be altered once the job has begun execution,
40 but it will not take affect until the job is rerun.
41 -A account_string
43 Replaces the account string associated with the job.
44 This attribute cannot be altered once the job has begun execu‐
46 tion.
47 -c interval
49 Replaces the the interval at which the job will be check‐
50 pointed. If the job executes upon a host which does not sup‐
51 port checkpoint, this option will be ignored.
52 The interval argument is specified as:
54 n No checkpointing is to be performed.
56 s Checkpointing is to be performed only when the server exe‐
58 cuting the job is shutdown.
59 c Checkpointing is to be performed at the default minimum cpu
61 time for the queue from which the job is executing.
62 c=minutes
64 Checkpointing is to be performed at an interval of minutes,
65 which is the integer number of minutes of CPU time used by
66 the job. This value must be greater than zero. If the num‐
67 ber is less than the default checkpoint time, the default
68 time will be used.
69 This attribute can be altered once the job has begun execution,
71 but the new value does not take affect until the job is rerun.
72 -e path Replaces the path to be used for the standard error stream of
74 the batch job. The path argument is of the form:
75 [hostname:]path_name
76 where hostname is the name of a host to which the file will be
77 returned and path_name is the path name on that host in the
78 syntax recognized by POSIX 1003.1. The argument will be inter‐
79 preted as follows:
80 path_name
82 Where path_name is not an absolute path name, then the
83 qalter command will expand the path name relative to the
84 current working directory of the command. The command
85 will supply the name of the host upon which it is exe‐
86 cuting for the hostname component.
87 hostname:path_name
89 Where path_name is not an absolute path name, then the
90 qalter command will not expand the path name. The exe‐
91 cution server will expand it relative to the home direc‐
92 tory of the user on the system specified by hostname.
93 path_name
95 Where path_name specifies an absolute path name, then
96 qalter will supply the name of the host on which it is
97 executing for the hostname.
98 hostname:path_name
100 Where path_name specifies an absolute path name, the
101 path will be used as specified.
102 This attribute can be altered once the job has begun execution,
104 but it will not take affect until the job is rerun.
105 -h hold_list
107 Updates the types of holds on the job. The hold_list argument
108 is a string of one or more of the following characters:
109 u Add the USER type hold.
111 s Add the SYSTEM type hold if the user has the appropriate
113 level of privilege. [Typically reserved to the batch ad‐
114 ministrator.]
115 o Add the OTHER (or OPERATOR ) type hold if the user has the
117 appropriate level of privilege. [Typically reserved to
118 the batch administrator and batch operator.]
119 n Set to none; that is clear the hold types which could be
121 applied with the users level of privilege.
122 Repetition of characters is permitted, but "n" may not appear
124 in the same option argument with the other three characters.
125 This attribute can be altered once the job has begun execution,
126 but the hold will not take affect until the job is rerun.
127 -j join Declares which standard streams of the job will be merged to‐
129 gether. The join argument value may be the characters "oe" and
130 "eo", or the single character "n".
131 A argument value of oe directs that the standard output and
133 standard error streams of the job will be merged, intermixed,
134 and returned as the standard output. A argument value of eo
135 directs that the standard output and standard error streams of
136 the job will be merged, intermixed, and returned as the stan‐
137 dard error.
138 A value of n directs that the two streams will be two separate
140 files. This attribute can be altered once the job has begun
141 execution, but it will not take affect until the job is rerun.
142 -k keep Defines which if either of standard output or standard error of
144 the job will be retained on the execution host. If set for a
145 stream, this option overrides the path name for that stream.
146 The argument is either the single letter "e", "o", or "n", or
148 one or more of the letters "e" and "o" combined in either or‐
149 der.
150 n No streams are to be retained.
152 e The standard error stream is to retained on the execution
154 host. The stream will be placed in the home directory of
155 the user under whose user id the job executed. The file
156 name will be the default file name given by: job_name.ese‐
157 quence where job_name is the name specified for the job,
158 and sequence is the sequence number component of the job
159 identifier.
160 o The standard output stream is to be retained on the execu‐
162 tion host. The stream will be placed in the home direc‐
163 tory of the user under whose user id the job executed.
164 The file name will be the default file name given by:
165 job_name.osequence where job_name is the name specified
166 for the job, and sequence is the sequence number component
167 of the job identifier.
168 eo Both the standard output and standard error streams will
170 be retained.
171 oe Both the standard output and standard error streams will
173 be retained.
174 This attribute cannot be altered once the job has begun execu‐
176 tion.
177 -l resource_list
179 Modifies the list of resources that are required by the job.
180 The Resource_List argument is in the following syntax:
181 resource_name[=[value]][,resource_name[=[value]],...]
182 If a requested modification to a resource would exceed the re‐
184 source limits for jobs in the current queue, the server will
185 reject the request.
186 If the job is running, only certain, resources can be altered.
188 Which resources can be altered in the run state is system de‐
189 pendent. A user may only lower the limit for those resources.
190 -L numa_list
192 Defines the NUMA-aware resource requests for NUMA hardware.
193 This option will work with non-NUMA hardware.
194 Note: The -L option is available with Torque 6.0 and later. The
196 -L option uses a different syntax than the -l resource_list op‐
197 tion.
198 -m mail_options
200 Replaces the set of conditions under which the execution server
201 will send a mail message about the job. The mail_options argu‐
202 ment is a string which consists of the single character "n", or
203 one or more of the characters "a", "b", and "e".
204 If the character "n" is specified, no mail will be sent.
206 For the letters "a", "b", and "e":
208 a mail is sent when the job is aborted by the batch system.
210 b mail is sent when the job begins execution.
212 e mail is sent when the job terminates.
214 -M user_list
216 Replaces the list of users to whom mail is sent by the execu‐
217 tion server when it sends mail about the job.
218 The user_list argument is of the form:
220 user[@host][,user[@host],...]
221 -n node exclusive
223 Sets whether or not the job has node exclusive access. To
224 specify node exclusive access, just use the single character
225 'y'. To specify that the job should not have node exclusive ac‐
226 cess, just use the single character 'n'.
227 -N name Renames the job. The name specified may be up to and including
229 15 characters in length. It must consist of printable, non
230 white space characters with the first character alphabetic.
231 -o path Replaces the path to be used for the standard output stream of
233 the batch job. The path argument is of the form:
234 [hostname:]path_name
235 where hostname is the name of a host to which the file will be
236 returned and path_name is the path name on that host in the
237 syntax recognized by POSIX. The argument will be interpreted
238 as follows:
239 path_name
241 Where path_name is not an absolute path name, then the
242 qalter command will expand the path name relative to the
243 current working directory of the command. The command
244 will supply the name of the host upon which it is exe‐
245 cuting for the hostname component.
246 hostname:path_name
248 Where path_name is not an absolute path name, then the
249 qalter command will not expand the path name. The exe‐
250 cution server will expand it relative to the home direc‐
251 tory of the user on the system specified by hostname.
252 path_name
254 Where path_name specifies an absolute path name, then
255 the qalter will supply the name of the host on which it
256 is executing for the hostname.
257 hostname:path_name
259 Where path_name specifies an absolute path name, the
260 path will be used as specified.
261 This attribute can be altered once the job has begun execution,
263 but it will not take affect until the job is rerun.
264 -p priority
266 Replaces the priority of the job. The priority argument must
267 be a integer between -1024 and +1023 inclusive.
268 This attribute can be altered once the job has begun execution,
270 but it will not take affect until the job is rerun.
271 -q Use an asynchronous (non-blocking alter call to the server.
273 -r c Declares whether the job is rerunable. See the qrerun command.
275 The option argument c is a single character. PBS recognizes
276 the following characters: y and n.
277 If the argument is "y", the job is marked rerunable. If the
279 argument is "n", the job is marked as not rerunable.
280 -S path Declares the shell that interprets the job script.
282 The option argument path_list is in the form:
284 path[@host][,path[@host],...]
285 Only one path may be specified for any host named. Only one
286 path may be specified without the corresponding host name. The
287 path selected will be the one with the host name that matched
288 the name of the execution host. If no matching host is found,
289 then if present the path specified without a host will be se‐
290 lected.
291 If the -S option is not specified, the option argument is the
293 null string, or no entry from the path_list is selected, the
294 execution will use the login shell of the user on the execution
295 host.
296 This attribute can be altered once the job has begun execution,
298 but it will not take affect until the job is rerun.
299 -t array_range
301 The array_range argument is an integer id or a range of inte‐
302 gers. Multiple ids or id ranges can be combined in a comma de‐
303 limted list. Examples : -t 1-100 or -t 1,10,50-100
304 If an array range isn't specified, the command tries to operate
306 on the entire array. The command acts on the array (or speci‐
307 fied range of the array) just as it would on an individual job.
308 An optional slot limit can be specified to limit the amount of
310 jobs that can run concurrently in the job array. The default
311 value is unlimited. The slot limit must be the last thing spec‐
312 ified in the array_request and is delimited from the array by a
313 percent sign (%).
314 qalter 15.napali[] -t %20
316 Here, the array 15.napali[] is configured to allow a maximum of
318 20 concurrently running jobs.
319 Note: Slot limits can be applied at job submit time with qsub,
321 or can be set in a global server parameter policy with
322 max_slot_limit.
323 -u user_list
325 Replaces the user name under which the job is to run on the ex‐
326 ecution system.
327 The user_list argument is of the form:
329 user[@host][,user[@host],...]
330 Only one user name may be given for per specified host. Only
331 one of the user specifications may be supplied without the cor‐
332 responding host specification. That user name will be used for
333 execution on any host not named in the argument list.
334 This attribute cannot be altered once the job has begun execu‐
336 tion.
337 -v Expand the list of environment variables that are exported to
339 the job.
340 names environment variables from the qsub command environment
341 that are made available to the job when it executes. The vari‐
342 able_list is a comma-separated list of strings of the form
343 variable or variable=value. These variables and their values
344 are passed to the job.
345 -x Modify the exec_host field of the job.
347 -W additional_attributes
349 The -W option allows for the modification of additional job at‐
350 tributes. The general syntax of the -W is in the form:
351 -W attr_name=value[,attr_name=value...]
352 Note if white space occurs anywhere within the option argument
353 string or the equal sign, "=", occurs within an attribute_value
354 string, then the string must be enclosed with either single or
355 double quote marks.
356 PBS currently supports the following attributes within the -W
358 option.
359 depend=dependency_list
361 Redefines the dependencies between this and other jobs. The
362 dependency_list is in the form: type[:argument[:argu‐
363 ment...][,type:argument...].
364 The argument is either a numeric count or a PBS job id accord‐
365 ing to type . If argument is a count, it must be greater than
366 0. If it is a job id and is not fully specified in the form:
367 seq_number.server.name, it will be expanded according to the
368 default server rules. If argument is null (the preceding colon
369 need not be specified), the dependency of the corresponding
370 type is cleared (unset).
371 synccount:count
373 This job is the first in a set of jobs to be executed
374 at the same time. Count is the number of additional
375 jobs in the set.
376 syncwith:jobid
378 This job is an additional member of a set of jobs to be
379 executed at the same time. Jobid is the job identifier
380 of the first job in the set.
381 after:jobid[:jobid...]
383 This job may be scheduled for execution at any point
384 after jobs jobid have started execution.
385 afterok:jobid[:jobid...]
387 This job may be scheduled for execution only after jobs
388 jobid have terminated with no errors.
389 afternotok:jobid[:jobid...]
391 This job may be scheduled for execution only after jobs
392 jobid have terminated with errors.
393 afterany:jobid[:jobid...]
395 This job may be scheduled for execution after jobs jo‐
396 bid have terminated, with or without errors.
397 on:count
399 This job may be scheduled for execution after count de‐
400 pendencies on other jobs have been satisfied. This
401 form is used in conjunction with one of the before
402 forms, see below.
403 before:jobid[:jobid...]
405 When this job has begun execution, then jobs jobid...
406 may begin.
407 beforeok:jobid[:jobid...]
409 If this job terminates execution without errors, then
410 jobs jobid... may begin.
411 beforenotok:jobid[:jobid...]
413 If this job terminates execution with errors, then jobs
414 jobid... may begin.
415 beforeany:jobid[:jobid...]
417 When this job terminates execution, jobs jobid... may
418 begin.
419 If any of the before forms are used, the job referenced
421 by jobid must have been submitted with a dependency
422 type of on.
423 The job specified in any of the before forms must have
425 the same owner as the job being altered.. Otherwise,
426 the dependency will not take effect.
427 Error processing of the existence, state, or condition of
429 the job on which the newly submitted job is a deferred ser‐
430 vice, i.e. the check is performed after the job is queued.
431 If an error is detected, the new job will be deleted by the
432 server. Mail will be sent to the job submitter stating the
433 error.
434 group_list=g_list
436 Alters the group name under which the job is to run on the exe‐
437 cution system.
438 The g_list argument is of the form:
440 group[@host][,group[@host],...]
441 Only one group name may be given per specified host. Only one
442 of the group specifications may be supplied without the corre‐
443 sponding host specification. That group name will used for ex‐
444 ecution on any host not named in the argument list.
445 stagein=file_list
447 stageout=file_list
448 Alters which files are staged (copied) in before job start or
449 staged out after the job completes execution. The file_list is
450 in the form: local_file@hostname:remote_file[,...]
451 The name local_file is the name on the system where the job ex‐
452 ecutes. It may be an absolute path or a path relative to the
453 home directory of the user. The name remote_file is the desti‐
454 nation name on the host specified by hostname. The name may be
455 absolute or relative to the user's home directory on the desti‐
456 nation host.
457
459 The qalter command accepts one or more job_identifier operands of the
460 form:
461 sequence_number[.server_name][@server]
462
464 Any error condition, either in processing the options or the operands,
465 or any error received in reply to the batch requests will result in a
466 error message being written to standard error.
467
469 Upon successful processing of all the operands presented to the qalter
470 command, the exit status will be a value of zero.
471 If the qalter command fails to process any operand, the command exits
473 with a value greater than zero.
474
476 qsub(1B), qstat(1B), pbs_alterjob(3B), pbs_statjob(3B), pbs_selec‐
477 tjob(3B), pbs_resources_*(7B), where * is system type, and the PBS ERS.
478Local qalter(1B)