1 02/12/85 abs
  2 
  3 Syntax as a command:  abs keyword {args}
  4 
  5 
  6 Function:  controls the absentee facility.  The absentee facility is
  7 designed to operate automatically, without any user intervention.
  8 Every use of the abs command overrides some parameter or control
  9 algorithm that would otherwise have been used automatically.  Thus the
 10 abs command should only be used in unusual circumstances, or at the
 11 direction of the system administrator.  This command can be used only
 12 in ring 4.
 13 
 14 
 15 Arguments:
 16 keyword
 17    must be chosen from the keywords listed under "Keyword Summary"
 18    below.
 19 args
 20    may be either job selection arguments, described under "Job
 21    Selection" below, or other arguments specific to each keyword, or
 22    both.  Exact usage is described under individual keywords.
 23 
 24 
 25 Notes on keyword summary:  The keywords accepted by the abs command
 26 are listed below in two groups:  those pertaining to the absentee
 27 facility as a whole, and those pertaining to individual jobs.
 28 Detailed descriptions of the keywords and their arguments are given
 29 under "List of Keyword Descriptions" below.
 30 
 31 
 32 List of keywords:
 33 Keywords pertaining to entire absentee facility.
 34 cpu_limit
 35    do not run jobs with time limits higher than the specified values
 36 maxq
 37    run only jobs from queues 1 through the specified queue
 38 maxu
 39    run no more than the specified number of jobs at once
 40 qres
 41    reserve the specified number of absentee slots for each queue
 42 start
 43    start absentee facility
 44 stop
 45    stop absentee facility
 46 
 47 
 48 Keywords pertaining to individual jobs.
 49 bump
 50    log out running job(s); leave in queue (if restartable)
 51 cancel
 52    delete job from queue; log out if running
 53 defer
 54    do not log job(s) in until they are released
 55 list
 56    list specified job(s)
 57 move
 58    move job(s) to another queue
 59 next
 60    log job in next
 61 
 62 
 63 release
 64    allow deferred job(s) to run
 65 run
 66    log job in immediately
 67 suspend
 68    cause running job(s) to stop running until released
 69 terminate
 70    same as "bump", but job will appear to have taken a fatal process
 71    error
 72 
 73 
 74 Notes on job selection:  Some of the keywords described in detail
 75 below specify operations that can be performed on a single job only
 76 (indicated in keyword usage lines as JOB), while others specify
 77 operations that can be performed on one or more jobs (indicated as
 78 JOBS).
 79 
 80 You can specify the job or jobs by using the job selection arguments
 81 described below.  Each argument can appear at most once in the command.
 82 
 83 If the request operates on a single job (indicated as JOB), enough job
 84 selection arguments must be given so that only one job is found.  If
 85 the request operates on multiple jobs, all jobs that match the
 86 specified job selection arguments are acted upon.
 87 
 88 
 89 To be considered a match, a job must fit all the job selection
 90 arguments specified.  That is, the selection arguments make selection
 91 more specific.  For example, "-queue 1" selects all jobs in absentee
 92 queue 1.  "-queue 1 -user Smith" selects all of Smith's jobs in
 93 absentee queue 1, but does not select any other user's jobs, nor does
 94 it select any of Smith's jobs that are in other queues.  Job selection
 95 arguments are not treated as "match at least one" but rather "match
 96 all".
 97 
 98 The job selection arguments can be chosen from the following list (each
 99 selection may be specified at most once).
