1 03/17/88  user_info_
  2 
  3 
  4 The user_info_ subroutine allows the user to obtain information
  5 concerning his login session.  All entry points that accept more than
  6 one argument count their arguments and only return values for the
  7 number of arguments given.
  8 
  9 
 10 Entry points in user_info_:
 11    (List is generated by the help command)
 12 
 13 
 14 :Entry:  user_info_:  03/08/85  user_info_
 15 
 16 
 17 Function:
 18 The user_info_ entry point returns the user's login name, project name,
 19 and account identifier.
 20 
 21 
 22 Syntax:
 23 declare user_info_ entry (char(*), char(*), char(*));
 24 call user_info_ (person_id, project_id, acct);
 25 
 26 
 27 Arguments:
 28 person_id
 29    is the user's name from the login line (maximum of 22 characters).
 30    (Output)
 31 project_id
 32    is the user's project identifier (maximum of 9 characters).
 33    (Output)
 34 acct
 35    is the user's account identifier (maximum of 32 characters).
 36    (Output)
 37 
 38 
 39 :Entry:  absentee_queue:  03/08/85 user_info_$absentee_queue
 40 
 41 
 42 Function:  This entry point returns the queue number of the absentee
 43 queue for an absentee process.  For an interactive process, the number
 44 returned is -1.
 45 
 46 
 47 Syntax:
 48 declare user_info_$absentee_queue entry (fixed bin);
 49 call user_info_$absentee_queue (queue);
 50 
 51 
 52 Arguments:
 53 queue
 54    is the number of the absentee queue.  (Output)
 55 
 56 
 57 :Entry:  absentee_request_id:  03/08/85 user_info_$absentee_request_id
 58 
 59 
 60 Function:  This entry point returns the identifier by which the
 61 absentee request is known to the absentee user manager.  This is the ID
 62 which is used by the absentee request commands enter_abs_request,
 63 cancel_abs_request and move_abs_request.
 64 
 65 
 66 Syntax:
 67 declare user_info_$absentee_request_id entry (fixed bin(71));
 68 call user_info_$absentee_request_id (request_id);
 69 
 70 
 71 Arguments:
 72 request_id
 73    is the request ID corresponding to this absentee process.  (Output)
 74    For an interactive or daemon process, the request_id returned is 0.
 75 
 76 
 77 :Entry: absentee_restarted: 03/30/86 user_info_$absentee_restarted
 78 
 79 
 80 Function: This entry point returns a bit indicating whether this
 81 absentee process has been restarted after a system crash.
 82 
 83 
 84 Syntax:
 85 declare user_info_$absentee_restarted entry (bit (1) aligned);
 86 call user_info_$absentee_restarted (restarted_bit);
 87 
 88 
 89 Arguments:
 90 restarted_bit
 91    is "1"b if this absentee process was restarted after a system
 92    crash, "0"b if not. See Notes. (Output).
 93 
 94 
 95 Notes:
 96 If this absentee process was restarted after a system crash, and the
 97 absout_truncation bit is on, truncation will not be performed. See
 98 user_info_$absout_truncation.
 99 
