1 01/07/86  cu_
   2 
   3 
   4 Entry points in cu_:
   5    (List is generated by the help command)
   6 
   7 
   8 :Entry:  af_arg_count:  03/05/85 cu_$af_arg_count
   9 
  10 
  11 Function: This entry point should be called by an active function.
  12 It returns to its caller the number of arguments passed to the
  13 caller by its caller, not including the active function return
  14 argument.  If the caller has not been invoked as an active
  15 function, a standard status code is returned, and, if the code is
  16 error_table_$not_act_fnc, nargs is the number of arguments in the
  17 call (similar to the cu_$arg_count entry point described below).
  18 
  19 
  20 Syntax:
  21 declare cu_$af_arg_count entry (fixed bin, fixed bin(35));
  22 call cu_$af_arg_count (nargs, code);
  23 
  24 
  25 Arguments:
  26 nargs
  27    is the number of input arguments passed to the caller.  (Output)
  28 code
  29    is a standard status code.  (Output)
  30    error_table_$nodescr
  31         no argument descriptors were passed to the caller or an
  32         incorrect argument list header was encountered.
  33    error_table_$not_act_fnc
  34         the caller was not invoked as an active function.
  35 
  36 
  37 Notes:  This entry point and the five following entry points beginning
  38 with $af_ have been provided so that active functions need not have
  39 knowledge of the mechanism for returning arguments.
  40 
  41 The entry points cu_$af_arg_count and cu_$af_arg_count_rel are retained
  42 for historical reasons; active function procedures should call
  43 cu_$af_return_arg and cu_$af_return_arg_rel instead to obtain the
  44 location and maximum length of the return argument as well as the
  45 arg_count.  This information will be needed for the active function to
  46 return a value.  When the procedure is invoked as an active function,
  47 the value of arg_count returned by cu_$af_arg_count will be one less
  48 than the value returned by cu_$arg_count, otherwise they will be the
  49 same.
  50 
  51 
  52 :Entry:  af_arg_count_rel:  03/05/85 cu_$af_arg_count_rel
  53 
  54 
  55 Function: This entry point is similar to cu_$af_arg_count, but
  56 instead of looking in the argument list of its caller, it is given
  57 a pointer to the argument list.
  58 
  59 
  60 Syntax:
  61 declare cu_$af_arg_count_rel entry (fixed bin, ptr, fixed bin(35));
  62 call cu_$af_arg_count_rel (nargs, arg_list_ptr, code);
  63 
  64 
  65 Arguments:
  66 nargs
  67    is the number of input arguments passed to the caller.  (Output)
  68 arg_list_ptr
  69    is a pointer to an argument list.  (Input)
  70 code
  71    is a standard status code.  (Output)
  72    error_table_$nodescr
  73         no argument descriptors were passed to the caller or an
  74         incorrect argument list header was encountered
  75    error_table_$not_act_fnc
  76         the caller was not invoked as an active function
  77 
  78 
  79 :Entry:  af_arg_ptr:  03/05/85 cu_$af_arg_ptr
  80 
  81 
  82 Function: This entry point assumes it has been called by an active
  83 function.  It operates in the same fashion as cu_$arg_ptr
  84 (described below), except that it verifies that the caller was
  85 invoked as an active function, and does not allow the return
  86 argument to be accessed.  If the (i+1)st argument does not exist,
  87 the code error_table_$noarg is returned.  The return argument is
  88 always the last one; thus, use of this entry point and
  89 cu_$af_return_arg allows the active function to be independent of
  90 the position of the return argument in the argument list (see
  91 "Notes" under cu_$af_arg_count above).
  92 
  93 
  94 Syntax:
  95 declare cu_$af_arg_ptr entry (fixed bin, ptr, fixed bin(21),
  96      fixed bin(35));
  97 call cu_$af_arg_ptr (arg_no, arg_ptr, arg_len, code);
  98 
  99 
 100 Arguments:
 101 arg_no
 102    is the number of the desired argument.  (Input)
 103 arg_ptr
 104    is a pointer to the unaligned character-string argument specified by
 105    arg_no.  (Output) It is set to the null value if any error is
 106    encountered.
 107 arg_len
 108    is the length (in characters) of the argument specified by arg_no.
 109    (Output) It is set to 0 if any error is encountered.
 110 
 111 
 112 code
 113    is a standard status code.  (Output)
 114    error_table_$nodescr
 115         the argument list does not contain descriptors.  In this case,
 116         arg_len is set to zero.
 117    error_table_$not_act_fnc
 118         the caller was not invoked as an active function.
 119    error_table_$noarg
 120         the program does not have an arg_no'th argument.  In this case,
 121         arg_ptr is set to null and arg_len is set to zero.
 122 
 123 
 124 :Entry:  af_arg_ptr_rel:  03/05/85 cu_$af_arg_ptr_rel
 125 
 126 
 127 Function: This entry point is similar to cu_$af_arg_ptr but
 128 instead of looking in the argument list of its caller, it is given
 129 a pointer to the argument list.
 130 
 131 
 132 Syntax:
 133 declare cu_$af_arg_ptr_rel entry (fixed bin, ptr, fixed bin(21),
 134      fixed bin(35), ptr);
 135 call cu_$af_arg_ptr_rel (arg_no, arg_ptr, arg_len, code, arg_list_ptr);
 136 
 137 
 138 Arguments:
 139 arg_no
 140    is the number of the desired argument.  (Input)
 141 arg_ptr
 142    is a pointer to the unaligned character-string argument specified by
 143    arg_no.  (Output) It is set to the null value if any error is
 144    encountered.
 145 arg_len
 146    is the length (in characters) of the argument specified by arg_no.
 147    (Output) It is set to 0 if any error is encountered.
 148 arg_list_ptr
 149    is a pointer to an argument list.  (Input)
 150 
 151 
 152 code
 153    is a standard status code.  (Output)
 154    error_table_$nodescr
 155         the argument list does not contain descriptors.  In this case,
 156         arg_len is set to zero.
 157    error_table_$not_act_fnc
 158         the caller was not invoked as an active function.
 159    error_table_$noarg
 160         the program does not have an arg_no'th argument.  In this case,
 161         arg_ptr is set to null and arg_len is set to zero.
 162 
 163 
 164 :Entry:  af_return_arg:  03/05/85 cu_$af_return_arg
 165 
 166 
 167 Function: This entry point assumes it has been called by an active
 168 function.  It makes the active function's return argument
 169 available as described in "Notes" below.  It is provided to permit
 170 writing of active functions that accept an arbitrary number of
 171 arguments (see "Notes" under cu_$af_arg_count above).
 172 
 173 
 174 Syntax:
 175 declare cu_$af_return_arg entry (fixed bin, ptr, fixed bin(21),
 176      fixed bin(35));
 177 declare return_string char (max_length) varying based (rtn_string_ptr);
 178 call cu_$af_return_arg (nargs, rtn_string_ptr, max_length, code);
 179 
 180 
 181 Arguments:
 182 nargs
 183    is the number of input arguments passed to the caller.  (Output)
 184 rtn_string_ptr
 185    is a pointer to the varying return argument of the active function.
 186    (Output)
 187 max_length
 188    is the maximum length of the varying string pointed to by
 189    rtn_string_ptr.  (Output)
 190 
 191 code
 192    is a standard status code.  (Output)
 193    error_table_$nodescr
 194         no argument descriptors were passed to the caller or an
 195         incorrect argument list header was encountered.
 196    error_table_$not_act_fnc
 197         the caller was not invoked as an active function.
 198 
 199 
 200 Notes:  An active function that takes an arbitrary number of arguments
 201 uses this entry point to return a value.  It calls the entry point to
 202 get a pointer to the return argument and to get its maximum length.  It
 203 declares the based varying string, return_string, as described above.
 204 It then assigns its return value to return_string.  Even if
 205 error_table_$not_act_fnc is returned, nargs will be set to the proper
 206 value.
 207 
 208 
 209 :Entry:  af_return_arg_rel:  03/05/85 cu_$af_return_arg_rel
 210 
 211 
 212 Function: This entry point is similar to cu_$af_return_arg, but
 213 instead of looking in the argument list of its caller, it is given
 214 a pointer to the argument list.
 215 
 216 
 217 Syntax:
 218 declare cu_$af_return_arg_rel entry (fixed bin, ptr, fixed bin(21),
 219      fixed bin(35), ptr);
 220 call cu_$af_return_arg_rel (nargs, rtn_string_ptr, max_length, code,
 221      arg_list_ptr);
 222 
 223 
 224 Arguments:
 225 nargs
 226    is the number of input arguments passed to the caller.  (Output)
 227 arg_list_ptr
 228    is a pointer to an argument list.  (Input)
 229 rtn_string_ptr
 230    is a pointer to the varying return argument of the active function.
 231    (Output)
 232 max_len
 233    is the maximum length of the varying string pointed to by
 234    rtn_string_ptr.  (Output)
 235 
 236 
 237 code
 238    is a standard status code.  (Output)
 239    error_table_$nodescr
 240         no argument descriptors were passed to the caller or an
 241         incorrect argument list header was encountered.
 242    error_table_$not_act_fnc
 243         the caller was not invoked as an active function.
 244 
 245 
 246 :Entry:  arg_count:  03/05/85 cu_$arg_count
 247 
 248 
 249 Function: The cu_$arg_count entry point can be used by any
 250 procedure to determine the number of arguments with which it was
 251 called.
 252 
 253 
 254 Syntax:
 255 declare cu_$arg_count entry (fixed bin, fixed bin (35));
 256 call cu_$arg_count (arg_count, code);
 257 
 258 
 259 Arguments:
 260 arg_count
 261    is the number of arguments.  (Output)
 262 code
 263    is a standard status code.  (Output)
 264    error_table_$nodescr
 265         no argument descriptors were passed to the caller or an
 266         incorrect argument list header was encountered.
 267    error_table_$active_function
 268         the caller was invoked as an active function.
 269 
 270 
 271 Notes:  Even if the code is nonzero, arg_count may still be valid.  If
 272 error_table_$active_function is returned, the arg_count will be the
 273 total number of arguments, including the active function return
 274 argument.  This number may differ from that returned by
 275 cu_$af_return_arg, described below.  This entry point is intended for
 276 use with command procedures that may not be used as active functions.
 277 
 278 For compatibility with old programs, the code argument may be omitted.
 279 
 280 
 281 :Entry:  arg_count_rel:  03/05/85 cu_$arg_count_rel
 282 
 283 
 284 Function: This entry point returns the number of arguments in any
 285 specified argument list.
 286 
 287 
 288 Syntax:
 289 declare cu_$arg_count_rel entry (fixed bin, ptr, fixed bin (35));
 290 call cu_$arg_count_rel (arg_count, arg_list_ptr, code);
 291 
 292 
 293 Arguments:
 294 arg_count
 295    is the number of arguments.  (Output)
 296 arg_list_ptr
 297    is a pointer to an argument list.  (Input) This pointer can be
 298    obtained by calling cu_$arg_list_ptr, described below.
 299 code
 300    is a standard status code.  (Output)
 301    error_table_$nodescr
 302         no argument descriptors were passed to the owner of the
 303         argument list or an incorrect argument list header was
 304         encountered.
 305    error_table_$active_function
 306         the owner of the argument list was invoked as an active
 307         function.
 308 
 309 
 310 :Entry:  arg_list_ptr:  03/05/85 cu_$arg_list_ptr
 311 
 312 
 313 Function: It is sometimes desirable to design a PL/I procedure to
 314 accept a variable number of arguments of varying data types (e.g.,
 315 the ioa_ subroutine).  In these cases, the PL/I procedure must be
 316 able to interrogate its argument list directly to determine the
 317 number, type, and location of each argument.  The cu_$arg_list_ptr
 318 entry point is designed for use in such cases and returns a
 319 pointer to the argument list of its caller.
 320 
 321 
 322 Syntax:
 323 declare cu_$arg_list_ptr entry (ptr);
 324 call cu_$arg_list_ptr (arg_list_ptr);
 325 
 326 
 327 Arguments:
 328 arg_list_ptr
 329    is a pointer to the argument list of the caller.  (Output)
 330 
 331 
 332 :Entry:  arg_ptr:  03/05/85 cu_$arg_ptr
 333 
 334 
 335 Function: The cu_$arg_ptr entry point is used by a command or
 336 subroutine that can be called with a varying number of arguments,
 337 each of which is a variable-length unaligned character string
 338 (i.e., declared char(*)).  This entry point returns a pointer to
 339 the character-string argument specified by the argument number and
 340 also returns the length of the argument.
 341 
 342 
 343 Syntax:
 344 declare cu_$arg_ptr entry (fixed bin, ptr, fixed bin(21), fixed
 345      bin(35));
 346 call cu_$arg_ptr (arg_no, arg_ptr, arg_len, code);
 347 
 348 
 349 Arguments:
 350 arg_no
 351    is an integer specifying the number of the desired argument.
 352    (Input)
 353 arg_ptr
 354    is a pointer to the unaligned character-string argument specified by
 355    arg_no.  (Output)
 356 arg_len
 357    is the length (in characters) of the argument specified by arg_no.
 358    (Output)
 359 
 360 
 361 code
 362    is a standard status code.  (Output)
 363    error_table_$nodescr
 364         the argument list does not contain descriptors.  In this case,
 365         argl_len set is to zero.
 366    error_table_$noarg
 367         the program does not have an arg_no'th argument.  In this case,
 368         arg_ptr is set to null and arg_len is set to zero.
 369 
 370 
 371 Notes:  The command or subroutine that uses this entry point must be
 372 called with data descriptors for its arguments.  Otherwise, the
 373 returned value of arg_len is 0.  If the argument specified by arg_no is
 374 not a character string, arg_len is the value of the "size" field of the
 375 descriptor (the rightmost 24 bits).  This entry point must not be
 376 called from an internal procedure that has its own stack frame or from
 377 within a begin block (because cu_$arg_ptr does not check for a display
 378 pointer).
 379 
 380 
 381 :Entry:  arg_ptr_rel:  03/05/85 cu_$arg_ptr_rel
 382 
 383 
 384 Function: Some PL/I procedures may need to reference arguments
 385 passed to other procedures.  This entry point permits a procedure
 386 to reference arguments in any specified argument list.
 387 
 388 
 389 Syntax:
 390 declare cu_$arg_ptr_rel entry (fixed bin, ptr, fixed bin(21),
 391      fixed bin(35), ptr);
 392 call cu_$arg_ptr_rel (arg_no, arg_ptr, arg_len, code, arg_list_ptr);
 393 
 394 
 395 Arguments:
 396 arg_no
 397    is an integer specifying the number of the desired argument.
 398    (Input)
 399 arg_ptr
 400    is a pointer to the unaligned character-string argument specified by
 401    arg_no.  (Output)
 402 arg_len
 403    is the length (in characters) of the argument specified by arg_no.
 404    (Output)
 405 
 406 
 407 code
 408    is a standard status code.  (Output)
 409    error_table_$nodescr
 410         the argument list does not contain descriptors.  In this case,
 411         argl_len is set to zero.
 412    error_table_$noarg
 413         the program does not have an arg_no'th argument.  In this case,
 414         arg_ptr is set to null and arg_len is set to zero.
 415   arg_list_ptr
 416      is a pointer to the argument list from which this argument is
 417      being extracted.  (Input) This pointer can be determined by
 418      calling cu_$arg_list_ptr in the program whose argument list is to
 419      be processed and then passing it to the program requesting
 420      reference to the argument list.
 421 
 422 
 423 :Entry:  caller_ptr:  03/05/85 cu_$caller_ptr
 424 
 425 
 426 Function: This entry point allows a routine to obtain a pointer to
 427 its caller.  The pointer that is returned points to the
 428 instruction within the text section after the instruction that
 429 called out.
 430 
 431 
 432 Syntax:
 433 declare cu_$caller_ptr entry (ptr);
 434 call cu_$caller_ptr (caller_ptr);
 435 
 436 
 437 Arguments:
 438 caller_ptr
 439    is a pointer into the text section of the caller.  (Output) If null,
 440    the invoker of the cu_ subroutine has no caller.
 441 
 442 
 443 :Entry:  cl:  03/05/85 cu_$cl
 444 
 445 
 446 Function: The cu_$cl entry point is called by all standard error
 447 handlers after printing a diagnostic message.  This entry point
 448 passes control to the procedure specified by the last call to
 449 cu_$set_cl_intermediary.  It takes an optional argument which is
 450 passed directly to that procedure.  If no such procedure has been
 451 specified (the norm), control is passed to the standard procedure,
 452 which establishes a new command level (see Notes below).
 453 
 454 
 455 Syntax:
 456 declare cu_$cl entry (1 aligned, 2 bit(1) unaligned, 2 bit(35)
 457      unaligned);
 458 dcl 1 flags         aligned,
 459       2 reset_sw  bit (1) unaligned,
 460       2 mbz       bit (35) unaligned;
 461 call cu_$cl (flags);
 462 
 463 
 464 Arguments:
 465 flags.reset_sw
 466    specifies whether the intermediary procedure should perform a
 467    "resetread" control order on the standard "user_i/o" I/O switch.
 468    (Input)
 469    "1"b do a "resetread" operation,
 470    "0"b do not perform a "resetread" operation.
 471 flags.mbz
 472    is reserved for future use and must be "0"b.  (Input)
 473 
 474 
 475 Notes:  If no argument is given, cu_$cl passes a static argument with
 476 flags.reset_sw set to "1"b.
 477 
 478 Establishing a new command level consists of saving the attachments of
 479 the standard I/O switches (user_input, user_output, and error_output),
 480 restoring these attachments to their default state, and entering a new
 481 loop of reading and executing command lines.  If the "start" command is
 482 issued, the attachments of the standard I/O switches are restored to
 483 the state saved above and control is returned to the caller of cu_$cl
 484 to continue from the interrupted exection.  If the "release" command is
 485 issued, the interrupted execution is aborted, the I/O switches are not
 486 restored, and control is returned to the previous command level.
 487 
 488 
 489 :Entry:  cp:  03/05/85 cu_$cp
 490 
 491 
 492 Function: The cu_$cp entry point, called when a Multics command
 493 line is recognized, passes the command line to the currently
 494 defined command processor for processing.  Some standard Multics
 495 commands (e.g., qedx) permit the user to escape from them to
 496 execute other commands.  In this case, the escapable command
 497 passes the line to be executed to the command processor.  The
 498 cu_$cp entry point is called by any standard command that
 499 recognizes other Multics command lines.
 500 
 501 
 502 Syntax:
 503 declare cu_$cp entry (ptr, fixed bin(21), fixed bin(35));
 504 call cu_$cp (line_ptr, line_len, code);
 505 
 506 
 507 Arguments:
 508 line_ptr
 509    is a pointer to the beginning of a character string containing a
 510    command line to be processed.  (Input)
 511 line_len
 512    is the length of the command line in characters.  (Input)
 513 code
 514    is a standard status code or the nonstandard code 100.  (Output) If
 515    an error has been detected, the caller of the cu_$cp entry point is
 516    not expected to print a diagnostic at this time since it can be
 517    expected that the command processor has already done so.  A returned
 518    code of 100 indicates that the command line is blank and no ready
 519    message should be printed.
 520 
 521 
 522 :Entry:  evaluate_active_string:  03/05/85 cu_$evaluate_active_string
 523 
 524 
 525 Function: This entry point evaluates an active string.  An active
 526 string consists of one or more active function invocations and
 527 their arguments.  Other entries are provided for subsystem writers
 528 to specify the procedure to be called by this entry.
 529 
 530 
 531 Syntax:
 532 declare cu_$evaluate_active_string entry (ptr, char(*), fixed bin,
 533      char(*) varying, fixed bin (35));
 534 call cu_$evaluate_active_string (info_ptr, active_string, string_type,
 535      return_value, code);
 536 
 537 
 538 Arguments:
 539 info_ptr
 540    is reserved for future expansion and must be null.  (Input)
 541 active_string
 542    is the active string to be evaluated.  (Input) It should not include
 543    the outermost brackets.
 544 
 545 
 546 string_type
 547    specifies the type of active string to be evaluated.  (Input) Its
 548    possible values are:
 549      NORMAL_ACTIVE_STRING
 550         the active string return value should be rescanned for all
 551         command processor constructs.  ([...])
 552      TOKENS_ONLY_ACTIVE_STRING
 553         the active string return value should be rescanned only for
 554         whitespace and quotes.  (|[...])
 555      ATOMIC_ACTIVE_STRING
 556         the active string return value should not be rescanned.
 557         (||[...])
 558 
 559 
 560 return_value
 561    is the result of the evaluation.  (Output)
 562 code
 563    is a standard system status code.  (Output) If its value is
 564    error_table_$command_line_overflow, the maximum length of the
 565    return_value argument was not large enough to hold the result of the
 566    evaluation.  In this case, the result will be truncated.
 567 
 568 
 569 Notes:  The constants used above for string_type are defined in the
 570 cp_active_string_types.incl.pl1 include file.  The active string should
 571 not be enclosed in brackets.
 572 
 573 
 574 :Entry:  generate_call:  03/05/85 cu_$generate_call
 575 
 576 
 577 Function: The cu_$generate_call entry point is used to generate a
 578 standard call to a specified procedure with a specified argument
 579 list.  This call is designed for cases in which a PL/I procedure
 580 has explicitly built an argument list from its input data.  The
 581 principal use of this entry is by command processors that call a
 582 command with an argument list built from a command line input from
 583 a terminal.
 584 
 585 
 586 Syntax:
 587 declare cu_$generate_call entry (entry, ptr);
 588 call cu_$generate_call (proc_entry, a_ptr);
 589 
 590 
 591 Arguments:
 592 proc_entry
 593    is the procedure entry point to be called.  (Input)
 594 a_ptr
 595    is a pointer to the argument list to be passed to the called
 596    procedure.  (Input)
 597 
 598 
 599 :Entry:  get_cl_intermediary:  03/05/85 cu_$get_cl_intermediary
 600 
 601 
 602 Function: This entry point returns to the caller the procedure
 603 entry currently being invoked by a call to cu_$cl.
 604 
 605 
 606 Syntax:
 607 declare cu_$get_cl_intermediary entry (entry);
 608 call cu_$get_cl_intermediary (proc_entry);
 609 
 610 
 611 Arguments:
 612 proc_entry
 613    is the procedure entry being called by the standard error handlers
 614    after printing a diagnostic message.  (Output)
 615 
 616 
 617 :Entry:  get_command_name:  01/07/86 cu_$get_command_name
 618 
 619 
 620 Function: This entrypoint allows a routine entered via the command
 621 processor to obtain the name used on the command line to invoke
 622 the procedure.  The values returned are as follows:
 623 
 624 Name used on command line               Returned Value
 625 -------------------------               --------------
 626 
 627 name                                    name
 628 path>name                               path>name
 629 name$entrypoint                         name$entrypoint
 630 path>name$entrypoint                    path>name$entrypoint
 631 
 632 
 633 Syntax:
 634 declare cu_$get_command_name entry (ptr, fixed bin (21),
 635         fixed bin(35));
 636 call cu_$get_command_name (command_name_ptr,
 637      command_name_length, error_code);
 638 
 639 
 640 Arguments:
 641 command_name_ptr
 642    Is a pointer to the command name of length name_length.  If
 643    null, the command name is unavailable for the current
 644    routine.  (Output)
 645 
 646 command_name_length
 647    Is the length of the returned command name.  If zero the
 648    command name is unavailable for the current routine.
 649    (Output)
 650 
 651 error_code
 652    Is a standard status code.  If the command name is
 653    unavailable its value is equal to
 654    error_table_$no_command_name_available.  (Output)
 655 
 656 
 657 :Entry:  get_command_name_rel:  01/07/86 cu_$get_command_name_rel
 658 
 659 
 660 Function: This entrypoint allows a routine entered via the command
 661 processor to obtain the name used on the command line to invoke
 662 the procedure.  The values returned are as follows:
 663 
 664 Name used on command line               Returned Value
 665 -------------------------               --------------
 666 
 667 name                                    name
 668 path>name                               path>name
 669 name$entrypoint                         name$entrypoint
 670 path>name$entrypoint                    path>name$entrypoint
 671 
 672 
 673 Syntax:
 674 declare cu_$get_command_name_rel entry (ptr, fixed bin (21),
 675         fixed bin(35), ptr);
 676 call cu_$get_command_name_rel (command_name_ptr,
 677      command_name_length, error_code, arglist_ptr);
 678 
 679 
 680 Arguments:
 681 command_name_ptr
 682    Is a pointer to the command name of length name_length.  If
 683    null, the command name is unavailable for the current
 684    routine.  (Output)
 685 
 686 command_name_length
 687    Is the length of the returned command name.  If zero the
 688    command name is unavailable for the current routine.
 689    (Output)
 690 
 691 error_code
 692    Is a standard status code.  If the command name is
 693    unavailable its value is equal to
 694    error_table_$no_command_name_available.  (Output)
 695 
 696 arglist_ptr
 697    Is a pointer to the argument list from which this argument
 698    is being extracted.  This pointer can be determined by
 699    calling cu_$arg_list_ptr in the program whose argument list
 700    is to be processed and then passing it to the program
 701    requesting reference to the argument list.  (Input)
 702 
 703 
 704 :Entry:  get_command_processor:  03/05/85 cu_$get_command_processor
 705 
 706 
 707 Function: This entry point returns to the caller the entry value
 708 of the procedure currently being invoked by a call to cu_$cp.
 709 
 710 
 711 Syntax:
 712 declare cu_$get_command_processor entry (entry);
 713 call cu_$get_command_processor (proc_entry);
 714 
 715 
 716 Arguments:
 717 proc_entry
 718    is the procedure entry point to which control is passed upon
 719    receiving a call to cu_$cp.  (Output)
 720 
 721 
 722 :Entry:  get_evaluate_active_string: 03/05/85 cu_$get_evaluate_active_string
 723 
 724 
 725 Function: This entry point returns to the caller the entry value
 726 of the procedure currently being invoked by a call to
 727 cu_$evaluate_active_string.
 728 
 729 
 730 Syntax:
 731 declare cu_$get_evaluate_active_string entry (entry);
 732 call cu_$get_evaluate_active_string (active_string_procedure);
 733 
 734 
 735 Arguments:
 736 active_string_procedure
 737    is the procedure entry point to which control is passed upon
 738    receiving a call to cu_$evaluate_active_string.  (Output)
 739 
 740 
 741 :Entry:  get_ready_mode:  03/05/85 cu_$get_ready_mode
 742 
 743 
 744 Function: This entry point returns the value of the internal
 745 static ready flags.
 746 
 747 
 748 Syntax:
 749 declare cu_$get_ready_mode entry (1 aligned, 2 bit(1) unaligned,
 750      2 bit(35) unaligned);
 751 dcl 1 mode aligned,
 752       2 ready_sw bit(1) unaligned,
 753       2 mbz bit(35) unaligned;
 754 call cu_$get_ready_mode (mode)
 755 
 756 
 757 Arguments:
 758 mode.ready_sw
 759    is the current value of the static ready switch.  (Output)
 760    "1"b print ready message.
 761    "0"b do not print ready message.
 762 mode.mbz
 763    is reserved for future use and must be "0"b.  (Output)
 764 
 765 
 766 :Entry:  get_ready_procedure:  03/05/85 cu_$get_ready_procedure
 767 
 768 
 769 Function: This entry point returns the entry value of the current
 770 ready procedure of the process.
 771 
 772 
 773 Syntax:
 774 declare cu_$get_ready_procedure entry (entry);
 775 call cu_$get_ready_procedure (ready_entry);
 776 
 777 
 778 Arguments:
 779 ready_entry
 780    is the current ready procedure.  (Output)
 781 
 782 
 783 :Entry:  grow_stack_frame:  03/05/85 cu_$grow_stack_frame
 784 
 785 
 786 Function: This entry point allows its caller to allocate temporary
 787 storage by extending the caller's current stack frame.
 788 
 789 
 790 Syntax:
 791 declare cu_$grow_stack_frame entry (fixed bin, ptr, fixed bin(35));
 792 call cu_$grow_stack_frame (len, data_ptr, code);
 793 
 794 
 795 Arguments:
 796 len
 797    is the length (in words) by which the caller's stack frame is to be
 798    extended.  (Input) The standard Multics call, push, and return
 799    discipline requires that stack frames begin on mod 16 word
 800    boundaries.  Therefore, if len is not a mod 16 number, the stack
 801    frame is grown by the next mod 16 quantity greater than len.
 802 data_ptr
 803    is a pointer to the first location of len words allocated in the
 804    caller's stack frame.  (Output)
 805 code
 806    is a standard status code.  (Output)
 807 
 808 
 809 Notes:  The cu_$grow_stack_frame and cu_$shrink_stack_frame entry
 810 points are for advanced subsystems writers only and should be used only
 811 when absolutely necessary.  Most PL/I programs can be written to use
 812 begin blocks to allocate extra storage in the current stack frame.  The
 813 entry points rely on internal workings of the PL/I compiler that are
 814 not guaranteed to continue working forever.
 815 
 816 
 817 :Entry:  level_get:  03/05/85 cu_$level_get
 818 
 819 
 820 Function: The cu_$level_get entry point is used to obtain the
 821 current ring validation level.  This entry point is normally used
 822 prior to a call to cu_$level_set to save the current validation
 823 level.
 824 
 825 
 826 Syntax:
 827 declare cu_$level_get entry (fixed bin);
 828 call cu_$level_get (level);
 829 
 830 
 831 Arguments:
 832 level
 833    is the current ring validation level.  (Output)
 834 
 835 
 836 :Entry:  level_set:  03/05/85 cu_$level_set
 837 
 838 
 839 Function: The cu_$level_set entry point is used to change the
 840 current protection ring validation level.  This entry point is
 841 useful for procedures that must distinguish the periods of time
 842 when the procedure is acting in behalf of itself (i.e., its own
 843 ring) and when it is acting in behalf of another procedure that
 844 can be in an outer (i.e., less privileged) protection ring.
 845 
 846 
 847 Syntax:
 848 declare cu_$level_set entry (fixed bin);
 849 call cu_$level_set (level);
 850 
 851 
 852 Arguments:
 853 level
 854    specifies the new protection validation level and must be greater
 855    than or equal to the current ring number.  (Input) The current ring
 856    number can be determined by the get_ring_ subroutine.
 857 
 858 
 859 :Entry:  make_entry_value:  03/05/85 cu_$make_entry_value
 860 
 861 
 862 Function: The cu_$make_entry_value entry point constructs a PL/I
 863 entry value from a pointer to an entry point.  The environment
 864 pointer of the entry value will be null, so the entry point
 865 pointer must point to an external procedure.
 866 
 867 
 868 Syntax:
 869 declare cu_$make_entry_value entry (pointer, entry);
 870 call cu_$make_entry_value (ep_ptr, entry_value);
 871 
 872 
 873 Arguments:
 874 ep_ptr
 875    is the entry point pointer.  (Input)
 876 entry_value
 877    is the entry value.  (Output)
 878 
 879 
 880 :Entry:  ready_proc:  03/05/85 cu_$ready_proc
 881 
 882 
 883 Function: The ready_proc entry point is used to call the current
 884 ready procedure of the process.  It takes an optional argument,
 885 which it passes to the ready procedure.  The ready procedure is
 886 automatically invoked by the listener after each command line is
 887 processed.  The ready procedure of the standard command
 888 environment prints the ready message.  The cu_$set_ready_procedure
 889 subroutine can be called to change the ready procedure.
 890 
 891 
 892 Syntax:
 893 declare cu_$ready_proc entry;
 894 call cu_$ready_proc ();
 895 or:
 896 dcl cu_$ready_proc entry (1 aligned, 2 bit(1) unaligned,
 897      2 bit(35) unaligned);
 898 dcl 1 mode       aligned,
 899       2 ready_sw bit(1) unaligned,
 900       2 mbz      bit(35) unaligned;
 901 call cu_$ready_proc (mode);
 902 
 903 
 904 Arguments:
 905 mode.ready_sw
 906    specifies whether the ready procedure should print a ready message.
 907    (Input)
 908    "1"b print ready message
 909    "0"b do not print ready message
 910 mode.mbz
 911    is reserved for future use and must be "0"b.  (Input)
 912 
 913 
 914 Notes:  If no argument is given, a static ready switch is passed to the
 915 ready procedure.  The default value of the static ready switch is "1"b.
 916 The value of the static ready switch can be obtained using the
 917 cu_$get_ready_mode entry point and changed using the cu_$set_ready_mode
 918 entry point.  The listener invokes the cu_$ready_proc entry point
 919 without an argument.  The ready_off command turns off the static ready
 920 switch, the ready_on command turns it on, and the ready command calls
 921 the cu_$ready_proc entry point with an argument whose ready_sw
 922 component is "1"b.  Thus, if a user-written ready procedure honors the
 923 ready switch, its printing of the ready message can be controlled by
 924 the standard ready, ready_on, and ready_off commands.
 925 
 926 
 927 :Entry:  reset_cl_intermediary:  03/05/85 cu_$reset_cl_intermediary
 928 
 929 
 930 Function: This entry point resets the procedure invoked by calls
 931 to cu_$cl to the standard system supplied procedure.
 932 
 933 
 934 Syntax:
 935 declare cu_$reset_cl_intermediary entry ();
 936 call cu_$reset_cl_intermediary ();
 937 
 938 
 939 :Entry:  reset_command_processor:  03/05/85 cu_$reset_command_processor
 940 
 941 
 942 Function: This entry point resets the procedure invoked by calls
 943 to cu_$cp to the standard system supplied procedure.
 944 
 945 
 946 Syntax:
 947 declare cu_$reset_command_processor entry ();
 948 call cu_$reset_command_processor ();
 949 
 950 
 951 :Entry:  reset_evaluate_active_string: 03/05/85 cu_$reset_evaluate_active_string
 952 
 953 
 954 Function: This entry point resets the procedure invoked by calls
 955 to cu_$evaluate_active_string to the standard system supplied
 956 procedure.
 957 
 958 
 959 Syntax:
 960 declare cu_$reset_evaluate_active_string entry ();
 961 call cu_$reset_evaluate_active_string ();
 962 
 963 
 964 :Entry:  reset_ready_procedure:  03/05/85 cu_$reset_ready_procedure
 965 
 966 
 967 Function: This entry point resets the procedure invoked by calls
 968 to cu_$ready_proc to the standard system supplied procedure.
 969 
 970 
 971 Syntax:
 972 declare cu_$reset_ready_procedure entry ();
 973 call cu_$reset_ready_procedure ();
 974 
 975 
 976 :Entry:  set_cl_intermediary:  03/05/85 cu_$set_cl_intermediary
 977 
 978 
 979 Function: The Multics system provides a set of procedures to
 980 handle any error conditions that can be signalled within a process
 981 (see the description of the signal_ subroutine).  The standard
 982 error handlers attempt to print an understandable diagnostic and
 983 call a procedure to reenter command level.  However, in order to
 984 allow use of the standard error handling procedures in a closed
 985 subsystem environment, the error handlers do not call the standard
 986 error handlers directly but call the cu_$cl entry point.  This
 987 entry point passes control to the procedure entry point currently
 988 defined by the last call to cu_$set_cl_intermediary.  If
 989 cu_$set_cl_intermediary has never been called in the process,
 990 control is passed to the standard error handlers on a call to
 991 cu_$cl.
 992 
 993 
 994 Syntax:
 995 declare cu_$set_cl_intermediary entry (entry);
 996 call cu_$set_cl_intermediary (proc_entry);
 997 
 998 
 999 Arguments:
