qselect(1p)

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

NAME

6       qselect - select batch jobs
7

SYNOPSIS

9       qselect [-a [op]date_time][-A account_string][-c [op]interval]
10               [-h hold_list][-l resource_list][-N name][-p [op]priority]
11               [-q destination][-r y|n][-s states][-u user_list]
12

DESCRIPTION

14       To  select  a  set of batch jobs is to return the batch job_identifiers
15       for each batch job that meets a list of selection criteria.  A  set  of
16       batch  jobs  is  selected  by  a request to a batch server. The qselect
17       utility is a user-accessible batch client that requests  the  selection
18       of batch jobs.
19
20       Upon  successful  completion, the qselect utility shall have returned a
21       list of zero or more batch job_identifiers that meet the criteria spec‐
22       ified by the options and option-arguments presented to the utility.
23
24       The  qselect  utility  shall select batch jobs by sending a Select Jobs
25       Request to a batch server. The qselect utility shall not exit until the
26       server replies to each request generated.
27
28       For  each  option  presented  to the qselect utility, the utility shall
29       restrict the set of selected batch jobs as  described  in  the  OPTIONS
30       section.
31
32       The  qselect  utility shall not restrict selection of batch jobs except
33       by authorization and as required by the options presented to the  util‐
34       ity.
35
36       When  an  option is specified with a mandatory or optional op component
37       to the option-argument, then op shall specify a  relation  between  the
38       value  of  a certain batch job attribute and the value component of the
39       option-argument. If an op is allowable on an option, then the  descrip‐
40       tion  of  the  option  letter  indicates  the op as either mandatory or
41       optional. Acceptable strings for the op component, and the relation the
42       string indicates, are shown in the following list:
43
44       .eq.   The value represented by the attribute of the batch job is equal
45              to the value represented by the option-argument.
46
47       .ge.   The value represented by the  attribute  of  the  batch  job  is
48              greater  than  or  equal to the value represented by the option-
49              argument.
50
51       .gt.   The value represented by the  attribute  of  the  batch  job  is
52              greater than the value represented by the option-argument.
53
54       .lt.   The  value represented by the attribute of the batch job is less
55              than the value represented by the option-argument.
56
57       .le.   The value represented by the attribute of the batch job is  less
58              than or equal to the value represented by the option-argument.
59
60       .ne.   The  value  represented by the attribute of the batch job is not
61              equal to the value represented by the option-argument.
62
63

OPTIONS