100 
101 :Entry:  absin:  03/08/85 user_info_$absin
102 
103 
104 Function:  This entry point returns the pathname of the absentee input
105 segment for an absentee job.  For an interactive user, the pathname is
106 returned as blanks.
107 
108 
109 Syntax:
110 declare user_info_$absin entry (char(*));
111 call user_info_$absin (path);
112 
113 
114 Arguments:
115 path
116    is the pathname of the absentee input segment (maximum of 168
117    characters).  (Output)
118 
119 
120 :Entry:  absout:  03/08/85 user_info_$absout
121 
122 
123 Function:  This entry point returns the pathname of the absentee output
124 segment for an absentee job.  For an interactive user, the pathname is
125 returned as blanks.
126 
127 
128 Syntax:
129 declare user_info_$absout entry (char(*));
130 call user_info_$absout (path);
131 
132 
133 Arguments:
134 path
135    is the pathname of the absentee output segment (maximum of 168
136    characters).  (Output)
137 
138 
139 :Entry: absout_truncation: 03/30/86 user_info_$absout_truncation
140 
141 
142 Function: This entry returns a bit indicating whether the absentee
143 process had the -truncate absout file argument requested.
144 
145 
146 Syntax:
147 declare user_info_$absout_truncation entry (bit (1) aligned);
148 call user_info_$absout_truncation (truncate_bit);
149 
150 
151 Arguments:
152 truncate_bit
153    is "1"b if the -truncate argument was used for the request which
154    created this absentee process, or "0"b if not. See Notes. (Output).
155 
156 
157 Notes:
158 If the absentee process has been restarted after a system crash, and the
159 truncate_absout bit is set, truncation will not be peoformed. See
160 user_info_$absentee_restarted.
161 
162 
163 :Entry:  attributes:  03/08/85 user_info_$attributes
164 
165 
166 Function:  This entry point returns a character string containing the
167 name of the user's attributes, each separated by a comma and a space,
168 and ending in a semicolon.  Attributes control such things as the ways
169 in which the user may log in, and the arguments that he is permitted to
170 give when logging in.  They are assigned by the project or system
171 administrator.  Login attributes are defined in the MAM Project
172 Administrator's manual.
173 
174 
175 Syntax:
176 declare user_info_$attributes entry (char(*) varying);
177 call user_info_$attributes (attr);
178 
179 
180 Arguments:
181 attr
182    is the string containing the names of the user's attributes.
183    (Output)
184 
185 
186 :Entry:  authorization_range:  03/08/85 user_info_$authorization_range
187 
188 
189 Function:  This entry point returns the range of authorizations at
190 which the calling user may create a process.
191 
192 
193 Syntax:
194 declare user_info_$authorization_range entry ((2) bit (72) aligned);
195 call user_info_$authorization_range (auth_range);
196 
197 
198 Arguments:
199 auth_range
200    represents the range of authorizations at which the user may log in.
201 
202 
203 :Entry:  homedir:  03/08/85 user_info_$homedir
204 
205 
206 Function:  This entry point returns the pathname of the user's initial
207 working directory.
208 
209 
210 Syntax:
211 declare user_info_$homedir entry (char(*));
212 call user_info_$homedir (hdir);
213 
214 
215 Arguments:
216 hdir
217    is the pathname of the user's home directory (maximum of 64
218    characters).  (Output)
219 
220 
221 :Entry:  limits:  03/08/85 user_info_$limits
222 
223 
224 Function:  This entry point returns the limit values established for
225 the user by the project administrator and also returns the user's
226 spending against these limits.
227 
228 If a limit is specified as open, the limit value returned is 1.0e37.
229 
230 
231 Syntax:
232 declare user_info_$limits entry (float bin, float bin, fixed bin(71),
233      fixed bin, (0:7) float bin, float bin, float bin,
234      (0:7) float bin);
235 call user_info_$limits (mlim, clim, cdate, crf, shlim, msp, csp, shsp);
236 
237 
238 Arguments:
239 mlim
240    is the dollar amount the user can spend in the month.  (Output)
241 clim
242    is the dollar amount the user can spend (cutoff limit).  (Output)
243 cdate
244    is the cutoff date.  (Output)
245 
246 
247 crf
248    is the cutoff refresh code.  (Output) This indicates what happens at
249    the cutoff date:
250    0   permanent cutoff
251    1   add one day
252    2   add one month
253    3   add one year
254    4   add one calendar year
255    5   add one fiscal year
256 
257 
258 shlim
259    is an array that shows the dollar amount the user can spend per
260    shift.  (Output)
261 msp
262    is the month-to-date spending in dollars.  (Output)
263 csp
264    is the spending against the cutoff limit in dollars.  (Output)
265 shsp
266    is the array of spending against shift limits in dollars.  (Output)
267 
268 
269 :Entry:  load_ctl_info:  03/08/85 user_info_$load_ctl_info
270 
271 
272 Function:  This entry point returns load control information for the
273 user.
274 
275 
276 Syntax:
277 declare user_info_$load_ctl_info entry (char(*), fixed bin,
278      fixed bin(71), fixed bin);
279 call user_info_$load_ctl_info (group, stby, preempt_time, weight);
280 
281 
282 Arguments:
283 group
284    is the name of the load control group.  (Output)
285 stby
286    indicates whether a user is a standby user (i.e., one who can be
287    preempted).  (Output)
288    1 can be preempted
289    0 cannot be preempted
290 preempt_time
291    is the clock time after which the user becomes standby.  (Output)
292 weight
293    is 10 times the user's weight.  (Output) Weight is a measure of the
294    load placed on the system by the user; most users have a weight of
295    1.
296 
297 
298 :Entry:  login_arg_count:  03/08/85 user_info_$login_arg_count
299 
300 
301 Function:  This entry point returns the number of arguments which were
302 provided to the process by the command responsible for the creation of
303 the process.  For an absentee process, arguments are given to the
304 enter_abs_request command, using the control argument -arguments.  For
305 interactive and daemon processes, arguments are specified on the login
306 command line, also using the control argument -arguments.
307 
308 
309 Syntax:
310 declare user_info_$login_arg_count entry (fixed bin, fixed bin (21),
311      fixed bin (21));
312 call user_info_$login_arg_count (count, max_length, total_length);
313 
314 
315 Arguments:
316 count
317    is a number representing the number of arguments supplied by the
318    command which caused the process creation.  (Output)
319 max_length
320    is the length of the longest login argument.  (Output)
321 total_length
322    is the total length of all the login arguments.  (Output)
323 
324 
325 :Entry:  login_arg_ptr:  03/08/85 user_info_$login_arg_ptr
326 
327 
328 Function:  This entry point returns a pointer to the character-string
329 login argument specified by the argument number, and also returns the
330 length of the argument-string.  See the description of
331 user_info_$login_arg_count for more information about login arguments.
332 
333 
334 Syntax:
335 declare user_info_$login_arg_ptr entry (fixed bin, ptr, fixed bin (21),
336      fixed bin (35));
337 call user_info_$login_arg_ptr (arg_no, arg_ptr, arg_len, code);
338 
339 
340 Arguments:
341 arg_no
342 is an integer specifying the number of the desired argument.
343    (Input)
344 arg_ptr
345    is a pointer to the unaligned character-string argument specified by
346    arg_no.  (Output)
347 arg_len
348    is the length (in characters) of the argument specified by arg_no.
349    (Output)
350 code
351    is a standard status code.  (Output) If the code error_table_$noarg
352    is returned, the values of arg_ptr and arg_len are undefined.
353 
354 
355 :Entry:  login_data:  03/08/85 user_info_$login_data
356 
357 
358 Function:  This entry point returns useful information about how the
359 user logged in.
360 
361 
362 Syntax:
363 declare user_info_$login_data entry (char(*), char(*), char(*),
364      fixed bin, fixed bin, fixed bin, fixed bin(71), char(*));
365 call user_info_$login_data (person_id, project_id, acct, anon, stby,
366      weight, time_login, login_word);
367 
368 
369 Arguments:
370 person_id
371    is the user's name from the login line (maximum of 22 characters).
372    (Output)
373 project_id
374    is the user's project identifier (maximum of 9 characters).
375    (Output)
376 acct
377    is the user's account identifier (maximum of 32 characters).
378    (Output)
379 anon
380    indicates whether a user is an anonymous user.  (Output)
381    1 is anonymous
382    0 is not anonymous
383 
384 
385 stby
386    indicates whether a user is a standby user (i.e., one who can be
387    preempted).  (Output)
388    1 can be preempted
389    0 cannot be preempted
390 weight
391    is 10 times the user's weight.  (Output) See the
392    user_info_$load_ctl_info entry point.
393 time_login
394    is the time the user logged in.  (Output) It is expressed as a
395    calendar clock reading in microseconds.
396 login_word
397    is "login" or "enter," depending on which command was used to log
398    in.  (Output)
399 
400 
401 :Entry:  logout_data:  03/08/85 user_info_$logout_data
402 
403 
404 Function:  This entry point returns information about how the user logs
405 out.
406 
407 
408 Syntax:
409 declare user_info_$logout_data entry (fixed bin(71), bit(36) aligned);
410 call user_info_$logout_data (logout_channel, logout_pid);
411 
412 
413 Arguments:
414 logout_channel
415    is the event channel over which logouts are to be signalled.
416    (Output)
417 logout_pid
418    is the process identifier of the answering service.  (Output)
419 
420 
421 :Entry:  outer_module:  03/08/85 user_info_$outer_module
422 
423 
424 Function:  This entry point returns the name of the user's outer
425 module.
426 
427 
428 Syntax:
429 declare user_info_$outer_module entry (char(*));
430    call user_info_$outer_module (om);
431 
432 
433 Arguments:
434 om
435    is the name of the user's outer module (maximum of 32 characters).
436    (Output) The outer module is the initial I/O module attached to the
437    user_i/o switch.
438 
439 
440 :Entry:  process_type:  03/08/85 user_info_$process_type
441 
442 
443 Function:  This entry point returns information about the type of the
444 current process.
445 
446 
447 Syntax:
448 declare user_info_$process_type entry (fixed bin (17));
449 call user_info_$process_type (process_type);
450 
451 
452 Arguments:
453 process_type
454    is the type of the user's current process.  (Output) It can be:
455    1   interactive
456    2   absentee
457    3   daemon
458 
459 
460 :Entry:  responder:  03/08/85 user_info_$responder
461 
462 
463 Function:  The user_info_$responder entry point returns the name of the
464 user's login responder.
465 
466 
467 Syntax:
468 declare user_info_$responder entry (char(*));
469 call user_info_$responder (resp);
470 
471 
472 Arguments:
473 resp
474    is the name of the user's login responder (maximum of 64
475    characters).  (Output)
476 
477 
478 :Entry:  ring_range:  12/07/87 user_info_$ring_range
479 
480 Function:  This entry returns the range of the user's authorized login
481 ring level.
482 
483 
484 Syntax:
485 dcl user_info_$ring_range entry ((2) fixed bin);
486 call user_info_$ring_range (ring_range);
487 
488 
489 Arguments:
490 ring_range
491    is the range (1 to 7) of the user's authorized login ring.
492 
493 
494 :Entry:  rs_name:  03/08/85 user_info_$rs_name
495 
496 
497 Function:  This entry returns the name of the rate structure that is in
498 effect for the process in which the call is made.
499 
500 
501 Syntax:
502 dcl user_info_$rs_name entry (char (*));
503 call user_info_$rs_name (rs_name);
504 
505 
506 Arguments:
507 rs_name
508    is the name of the rate structure in effect for this process.
509    (Output) (The name may be up to 32 characters long).
510 
511 
512 :Entry:  rs_number:  03/08/85 user_info_$rs_number
513 
514 
515 Function:  This entry returns the number of the rate structure that is
516 in effect for the process in which the call is made.
517 
518 
519 Syntax:
520 dcl user_info_$rs_number entry (fixed bin (9));
521 call user_info_$rs_number (rs_number);
522 
523 
524 Arguments:
525 rs_number
526    is the number of the rate structure in effect for this process.
527    (Output)
528 
529 
530 :Entry:  service_type:  03/08/85 user_info_$service_type
531 
532 
533 Function:  This entry point returns the service type of the terminal on
534 which the user logged in.
535 
536 
537 Syntax:
538 declare user_info_$service_type entry (fixed bin);
539 call user_info_$service_type (type);
540 
541 
542 Arguments:
543 type
544    is a number representing the service type of the user's terminal.
545    (Output) It can be:
546    1  login type; interactive command level.
547    2  FTP type; Advanced Research Projects Agency Network (ARPANET)
548       file transfer protocol
549 
550 
551 :Entry:  terminal_data:  03/08/85 user_info_$terminal_data
552 
553 
554 Function:  This entry point returns information about the terminal on
555 which the user is logged in.
556 
557 
558 Syntax:
559 declare user_info_$terminal_data entry (char(*), char(*), char(*),
560      fixed bin, char(*));
561 call user_info_$terminal_data (id_code, type, channel, line_type,
562      charge_type);
563 
564 
565 Arguments:
566 id_code
567    is the identifier code of the user's terminal (maximum of 4
568    characters).  (Output)
569 type
570    is the type of terminal as it was at login time.  (Output)
571 channel
572    is the channel identification (maximum of 32 characters).  (Output)
573 line_type
574    is the line type associated with the channel.  (Output)
575 charge_type
576    is the name of the device charge associated with the user's login
577    terminal (maximum of 8 characters).  (Output) The rate can be found
578    in the array returned by system_info_$device_prices.
579 
580 
581 :Entry:  usage_data:  03/08/85 user_info_$usage_data
582 
583 
584 Function:  This entry point returns user usage data.
585 
586 
587 Syntax:
588 declare user_info_$usage_data entry (fixed bin, fixed bin(71),
589      fixed bin(71), fixed bin(71), fixed bin(71), fixed bin(71));
590 call user_info_$usage_data (nproc, old_cpu, time_login, time_create,
591      old_mem, old_io_ops);
592 
593 
594 Arguments:
595 nproc
596    is the number of processes created for this login session.  (Output)
597 old_cpu
598    is the CPU time used by previous processes in the login session.
599    (Output)
600 time_login
601    is the time the user logged in.  (Output) It is expressed as a
602    calendar clock reading in microseconds.
603 
604 
605 time_create
606    is the time that the current process was created.  (Output)
607 old_mem
608    is the memory usage by previous processes in this login session.
609    (Output)
610 old_io_ops
611    is the number of terminal I/O operations by previous processes in
612    this login session.  (Output)
613 
614 
615 :Entry:  whoami:  03/08/85 user_info_$whoami
616 
617 
618 Function:  The user_info_$whoami entry point is the same as the
619 user_info_ entry point.  The name is a mnemonic device added for
620 convenience.
621 
622 
623 Syntax:
624 declare user_info_$whoami entry (char(*), char(*), char(*));
625 call user_info_$whoami (person_id, project_id, acct);
626 
627 
628 Arguments:
629 person_id
630    is the user's name from the login line (maximum of 22 characters).
631    (Output)
632 project_id
633    is the user's project identifier (maximum of 9 characters).
634    (Output)
635 acct
636    is the user's account identifier (maximum of 32 characters).
637    (Output)