qalter(1B)

NAME
qalter - alter PBS job

SYNOPSIS
qalter [-a <date and time>] [-A <account string>]
    [-c <checkpoint spec>] [-e <error path>] [-h <hold list>] [-j <join>] [-k <discard>] [-l <resource list>] [-m <mail events>] [-M <user list>] [-N <name>] [-o <output path>] [-p <priority>] [-P <project>] [-r <y|n>] [-S <path list>] [-u <user list>] [-W <additional attributes>] <job ID> [<job ID> ...]
qalter --version

DESCRIPTION
The qalter command is used to alter one or more PBS batch jobs. Each of certain job attributes can be modified using the qalter option for that attribute. Required Privilege
A non-privileged user can alter their own jobs, whether they are queued or running. An Operator or Manager can alter any job, whether it is queued or running. A non-privileged user can only lower resource requests. A Manager or Operator can raise or lower resource requests. Modifying resources and job placement
A Manager or Operator may lower or raise requested resource limits, except for per-process limits such as pcput and pmem, because these are set when the process starts, and enforced by the kernel. A non-privileged user can only lower resource requests. The qalter command cannot be used by a non-privileged user to alter a custom resource which has been created to be invisible or read-only for users. If a job is running, the only resources that can be modified are mppnodes, mppt, cput, walltime, min_walltime, and max_walltime. If a job is queued, any resource mentioned in the options to the qalter command can be modified, but requested modifications must fit within the limits set at the server and queue for the amount of each resource allocated for queued jobs. If a requested modification does not fit within these limits, the modification is rejected. A job's resource request must fit within the queue's and server's resource run limits. If a modification to a resource exceeds the amount of the resource allowed by the queue or server to be used by running jobs, the job is never run. Requesting resources includes setting limits on resource usage and controlling how the job is placed on vnodes. Syntax for Modifying Resources and Job Placement
Resources are modified by using the -l option, either in chunks inside of selection statements, or in job-wide requests using <resource name>=<value> pairs. The selection statement is of the form:

    -l select=[<N>:]<chunk>[+[<N>:]<chunk> ...]

where N specifies how many of that chunk, and a chunk is of the form:

    <resource name>=<value>[:<resource name>=<value> ...]

Job-wide <resource name>=<value> requests are of the form:

    -l <resource name>=<value>[,<resource name>=<value> ...]

The Place Statement
You choose how your chunks are placed using the place statement. The place statement can contain the following elements, in any order:

    -l place=[<arrangement>][:<sharing>][:<grouping>]

where
arrangement
    Whether this chunk is willing to share this vnode or host with other chunks from the same job. One of free | pack | scatter | vscatter

sharing
    Whether this chunk is willing to share this vnode or host with other jobs. One of excl | shared | exclhost

grouping
    Whether the chunks from this job should be placed on vnodes that all have the same value for a resource. Can have only one instance of group=<resource name>

free
    Place job on any vnodes.

pack
    All chunks are taken from one host.

scatter
    Only one chunk with any MPI processes is taken from a host. A chunk with no MPI processes may be taken from the same vnode as another chunk.

vscatter
    Only one chunk is taken from any vnode. Each chunk must fit on a vnode.

excl
    Only this job uses the vnodes chosen.

shared
    This job can share the vnodes chosen.

exclhost
    The entire host is allocated to the job.

group=<resource name>
    Chunks are grouped according to a resource. All vnodes in the group must have a common value for resource, which can be either the built-in resource host or a custom vnode-level resource. The resource name must be a string or a string array.

The place statement cannot begin with a colon. Colons are delimiters; use them only to separate parts of a place statement, unless they are quoted inside resource values. For more on resource requests, usage limits and job placement, see pbs_resources(7B). Modifying Attributes
The user alters job attributes via options to the qalter command. Each qalter option changes a job attribute. See the PBS Professional User's Guide and pbs_job_attributes(7B). The behavior of the qalter command may be affected by any site hooks. Site hooks can modify the job's attributes, change its routing, etc.

Caveats and Restrictions for Altering Jobs
When you lengthen the walltime of a running job, make sure that the new walltime will not interfere with any existing reservations etc. If any of the modifications to a job fails, none of the job's attributes is modified. A job that is in the process of provisioning cannot be altered.

