qhold(1p)

1QHOLD(P)                   POSIX Programmer's Manual                  QHOLD(P)
2
3
4

NAME

6       qhold - hold batch jobs
7

SYNOPSIS

9       qhold [-h hold_list] job_identifier ...
10

DESCRIPTION

12       A  hold  is placed on a batch job by a request to the batch server that
13       manages the batch job. A batch job that has one or more  holds  is  not
14       eligible  for  execution. The qhold utility is a user-accessible client
15       of batch services that requests one or more types of hold to be  placed
16       on one or more batch jobs.
17
18       The  qhold  utility  shall  place holds on those batch jobs for which a
19       batch job_identifier is presented to the utility.
20
21       The qhold utility shall place holds on batch jobs in the order in which
22       their  batch job_identifiers are presented to the utility. If the qhold
23       utility fails to process any  batch  job_identifier  successfully,  the
24       utility  shall  proceed to process the remaining batch job_identifiers,
25       if any.
26
27       The qhold utility shall place holds on each batch job by sending a Hold
28       Job Request to the batch server that manages the batch job.
29
30       The  qhold  utility  shall not exit until holds have been placed on the
31       batch job corresponding to each successfully processed batch  job_iden‐
32       tifier.
33

OPTIONS

35       The  qhold  utility  shall  conform  to  the Base Definitions volume of
36       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
37
38       The following option shall be supported by the implementation:
39
40       -h  hold_list
41              Define the types of holds to be placed on the batch job.
42
43       The qhold -h option shall accept a value for the hold_list option-argu‐
44       ment  that is a string of alphanumeric characters in the portable char‐
45       acter set (see the Base  Definitions  volume  of  IEEE Std 1003.1-2001,
46       Section 6.1, Portable Character Set).
47
48       The  qhold  utility shall accept a value for the hold_list option-argu‐
49       ment that is a string of one or more of the characters 'u' , 's'  ,  or
50       'o' , or the single character 'n' .
51
52       For  each  unique character in the hold_list option-argument, the qhold
53       utility shall add a value to the Hold_Types attribute of the batch  job
54       as follows, each representing a different hold type:
55
56       u
57              USER
58
59       s
60              SYSTEM
61
62       o
63              OPERATOR
64
65
66       If any of these characters are duplicated in the hold_list option-argu‐
67       ment, the duplicates shall be ignored.
68
69       An existing Hold_Types attribute can be cleared by the  following  hold
70       type:
71
72       n
73              NO_HOLD
74
75
76       The  qhold  utility  shall  consider it an error if any hold type other
77       than 'n' is combined with hold type 'n' .
78
79       Strictly conforming applications shall not repeat any of the characters
80       'u'  ,  's'  ,  'o'  , or 'n' within the hold_list option-argument. The
81       qhold utility shall permit the repetition of characters, but shall  not
82       assign additional meaning to the repeated characters.
83
84       An implementation may define other hold types. The conformance document
85       for an implementation shall describe any  additional  hold  types,  how
86       they  are  specified,  their internal behavior, and how they affect the
87       behavior of the utility.
88
89       If the -h option is not presented to the qhold utility, the implementa‐
90       tion shall set the Hold_Types attribute to USER.
91
92

OPERANDS

94       The qhold utility shall accept one or more operands that conform to the
95       syntax for a batch job_identifier (see Batch Job Identifier ).
96

STDIN

98       Not used.
99

INPUT FILES

101       None.
102

ENVIRONMENT VARIABLES

104       The following environment  variables  shall  affect  the  execution  of
105       qhold:
106
107       LANG   Provide  a  default value for the internationalization variables
108              that are unset or null. (See  the  Base  Definitions  volume  of
109              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari‐
110              ables for the precedence of internationalization variables  used
111              to determine the values of locale categories.)
112
113       LC_ALL If  set  to a non-empty string value, override the values of all
114              the other internationalization variables.
115
116       LC_CTYPE
117              Determine the locale for  the  interpretation  of  sequences  of
118              bytes  of  text  data as characters (for example, single-byte as
119              opposed to multi-byte characters in arguments).
120
121       LC_MESSAGES
122              Determine the locale that should be used to  affect  the  format
123              and contents of diagnostic messages written to standard error.
124
125       LOGNAME
126              Determine the login name of the user.
127
128

ASYNCHRONOUS EVENTS

130       Default.
131

STDOUT

133       None.
134

STDERR

136       The standard error shall be used only for diagnostic messages.
137

OUTPUT FILES

139       None.
140

EXTENDED DESCRIPTION

142       None.
143

EXIT STATUS

145       The following exit values shall be returned:
146
147        0     Successful completion.
148
149       >0     An error occurred.
150
151

CONSEQUENCES OF ERRORS

153       In  addition  to  the  default behavior, the qhold utility shall not be
154       required to write a diagnostic message to standard error when the error
155       reply received from a batch server indicates that the batch job_identi‐
156       fier does not exist on the server. Whether or  not  the  qhold  utility
157       waits  to  output the diagnostic message while attempting to locate the
158       job on other servers is implementation-defined.
159
160       The following sections are informative.
161

APPLICATION USAGE

163       None.
164

EXAMPLES

166       None.
167

RATIONALE

169       The qhold utility allows users to place a hold on one or more  jobs.  A
170       hold makes a batch job ineligible for execution.
171
172       The  qhold  utility has options that allow the user to specify the type
173       of hold. Should the user wish to place a hold on a  set  of  jobs  that
174       meet  a  selection  criteria, such a list of jobs can be acquired using
175       the qselect utility.
176
177       The -h option allows the user to specify the type of hold that is to be
178       placed  on  the job. This option allows for USER, SYSTEM, OPERATOR, and
179       implementation-defined hold types. The USER and OPERATOR holds are dis‐
180       tinct. The batch server that manages the batch job will verify that the
181       user is authorized to set the specified hold for the batch job.
182
183       Mail is not required on hold because the administrator  has  the  tools
184       and libraries to build this option if he or she wishes.
185
186       Historically,  the qhold utility has been a part of some existing batch
187       systems, although it has not traditionally been a part of the NQS.
188

FUTURE DIRECTIONS

190       None.
191

COPYRIGHT

196       Portions of this text are reprinted and reproduced in  electronic  form
197       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
198       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
199       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
200       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
201       event of any discrepancy between this version and the original IEEE and
202       The Open Group Standard, the original IEEE and The Open Group  Standard
203       is  the  referee document. The original Standard can be obtained online
204       at http://www.opengroup.org/unix/online.html .
205
206
207
208IEEE/The Open Group                  2003                             QHOLD(P)