path: root/man-pages-posix-2003/man1p/qalter.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "QALTER" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" qalter 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
qalter \- alter batch job
.SH SYNOPSIS
.LP
\fBqalter\fP \fB[\fP\fB-a\fP \fIdate_time\fP\fB][\fP\fB-A\fP
\fIaccount_string\fP\fB][\fP\fB-c\fP \fIinterval\fP\fB][\fP\fB-e\fP
\fIpath_name\fP\fB]
.br
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-h\fP \fIhold_list\fP\fB][\fP\fB-j\fP
\fIjoin_list\fP\fB][\fP\fB-k\fP \fIkeep_list\fP\fB][\fP\fB-l\fP \fIresource_list\fP\fB]
.br
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-m\fP \fImail_options\fP\fB][\fP\fB-M\fP
\fImail_list\fP\fB][\fP\fB-N\fP \fIname\fP\fB][\fP\fB-o\fP \fIpath_name\fP\fB]
.br
\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-p\fP \fIpriority\fP\fB][\fP\fB-r\fP
\fIy\fP\fB|\fP\fIn\fP\fB][\fP\fB-S\fP \fIpath_name_list\fP\fB][\fP\fB-u\fP
\fIuser_list\fP\fB]
.br
\fP \fB\ \ \ \ \ \ \fP \fB\fP\fIjob_identifier\fP \fB... \fP
.SH DESCRIPTION
.LP
The attributes of a batch job are altered by a request to the batch
server that manages the batch job. The \fIqalter\fP utility
is a user-accessible batch client that requests the alteration of
the attributes of one or more batch jobs.
.LP
The \fIqalter\fP utility shall alter the attributes of those batch
jobs, and only those batch jobs, for which a batch
\fIjob_identifier\fP is presented to the utility.
.LP
The \fIqalter\fP utility shall alter the attributes of batch jobs
in the order in which the batch \fIjob_identifier\fPs are
presented to the utility.
.LP
If the \fIqalter\fP utility fails to process a batch \fIjob_identifier\fP
successfully, the utility shall proceed to process
the remaining batch \fIjob_identifier\fPs, if any.
.LP
For each batch \fIjob_identifier\fP for which the \fIqalter\fP utility
succeeds, each attribute of the identified batch job
shall be altered as indicated by all the options presented to the
utility.
.LP
For each identified batch job for which the \fIqalter\fP utility fails,
the utility shall not alter any attribute of the batch
job.
.LP
For each batch job that the \fIqalter\fP utility processes, the utility
shall not modify any attribute other than those
required by the options and option-arguments presented to the utility.
.LP
The \fIqalter\fP utility shall alter batch jobs by sending a \fIModify
Job Request\fP to the batch server that manages each
batch job. At the time the \fIqalter\fP utility exits, it shall have
modified the batch job corresponding to each successfully
processed batch \fIjob_identifier\fP. An attempt to alter the attributes
of a batch job in the RUNNING state is
implementation-defined.
.SH OPTIONS
.LP
The \fIqalter\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported by the implementation:
.TP 7
\fB-a\ \fP \fIdate_time\fP
Redefine the time at which the batch job becomes eligible for execution.
.LP
The \fIdate_time\fP argument shall be in the same form and represent
the same time as for the \fItouch\fP utility. The time so represented
shall be set into the \fIExecution_Time\fP attribute
of the batch job. If the time specified is earlier than the current
time, the \fB-a\fP option shall have no effect.
.TP 7
\fB-A\ \fP \fIaccount_string\fP
.sp
Redefine the account to which the resource consumption of the batch
job should be charged. 
.LP
The syntax of the \fIaccount_string\fP option-argument is unspecified.
.LP
The \fIqalter\fP utility shall set the \fIAccount_Name\fP attribute
of the batch job to the value of the \fIaccount_string\fP
option-argument.
.TP 7
\fB-c\ \fP \fIinterval\fP
Redefine whether the batch job should be checkpointed, and if so,
how often. 
.LP
The \fIqalter\fP utility shall accept a value for the interval option-argument
that is one of the following:
.TP 7
\fBn\fP
.RS
No checkpointing is to be performed on the batch job (NO_CHECKPOINT).
.RE
.TP 7
\fBs\fP
.RS
Checkpointing is to be performed only when the batch server is shut
down (CHECKPOINT_AT_SHUTDOWN).
.RE
.TP 7
\fBc\fP
.RS
Automatic periodic checkpointing is to be performed at the \fIMinimum_Cpu_Interval\fP
attribute of the batch queue, in units
of CPU minutes (CHECKPOINT_AT_MIN_CPU_INTERVAL).
.RE
.TP 7
\fBc\fP=\fIminutes\fP
.RS
Automatic periodic checkpointing is to be performed every \fIminutes\fP
of CPU time, or every \fIMinimum_Cpu_Interval\fP
minutes, whichever is greater. The \fIminutes\fP argument shall conform
to the syntax for unsigned integers and shall be greater
than zero.
.RE
.sp
.LP
An implementation may define other checkpoint intervals. The conformance
document for an implementation shall describe any
alternative checkpoint intervals, how they are specified, their internal
behavior, and how they affect the behavior of the
utility.
.LP
The \fIqalter\fP utility shall set the \fICheckpoint\fP attribute
of the batch job to the value of the \fIinterval\fP
option-argument.
.TP 7
\fB-e\ \fP \fIpath_name\fP
Redefine the path to be used for the standard error stream of the
batch job. 
.LP
The \fIqalter\fP utility shall accept a \fIpath_name\fP option-argument
that conforms to the syntax of the \fIpath_name\fP
element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
which can be preceded by a host name element of
the form \fIhostname\fP:.
.LP
If the \fIpath_name\fP option-argument constitutes an absolute pathname,
the \fIqalter\fP utility shall set the
\fIError_Path\fP attribute of the batch job to the value of the \fIpath_name\fP
option-argument, including the host name element,
if present.
.LP
If the \fIpath_name\fP option-argument constitutes a relative pathname
and no host name element is specified, the \fIqalter\fP
utility shall set the \fIError_Path\fP attribute of the batch job
to the value of the absolute pathname derived by expanding the
\fIpath_name\fP option-argument relative to the current directory
of the process that executes the \fIqalter\fP utility.
.LP
If the \fIpath_name\fP option-argument constitutes a relative pathname
and a host name element is specified, the \fIqalter\fP
utility shall set the \fIError_Path\fP attribute of the batch job
to the value of the option-argument without expansion.
.LP
If the \fIpath_name\fP option-argument does not include a host name
element, the \fIqalter\fP utility shall prefix the
pathname in the \fIError_Path\fP attribute with \fIhostname\fP:, where
\fIhostname\fP is the name of the host upon which the
\fIqalter\fP utility is being executed.
.TP 7
\fB-h\ \fP \fIhold_list\fP
Redefine the types of holds, if any, on the batch job. The \fIqalter\fP
\fB-h\fP option shall accept a value for the
\fIhold_list\fP option-argument that is a string of alphanumeric characters
in the portable character set. 
.LP
The \fIqalter\fP utility shall accept a value for the \fIhold_list\fP
option-argument that is a string of one or more of the
characters \fB'u'\fP, \fB's'\fP, or \fB'o'\fP, or the single character
\fB'n'\fP . For each unique character in the
\fIhold_list\fP option-argument, the \fIqalter\fP utility shall add
a value to the \fIHold_Types\fP attribute of the batch job
as follows, each representing a different hold type:
.TP 7
\fBu\fP
.RS
USER
.RE
.TP 7
\fBs\fP
.RS
SYSTEM
.RE
.TP 7
\fBo\fP
.RS
OPERATOR
.RE
.sp
.LP
If any of these characters are duplicated in the \fIhold_list\fP option-argument,
the duplicates shall be ignored. An existing
\fIHold_Types\fP attribute can be cleared by the hold type:
.TP 7
\fBn\fP
.RS
NO_HOLD
.RE
.sp
.LP
The \fIqalter\fP utility shall consider it an error if any hold type
other than \fB'n'\fP is combined with hold type
\fB'n'\fP . Strictly conforming applications shall not repeat any
of the characters \fB'u'\fP, \fB's'\fP, \fB'o'\fP,
or \fB'n'\fP within the \fIhold_list\fP option-argument. The \fIqalter\fP
utility shall permit the repetition of characters,
but shall not assign additional meaning to the repeated characters.
An implementation may define other hold types. The conformance
document for an implementation shall describe any additional hold
types, how they are specified, their internal behavior, and how
they affect the behavior of the utility.
.TP 7
\fB-j\ \fP \fIjoin_list\fP
Redefine which streams of the batch job are to be merged. The \fIqalter\fP
\fB-j\fP option shall accept a value for the
\fIjoin_list\fP option-argument that is a string of alphanumeric characters
in the portable character set. 
.LP
The \fIqalter\fP utility shall accept a \fIjoin_list\fP option-argument
that consists of one or more of the characters
\fB'e'\fP and \fB'o'\fP, or the single character \fB'n'\fP .
.LP
All of the other batch job output streams specified shall be merged
into the output stream represented by the character listed
first in the \fIjoin_list\fP option-argument.
.LP
For each unique character in the \fIjoin_list\fP option-argument,
the \fIqalter\fP utility shall add a value to the
\fIJoin_Path\fP attribute of the batch job as follows, each representing
a different batch job stream to join:
.TP 7
\fBe\fP
.RS
The standard error of the batch job (JOIN_STD_ERROR).
.RE
.TP 7
\fBo\fP
.RS
The standard output of the batch job (JOIN_STD_OUTPUT).
.RE
.sp
.LP
An existing \fIJoin_Path\fP attribute can be cleared by the join type:
.TP 7
\fBn\fP
.RS
NO_JOIN
.RE
.sp
.LP
If \fB'n'\fP is specified, then no files are joined. The \fIqalter\fP
utility shall consider it an error if any join type
other than \fB'n'\fP is combined with join type \fB'n'\fP .
.LP
Strictly conforming applications shall not repeat any of the characters
\fB'e'\fP, \fB'o'\fP, or \fB'n'\fP within the
\fIjoin_list\fP option-argument. The \fIqalter\fP utility shall permit
the repetition of characters, but shall not assign
additional meaning to the repeated characters.
.LP
An implementation may define other join types. The conformance document
for an implementation shall describe any additional
batch job streams, how they are specified, their internal behavior,
and how they affect the behavior of the utility.
.TP 7
\fB-k\ \fP \fIkeep_list\fP
Redefine which output of the batch job to retain on the execution
host. 
.LP
The \fIqalter\fP \fB-k\fP option shall accept a value for the \fIkeep_list\fP
option-argument that is a string of
alphanumeric characters in the portable character set.
.LP
The \fIqalter\fP utility shall accept a \fIkeep_list\fP option-argument
that consists of one or more of the characters
\fB'e'\fP and \fB'o'\fP, or the single character \fB'n'\fP .
.LP
For each unique character in the \fIkeep_list\fP option-argument,
the \fIqalter\fP utility shall add a value to the
\fIKeep_Files\fP attribute of the batch job as follows, each representing
a different batch job stream to keep:
.TP 7
\fBe\fP
.RS
The standard error of the batch job (KEEP_STD_ERROR).
.RE
.TP 7
\fBo\fP
.RS
The standard output of the batch job (KEEP_STD_OUTPUT).
.RE
.sp
.LP
If both \fB'e'\fP and \fB'o'\fP are specified, then both files are
retained. An existing \fIKeep_Files\fP attribute can
be cleared by the keep type:
.TP 7
\fBn\fP
.RS
NO_KEEP
.RE
.sp
.LP
If \fB'n'\fP is specified, then no files are retained. The \fIqalter\fP
utility shall consider it an error if any keep type
other than \fB'n'\fP is combined with keep type \fB'n'\fP .
.LP
Strictly conforming applications shall not repeat any of the characters
\fB'e'\fP, \fB'o'\fP, or \fB'n'\fP within the
\fIkeep_list\fP option-argument. The \fIqalter\fP utility shall permit
the repetition of characters, but shall not assign
additional meaning to the repeated characters. An implementation may
define other keep types. The conformance document for an
implementation shall describe any additional keep types, how they
are specified, their internal behavior, and how they affect the
behavior of the utility.
.TP 7
\fB-l\ \fP \fIresource_list\fP
.sp
Redefine the resources that are allowed or required by the batch job.
.LP
The \fIqalter\fP utility shall accept a \fIresource_list\fP option-argument
that conforms to the following syntax:
.sp
.RS
.nf