OPTIONS

-a <date and time>
    Changes the point in time after which the job is eligible for execution. Given in pairs of digits. Sets job's Execution_Time attribute to date and time. Format:
    [[[[CC]YY]MM]DD]hhmm[.SS]

    where CC is the century, YY is the year, MM is the month, DD is the day of the month, hh is the hour, mm is the minute, and SS is the seconds. Each portion of the date defaults to the current date, as long as the next-smaller portion is in the future. For example, if today is the 3rd of the month and the specified day DD is the 5th, the month MM is set to the current month. If a specified portion has already passed, the next-larger portion is set to one after the current date. For example, if the day DD is not specified, but the hour hh is specified to be 10:00 a.m. and the current time is 11:00 a.m., the day DD is set to tomorrow. The job's Execution_Time attribute can be altered after the job has begun execution, in which case it will not take effect until the job is rerun.

-A <account string>
    Replaces the accounting string associated with the job. Used for labeling accounting data. Sets job's Account_Name attribute to account string. This attribute cannot be altered once the job has begun execution.
    Format: String

-c <checkpoint spec>
    Changes when the job will be checkpointed. Sets job's Checkpoint attribute. An $action script is required to checkpoint the job. See the pbs_mom(8B) man page. This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

    The argument checkpoint spec can take one of the following values:

    c   Checkpoint at intervals, measured in CPU time, set on job's execution queue. If no interval set at queue, job is not checkpointed.

    c=<minutes of CPU time>
        Checkpoint at intervals of specified number of minutes of job CPU time. This value must be greater than zero. If interval specified is less that that set on job's execution queue, queue's interval is used.
        Format: Integer

    w   Checkpoint at intervals, measured in walltime, set on job's execution queue. If no interval set at queue, job is not checkpointed.

    w=<minutes of walltime>
        Checkpoint at intervals of the specified number of minutes of job walltime. This value must be greater than zero. If the interval specified is less than that set on the job's execution queue, the queue's interval is used.
        Format: Integer

    n   No checkpointing.

    s   Checkpoint only when the server is shut down.

    u   Unset. Defaults to behavior when interval argument is set to s.

    Default: u
    Format: String

-e <error path>
    Replaces the path to be used for the job's standard error stream. Sets job's Error_Path attribute to error path. Overridden by -k option.
    Format:
    [<hostname>:]<path>
    The error path is interpreted as follows:

    path
        If path is relative, it is taken to be relative to the current working directory of the qalter command, where it is executing on the current host. If path is absolute, then it is taken to be an absolute path on the current host where the qalter command is executing.

    hostname:path
        If path is relative, it is taken to be relative to the user's home directory on the host named hostname. If path is absolute, it is the absolute path on the host named hostname.

    If path does not include a filename, the default filename is
        <job ID>.ER
    If the -e option is not specified, PBS writes standard error to the default filename, which has this form:
        <job name>.e<sequence number>
    This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun. If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

-h <hold list>
    Updates the job's hold list. Adds hold list to the job's Hold_Types attribute. The hold list is a string of one or more characters. The following table shows the holds and the privilege required to set each:
    Hold Meaning Who Can Set
    --------------------------------------------------------------

    u   User Job owner, Operator, Manager,
                      administrator, root

    o   Other Operator, Manager, administrator, root

    s   System Manager, administrator, root,
                      PBS (dependency)

    n   None Job owner, Operator, Manager,
                      administrator, root

    p   Bad password Administrator, root

    This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun.

-j <join>
    Changes whether and how to join the job's standard error and standard output streams. Sets job's Join_Path attribute to join.
    This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun. The join argument can take the following values:

    oe  Standard error and standard output are merged into standard output.

    eo  Standard error and standard output are merged into standard error.

    n   Standard error and standard output are not merged.

    Default: n; not merged