100 absN
101    where N is a decimal number or "*".  This selects the running job in
102    absentee slot N, or all running jobs if "*" is given.  Slot numbers
103    are printed by the who initializer command or the as_who command in
104    Multics.
105 
106 
107 -entry STR, -et STR
108    where STR is the entryname of the absin segment.  It may be a
109    starname.
110 -foreground, -fg
111    this argument is equivalent to the -queue foreground control
112    argument.
113 -id ID, ID
114    where ID can be a long job ID or a substring of a job ID long enough
115    to uniquely identify one job.  A long job ID is a 19 digit number of
116    the form shown below.
117 
118          yymmddHHMMSS.UUUUUU
119 
120 
121    which is the time (GMT) at which the job was entered.  Any substring
122    of the ID that contains either the decimal point or the digit to its
123    left can be given.  If the decimal point is not given, it is assumed
124    to be to the right of the last digit given.  Any other job selection
125    arguments given must identify the same job, no matter what keyword
126    it is given with.  If the other job selection arguments do not match
127    the uniquely specified job, the command is rejected.  Both -user
128    NAME and -id ID may be given without their identifying control
129    arguments if either one, or both, are the first arguments after the
130    keyword.
131 path
132    is the absolute pathname of the absentee input (absin) segment.  The
133    pathname may end in a starname.
134 
135 
136 -queue STR, -q STR
137    where STR is the absentee queue to be searched for the job.  (If
138    this argument is omitted, all queues are searched.)  STR can be 1
139    through 4 or "foreground" or "fg".
140 -sender STR
141    where STR is the name of the RJE station from which the job was
142    entered.  It may be a starname.
143 
144 
145 -user NAME
146    where NAME may be specified in one of the following forms shown
147    below.
148          Person
149          Person Project
150          Person.Project
151          .Project
152 
153    The star convention is allowed except when a single job is selected.
154    Both -user NAME and -id ID may be given without their identifying
155    control arguments if either one, or both, are the first arguments
156    after the keyword.
157 
158 
159 List of keyword descriptions:
160 bump JOBS
161    bumps the specified running job or jobs.  If they are restartable
162    jobs, they remain in the queue and are restarted at some later time.
163 cancel JOB
164    deletes a single job from the absentee queues, and bumps it if it is
165    running.  Note that some form of the user name must always be given
166    with the cancel keyword as protection against accidental
167    cancellation of the wrong user's job.
168 
169 
170 cpu_limit, cpu_limit auto, cpu_limit s1,s2,s3,s4
171    either prints the CPU time limits, restores them to their automatic
172    values (which are per-shift values set by the system administrator),
173    or sets them to the specified values.  Values, in seconds, must be
174    given for queues 1 through 4, separated by commas.  Omitted values
175    (indicated by adjacent commas) leave the limits for the respective
176    shifts unchanged.  (Trailing commas are optional.)  The limits
177    remain at the specified values until the next Multics bootload,
178    unless reset to their automatic values by specifying cpu_limit auto.
179    Jobs with estimated times greater than the automatic or
180    user-specified CPU time limits are not run until the limits are
181    raised (either by the operator or by the arrival of a shift having
182    higher limits).  If no argument is given, the current CPU time
183    limits are printed.
184 
185 
186 defer JOBS
187    places the specified jobs in the deferred state.  Jobs in this state
188    are deferred indefinitely, even across Multics bootloads -- that is,
189    they are not run until released (by the abs command with the release
190    keyword).  Users can place their own jobs in the deferred state.
191    This is useful if a job is not to be run until the occurrence of
192    some event, such as the delivery of a reel of tape to the computer
193    room.  The list keyword (with suitable arguments) can be used to
194    list all jobs that are deferred indefinitely.
195 
196 
197 list JOBS {-control_args}
198    lists the specified jobs.  All of the control arguments accepted by
199    the list_abs_requests command (described in the Multics Commands and
200    Active Functions manual, Order No   AG92) are accepted with the list
201    keyword.  These control arguments are summarized below.
202    -absolute_pathname, -absp
203       prints absolute pathname of selected jobs.  (The default is that
204       entry name is printed.)
205    -all, -a
206       prints totals for all nonempty queues.  (The default is that
207       nothing is printed for queues from which no jobs are selected.)
208    -deferred_indefinitely, -dfi
209       selects only jobs that are deferred indefinitely.
210 
211 
212    -immediate, -im
213       selects only jobs that are neither deferred indefinitely nor
214       deferred until a specified time.
215    -long, -lg
216       prints all information for each selected job.  This argument
217       produces many output lines for each job, and should not be used
218       when a large number of jobs are being listed.
219    -long_id, -lgid
220       prints all 19 digits of IDs of selected jobs.
221    -position, -psn
222       prints the position in the queue of each selected job.
223 
224 
225    -resource {STR}, -rsc {STR}
226       selects only jobs with resource requirements, where STR is the
227       name of a resource.  If STR is given, selects only jobs requiring
228       the specified resource (e.g., -rsc tape_drive).
229    -total, -tt
230       prints only the total number of jobs selected from each queue.
231       (The default is that one line is printed for each selected job).
232 
233 
234 maxq, maxq auto, maxq N
235    either prints the highest numbered (lowest priority) queue being
236    searched, restores it to its automatic value (which is a per-shift
237    value set by the system administrator), or sets it to the specified
238    value N.  The maximum queue remains at the specified value until the
239    next Multics bootload, unless reset to its automatic value by
240    specifying maxq auto.  Jobs from higher numbered queues are not
241    logged in until the maximum queue is raised (either by the operator
242    or by the arrival of a shift with a higher automatic maxq value).
243    If no argument is given, the current maxq figure is printed.
244 
245 
246 maxu, maxu auto, maxu N
247    either prints the number of absentee slots (i.e., the maximum number
248    of simultaneously running background absentee jobs) restores it to
249    its automatic value (a per-shift value set by the system
250    administrator that can optionally adjust itself automatically
251    depending on the interactive load), or sets it to the specified
252    value N.  The number of slots remains at the specified value until
253    the next Multics bootload, unless reset to its automatic value by
254    specifying maxu auto.  If no argument is given, the current abs maxu
255    value is printed.
256 move JOBS -to_queue N, move JOBS -to_q N
257    moves the specified job or jobs to the end of the specified queue
258    (N).  Any jobs already running are not moved.  The abs move command
259    operates the same as the move_abs_request command, described in the
260    Multics Commands and Active Functions manual, Order No.  AG92, and
261    accepts the same arguments.  See that manual for more information.
262 
263 
264 next JOB
265    places the specified job ahead of all other queued jobs, so that it
266    is the next job to log in.  The job is actually moved to queue zero,
267    which has higher priority than queue 1.  The job is charged queue 1
268    rates when it runs.  A series of abs next commands cause the
269    specified jobs to accumulate in queue zero; they are run in the
270    order in which they are specified.
271 qres, qres auto, qres R1 {R2 {R3 {R4}}}
272    either prints the per-queue reserved slot values, restores them to
273    their automatic per-shift values (specified by the system
274    administrator), or changes them to the specified values.  Values for
275    up to 4 queues may be given; zero is the default for any values not
276    given.  To set all 4 values to zero, type "abs qres 0".  If no
277    arguments are given, the current values are printed.  Values set by
278    this command remain in effect until the next Multics bootload,
279    unless restored to their automatic values by specifying qres auto.
280 
281 
282    The slot reservation feature prevents jobs from lower priority
283    queues from logging in if they would occupy slots reserved for
284    higher priority queues.  However, jobs from higher priority queues
285    are permitted to log in and occupy slots reserved for lower priority
286    queues.
287 release JOBS
288    releases the specified job(s) from the deferred or suspended states,
289    allowing them to log in, or to resume running, as the case may be.
290 run JOB
291    forces the specified job to be logged in immediately, bypassing all
292    absentee load control processing.  A new temporary absentee slot is
293    created, if necessary.  Under certain circumstances, the user is
294    warned that logging in the job might create problems, and is asked
295    if the job should be logged in despite the potential problems.  Note
296    that some form of the user name must be given with the run keyword.
297 
298 
299 start {M {Q}}, start queue Q
300    the first form is used to start the absentee facility.  (It is
301    normally started at answering service startup time, making use of
302    this command unnecessary.)  The optional arguments are the maximum
303    numbers of users (M) and queues (Q).  (These are the same parameters
304    that can be set by the maxu and maxq keywords.)  If they are not
305    specified, the automatic values set by the system administrator are
306    used.
307 
308    The second form restarts a queue that was dropped due to errors, and
309    it also wakes up the absentee facility, causing it to check whether
310    any jobs waiting to log in could now do so due to changed
311    conditions.  If Q is omitted in the second form, the current error
312    status of each queue is printed.  If Q is "all" then all queues are
313    restarted.
314 
315 
316 stop {now}, stop queue Q
317    the first form is used to stop the absentee facility 30 minutes
318    after the command line is issued.  If "now" is specified, the
319    absentee facility is immediately stopped without the 30 minute
320    grace.  (See "Notes" below.)
321 
322    The abs stop command can also be given before the answering service
323    is started to prevent the absentee facility from being started
324    automatically.
325 
326    The second form causes the specified queue to be dropped, as if it
327    had gotten too many errors.  The absentee facility continues to run,
328    taking requests from the other queues.  If Q is "all" then all
329    queues are dropped.  The queue(s) can be restarted using the abs
330    start queue command.
331 
332 
333 suspend JOBS
334    causes the specified running job(s) to enter the suspended state, in
335    which they remain logged in but use no cpu or memory resources.  The
336    jobs remain in this state until released.  A suspended job places no
337    load on the system (although it does occupy an absentee slot and
338    uses up some units from its load control group, possibly preventing
339    other interactive or absentee users from logging in).  Jobs can be
340    suspended to reduce the load on the system, allowing the timely
341    completion of some critical work in another process.  Suspended jobs
342    should be released as soon as the critical work is completed, since
343    they are NOT preserved across shutdowns and crashes.
344 
345 
346 terminate JOBS
347    causes the specified running job(s) to be bumped in a way that makes
348    them appear to have failed because of a fatal process error.
349    Certain debugging facilities treat such failures differently from
350    normal bumps.  This keyword should only be used at the request of
351    the user.
352 
353 
354 Notes:  Some of the abs command keywords place the absentee facility,
355 or one or more jobs, in an unusual state, where they will remain
356 indefinitely.  You must always remember to restore the absentee
357 facility or the affected jobs to normal operation after the unusual
358 circumstances have passed.
359 
360 The "abs stop" command line should be issued about 20 minutes before a
361 stop command is invoked.  If a down command has been issued, "abs stop"
362 is automatically issued 20 minutes before the scheduled shutdown time.
363 
364 After an "abs stop" command line is issued, the absentee facility does
365 not let any more absentee users log in and waits for all current ones
366 to log out.  If all absentee users have not logged out in 30 minutes,
367 the absentee facility automatically bumps the remaining absentee users.
368 
369 
370 The difference between the 30-minute time limit on absentee jobs and
371 the 20 minutes between a scheduled shutdown and the automatic "abs
372 stop" is intended to give absentee processes an additional 10 minutes
373 to finish after all interactive users are bumped.
374 
375 If all absentee users log out before 30 minutes, the following message
376 is printed.
377 
378       admin:  All absentee processes have run to completion.
379 
380 If not, then this message is printed.
381 
382       admin:  bumping all remaining absentee processes.
383 
384 
385 If it is necessary to stop the absentee facility immediately with an
386 "abs stop now" command line, all absentee users are bumped as if the
387 30-minute time limit had expired.  Since this command line forcibly
388 terminates user programs that may have difficulty restarting, the now
389 argument should be used only when specifically authorized.
390 
391 If a down command has scheduled an automatic shutdown, issuing an "abs
392 start" automatically schedules an "abs stop" 20 minutes before the
393 scheduled shutdown time.
394 
395 
396 The "abs bump" command line causes an absentee user to be bumped.  If
397 the absentee job has been declared restartable, the job is left in the
398 queue and reexecuted later.  This command can be used when shutting
399 down the absentee facility quickly because of some system malfunction,
400 usually at the request of a system programmer.  If a user calls and
401 asks to have his absentee job bumped, you should make certain that the
402 "abs cancel" command is not intended instead.
403 
404 The "abs cancel" command line can also cause an absentee user to be
405 bumped.  It differs from "abs bump" in that restartable absentee
406 requests are removed from the queue, and not restarted, and jobs not
407 yet started can be removed from the queue.  This command line is used
408 to cancel an absentee job that is in trouble (for instance, one that
409 seems to be reissuing itself in a loop, or one that calls for a tape
410 that does not exist) or that a user has requested be cancelled.