mirror of https://github.com/mkerrisk/man-pages
796 lines
28 KiB
Groff
796 lines
28 KiB
Groff
.\" 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 .
|