-k <discard>
    Changes whether and which of the standard output and standard error streams is left behind on the execution host, and whether they are written to their final destinations. Sets the job's Keep_Files attribute to discard. This attribute cannot be altered once the job has begun execution. In the case where output and/or error is retained on the execution host in a job-specific staging and execution directory created by PBS, these files are deleted when PBS deletes the directory. Default: n; neither is retained, and files are not written to final destinations The discard argument can take the following values:

    e   The standard error stream is retained on the execution host, in the job's staging and execution directory. The filename is:
            <job name>.e<sequence number>

    o   The standard output stream is retained on the execution host, in the job's staging and execution directory. The filename is:
            <job name>.o<sequence number>

    eo, oe
        Both standard output and standard error streams are retained on the execution host, in the job's staging and execution directory.

    d   Output and/or error are written directly to their final destination. Overrides the action of leaving files behind on the execution host.

    n   Neither stream is retained.

-l <resource list>
    Allows the user to change requested resources and job placement. Sets job's Resource_list attribute to resource list. Uses resource request syntax. Requesting a resource places a limit on its usage. Users without manager or operator privilege cannot alter a custom resource which was created to be invisible or read-only for users. For syntax, see Syntax for Modifying Resources and Job Placement above. If a requested modification to a resource would exceed the server's or job queue's limits, the resource request is rejected. Which resources can be altered is system-dependent. If the job was submitted with an explicit "-l select=", vnode-level resources must be qaltered using the "-l select=" form. In this case a vnode level resource <resource> cannot be qaltered with the "-l <resource name>" form. The place statement cannot begin with a colon. For example:
        Submit the job:
        % qsub -l select=1:ncpus=2:mem=512mb jobscript
        Job's ID is 230 qalter the job using "-l <resource name>" form:
        % qalter -l ncpus=4 230
        Error reported by qalter:
        qalter: Resource must only appear in "select" specification when select is used: ncpus 230
        qalter the job using the "-l select=" form:
        % qalter -l select=1:ncpus=4:mem=512mb 230
        No error reported by qalter:
        %
    For more on resource requests, usage limits and job placement, see pbs_resources(7B).

-m <mail events>
    Changes the set of conditions under which mail about the job is sent. Sets job's Mail_Points attribute to mail events. The mail events argument can be either "n" or any combination of "a", "b", and "e".

    n   No mail is sent

    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

    Format: String
    Default: a

-M <user list>
    Alters list of users to whom mail about the job is sent. Sets job's Mail_Users attribute to user list.
    Format:
    <username>[@<hostname>][,<username>[@<hostname>],...]
    Default: job owner

-N <name>
    Renames the job. Sets job's Job_Name attribute to name.
    Format: Job Name (See Formats in the PBS Professional Reference Guide. )
    Default: if a script is used to submit the job, the job's name is the name of the script. If no script is used, the job's name is STDIN .

-o <output path>
    Alters path to be used for the job's standard output stream. Sets job's Output_Path attribute to output path. Overridden by -k option. Format:
    [<hostname>:]<path>
    The output path is interpreted as follows:

    path
        If path is relative, it is taken to be relative to the current working directory of the command, where it is executing on the current host. If path is absolute, it is taken to be an absolute path on the current host where the command is executing.

    hostname:path
        If path is relative, it is taken to be relative to the user's home directory on the host named hostname. If path is absolute, it is the absolute path on the host named hostname. If path does not include a filename, the default filename is
        <job ID>.OU

    If the -o option is not specified, PBS writes standard output to the default filename, which has this form:
        <job name>.o<sequence_number>
    This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun. If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

-p <priority>
    Alters priority of the job. Sets job's Priority attribute to priority. This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun. Format: Host-dependent integer
    Range: [-1024, +1023] inclusive
    Default: Zero

-P <project>
    Specifies a project for the job. Sets job's project attribute to specified value. Format: Project Name (See Formats in the PBS Professional Reference Guide. )
    Default: _pbs_project_default

-r <y|n>
    Changes whether the job is rerunnable. Sets job's Rerunable attribute to the argument. Does not affect how the job is handled when the job is unable to begin execution.
    See the qrerun(1B) command.
    Format: Single character, y or n

    y   Job is rerunnable.

    n   Job is not rerunnable.

    Default: y Interactive jobs are not rerunnable. Job arrays are always rerunnable.

