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 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 argument syntax is:
- If the month, is not specified, it will default to the
current month if the specified day is in the future. Otherwise, the month
will be set to next month. Likewise, if the day, is not specified, it will
default to today if the time 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 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 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 argument is of the form:
where is the name of a host to which the file will be returned and 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 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: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 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 argument value may be the characters "oe" and
"eo", or the single character "n".
- A argument value of 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 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 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 argument is in the following syntax:
- 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 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 argument is of the form:
- -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 argument is of the form:
where is the name of a host to which the file will be returned and 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 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: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 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 is a single character. PBS
recognizes the following characters: and
- 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 is in the form:
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 option is not specified, the option argument is the
null string, or no entry from the 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 argument is of the form:
Only one user name may be given for per specified host. Only one of the
specifications may be supplied without the corresponding 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 string, then the string must
be enclosed with either single or double quote marks.
- PBS currently supports the following attributes within the
-W option.
-
Redefines the dependencies between this and other jobs. The is in the form:
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: 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.
-
Alters the group name under which the job is to run on the execution
system.
- The argument is of the form:
Only one group name may be given per specified host. Only one of the
specifications may be supplied without the corresponding specification.
That group name will used for execution on any host not named in the
argument list.
-
Alters which files are staged (copied) in before job start or staged out
after the job completes execution. The is in the form:
The name 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 is the destination name on the host specified by 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 operands of the form:
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.