\fBresource=value[,,resource=value,,...]
\fP
.fi
.RE
.LP
The \fIqalter\fP utility shall set one entry in the value of the \fIResource_List\fP
attribute of the batch job for each
resource listed in the \fIresource_list\fP option-argument.
.LP
Because the list of supported resource names might vary by batch server,
the \fIqalter\fP utility shall rely on the batch
server to validate the resource names and associated values. See \fIMultiple
Keyword-Value
Pairs\fP for a means of removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@
\fIkeyword\fP) pairs and other general rules
for list-oriented batch job attributes.
.TP 7
\fB-m\ \fP \fImail_options\fP
.sp
Redefine the points in the execution of the batch job at which the
batch server is to send mail about a change in the state of the
batch job. 
.LP
The \fIqalter\fP \fB-m\fP option shall accept a value for the \fImail_options\fP
option-argument that is a string of
alphanumeric characters in the portable character set.
.LP
The \fIqalter\fP utility shall accept a value for the \fImail_options\fP
option-argument that is a string of one or more of
the characters \fB'e'\fP, \fB'b'\fP, and \fB'a'\fP, or the single
character \fB'n'\fP . For each unique character in
the \fImail_options\fP option-argument, the \fIqalter\fP utility shall
add a value to the \fIMail_Users\fP attribute of the
batch job as follows, each representing a different time during the
life of a batch job at which to send mail:
.TP 7
\fBe\fP
.RS
MAIL_AT_EXIT
.RE
.TP 7
\fBb\fP
.RS
MAIL_AT_BEGINNING
.RE
.TP 7
\fBa\fP
.RS
MAIL_AT_ABORT
.RE
.sp
.LP
If any of these characters are duplicated in the \fImail_options\fP
option-argument, the duplicates shall be ignored.
.LP
An existing \fIMail_Points\fP attribute can be cleared by the mail
type:
.TP 7
\fBn\fP
.RS
NO_MAIL
.RE
.sp
.LP
If \fB'n'\fP is specified, then mail is not sent. The \fIqalter\fP
utility shall consider it an error if any mail type other
than \fB'n'\fP is combined with mail type \fB'n'\fP . Strictly conforming
applications shall not repeat any of the characters
\fB'e'\fP, \fB'b'\fP, \fB'a'\fP, or \fB'n'\fP within the \fImail_options\fP
option-argument. The \fIqalter\fP
utility shall permit the repetition of characters but shall not assign
additional meaning to the repeated characters.
.LP
An implementation may define other mail types. The conformance document
for an implementation shall describe any additional mail
types, how they are specified, their internal behavior, and how they
affect the behavior of the utility.
.TP 7
\fB-M\ \fP \fImail_list\fP
Redefine the list of users to which the batch server that executes
the batch job is to send mail, if the batch server sends
mail about the batch job. 
.LP
The syntax of the \fImail_list\fP option-argument is unspecified.
If the implementation of the \fIqalter\fP utility uses a
name service to locate users, the utility shall accept the syntax
used by the name service.
.LP
If the implementation of the \fIqalter\fP utility does not use a name
service to locate users, the implementation shall accept
the following syntax for user names:
.sp
.RS
.nf