R <remove options>
    Changes whether standard output and/or standard error files are automatically removed upon job completion. Sets job's Remove_Files attribute to remove options. Overrides default path names for these streams. Overrides -o and -e options. This attribute cannot be altered once the job has begun execution. Default: Unset; neither is removed The remove options argument can take the following values:

    e   The standard error stream is removed (deleted) upon job completion

    o   The standard output stream is removed (deleted) upon job completion

    eo, oe
        Both standard error and standard output streams are removed (deleted) upon job completion

    unset
        Neither stream is removed

-S <path list>
    Specifies the interpreter or shell path for the job script. Sets job's Shell_Path_List attribute to path list. The path_list argument is the full path to the interpreter or shell including the executable name. Only one path may be specified without a hostname. Only one path may be specified per named host. The path selected is the one whose hostname is that of the server on which the job resides. This attribute can be altered after the job has begun execution, in which case the new value will not take effect until the job is rerun. Format:

        <path>[@<hostname>][,<path>@<hostname> ...]

    If the path contains spaces, it must be quoted, for example:

        qsub -S "C:Program Files\PBS Pro\bin\pbs_python.exe" <script name>

    Default: User's login shell on execution node Example of using bash via a directive:

        #PBS -S /bin/bash@mars,/usr/bin/bash@jupiter

    Example of using a Python script from the command line on Linux:

        qsub -S $PBS_EXEC/bin/pbs_python <script name>

    Example of using a Python script from the command line on Windows:

        qsub -S PBS_EXEC\bin\pbs_python.exe <script name>

-u <user list>
    Alters list of usernames. Job will be run under a username from this list. Sets job's User_List attribute to user list. Only one username may be specified without a hostname. Only one username may be specified per named host. The server on which the job resides will select first the username whose hostname is the same as the server name. Failing that, the next selection will be the username with no specified hostname. The usernames on the server and execution hosts must be the same. The job owner must have authorization to run as the specified user. This attribute cannot be altered once the job has begun execution. Format:
    <username>[@<hostname>][,<username>@<hostname> ...] Default: Job owner (username on submit host)

-W <additional attributes>
    Each sub-option to the -W option allows you to change a specific job attribute
    Format:
    -W <attribute name>=<value>[,<attribute name>=<value>...] If white space occurs within the additional attributes argument, or the equal sign "=" occurs within an attribute value string, that argument or string must be enclosed with single or double quotes. PBS supports the following attributes via the -W option: depend=<dependency list>

    Defines dependencies between this and other jobs. Sets the job's depend attribute to dependency list. The dependency list has the form:
        <type>:<arg list>[,<type>:<arg list> ...]
    where except for the on type, the arg list is one or more PBS job IDs in the form:
        <job ID>[:<job ID> ...]
    The types and their argument lists can be:

    after: <arg list>
        This job may be scheduled for execution at any point after all jobs in arg list have started execution.

    afterok: <arg list>
        This job may be scheduled for execution only after all jobs in arg list have terminated with no errors. See "Warning about exit status with csh" in EXIT STATUS.

    afternotok: <arg list>
        This job may be scheduled for execution only after all jobs in arg list have terminated with errors. See "Warning about exit status with csh" in EXIT STATUS.

    afterany: <arg list>
        This job may be scheduled for execution after all jobs in arg list have finished execution, with any exit status (with or without errors.) This job will not run if a job in the arg list was deleted without ever having been run.

    before: <arg list>
        Jobs in arg list may begin execution once this job has begun execution.

    beforeok: <arg list>
        Jobs in arg list may begin execution once this job terminates without errors. See "Warning about exit status with csh" in EXIT STATUS.

    beforenotok: <arg list>
        If this job terminates execution with errors, jobs in arg list may begin. See "Warning about exit status with csh" in EXIT STATUS.

    beforeany: <arg list>
        Jobs in arg list may begin execution once this job terminates execution, with or without errors.

    on: count
        This job may be scheduled for execution after count dependencies on other jobs have been satisfied. This type is used in conjunction with one of the before types listed. Count is an integer greater than 0.

    Restrictions
    Job IDs in the arg list of before types must have been submitted with a type of on. To use the before types, the user must have the authority to alter the jobs in arg list. Otherwise, the dependency is rejected and the new job aborted. Error processing of the existence, state, or condition of the job on which the newly submitted job depends is performed after the job is queued. If an error is detected, the new job is deleted by the server. Mail is sent to the job submitter stating the error. Dependency examples:
    qalter -W depend=afterok:123.host1.domain.com /tmp/script
    qalter -W depend=before:234.host1.com:235.host1.com /tmp/script

