xenial (1) qalter.1B.gz

Provided by: torque-client-x11_2.4.16+dfsg-1.5_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.