qalter(1)

NAME
qalter - alter a job in the DQS queuing system

SYNTAX
qalter [-options] [script]

DESCRIPTION
qalter alters queued, but not yet scheduled jobs in the DQS queuing system. DQS flags may be entered as arguments to qalter or as embedded flags in the shell script.

-a date_time

                  The time at which a job is
                  eligble for execution.
                  Data_time conforms to the
                  following:
                  [[CC]YY]MMDDhhmm where:

-A account_list
                  Account_list to which to charge
                  the job.

-cell cell_name
                  The cell to which the request
                  is forwarded.

-clean
                  Start from scratch with resources
           args, etc.

-cwd
                  Specifies to use the current working
                  directory at job exec time.

-C Defines the prefix that declares a
                  directive to qalter. The prefix is not
                  a job attribute, but affects the
                  behavior of qalter. If the -C option
                  is presented with the value of the
                  directive prefix as a null string,
                  qalter will not scan the scriptfile

-e path_list The path used for standard error stream
                  of the job with the following form:

                  [hostname1:]/usr[,hostname2:]/tmp,...]

                  If the path-list option -argument
                  constitutes an absolute path name,
                  the error-path attribute of the job is
                  set to the value of the path_list
                  option argument, including the hostname,
                  if present.

                  By default the file name for standard error
                  has the following form:
                    job_name.esequence_number

-hard Specifies that subsequent resource
                  requests must be satisfied in full
                  before a job is to be scheduled.

-help Prints a listing of all options.