\fBmail_address[,,mail_address,,...]
\fP
.fi
.RE
.LP
The interpretation of \fImail_address\fP is implementation-defined.
.LP
The \fIqalter\fP utility shall set the \fIMail_Users\fP attribute
of the batch job to the value of the \fImail_list\fP
option-argument.
.TP 7
\fB-N\ \fP \fIname\fP
Redefine the name of the batch job. 
.LP
The \fIqalter\fP \fB-N\fP option shall accept a value for the \fIname\fP
option-argument that is a string of up to 15
alphanumeric characters in the portable character set where the first
character is alphabetic.
.LP
The syntax of the \fIname\fP option-argument is unspecified.
.LP
The \fIqalter\fP utility shall set the \fIJob_Name\fP attribute of
the batch job to the value of the \fIname\fP
option-argument.
.TP 7
\fB-o\ \fP \fIpath_name\fP
Redefine the path for the standard output of the batch job. 
.LP
The \fIqalter\fP utility shall accept a \fIpath_name\fP option-argument
that conforms to the syntax of the \fIpath_name\fP
element defined in the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
which can be preceded by a host name element of
the form \fIhostname\fP:.
.LP
If the \fIpath_name\fP option-argument constitutes an absolute pathname,
the \fIqalter\fP utility shall set the
\fIOutput_Path\fP attribute of the batch job to the value of the \fIpath_name\fP
option-argument.
.LP
If the \fIpath_name\fP option-argument constitutes a relative pathname
and no host name element is specified, the \fIqalter\fP
utility shall set the \fIOutput_Path\fP attribute of the batch job
to the absolute pathname derived by expanding the
\fIpath_name\fP option-argument relative to the current directory
of the process that executes the \fIqalter\fP utility.
.LP
If the \fIpath_name\fP option-argument constitutes a relative pathname
and a host name element is specified, the \fIqalter\fP
utility shall set the \fIOutput_Path\fP attribute of the batch job
to the value of the \fIpath_name\fP option-argument without
any expansion of the pathname.
.LP
If the \fIpath_name\fP option-argument does not include a host name
element, the \fIqalter\fP utility shall prefix the
pathname in the \fIOutput_Path\fP attribute with \fIhostname\fP:,
where \fIhostname\fP is the name of the host upon which the
\fIqalter\fP utility is being executed.
.TP 7
\fB-p\ \fP \fIpriority\fP
Redefine the priority of the batch job. 
.LP
The \fIqalter\fP utility shall accept a value for the priority option-argument
that conforms to the syntax for signed decimal
integers, and which is not less than -1024 and not greater than 1023.
.LP
The \fIqalter\fP utility shall set the \fIPriority\fP attribute of
the batch job to the value of the \fIpriority\fP
option-argument.
.TP 7
\fB-r\ \fP \fBy\fP|\fBn\fP
Redefine whether the batch job is rerunnable. 
.LP
If the value of the option-argument is \fB'y'\fP, the \fIqalter\fP
utility shall set the \fIRerunable\fP attribute of the
batch job to TRUE.
.LP
If the value of the option-argument is \fB'n'\fP, the \fIqalter\fP
utility shall set the \fIRerunable\fP attribute of the
batch job to FALSE.
.LP
The \fIqalter\fP utility shall consider it an error if any character
other than \fB'y'\fP or \fB'n'\fP is specified in
the option-argument.
.TP 7
\fB-S\ \fP \fIpath_name_list\fP
.sp
Redefine the shell that interprets the script at the destination system.
.LP
The \fIqalter\fP utility shall accept a \fIpath_name_list\fP option-argument
that conforms to the following syntax:
.sp
.RS
.nf

