1qalter(1B)                            PBS                           qalter(1B)
2
3
4

NAME

6       qalter - alter pbs batch job
7

SYNOPSIS

9       qalter  [-a  date_time] [-A account_string] [-c interval] [-e path] [-h
10       hold_list] [-j join] [-k keep] [-l resource_list] [-m mail_options] [-M
11       user_list] [-n node exclusive] [-N name] [-o path] [-p priority] [-r c]
12       [-S path] [-t array_range] [-u  user_list]  [-W  additional_attributes]
13       job_identifier...
14

DESCRIPTION

16       The qalter command modifies the attributes of the job or jobs specified
17       by job_identifier on the command line.  Only those attributes listed as
18       options  on  the  command  will  be  modified.  If any of the specified
19       attributes cannot be modified for a job for any reason,  none  of  that
20       job's attributes will be modified.
21
22       The  qalter  command accomplishes the modifications by sending a Modify
23       Job batch request to the batch server which owns each job.
24

OPTIONS

26       -a date_time
27               Replaces the time at which the job becomes eligible for  execu‐
28               tion.       The      date_time      argument     syntax     is:
29               [[[[CC]YY]MM]DD]hhmm[.SS].
30
31               If the month, MM, is not specified, it will default to the cur‐
32               rent  month  if the specified day DD, is in the future.  Other‐
33               wise, the month will be set to next month.   Likewise,  if  the
34               day, DD, is not specified, it will default to today if the time
35               hhmm is in the future.  Otherwise,  the  day  will  be  set  to
36               tomorrow.
37
38               This attribute can be altered once the job has begun execution,
39               but it will not take affect until the job is rerun.
40
41       -A account_string
42               Replaces the account string associated with the job.
43
44               This attribute cannot be altered once the job has begun  execu‐
45               tion.
46
47       -c interval
48               Replaces  the  the  interval  at  which  the job will be check‐
49               pointed.  If the job executes upon a host which does  not  sup‐
50               port checkpoint, this option will be ignored.
51
52               The interval argument is specified as:
53
54               n   No checkpointing is to be performed.
55
56               s   Checkpointing  is to be performed only when the server exe‐
57                   cuting the job is shutdown.
58
59               c   Checkpointing is to be performed at the default minimum cpu
60                   time for the queue from which the job is executing.
61
62               c=minutes
63                  Checkpointing  is to be performed at an interval of minutes,
64                  which is the integer number of minutes of CPU time  used  by
65                  the job.  This value must be greater than zero.  If the num‐
66                  ber is less than the default checkpoint  time,  the  default
67                  time will be used.
68
69               This attribute can be altered once the job has begun execution,
70               but the new value does not take affect until the job is rerun.
71
72       -e path Replaces the path to be used for the standard error  stream  of
73               the batch job.  The path argument is of the form:
74                   [hostname:]path_name
75               where  hostname is the name of a host to which the file will be
76               returned and path_name is the path name on  that  host  in  the
77               syntax recognized by POSIX 1003.1.  The argument will be inter‐
78               preted as follows:
79
80               path_name
81                      Where path_name is not an absolute path name,  then  the
82                      qalter command will expand the path name relative to the
83                      current working directory of the command.   The  command
84                      will  supply  the name of the host upon which it is exe‐
85                      cuting for the hostname component.
86
87               hostname:path_name
88                      Where path_name is not an absolute path name,  then  the
89                      qalter  command will not expand the path name.  The exe‐
90                      cution server will expand it relative to the home direc‐
91                      tory of the user on the system specified by hostname.
92
93               path_name
94                      Where  path_name  specifies  an absolute path name, then
95                      qalter will supply the name of the host on which  it  is
96                      executing for the hostname.
97
98               hostname:path_name
99                      Where  path_name  specifies  an  absolute path name, the
100                      path will be used as specified.
101
102               This attribute can be altered once the job has begun execution,
103               but it will not take affect until the job is rerun.
104
105       -h hold_list
106               Updates  the types of holds on the job.  The hold_list argument
107               is a string of one or more of the following characters:
108
109               u    Add the USER type hold.
110
111               s    Add the SYSTEM type hold if the user has  the  appropriate
112                    level  of  privilege.   [Typically  reserved  to the batch
113                    administrator.]
114
115               o    Add the OTHER (or OPERATOR ) type hold if the user has the
116                    appropriate  level  of  privilege.  [Typically reserved to
117                    the batch administrator and batch operator.]
118
119               n    Set to none; that is clear the hold types which  could  be
120                    applied with the users level of privilege.
121
122               Repetition  of  characters is permitted, but "n" may not appear
123               in the same option argument with the  other  three  characters.
124               This attribute can be altered once the job has begun execution,
125               but the hold will not take affect until the job is rerun.
126
127       -j join Declares which standard streams  of  the  job  will  be  merged
128               together.   The  join argument value may be the characters "oe"
129               and "eo", or the single character "n".
130
131               A argument value of oe directs that  the  standard  output  and
132               standard  error  streams of the job will be merged, intermixed,
133               and returned as the standard output.  A argument  value  of  eo
134               directs  that the standard output and standard error streams of
135               the job will be merged, intermixed, and returned as  the  stan‐
136               dard error.
137
138               A  value of n directs that the two streams will be two separate
139               files.  This attribute can be altered once the  job  has  begun
140               execution, but it will not take affect until the job is rerun.
141
142       -k keep Defines which if either of standard output or standard error of
143               the job will be retained on the execution host.  If set  for  a
144               stream, this option overrides the path name for that stream.
145
146               The  argument  is either the single letter "e", "o", or "n", or
147               one or more of the letters  "e"  and  "o"  combined  in  either
148               order.
149
150               n    No streams are to be retained.
151
152               e    The  standard error stream is to retained on the execution
153                    host.  The  stream will be placed in the home directory of
154                    the  user  under whose user id the job executed.  The file
155                    name will be the default file name given by: job_name.ese‐
156                    quence  where  job_name is the name specified for the job,
157                    and sequence is the sequence number component of  the  job
158                    identifier.
159
160               o    The standard output stream is to be retained on the execu‐
161                    tion host.  The  stream will be placed in the home  direc‐
162                    tory  of  the  user  under whose user id the job executed.
163                    The file name will be the  default  file  name  given  by:
164                    job_name.osequence  where  job_name  is the name specified
165                    for the job, and sequence is the sequence number component
166                    of the job identifier.
167
168               eo   Both  the  standard output and standard error streams will
169                    be retained.
170
171               oe   Both the standard output and standard error  streams  will
172                    be retained.
173
174               This  attribute cannot be altered once the job has begun execu‐
175               tion.
176
177       -l resource_list
178               Modifies the list of resources that are required  by  the  job.
179               The Resource_List argument is in the following syntax:
180               resource_name[=[value]][,resource_name[=[value]],...]
181
182               If  a  requested  modification  to  a resource would exceed the
183               resource limits for jobs in the current queue, the server  will
184               reject the request.
185
186               If  the job is running, only certain, resources can be altered.
187               Which resources can be altered  in  the  run  state  is  system
188               dependent.    A  user  may  only  lower  the  limit  for  those
189               resources.
190
191       -m mail_options
192               Replaces the set of conditions under which the execution server
193               will send a mail message about the job.  The mail_options argu‐
194               ment is a string which consists of the single character "n", or
195               one or more of the characters "a", "b", and "e".
196
197               If the character "n" is specified, no mail will be sent.
198
199               For the letters "a", "b", and "e":
200
201               a    mail is sent when the job is aborted by the batch system.
202
203               b    mail is sent when the job begins execution.
204
205               e    mail is sent when the job terminates.
206
207       -M user_list
208               Replaces  the  list of users to whom mail is sent by the execu‐
209               tion server when it sends mail about the job.
210
211               The user_list argument is of the form:
212                   user[@host][,user[@host],...]
213
214       -n node exclusive
215               Sets whether or not the job  has  node  exclusive  access.   To
216               specify  node  exclusive  access, just use the single character
217               'y'. To specify that the job should  not  have  node  exclusive
218               access, just use the single character 'n'.
219
220       -N name Renames the job.  The name specified may be up to and including
221               15 characters in length.  It must  consist  of  printable,  non
222               white space characters with the first character alphabetic.
223
224       -o path Replaces  the path to be used for the standard output stream of
225               the batch job.  The path argument is of the form:
226                   [hostname:]path_name
227               where hostname is the name of a host to which the file will  be
228               returned  and  path_name  is  the path name on that host in the
229               syntax recognized by POSIX.  The argument will  be  interpreted
230               as follows:
231
232               path_name
233                      Where  path_name  is not an absolute path name, then the
234                      qalter command will expand the path name relative to the
235                      current  working  directory of the command.  The command
236                      will supply the name of the host upon which it  is  exe‐
237                      cuting for the hostname component.
238
239               hostname:path_name
240                      Where  path_name  is not an absolute path name, then the
241                      qalter command will not expand the path name.  The  exe‐
242                      cution server will expand it relative to the home direc‐
243                      tory of the user on the system specified by hostname.
244
245               path_name
246                      Where path_name specifies an absolute  path  name,  then
247                      the  qalter will supply the name of the host on which it
248                      is executing for the hostname.
249
250               hostname:path_name
251                      Where path_name specifies an  absolute  path  name,  the
252                      path will be used as specified.
253
254               This attribute can be altered once the job has begun execution,
255               but it will not take affect until the job is rerun.
256
257       -p priority
258               Replaces the priority of the job.  The priority  argument  must
259               be a integer between -1024 and +1023 inclusive.
260
261               This attribute can be altered once the job has begun execution,
262               but it will not take affect until the job is rerun.
263
264       -r c    Declares whether the job is rerunable.  See the qrerun command.
265               The  option  argument  c is a single character.  PBS recognizes
266               the following characters: y and n.
267
268               If the argument is "y", the job is marked  rerunable.   If  the
269               argument is "n", the job is marked as not rerunable.
270
271       -S path Declares the shell that interprets the job script.
272
273               The option argument path_list is in the form:
274                   path[@host][,path[@host],...]
275               Only  one  path  may be specified for any host named.  Only one
276               path may be specified without the corresponding host name.  The
277               path  selected  will be the one with the host name that matched
278               the name of the execution host.  If no matching host is  found,
279               then  if  present  the  path  specified  without a host will be
280               selected.
281
282               If the -S option is not specified, the option argument  is  the
283               null  string,  or  no entry from the path_list is selected, the
284               execution will use the login shell of the user on the execution
285               host.
286
287               This attribute can be altered once the job has begun execution,
288               but it will not take affect until the job is rerun.
289
290       -t array_range
291               The array_range argument is an integer id or a range  of  inte‐
292               gers.  Multiple  ids  or  id  ranges can be combined in a comma
293               delimted list. Examples : -t 1-100 or -t 1,10,50-100
294
295               If an array range isn't specified, the command tries to operate
296               on  the  entire array. The command acts on the array (or speci‐
297               fied range of the array) just as it would on an individual job.
298
299               An optional slot limit can be specified to limit the amount  of
300               jobs  that  can  run concurrently in the job array. The default
301               value is unlimited. The slot limit must be the last thing spec‐
302               ified in the array_request and is delimited from the array by a
303               percent sign (%).
304
305               qalter weatherSimulationArray[] -t %20
306
307               Here, the array weatherSimulationArray[] is configured to allow
308               a maximum of 20 concurrently running jobs.
309
310               Note:  Slot limits can be applied at job submit time with qsub,
311               or can  be  set  in  a  global  server  parameter  policy  with
312               max_slot_limit.
313
314       -u user_list
315               Replaces  the  user  name  under which the job is to run on the
316               execution system.
317
318               The user_list argument is of the form:
319                   user[@host][,user[@host],...]
320               Only one user name may be given for per specified  host.   Only
321               one of the user specifications may be supplied without the cor‐
322               responding host specification.  That user name will be used for
323               execution on any host not named in the argument list.
324
325               This  attribute cannot be altered once the job has begun execu‐
326               tion.
327
328       -W additional_attributes
329               The -W option allows for the  modification  of  additional  job
330               attributes.  The general syntax of the -W is in the form:
331                   -W attr_name=value[,attr_name=value...]
332               Note  if white space occurs anywhere within the option argument
333               string or the equal sign, "=", occurs within an attribute_value
334               string,  then the string must be enclosed with either single or
335               double quote marks.
336
337               PBS currently supports the following attributes within  the  -W
338               option.
339
340               depend=dependency_list
341               Redefines  the  dependencies  between this and other jobs.  The
342               dependency_list   is   in   the   form:   type[:argument[:argu‐
343               ment...][,type:argument...].
344               The  argument is either a numeric count or a PBS job id accord‐
345               ing to type .  If argument is a count, it must be greater  than
346               0.   If  it is a job id and is not fully specified in the form:
347               seq_number.server.name, it will be expanded  according  to  the
348               default server rules.  If argument is null (the preceding colon
349               need not be specified), the  dependency  of  the  corresponding
350               type is cleared (unset).
351
352                   synccount:count
353                       This  job  is the first in a set of jobs to be executed
354                       at the same time.  Count is the  number  of  additional
355                       jobs in the set.
356
357                   syncwith:jobid
358                       This job is an additional member of a set of jobs to be
359                       executed at the same time.  Jobid is the job identifier
360                       of the first job in the set.
361
362                   after:jobid[:jobid...]
363                       This  job  may  be scheduled for execution at any point
364                       after jobs jobid have started execution.
365
366                   afterok:jobid[:jobid...]
367                       This job may be scheduled for execution only after jobs
368                       jobid have terminated with no errors.
369
370                   afternotok:jobid[:jobid...]
371                       This job may be scheduled for execution only after jobs
372                       jobid have terminated with errors.
373
374                   afterany:jobid[:jobid...]
375                       This job may be  scheduled  for  execution  after  jobs
376                       jobid have terminated, with or without errors.
377
378                   on:count
379                       This  job  may  be  scheduled for execution after count
380                       dependencies on other jobs have been  satisfied.   This
381                       form  is  used  in  conjunction  with one of the before
382                       forms, see below.
383
384                   before:jobid[:jobid...]
385                       When this job has begun execution, then  jobs  jobid...
386                       may begin.
387
388                   beforeok:jobid[:jobid...]
389                       If  this  job terminates execution without errors, then
390                       jobs jobid... may begin.
391
392                   beforenotok:jobid[:jobid...]
393                       If this job terminates execution with errors, then jobs
394                       jobid... may begin.
395
396                   beforeany:jobid[:jobid...]
397                       When  this  job terminates execution, jobs jobid... may
398                       begin.
399
400                       If any of the before forms are used, the job referenced
401                       by  jobid  must  have  been submitted with a dependency
402                       type of on.
403
404                       The job specified in any of the before forms must  have
405                       the  same  owner as the job being altered..  Otherwise,
406                       the dependency will not take effect.
407
408                   Error processing of the existence, state, or  condition  of
409                   the job on which the newly submitted job is a deferred ser‐
410                   vice, i.e. the check is performed after the job is  queued.
411                   If an error is detected, the new job will be deleted by the
412                   server.  Mail will be sent to the job submitter stating the
413                   error.
414
415               group_list=g_list
416               Alters the group name under which the job is to run on the exe‐
417               cution system.
418
419               The     g_list     argument      is      of      the      form:
420                 group[@host][,group[@host],...]
421               Only  one group name may be given per specified host.  Only one
422               of the group specifications may be supplied without the  corre‐
423               sponding  host  specification.   That  group name will used for
424               execution on any host not named in the argument list.
425
426               stagein=file_list
427               stageout=file_list
428               Alters which files are staged (copied) in before job  start  or
429               staged out after the job completes execution.  The file_list is
430               in the form: local_file@hostname:remote_file[,...]
431               The name local_file is the name on the  system  where  the  job
432               executes.  It may be an absolute path or a path relative to the
433               home directory of the user.  The name remote_file is the desti‐
434               nation name on the host specified by hostname.  The name may be
435               absolute or relative to the user's home directory on the desti‐
436               nation host.
437

OPERANDS

439       The  qalter  command accepts one or more job_identifier operands of the
440       form:
441           sequence_number[.server_name][@server]
442

STANDARD ERROR

444       Any error condition, either in processing the options or the  operands,
445       or  any  error received in reply to the batch requests will result in a
446       error message being written to standard error.
447

EXIT STATUS

449       Upon successful processing of all the operands presented to the  qalter
450       command, the exit status will be a value of zero.
451
452       If  the  qalter command fails to process any operand, the command exits
453       with a value greater than zero.
454

SEE ALSO

456       qsub(1B),  qstat(1B),  pbs_alterjob(3B),  pbs_statjob(3B),   pbs_selec‐
457       tjob(3B), pbs_resources_*(7B), where * is system type, and the PBS ERS.
458
459
460
461Local                                                               qalter(1B)
Impressum