Provided by: torque-client_2.4.16+dfsg-1.3ubuntu1.1_amd64 
NAME
qalter - alter pbs batch job
SYNOPSIS
qalter [-a date_time] [-A account_string] [-c interval] [-e path] [-h hold_list] [-j join]
[-k keep] [-l resource_list] [-m mail_options] [-M user_list] [-N name] [-o path] [-p
priority] [-r c] [-S path] [-u user_list] [-W additional_attributes] 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
-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 affect until the job is rerun.
-A account_string
Replaces the the account string associated with the job.
This attribute cannot be altered once the job has begun execution.
-c interval
Replaces the the interval at which the job will be checkpointed. If the job
executes upon a host which does not support checkpoint, this option will be
ignored.
The interval argument is specified as:
n No checkpointing is to be performed.
s Checkpointing is to be performed only when the server executing the job is
shutdown.
c Checkpointing is to be performed at the default minimum cpu time for the queue
from which the job is executing.
c=minutes
Checkpointing is to be performed at an interval of minutes, which is the
integer number of minutes of CPU time used by the job. 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 affect until the job is rerun.
-e path Replaces the 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:
path_name
Where path_name is not an absolute path name, then the qalter command will
expand the path name relative to the current working directory of the
command. The command will supply the name of the host upon which it is
executing for the hostname component.
hostname:path_name
Where path_name is not an absolute path name, then the qalter command will
not expand the path name. The execution server will expand it relative to
the home directory of the user on the system specified by hostname.
path_name
Where path_name specifies an absolute path name, then qalter will supply
the name of the host on which it is executing for the hostname.
hostname:path_name
Where path_name specifies an absolute path name, the path will be used as
specified.
This attribute can be altered once the job has begun execution, but it will not
take affect until 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:
u Add the USER type hold.
s Add the SYSTEM type hold if the user has the appropriate level of privilege.
[Typically reserved to the batch administrator.]
o Add the OTHER (or OPERATOR ) type hold if the user has the appropriate level
of privilege. [Typically reserved to the batch administrator and batch
operator.]
n Set to none; that is clear the hold types which could be applied with the
users level of privilege.
Repetition of characters is permitted, but "n" may not appear in the same option
argument with the other three characters. This attribute can be altered once the
job has begun execution, but the hold will not take affect until 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
affect until 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.
n No streams are to be retained.
e The standard error stream is to retained on the execution host. The stream
will be placed in the home directory of the user under whose user id the job
executed. The file name will be the default file name given by:
job_name.esequence where job_name is the name specified for the job, and
sequence is the sequence number component of the job identifier.
o The standard output stream is to be retained on the execution host. The
stream will be placed in the home directory of the user under whose user id
the job executed. The file name will be the default file name given by:
job_name.osequence where job_name is the name specified for the job, and
sequence is the sequence number component of the job identifier.
eo Both the standard output and standard error streams will be retained.
oe Both the standard output and standard error streams will be retained.
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":
a mail is sent when the job is aborted by the batch system.
b mail is sent when the job begins execution.
e mail is sent when the job terminates.
-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 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:
path_name
Where path_name is not an absolute path name, then the qalter command will
expand the path name relative to the current working directory of the
command. The command will supply the name of the host upon which it is
executing for the hostname component.
hostname:path_name
Where path_name is not an absolute path name, then the qalter command will
not expand the path name. The execution server will expand it relative to
the home directory of the user on the system specified by hostname.
path_name
Where path_name specifies an absolute path name, then the qalter will
supply the name of the host on which it is executing for the hostname.
hostname:path_name
Where path_name specifies an absolute path name, the path will be used as
specified.
This attribute can be altered once the job has begun execution, but it will not
take affect until 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 affect until the job is rerun.
-r c 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 if present 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 affect until the job is rerun.
-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. The
general syntax of the -W is in the form:
-W attr_name=value[,attr_name=value...]
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.
PBS currently supports the following attributes within the -W option.
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 according 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).
synccount:count
This job is the first in a set of jobs to be executed at the same time.
Count is the number of additional jobs in the set.
syncwith:jobid
This job is an additional member of a set of jobs to be executed at the
same time. Jobid is the job identifier of the first job in the set.
after:jobid[:jobid...]
This job may be scheduled for execution at any point after jobs jobid have
started execution.
afterok:jobid[:jobid...]
This job may be scheduled for execution only after jobs jobid have
terminated with no errors.
afternotok:jobid[:jobid...]
This job may be scheduled for execution only after jobs jobid have
terminated with errors.
afterany:jobid[:jobid...]
This job may be scheduled for execution after jobs jobid have terminated,
with or without errors.
on:count
This job may be scheduled for execution after count dependencies on other
jobs have been satisfied. This form is used in conjunction with one of
the before forms, see below.
before:jobid[:jobid...]
When this job has begun execution, then jobs jobid... may begin.
beforeok:jobid[:jobid...]
If this job terminates execution without errors, then jobs jobid... may
begin.
beforenotok:jobid[:jobid...]
If this job terminates execution with errors, then jobs jobid... may
begin.
beforeany:jobid[:jobid...]
When this job terminates execution, jobs jobid... may begin.
If any of the before forms are used, the job referenced by jobid must have
been submitted with a dependency type of on.
The job specified in any of the before forms 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 on which the
newly submitted job is a deferred service, i.e. the check is performed after
the job is queued. If an error is detected, the new 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 user's 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 a 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.
SEE ALSO
qsub(1B), qstat(1B), pbs_alterjob(3B), pbs_statjob(3B), pbs_selectjob(3B),
pbs_resources_*(7B), where * is system type, and the PBS ERS.