65       The qselect utility shall conform to the  Base  Definitions  volume  of
66       IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
67
68       The following options shall be supported by the implementation:
69
70       -a [op]date_time
71
72              Restrict selection to a specific time, or a range of times.
73
74       The qselect utility shall select only batch jobs for which the value of
75       the Execution_Time attribute is related to the Epoch equivalent of  the
76       local  time  expressed  by  the value of the date_time component of the
77       option-argument in the manner indicated by the value of the  op  compo‐
78       nent of the option-argument.
79
80       The  qselect  utility shall accept a date_time component of the option-
81       argument that conforms to the syntax of the time operand of  the  touch
82       utility.
83
84       If the op component of the option-argument is not presented to the qse‐
85       lect utility, the utility shall select batch jobs for which the  Execu‐
86       tion_Time  attribute is equal to the date_time component of the option-
87       argument.
88
89       When comparing times, the qselect utility shall use the following defi‐
90       nitions for the op component of the option-argument:
91
92       .eq.
93              The time represented by value of the Execution_Time attribute of
94              the batch job is equal to the time represented by the  date_time
95              component of the option-argument.
96
97       .ge.
98              The time represented by value of the Execution_Time attribute of
99              the batch job is after or equal to the time represented  by  the
100              date_time component of the option-argument.
101
102       .gt.
103              The time represented by value of the Execution_Time attribute of
104              the batch job is after the time  represented  by  the  date_time
105              component of the option-argument.
106
107       .lt.
108              The time represented by value of the Execution_Time attribute of
109              the batch job is before the time represented  by  the  date_time
110              component of the option-argument.
111
112       .le.
113              The time represented by value of the Execution_Time attribute of
114              the batch job is before or equal to the time represented by  the
115              date_time component of the option-argument.
116
117       .ne.
118              The time represented by value of the Execution_Time attribute of
119              the batch job is not  equal  to  the  time  represented  by  the
120              date_time component of the option-argument.
121
122
123       The  qselect utility shall accept the defined character strings for the
124       op component of the option-argument.
125
126       -A  account_string
127
128              Restrict selection  to  the  batch  jobs  charging  a  specified
129              account.
130
131       The qselect utility shall select only batch jobs for which the value of
132       the Account_Name attribute of the batch job matchs  the  value  of  the
133       account_string option-argument.
134
135       The syntax of the account_string option-argument is unspecified.
136
137       -c [op]interval
138
139              Restrict  selection  to  batch jobs within a range of checkpoint
140              intervals.
141
142       The qselect utility shall select only batch jobs for which the value of
143       the Checkpoint attribute relates to the value of the interval component
144       of the option-argument in the manner indicated by the value of  the  op
145       component of the option-argument.
146
147       If  the  op  component  of  the option-argument is omitted, the qselect
148       utility shall select batch jobs for which the value of  the  Checkpoint
149       attribute  is  equal  to  the  value  of  the interval component of the
150       option-argument.
151
152       When comparing checkpoint intervals, the qselect utility shall use  the
153       following definitions for the op component of the option-argument:
154
155       .eq.
156              The  value  of  the Checkpoint attribute of the batch job equals
157              the value of the interval component of the option-argument.
158
159       .ge.
160              The value of the  Checkpoint  attribute  of  the  batch  job  is
161              greater  than  or  equal  to the value of the interval component
162              option-argument.
163
164       .gt.
165              The value of the  Checkpoint  attribute  of  the  batch  job  is
166              greater  than  the  value of the interval component option-argu‐
167              ment.
168
169       .lt.
170              The value of the Checkpoint attribute of the batch job  is  less
171              than the value of the interval component option-argument.
172
173       .le.
174              The  value  of the Checkpoint attribute of the batch job is less
175              than or equal to the value of  the  interval  component  option-
176              argument.
177
178       .ne.
179              The  value of the Checkpoint attribute of the batch job does not
180              equal the value of the interval component option-argument.
181
182
183       The qselect utility shall accept the defined character strings for  the
184       op component of the option-argument.
185
186       The  ordering  relationship for the values of the interval option-argu‐
187       ment is defined to be:
188
189
190              `n' .gt. `s' .gt. `c=minutes' .ge. `c'
191       When comparing Checkpoint attributes with an interval having the  value
192       of  the  single  character  'u' , only equality or inequality are valid
193       comparisons.
194
195       -h  hold_list
196              Restrict selection to batch jobs that have a  specific  type  of
197              hold.
198
199       The qselect utility shall select only batch jobs for which the value of
200       the Hold_Types attribute matches the value  of  the  hold_list  option-
201       argument.
202
203       The  qselect  -h  option shall accept a value for the hold_list option-
204       argument that is a string of alphanumeric characters  in  the  portable
205       character set (see the Base Definitions volume of IEEE Std 1003.1-2001,
206       Section 6.1, Portable Character Set).
207
208       The qselect utility shall accept a value for the hold_list option-argu‐
209       ment  that  is a string of one or more of the characters 'u' , 's' , or
210       'o' , or the single character 'n' .
211
212       Each unique character in the hold_list option-argument of  the  qselect
213       utility is defined as follows, each representing a different hold type:
214
215       u
216              USER
217
218       s
219              SYSTEM
220
221       o
222              OPERATOR
223
224
225       If any of these characters are duplicated in the hold_list option-argu‐
226       ment, the duplicates shall be ignored.
227
228       The qselect utility shall consider it an error if any hold  type  other
229       than 'n' is combined with hold type 'n' .
230
231       Strictly conforming applications shall not repeat any of the characters
232       'u' , 's' , 'o' , or 'n' within the hold_list option-argument. The qse‐
233       lect  utility  shall permit the repetition of characters, but shall not
234       assign additional meaning to the repeated characters.
235
236       An implementation may define other hold types. The conformance document
237       for  an  implementation  shall  describe any additional hold types, how
238       they are specified, their internal behavior, and how  they  affect  the
239       behavior of the utility.
240
241       -l  resource_list
242
243              Restrict  selection to batch jobs with specified resource limits
244              and attributes.
245
246       The qselect utility shall accept a resource_list  option-argument  with
247       the following syntax:
248
249
250              resource_name op value [,,resource_name op value,, ...]
251
252       When  comparing resource values, the qselect utility shall use the fol‐
253       lowing definitions for the op component of the option-argument:
254
255       .eq.
256              The value of the resource of the same name in the  Resource_List
257              attribute  of the batch job equals the value of the value compo‐
258              nent of the option-argument.
259
260       .ge.
261              The value of the resource of the same name in the  Resource_List
262              attribute of the batch job is greater than or equal to the value
263              of the value component of the option-argument.
264
265       .gt.
266              The value of the resource of the same name in the  Resource_List
267              attribute  of  the  batch  job  is greater than the value of the
268              value component of the option-argument.
269
270       .lt.
271              The value of the resource of the same name in the  Resource_List
272              attribute  of  the batch job is less than the value of the value
273              component of the option-argument.
274
275       .ne.
276              The value of the resource of the same name in the  Resource_List
277              attribute of the batch job does not equal the value of the value
278              component of the option-argument.
279
280       .le.
281              The value of the resource of the same name in the  Resource_List
282              attribute of the batch job is less than or equal to the value of
283              the value component of the option-argument.
284
285
286       When comparing the limit of a Resource_List attribute  with  the  value
287       component  of the option-argument, if the limit, the value, or both are
288       non-numeric, only equality or inequality are valid comparisons.
289
290       The qselect utility shall select only batch jobs for which  the  values
291       of the resource_names listed in the resource_list option-argument match
292       the corresponding limits of the Resource_List attribute  of  the  batch
293       job.
294
295       Limits  of resource_names present in the Resource_List attribute of the
296       batch job that  have  no  corresponding  values  in  the  resource_list
297       option-argument shall not be considered when selecting batch jobs.
298
299       -N  name
300              Restrict selection to batch jobs with a specified name.
301
302       The qselect utility shall select only batch jobs for which the value of
303       the Job_Name attribute matches the value of the  name  option-argument.
304       The string specified in the name option-argument shall be passed, unin‐
305       terpreted, to the server. This allows an implementation to match "wild‐
306       card" patterns against batch job names.
307
308       An implementation shall describe in the conformance document the format
309       it supports for matching against the Job_Name attribute.
310
311       -p [op]priority
312
313              Restrict selection to batch jobs of the  specified  priority  or
314              range of priorities.
315
316       The qselect utility shall select only batch jobs for which the value of
317       the Priority attribute of the batch job relates to  the  value  of  the
318       priority  component  of  the option-argument in the manner indicated by
319       the value of the op component of the option-argument.
320
321       If the op component of the  option-argument  is  omitted,  the  qselect
322       utility  shall  select  batch  jobs for which the value of the Priority
323       attribute of the batch job is equal to the value of the priority compo‐
324       nent of the option-argument.
325
326       When  comparing priority values, the qselect utility shall use the fol‐
327       lowing definitions for the op component of the option-argument:
328
329       .eq.
330              The value of the Priority attribute of the batch job equals  the
331              value of the priority component of the option-argument.
332
333       .ge.
334              The  value of the Priority attribute of the batch job is greater
335              than or equal to the value of  the  priority  component  option-
336              argument.
337
338       .gt.
339              The  value of the Priority attribute of the batch job is greater
340              than the value of the priority component option-argument.
341
342       .lt.
343              The value of the Priority attribute of the  batch  job  is  less
344              than the value of the priority component option-argument.
345
346       .lt.
347              The  value  of  the  Priority attribute of the batch job is less
348              than or equal to the value of  the  priority  component  option-
349              argument.
350
351       .ne.
352              The  value  of  the Priority attribute of the batch job does not
353              equal the value of the priority component option-argument.
354
355
356       -q  destination
357
358              Restrict selection to the specified batch queue  or  server,  or
359              both.
360
361       The  qselect  utility  shall select only batch jobs that are located at
362       the destination indicated by the value of the destination  option-argu‐
363       ment.
364
365       The  destination defines a batch queue, a server, or a batch queue at a
366       server.
367
368       The qselect utility shall accept an option-argument for the  -q  option
369       that  conforms to the syntax for a destination. If the -q option is not
370       presented to the qselect utility, the utility shall select  batch  jobs
371       from all batch queues at the default batch server.
372
373       If  the option-argument describes only a batch queue, the qselect util‐
374       ity shall select only batch jobs from the batch queue of the  specified
375       name at the default batch server. The means by which qselect determines
376       the default server is implementation-defined.
377
378       If the option-argument describes only a batch server, the qselect util‐
379       ity  shall  select  batch  jobs from all the batch queues at that batch
380       server.
381
382       If the option-argument describes both a batch queue and a batch server,
383       the  qselect  utility  shall  select only batch jobs from the specified
384       batch queue at the specified server.
385
386       -r  y|n
387              Restrict selection to batch jobs with the specified rerunability
388              status.
389
390       The qselect utility shall select only batch jobs for which the value of
391       the Rerunable attribute of the batch  job  matches  the  value  of  the
392       option-argument.
393
394       The  qselect  utility shall accept a value for the option-argument that
395       consists of either the single character 'y' or the single character 'n'
396       .  The  character  'y' represents the value TRUE, and the character 'n'
397       represents the value FALSE.
398
399       -s  states
400              Restrict selection to batch jobs in the specified states.
401
402       The qselect utility shall accept an option-argument  that  consists  of
403       any combination of the characters 'e' , 'q' , 'r' , 'w' , 'h' , and 't'
404       .
405
406       Conforming applications shall not repeat any character in  the  option-
407       argument.   The  qselect utility shall permit the repetition of charac‐
408       ters in the option-argument, but shall not assign additional meaning to
409       repeated characters.
410
411       The  qselect  utility  shall  interpret  the  characters  in the states
412       option-argument as follows:
413
414       e
415              Represents the EXITING state.
416
417       q
418              Represents the QUEUED state.
419
420       r
421              Represents the RUNNING state.
422
423       t
424              Represents the TRANSITING state.
425
426       h
427              Represents the HELD state.
428
429       w
430              Represents the WAITING state.
431
432
433       For each character in the states option-argument, the  qselect  utility
434       shall select batch jobs in the corresponding state.
435
436       -u  user_list
437              Restrict  selection  to  batch  jobs owned by the specified user
438              names.
439
440       The qselect utility shall select only the batch  jobs  of  those  users
441       specified in the user_list option-argument.
442
443       The  qselect utility shall accept a user_list option-argument that con‐
444       forms to the following syntax:
445
446
447              username[@host][,,username[@host],, ...]
448
449       The qselect utility shall accept only one user name that is  missing  a
450       corresponding host name. The qselect utility shall accept only one user
451       name per named host.
452
453

OPERANDS

455       None.
456

STDIN

458       Not used.
459

INPUT FILES

461       None.
462

ENVIRONMENT VARIABLES

464       The following environment variables shall affect the execution of  qse‐
465       lect:
466
467       LANG   Provide  a  default value for the internationalization variables
468              that are unset or null. (See  the  Base  Definitions  volume  of
469              IEEE Std 1003.1-2001,  Section  8.2,  Internationalization Vari‐
470              ables for the precedence of internationalization variables  used
471              to determine the values of locale categories.)
472
473       LC_ALL If  set  to a non-empty string value, override the values of all
474              the other internationalization variables.
475
476       LC_CTYPE
477              Determine the locale for  the  interpretation  of  sequences  of
478              bytes  of  text  data as characters (for example, single-byte as
479              opposed to multi-byte characters in arguments).
480
481       LC_MESSAGES
482              Determine the locale that should be used to  affect  the  format
483              and contents of diagnostic messages written to standard error.
484
485       LOGNAME
486              Determine the login name of the user.
487
488       TZ     Determine  the  timezone used to interpret the date-time option-
489              argument.  If TZ is unset or null, an unspecified default  time‐
490              zone shall be used.
491
492

ASYNCHRONOUS EVENTS

494       Default.
495

STDOUT

497       The  qselect  utility shall write zero or more batch job_identifiers to
498       standard output.
499
500       The qselect utility shall separate the batch job_identifiers written to
501       standard output by white space.
502
503       The  qselect utility shall write batch job_identifiers in the following
504       format:
505
506
507              sequence_number.server_name@server
508

STDERR

510       The standard error shall be used only for diagnostic messages.
511

OUTPUT FILES

513       None.
514

EXTENDED DESCRIPTION

516       None.
517

EXIT STATUS

519       The following exit values shall be returned:
520
521        0     Successful completion.
522
523       >0     An error occurred.
524
525

CONSEQUENCES OF ERRORS

527       Default.
528
529       The following sections are informative.
530

APPLICATION USAGE

532       None.
533

EXAMPLES

535       The following example shows how a user might use the qselect utility in
536       conjunction  with  the qdel utility to delete all of his or her jobs in
537       the queued state without affecting any jobs that are already running:
538
539
540              qdel $(qselect -s q)
541
542       or:
543
544
545              qselect -s q || xargs qdel
546

RATIONALE

548       The qselect utility allows users to acquire a list of  job  identifiers
549       that  match  user-specified selection criteria. The list of identifiers
550       returned by the qselect utility conforms to the syntax of the batch job
551       identifier  list  processed by a utility such as qmove, qdel, and qrls.
552       The qselect utility is thus a powerful tool for causing  another  batch
553       system utility to act upon a set of jobs that match a list of selection
554       criteria.
555
556       The options of the qselect utility let the user apply a number of  use‐
557       ful  filters  for  selecting  jobs.  Each  option further restricts the
558       selection of jobs. Many of the selection options allow  the  specifica‐
559       tion of a relational operator. The FORTRAN-like syntax of the operator-
560       that is, ".lt." - was chosen rather than the C-like  "<="  meta-charac‐
561       ters.
562
563       The  -a option allows users to restrict the selected jobs to those that
564       have been submitted (or altered) to wait until a particular  time.  The
565       time  period  is  determined  by  the  argument  of  this option, which
566       includes both a time and an operator-it is thus possible to select jobs
567       waiting until a specific time, jobs waiting until after a certain time,
568       or those waiting for a time before the specified time.
569
570       The -A option allows users to restrict the selected jobs to those  that
571       have been submitted (or altered) to charge a particular account.
572
573       The -c option allows users to restrict the selected jobs to those whose
574       checkpointing interval falls within the specified range.
575
576       The -l option allows users to select those jobs whose  resource  limits
577       fall  within  the range indicated by the value of the option. For exam‐
578       ple, a user could select those jobs for which the  CPU  time  limit  is
579       greater than two hours.
580
581       The  -N  option  allows users to select jobs by job name. For instance,
582       all the parts of a task that have been divided in parallel  jobs  might
583       be  given  the  same  name, and thus manipulated as a group by means of
584       this option.
585
586       The -q option allows users to select jobs in a specified queue.
587
588       The -r option allows users to select only those jobs with  a  specified
589       rerun  criteria. For instance, a user might select only those jobs that
590       can be rerun for use with the qrerun utility.
591
592       The -s option allows users to select only those jobs that are in a cer‐
593       tain state.
594
595       The  -u  option allows users to select jobs that have been submitted to
596       execute under a particular account.
597
598       The selection criteria provided by the options of the  qselect  utility
599       allow users to select jobs based on all the appropriate attributes that
600       can be assigned to jobs by the qsub utility.
601
602       Historically, the qselect utility has not been a part of existing prac‐
603       tice;  it  is an improvement that has been introduced in this volume of
604       IEEE Std 1003.1-2001.
605

FUTURE DIRECTIONS

607       None.
608

COPYRIGHT

614       Portions  of  this text are reprinted and reproduced in electronic form
615       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
616       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
617       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
618       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
619       event of any discrepancy between this version and the original IEEE and
620       The  Open Group Standard, the original IEEE and The Open Group Standard
621       is the referee document. The original Standard can be  obtained  online
622       at http://www.opengroup.org/unix/online.html .
623
624
625
626IEEE/The Open Group                  2003                           QSELECT(P)