1000 proc_entry
1001    is the procedure entry to be called by the standard error handlers
1002    after printing a diagnostic message.  (Input)
1003 
1004 
1005 :Entry:  set_command_processor:  03/05/85 cu_$set_command_processor
1006 
1007 
1008 Function: Some standard Multics commands permit the user to escape
1009 from them to execute other commands.  In this case, the escapable
1010 command passes the line to be executed to the command processor.
1011 To allow use of these escapable standard commands in a closed
1012 subsystem environment, instead of calling the command processor
1013 directly, the cu_$cp entry point is called.  The latter passes
1014 control to the procedure entry point defined as the current
1015 command processor.  The cu_$set_command_processor entry point
1016 allows a subsystem developer to replace the standard command
1017 processor with a different procedure.  This mechanism can be used
1018 to ensure that the subsystem remains in full control and still
1019 allow subsystem users the use of many standard commands.
1020 
1021 
1022 Syntax:
1023 declare cu_$set_command_processor entry (entry);
1024 call cu_$set_command_processor (proc_entry);
1025 
1026 
1027 Arguments:
1028 proc_entry
1029    is the procedure entry point to which control is passed upon
1030    receiving a call to cu_$cp.  (Input)
1031 
1032 
1033 :Entry:  set_evaluate_active_string: 03/05/85 cu_$set_evaluate_active_string
1034 
1035 
1036 Function: Some standard Multics commands (e.g., compose and
1037 exec_com) permit the user to evaluate active strings which are a
1038 sequence of one or more active function invocations with their
1039 arguments.  To allow the use of these commands in a closed
1040 subsystem, instead of calling the command processor directly to
1041 evaluate the active string, the cu_$evaluate_active_string entry
1042 is called.  The latter passes control to the procedure entry point
1043 defined as the current active string evaluator.  The
1044 cu_$set_evaluate_active_string entry point allows a subsystem
1045 developer to replace the standard active string evaluator with a
1046 different procedure.  This mechanism can be used to insure that
1047 the subsystem remains in full control and still allow subsystem
1048 users the use of many standard commands.
1049 
1050 
1051 Syntax:
1052 declare cu_$set_evaluate_active_string entry (entry);
1053 call cu_$set_evaluate_active_string (active_string_procedure);
1054 
1055 
1056 Arguments:
1057 active_string_procedure
1058    is the procedure entry point to which control is passed upon
1059    receiving a call to cu_$evaluate_active_string.  (Input)
1060 
1061 
1062 :Entry:  set_ready_mode:  03/05/85 cu_$set_ready_mode
1063 
1064 
1065 Function: This entry point allows the user to change the value of
1066 the static ready mode.
1067 
1068 
1069 Syntax:
1070 declare cu_$set_ready_mode entry (1 aligned, 2 bit(1) unaligned,
1071      2 bit(35) unaligned);
1072 dcl 1 mode       aligned,
1073       2 ready_sw bit(1) unaligned,
1074       2 mbz      bit(35) unaligned;
1075 call cu_$set_ready_mode (mode);
1076 
1077 
1078 Arguments:
1079 mode.ready_sw
1080    is the new value of the static ready switch.  (Input)
1081    "1"b print ready message
1082    "0"b do not print ready message
1083 mode.mbz
1084    is reserved for future use and must be "0"b.  (Input)
1085 
1086 
1087 :Entry:  set_ready_procedure:  03/05/85 cu_$set_ready_procedure
1088 
1089 
1090 Function: This entry point allows the user to change the ready
1091 procedure invoked by cu_$ready_proc.
1092 
1093 
1094 Syntax:
1095 declare cu_$set_ready_procedure entry (entry);
1096 call cu_$set_ready_procedure (ready_entry);
1097 
1098 
1099 Arguments:
1100 ready_entry
1101    is the procedure entry point that is to become the new ready
1102    procedure of the process.  (Input)
1103 
1104 
1105 :Entry:  shrink_stack_frame:  03/05/85 cu_$shrink_stack_frame
1106 
1107 
1108 Function: This entry point allows its caller to deallocate
1109 temporary storage by reducing the caller's current stack frame.
1110 Such storage must have been allocated via a call to
1111 cu_$grow_stack_frame.
1112 
1113 
1114 Syntax:
1115 declare cu_$shrink_stack_frame entry (ptr, fixed bin(35));
1116 call cu_$shrink_stack_frame (ptr, code);
1117 
1118 
1119 Arguments:
1120 ptr
1121    is a pointer to the first word of the storage to be deallocated.
1122    (Input) It must point to a mod 16 word boundary.  The stack frame
1123    from the word indicated by ptr to the end of the frame is
1124    deallocated.
1125 code
1126    is a standard status code.  (Output)
1127 
1128 
1129 :Entry:  stack_frame_ptr:  03/05/85 cu_$stack_frame_ptr
1130 
1131 
1132 Function: The cu_$stack_frame_ptr entry point returns a pointer to
1133 the stack frame of its caller.  The stackframeptr builtin function
1134 should be used to get this information in PL/I programs, since it
1135 is more efficient.
1136 
1137 
1138 Syntax:
1139 declare cu_$stack_frame_ptr entry (ptr);
1140 call cu_$stack_frame_ptr (stack_ptr);
1141 
1142 
1143 Arguments:
1144 stack_ptr
1145    is a pointer to the stack frame of its caller.  (Output)
1146 
1147 
1148 :Entry:  stack_frame_size:  03/05/85 cu_$stack_frame_size
1149 
1150 
1151 Function: The cu_$stack_frame_size entry point returns the size
1152 (in words) of the stack frame of its caller.
1153 
1154 
1155 Syntax:
1156 declare cu_$stack_frame_size entry (fixed bin);
1157 call cu_$stack_frame_size (size);
1158 
1159 
1160 Arguments:
1161 size
1162    is the size (in words) of the caller's stack frame.  (Output)