\fBpathname[@host][,pathname[@host],...]
\fP
.fi
.RE
.LP
The \fIqalter\fP utility shall accept only one pathname that is missing
a corresponding host name. The \fIqalter\fP utility
shall allow only one pathname per named host.
.LP
The \fIqalter\fP utility shall add a value to the \fIShell_Path_List\fP
attribute of the batch job for each entry in the
\fIpath_name_list\fP option-argument. See \fIMultiple Keyword-Value
Pairs\fP for a
means of removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@ \fIkeyword\fP)
pairs and other general rules for list-oriented
batch job attributes.
.TP 7
\fB-u\ \fP \fIuser_list\fP
Redefine the user name under which the batch job is to run at the
destination system. 
.LP
The \fIqalter\fP utility shall accept a \fIuser_list\fP option-argument
that conforms to the following syntax:
.sp
.RS
.nf

\fBusername[@host][,,username[@host],,...]
\fP
.fi
.RE
.LP
The \fIqalter\fP utility shall accept only one user name that is missing
a corresponding host name. The \fIqalter\fP utility
shall accept only one user name per named host.
.LP
The \fIqalter\fP utility shall add a value to the \fIUser_List\fP
attribute of the batch job for each entry in the
\fIuser_list\fP option-argument. See \fIMultiple Keyword-Value Pairs\fP
for a means of
removing \fIkeyword\fP= \fIvalue\fP (and \fIvalue\fP@ \fIkeyword\fP)
pairs and other general rules for list-oriented batch job
attributes.
.sp
.SH OPERANDS
.LP
The \fIqalter\fP utility shall accept one or more operands that conform
to the syntax for a batch \fIjob_identifier\fP (see \fIBatch Job Identifier\fP
).
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIqalter\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fILOGNAME\fP
Determine the login name of the user.
.TP 7
\fITZ\fP
Determine the timezone used to interpret the \fIdate-time\fP option-argument.
If \fITZ\fP is unset or null, an unspecified
default timezone shall be used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
None.
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
In addition to the default behavior, the \fIqalter\fP utility shall
not be required to write a diagnostic message to standard
error when the error reply received from a batch server indicates
that the batch \fIjob_identifier\fP does not exist on the
server. Whether or not the \fIqalter\fP utility attempts to locate
the batch job on other batch servers is
implementation-defined.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
None.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
The \fIqalter\fP utility allows users to change the attributes of
a batch job.
.LP
As a means of altering a queued job, the \fIqalter\fP utility is superior
to deleting and requeuing the batch job insofar as an
altered job retains its place in the queue with some traditional selection
algorithms. In addition, the \fIqalter\fP utility is
both shorter and simpler than a sequence of \fIqdel\fP and \fIqsub\fP
utilities.
.LP
The result of an attempt on the part of a user to alter a batch job
in a RUNNING state is implementation-defined because a batch
job in the RUNNING state will already have opened its output files
and otherwise performed any actions indicated by the options in
effect at the time the batch job began execution.
.LP
The options processed by the \fIqalter\fP utility are identical to
those of the \fIqsub\fP utility, with a few exceptions: \fB-V\fP,
\fB-v\fP, and \fB-q\fP. The \fB-V\fP and
\fB-v\fP are inappropriate for the \fIqalter\fP utility, since they
capture potentially transient environment information from
the submitting process. The \fB-q\fP option would specify a new queue,
which would largely negate the previously stated advantage
of using \fIqalter\fP; furthermore, the \fIqmove\fP utility provides
a superior means of
moving jobs.
.LP
Each of the following paragraphs provides the rationale for a \fIqalter\fP
option.
.LP
Additional rationale concerning these options can be found in the
rationale for the \fIqsub\fP utility.
.LP
The \fB-a\fP option allows users to alter the date and time at which
a batch job becomes eligible to run.
.LP
The \fB-A\fP option allows users to change the account that will be
charged for the resources consumed by the batch job.
Support for the \fB-A\fP option is mandatory for conforming implementations
of \fIqalter\fP, even though support of accounting is
optional for servers. Whether or not to support accounting is left
to the implementor of the server, but mandatory support of the
\fB-A\fP option assures users of a consistent interface and allows
them to control accounting on servers that support
accounting.
.LP
The \fB-c\fP option allows users to alter the checkpointing interval
of a batch job. A checkpointing system, which is not
defined by IEEE\ Std\ 1003.1-2001, allows recovery of a batch job
at the most recent checkpoint in the event of a crash.
Checkpointing is typically used for jobs that consume expensive computing
time or must meet a critical schedule. Users should be
allowed to make the tradeoff between the overhead of checkpointing
and the risk to the timely completion of the batch job;
therefore, this volume of IEEE\ Std\ 1003.1-2001 provides the checkpointing
interval option. Support for checkpointing is
optional for servers.
.LP
The \fB-e\fP option allows users to alter the name and location of
the standard error stream written by a batch job. However,
the path of the standard error stream is meaningless if the value
of the \fIJoin_Path\fP attribute of the batch job is TRUE.
.LP
The \fB-h\fP option allows users to set the hold type in the \fIHold_Types\fP
attribute of a batch job. The \fIqhold\fP and \fIqrls\fP utilities
add or remove hold types
to the \fIHold_Types\fP attribute, respectively. The \fB-h\fP option
has been modified to allow for implementation-defined hold
types.
.LP
The \fB-j\fP option allows users to alter the decision to join (merge)
the standard error stream of the batch job with the
standard output stream of the batch job.
.LP
The \fB-l\fP option allows users to change the resource limits imposed
on a batch job.
.LP
The \fB-m\fP option allows users to modify the list of points in the
life of a batch job at which the designated users will
receive mail notification.
.LP
The \fB-M\fP option allows users to alter the list of users who will
receive notification about events in the life of a batch
job.
.LP
The \fB-N\fP option allows users to change the name of a batch job.
.LP
The \fB-o\fP option allows users to alter the name and path to which
the standard output stream of the batch job will be
written.
.LP
The \fB-P\fP option allows users to modify the priority of a batch
job. Support for priority is optional for batch servers.
.LP
The \fB-r\fP option allows users to alter the rerunability status
of a batch job.
.LP
The \fB-S\fP option allows users to change the name and location of
the shell image that will be invoked to interpret the
script of the batch job. This option has been modified to allow a
list of shell name and locations associated with different
hosts.
.LP
The \fB-u\fP option allows users to change the user identifier under
which the batch job will execute.
.LP
The \fIjob_identifier\fP operand syntax is provided so that the user
can differentiate between the originating and destination
(or executing) batch server. These may or may not be the same. The
\&. \fIserver_name\fP portion identifies the originating batch
server, while the @ \fIserver\fP portion identifies the destination
batch server.
.LP
Historically, the \fIqalter\fP utility has been a component of the
Network Queuing System (NQS), the existing practice from
which this utility has been derived.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIBatch Environment Services\fP, \fIqdel\fP, \fIqhold\fP, \fIqmove\fP,
\fIqrls\fP, \fIqsub\fP, \fItouch\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .