Alter batch job.
Synopsis
qalter [-a date_time][-A account_string][-c interval][-e path_name]
[-h hold_list][-j join_list][-k keep_list][-l resource_list]
[-m mail_options][-M mail_list][-n][-N name][-o path_name]
[-p priority][-q ][-r y|n][-S path_name_list][-u user_list]
[-v variable_list][-W additional_attributes]
[-t array_range]
job_identifier ...
Description
The qalter command modifies the attributes of the job or jobs specified by job_identifier on the command line. Only those attributes listed as options on the command will be modified. If any of the specified attributes cannot be modified for a job for any reason, none of that job's attributes will be modified.
The qalter command accomplishes the modifications by sending a Modify Job batch request to the batch server which owns each job.
Options
Option | Name | Description |
---|---|---|
-a | date_time |
Replaces the time at which the job becomes eligible for execution. The date_time argument syntax is: [[[[CC]YY]MM]DD]hhmm[.SS] If the month, MM, is not specified, it will default to the current month if the specified day DD, is in the future. Otherwise, the month will be set to next month. Likewise, if the day, DD, is not specified, it will default to today if the time hhmm is in the future. Otherwise, the day will be set to tomorrow. This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-A | account_string | Replaces the account string associated with the job. This attribute cannot be altered once the job has begun execution. |
-c | checkpoint_interval |
Replaces the interval at which the job will be checkpointed. If the job executes upon a host which does not support checkpointing, this option will be ignored. The interval argument is specified as:
This value must be greater than zero. If the number is less than the default checkpoint time, the default time will be used. This attribute can be altered once the job has begun execution, but the new value does not take effect unless the job is rerun. |
-e | path_name |
Replaces the path to be used for the standard error stream of the batch job. The path argument is of the form: [hostname:]path_name where hostname is the name of a host to which the file will be returned and path_name is the path name on that host in the syntax recognized by POSIX 1003.1. The argument will be interpreted as follows:
This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-h | hold_list |
Updates the the types of holds on the job. The hold_list argument is a string of one or more of the following characters:
This attribute can be altered once the job has begun execution, but the hold will not take effect unless the job is rerun. |
-j | join |
Declares which standard streams of the job will be merged together. The join argument value may be the characters "oe" and "eo", or the single character "n". A argument value of oe directs that the standard output and standard error streams of the job will be merged, intermixed, and returned as the standard output. A argument value of eo directs that the standard output and standard error streams of the job will be merged, intermixed, and returned as the standard error. A value of n directs that the two streams will be two separate files. This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-k | keep |
Defines which if either of standard output or standard error of the job will be retained on the execution host. If set for a stream, this option overrides the path name for that stream. The argument is either the single letter "e", "o", or "n", or one or more of the letters "e" and "o" combined in either order.
job_name.esequence where job_name is the name specified for the job, and sequence is the sequence number component of the job identifier. job_name.osequence where job_name is the name specified for the job, and sequence is the sequence number component of the job identifier. This attribute cannot be altered once the job has begun execution. |
-l | resource_list |
Modifies the list of resources that are required by the job. The resource_list argument is in the following syntax: resource_name[=[value]][,resource_name[=[value]],...] If a requested modification to a resource would exceed the resource limits for jobs in the current queue, the server will reject the request. If the job is running, only certain resources can be altered. Which resources can be altered in the run state is system dependent. A user may only lower the limit for those resources. |
-m | mail_options |
Replaces the set of conditions under which the execution server will send a mail message about the job. The mail_options argument is a string which consists of the single character "n", or one or more of the characters "a", "b", and "e". If the character "n" is specified, no mail will be sent. For the letters "a", "b", and "e":
|
-M | user_list |
Replaces the list of users to whom mail is sent by the execution server when it sends mail about the job. The user_list argument is of the form: user[@host][,user[@host],...] |
-n | node-exclusive |
Sets or unsets exclusive node allocation on a job. Use the y and n options to enable or disable the feature. This affects only cpusets and compatible schedulers. > qalter ... -n y #enables exclusive node allocation on a job > qalter ... -n n #disables exclusive node allocation on a job |
-N | name | Renames the job. The name specified may be up to and including 15 characters in length. It must consist of printable, non white space characters with the first character alphabetic. |
-o | path |
Replaces the path to be used for the standard output stream of the batch job. The path argument is of the form: [hostname:]path_name where hostname is the name of a host to which the file will be returned and path_name is the path name on that host in the syntax recognized by POSIX. The argument will be interpreted as follows:
This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-p | priority |
Replaces the priority of the job. The priority argument must be a integer between -1024 and +1023 inclusive. This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-r | [y/n] |
Declares whether the job is rerunable (see the qrerun command). The option argument c is a single character. PBS recognizes the following characters: y and n. If the argument is "y", the job is marked rerunable. If the argument is "n", the job is marked as not rerunable. |
-S | path |
Declares the shell that interprets the job script. The option argument path_list is in the form: path[@host][,path[@host],...] Only one path may be specified for any host named. Only one path may be specified without the corresponding host name. The path selected will be the one with the host name that matched the name of the execution host. If no matching host is found, then the path specified (without a host) will be selected. If the -S option is not specified, the option argument is the null string, or no entry from the path_list is selected, the execution will use the login shell of the user on the execution host. This attribute can be altered once the job has begun execution, but it will not take effect unless the job is rerun. |
-t | array_range |
The array_range argument is an integer id or a range of integers. Multiple ids or id ranges can be combined in a comma delimted list. Examples: -t 1-100 or -t 1,10,50-100 If an array range isn't specified, the command tries to operate on the entire array. The command acts on the array (or specified range of the array) just as it would on an individual job. An optional "slot limit" can be specified to limit the amount of jobs that can run concurrently in the job array. The default value is unlimited. The slot limit must be the last thing specified in the array_request and is delimited from the array by a percent sign (%). qalter weatherSimulationArray[] -t %20 Here, the array weatherSimulationArray[] is configured to allow a maximum of 20 concurrently running jobs. Slot limits can be applied at job submit time with qsub, or can be set in a global server parameter policy with max_slot_limit. |
-u | user_list |
Replaces the user name under which the job is to run on the execution system. The user_list argument is of the form: user[@host][,user[@host],...] Only one user name may be given for per specified host. Only one of the user specifications may be supplied without the corresponding host specification. That user name will be used for execution on any host not named in the argument list. This attribute cannot be altered once the job has begun execution. |
-W | additional_attributes |
The -W option allows for the modification of additional job attributes. Note if white space occurs anywhere within the option argument string or the equal sign, "=", occurs within an attribute_value string, then the string must be enclosed with either single or double quote marks. To see the attributes PBS currently supports within the -W option, see Table A-1: -W additional_attributes. |
Table A-1: -W additional_attributes
Attribute | Description |
---|---|
depend=dependency_list |
Redefines the dependencies between this and other jobs. The dependency_list is in the form: type[:argument[:argument...][,type:argument...] The argument is either a numeric count or a PBS job id accord ing to type. If argument is a count, it must be greater than 0. If it is a job id and is not fully specified in the form: seq_number.server.name, it will be expanded according to the default server rules. If argument is null (the preceding colon need not be specified), the dependency of the corresponding type is cleared (unset).
If any of the before forms are used, the job referenced by jobid must have been submitted with a dependency type of on. If any of the before forms are used, the jobs referenced by jobid must have the same owner as the job being altered. Otherwise, the dependency will not take effect. Error processing of the existence, state, or condition of the job specified to qalter is a deferred service, i.e. the check is performed after the job is queued. If an error is detected, the job will be deleted by the server. Mail will be sent to the job submitter stating the error. |
group_list=g_list |
Alters the group name under which the job is to run on the execution system. The g_list argument is of the form: group[@host][,group[@host],...] Only one group name may be given per specified host. Only one of the group specifications may be supplied without the corresponding host specification. That group name will used for execution on any host not named in the argument list. |
stagein=file_list stageout=file_list |
Alters which files are staged (copied) in before job start or staged out after the job completes execution. The file_list is in the form: local_file@hostname:remote_file[,...] The name local_file is the name on the system where the job executes. It may be an absolute path or a path relative to the home directory of the user. The name remote_file is the destination name on the host specified by hostname. The name may be absolute or relative to the users home directory on the destination host. |
Operands
The qalter command accepts one or more job_identifier operands of the form:
sequence_number[.server_name][@server]
Standard error
Any error condition, either in processing the options or the operands, or any error received in reply to the batch requests will result in an error message being written to standard error.
Exit status
Upon successful processing of all the operands presented to the qalter command, the exit status will be a value of zero.
If the qalter command fails to process any operand, the command exits with a value greater than zero.
Copyright
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright © 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
Related topics
Non-Adaptive Computing topics