group_list=<group list>
    Alters list of group names. Job will run under a group name from this list. Sets job's group_List attribute to group list. Only one group name may be specified without a hostname. Only one group name may be specified per named host. The server on which the job resides will select first the group name whose hostname is the same as the server name. Failing that, the next selection will be the group name with no specified hostname. The group names on the server and execution hosts must be the same. Format:
    <group>[@<hostname>][,<group>@<hostname> ...] Default: Login group name of job owner

release_nodes_on_stageout=<value>
    When set to True, all of the job's vnodes not on the primary execution host are released when stageout begins. Cannot be used with vnodes managed by cpuset MoMs, (whose arch is linux_cpuset ), or with vnodes tied to Cray X* series systems. When cgroups is enabled and this is used with some but not all vnodes from one MoM, resources on those vnodes that are part of a cgroup are not released until the entire cgroup is released. The job's stageout attribute must be set for the release_nodes_on_stageout attribute to take effect. Format: Boolean
    Default: False

run_count=<count>
    Sets the number of times the server thinks it has run the job. Sets the job's run_count attribute to count. Can be set while job is running. Job is held when the value of this attribute goes over 20. Format: Integer greater than or equal to zero

sandbox=<sandbox spec>
    Changes which directory PBS uses for the job's staging and execution. Sets job's sandbox attribute to the value of sandbox spec. Format: String Allowed values for sandbox spec:

    PRIVATE
        PBS creates a job-specific directory for staging and execution.

    HOME
        PBS uses the user's home directory for staging and execution.

stagein=<path list>

stageout=<path list>
    Changes files or directories to be staged in before execution or staged out after execution is complete. Sets the job's stagein and stageout attributes to the specified path lists. On completion of the job, all staged-in and staged-out files and directories are removed from the execution host(s). A path list has the form:
    <filespec>[,<filespec>]
    where filespec is
    <execution path>@<hostname>:<storage path>
    regardless of the direction of the copy. The execution path is the name of the file or directory on the primary execution host. It can be relative to the staging and execution directory on the execution host, or it can be an absolute path. The "@" character separates execution path from storage path. The storage path is the path on hostname. The name can be relative to the staging and execution directory on the primary execution host, or it can be an absolute path. If path list has more than one filespec, i.e. it contains commas, it must be enclosed in double quotes. If you use a UNC path, the hostname is optional. If you use a non-UNC path, the hostname is required.

umask=<value>
    Alters the umask with which the job is started. Controls umask of job's standard output and standard error. Sets job's umask attribute to value. Format: One to four digits; typically two Default: 077 The following example allows group and world read of the job's output and error:
    -W umask=33

--version
    The qalter command returns its PBS version information and exits. This option can only be used alone.

OPERANDS
The qalter command accepts a job ID list as its operand. The job ID list is a space-separated list of one or more job IDs for normal jobs or array jobs. Subjobs and ranges of subjobs are not alterable. Job IDs have the form:
<sequence number>[.<server name>][@<server name>]
<sequence number>[][.<server name>][@<server name>] Note that some shells require that you enclose a job array ID in double quotes.

STANDARD ERROR
The qalter command writes a diagnostic message to standard error for each error occurrence.

EXIT STATUS

Zero
    Upon successful processing of input

Greater than zero
    Upon failure

Warning about exit status with csh:
If a job is run in csh and a .logout file exists in the home directory in which the job executes, the exit status of the job is that of the .logout script, not the job script. This may impact any inter-job dependencies.

SEE ALSO
The PBS Professional User's Guide, the PBS Professional Administrator's Guide,
pbs_job_attributes(7B), pbs_resources(7B), qdel(1B), qhold(1B), qmove(1B), qmsg(1B), qrerun(1B), qrls(1B), qselect(1B), qstat(1B), qsub(1B)