qalter Manual Page
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 modi-
fied 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 speci-
fied, 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 fol-
lows:
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
reservered to the batch administrator.]
o Add the OTHER (or OPERATOR ) type hold if the
user has the appropriate level of privilege.
[Typically reservered to the batch administra-
tor 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 stan-
dard error of the job will be retained on the execu-
tion host. If set for a stream, this option over-
rides 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 com-
ponent 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 identif-
ier.
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 fol-
lowing 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 exe-
cution 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 con-
sist 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 host-
name.
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 argu-
ment 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 specifica-
tion. 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 addi-
tional 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 accord-
ing to the default server rules. If argument is
null (the preceeding colon need not be specified),
the dependency of the cooresponding 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 exe-
cution.
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 con-
junction 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 existance, state, or
condition of the job on which the newly submit-
ted 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 execu-
tion. 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 abso-
lute 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 the qalter command, the exit status will be a value of
zero.
If the qalter command fails to process any operand, the com-
mand 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.
|