Provided by: torque-client_2.4.16+dfsg-1.3ubuntu1.1_amd64 bug

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.