-hold hold_list List of holds to place on job.
                  `u' `s' `o' `n'

-j y||n Specifies whether or not the standard
                  error stream of the job is merged into
                  the standard output stream.

                  If both the -j y and the -e options
                  are present, DQS sets, but ignores
                  the error-path attribute.

-jid jid jid to apply qalter to.

-l resource_list Defines the resources required by
                   the job.
                   Resource_list is of the form:
    resource[.op.resource_field][,resource[.op.resource_field],...]

-master destination_identifier,...
                   Defines the queue to serve as the master
                   for said job. destination_identifier
                   is of the form:
                       queue
                       @cell
                       queue@cell

                   DQS will attempt to assign the master
                   based on a first to last tranversal
                   of the destination_identifier_list,
                   DQS will assign a master as available.

-m mail_options Redefines the points in the execution of the job
                   at which the server will send mail about a state change.

                       e MAIL_AT_EXIT
                       b MAIL_AT_BEGINNING
                       a MAIL_AT_ABORT
                       s MAIL_AT_SUSPENSION
                       n NO_MAIL

-M Mail_list       list of users to send mail to.

-notify
                   Specifies that the job should be signaled
                   via a SIGUSR1 on an impending SIGSTOP and
                   the SIGUSR2 on an impending SIGKILL.

-N name The name of a specific job. The name
                   can be any printable set of characters
                   up to 8 chars long. Names in excess of
                   8 characters will be truncated.

-par par_package Parallel package to instantiate.

-o path_list The pathname for standard output.
                   For example:
                    -e hostname:/user/users/green/aix
                    -e hostname:aix
                   The default file name for standard output
                   has the following form:

                        job_name.osequence_number

-p priority Specifies priority of job relative
                   to other jobs. Priority is an integer
                   in the range -1024 to 1024.

-passwd Specifies that a password list will
                   be requested for AFS and or DFS
                   reauthentication. If given, DQS
                   shall utilize the password list to
                   authenticate prior to executing the job
                   and reauthenticate as necessary.
                   Qalter prompts for password(s) to be
                   entered interactivly until CTRL-D
                   is entered and is of the format:
                      password[@cell]

-passwd_file filename
                   The name of the file in which the
                   password(s) reside. Entries in the
                   file will be in the format:
                     password[@cell]
                     password[@cell]
                     ...

-q destination_identifier_list

                   Destination_id is not a job
                   attribute it determines the queue,
                   server or queue at a server to which
                   the job is queued.
                   The destination_id list option argument
                   conforms to the following:
     destination_id[@cell][,destination_id[@cell],...]

-r y||n
                   Identifies the ability of a job to be
                   rerun or not. If the -r option is not
                   presented qalter, jobs are not rerun.

-soft Specifies that subsequent resource and
                   destination identifiers are to be filled
                   on an "as available" basis.

-rc consumable=amount

                   Returns the specified amount of named consumable.
                   During the job execution the qalter utility may be
                   executed to modify one job attribute only, the amount
                   of a named consumable resource.

-reauth seconds Specifies the interval in which to
                   reauthenticate.

-S path_list Specifies the interpreting shell.
                   Path_list has the following syntax:
                   pathname[@host][,pathname[@host],...]
                   The qalter only allows one path name for
                   a given host.

-u user_list Specifies the user name or access list.
                   User_list has the following syntax:

                   user_name[@host}[,user_name[@host],...]
                   Qalter only allows one user name for a
                   given host.

-v variable_list Defines the environmental variables to
                   be exported. A variable list is a set
                   of strings delimited by commas of either
                   the form:
                   < variable > or
                   < variable = value >

-verify Causes DQS to print request to stdout.
                   No action taken.

-V Specifies that all environmental
                   variables be exported to the
                   context of the job.

-z Specifies that qalter should not write the
                   job identifier to the standard output. script If the script operand is not present
                   to qalter, or if the operand is the
                   single-character string '-', qalter reads
                   the script from standard input.

Environmental Variables:

    DQS_CELL If set, specifies the default DQS cell.
    DQS_DEBUG If set, specifies that debug information
                    should be written to stderr.
    DQS_EXT_DEBUG If set, specifies that extended debug
                    information should be written to stderr.

SCHEDULING
The qmaster uses a stingy algorithm for the scheduler. It will attempt to allocate queues on a first come first served basis. If all the hard requests for a job cannot be met, the scheduler will proceed until a runnable job(s) can be found.(Jobs which cannot be run remained spooled.)

Example
The following is a short example of a DQS script file.
=====================================================
#!/bin/csh
#$ -l qty.eq.1      # I want 1 queue
   a.out
The following is a more complex DQS script.
=====================================================
#!/bin/csh

# Which account to be charged cpu time
#$ -account green@foo
#$ -cell scri
#Which pvm is the master host
#$ -master ibm1,ibm2,ibm
# date-time to run, format [[CC]yy]MMDDhhmm[.SS]
#$ -a 12241200
# I want 6 or more machines of group ibm
# with memory greater than 128M, that has pvm
#$ -l qty.gt.6,mem.gt.128,group.eq.ibm,pvm
# If I can get it, I would also like 1 machine
# with memory greater than 256M of group dec
#$ -soft -l qty.eq.1,mem.gt.256,group.eq.dec
# If I run on ibm1 pub stderr in /usr/foo, if I
# run on ibm2, pub stderr in /usr/green/foo
#$ -e /usr/foo@ibm1,/usrgreen/foo@ibm2
# Send mail to these users
#$ -M green@scri.fsu.edu,pasko@scri
# Mail at beginning/end/on suspension
#$ -m bes
# Export these environmental variables
#$ -v PATH,PWD,FOOBAR=BAR
# The job is located in the current
# working directory.
#$ -cwd
a.out
==========================================================
The name of the environment variable is the current name
prefixed with the string {DQS_O_}.
In addition to the variables dsecribed above, qalter
adds the following variables with the indicated values to the variable
list:
  DQS_O_WORKDIR - the absolute path of the current working directory
                  of qalter process.

  DQS_O_HOST    - the name of the host on which qalter is running.

SEE ALSO
qalter(l), qconf(l), qmod(l), qdel(l), qstat(l), qmon(l), qidle(l), qrls(l)