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]  [-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

DESCRIPTION

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
23       The qalter command accomplishes the modifications by sending  a  Modify
24       Job batch request to the batch server which owns each job.
25

OPTIONS

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
32               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
39               This attribute can be altered once the job has begun execution,
40               but it will not take affect until the job is rerun.
41
42       -A account_string
43               Replaces the account string associated with the job.
44
45               This  attribute cannot be altered once the job has begun execu‐
46               tion.
47
48       -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
53               The interval argument is specified as:
54
55               n   No checkpointing is to be performed.
56
57               s   Checkpointing is to be performed only when the server  exe‐
58                   cuting the job is shutdown.
59
60               c   Checkpointing is to be performed at the default minimum cpu
61                   time for the queue from which the job is executing.
62
63               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
70               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
73       -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
81               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
88               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
94               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
99               hostname:path_name
100                      Where path_name specifies an  absolute  path  name,  the
101                      path will be used as specified.
102
103               This attribute can be altered once the job has begun execution,
104               but it will not take affect until the job is rerun.
105
106       -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
110               u    Add the USER type hold.
111
112               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
116               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
120               n    Set  to  none; that is clear the hold types which could be
121                    applied with the users level of privilege.
122
123               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
128       -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
132               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
139               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
143       -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
147               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
151               n    No streams are to be retained.
152
153               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
161               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
169               eo   Both the standard output and standard error  streams  will
170                    be retained.
171
172               oe   Both  the  standard output and standard error streams will
173                    be retained.
174
175               This attribute cannot be altered once the job has begun  execu‐
176               tion.
177
178       -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
183               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
187               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
191       -L numa_list
192               Defines the NUMA-aware resource  requests  for  NUMA  hardware.
193               This option will work with non-NUMA hardware.
194
195               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
199       -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
205               If the character "n" is specified, no mail will be sent.
206
207               For the letters "a", "b", and "e":
208
209               a    mail is sent when the job is aborted by the batch system.
210
211               b    mail is sent when the job begins execution.
212
213               e    mail is sent when the job terminates.
214
215       -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
219               The user_list argument is of the form:
220                   user[@host][,user[@host],...]
221
222       -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
228       -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
232       -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
240               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
247               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
253               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
258               hostname:path_name
259                      Where  path_name  specifies  an  absolute path name, the
260                      path will be used as specified.
261
262               This attribute can be altered once the job has begun execution,
263               but it will not take affect until the job is rerun.
264
265       -p priority
266               Replaces  the  priority of the job.  The priority argument must
267               be a integer between -1024 and +1023 inclusive.
268
269               This attribute can be altered once the job has begun execution,
270               but it will not take affect until the job is rerun.
271
272       -q      Use an asynchronous (non-blocking alter call to the server.
273
274       -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
278               If  the  argument  is "y", the job is marked rerunable.  If the
279               argument is "n", the job is marked as not rerunable.
280
281       -S path Declares the shell that interprets the job script.
282
283               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
292               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
297               This attribute can be altered once the job has begun execution,
298               but it will not take affect until the job is rerun.
299
300       -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
305               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
309               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
315               qalter 15.napali[] -t %20
316
317               Here, the array 15.napali[] is configured to allow a maximum of
318               20 concurrently running jobs.
319
320               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
324       -u user_list
325               Replaces the user name under which the job is to run on the ex‐
326               ecution system.
327
328               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
335               This attribute cannot be altered once the job has begun  execu‐
336               tion.
337
338       -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
346       -x      Modify the exec_host field of the job.
347
348       -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
357               PBS currently supports the following attributes within  the  -W
358               option.
359
360               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
372                   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
377                   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
382                   after:jobid[:jobid...]
383                       This  job  may  be scheduled for execution at any point
384                       after jobs jobid have started execution.
385
386                   afterok:jobid[:jobid...]
387                       This job may be scheduled for execution only after jobs
388                       jobid have terminated with no errors.
389
390                   afternotok:jobid[:jobid...]
391                       This job may be scheduled for execution only after jobs
392                       jobid have terminated with errors.
393
394                   afterany:jobid[:jobid...]
395                       This job may be scheduled for execution after jobs  jo‐
396                       bid have terminated, with or without errors.
397
398                   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
404                   before:jobid[:jobid...]
405                       When this job has begun execution, then  jobs  jobid...
406                       may begin.
407
408                   beforeok:jobid[:jobid...]
409                       If  this  job terminates execution without errors, then
410                       jobs jobid... may begin.
411
412                   beforenotok:jobid[:jobid...]
413                       If this job terminates execution with errors, then jobs
414                       jobid... may begin.
415
416                   beforeany:jobid[:jobid...]
417                       When  this  job terminates execution, jobs jobid... may
418                       begin.
419
420                       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
424                       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
428                   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
435               group_list=g_list
436               Alters the group name under which the job is to run on the exe‐
437               cution system.
438
439               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
446               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

OPERANDS

459       The  qalter  command accepts one or more job_identifier operands of the
460       form:
461           sequence_number[.server_name][@server]
462

STANDARD ERROR

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

EXIT STATUS

469       Upon successful processing of all the operands presented to the  qalter
470       command, the exit status will be a value of zero.
471
472       If  the  qalter command fails to process any operand, the command exits
473       with a value greater than zero.
474

SEE ALSO

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.
478
479
480
481Local                                                               qalter(1B)
Impressum