1 01/24/83 ssu_
2
3 The ssu_ subroutine provides a set of standard functions for use by
4 application writers in developing their own subsystems. Use of ssu_
5 functions will enable the application builder to provide subsystems
6 which are consistent in terms of user interface and system response.
7 For detailed instructions on creating subsystems, see "Interactive
8 Subsystem Programming Environment" in Section 4 of the Programmer's
9 Reference Manual.
10
11
12 Entry points in ssu_:
13 List is generated by the help command
14
15
16 :Entry: abort_line: 01/19/83 ssu_$abort_line
17
18
19 Function: This entry is used to print an error message and abort the
20 execution of the current request line. Additional information on
21 interactive subsystem error handling is contained in the Programmer's
22 Reference Manual.
23
24
25 Syntax:
26 declare ssu_$abort_line entry options variable;
27
28 call ssu_$abort_line sci_ptr status_code ioa_string optional_args;
29
30
31 Arguments:
32 sci_ptr
33 is a pointer to the subsystem control structure for this invocation
34 as returned by ssu_$create_invocation. Input It must be an
35 aligned unpacked pointer.
36 status_code
37 is the status code for printing a message from an error table.
38 Input If it is zero, no error table message is printed. It can be
39 any datatype which can be converted to fixed bin35. This argument
40 is optional.
41
42
43 ioa_string
44 is an ioa_ control string used to generate the user message portion
45 of the message to be printed. Input optional It can be a varying
46 or nonvarying character string. If it is not present, no user
47 message is printed.
48 optional_args
49 are arguments to be substituted into the ioa_ control string.
50 Input optional They can be of any type required by the control
51 string.
52
53
54 Notes: This is a replaceable procedure. See the Programmer's
55 Reference Manual for information on the use of replaceable procedures
56 within interactive subsystems.
57
58 In a standalone invocation, a call to this entry point is translated
59 into a call to com_err_ or active_fnc_err_ as appropriate. See the
60 Programmer's Reference Manual for information on the use of standalone
61 subsystem invocations.
62
63 The format of the message is as follows:
64 subsystem_name request_name: Code message User message
65 or:
66 system_name: Code message User message
67
68
69 The second form without the request name is used when the call is
70 made when no request is currently being executed, such as when it is
71 called by the subsystem command procedure, rather than a request
72 procedure.
73
74 The "Code message" is the error message associated with the status
75 code. If the code argument is omitted or if its value is zero, the
76 "Code message" is omitted, and only the "User message" is printed. The
77 "User message" is formed by the appropriate substitutions in the ioa_
78 control string.
79
80
81 :Entry: abort_subsystem: 01/19/83 ssu_$abort_subsystem
82
83
84 Function: This entry is used to abort the current invocation of the
85 subsystem, and optionally print an error message. Additional
86 information on interactive subsystem error handling is contained in the
87 Programmer's Reference Manual.
88
89
90 Syntax:
91 declare ssu_$abort_subsystem entry options variable;
92
93 call ssu_$abort_subsystem sci_ptr status_code ioa_string
94 optional_args;
95
96
97 Arguments:
98 sci_ptr
99 is a pointer to the subsystem control structure for this invocation
100 as returned by ssu_$create_invocation. Input It must be an
101 aligned unpacked pointer.
102 status_code
103 is the status code for printing a message from an error table.
104 Input optional If it is zero or omitted, no error table message
105 is printed. It can be any datatype which can be converted to fixed
106 bin35.
107
108
109 ioa_string
110 is an ioa_ control string which will be used to generate the user
111 message portion of the message to be printed. Input optional It
112 can be a varying or nonvarying character string. If it is not
113 present, no user message is printed.
114 optional_args
115 are arguments to be substituted into the ioa_ control string.
116 Input optional They can be of any type required by the control
117 string.
118
119
120 Notes: This is a replaceable procedure. See the Programmer's
121 Reference Manual for information on the use of replaceable procedures
122 within interactive subsystems.
123
124 In a standalone invocation, a call to this entrypoint is translated
125 into a call to com_err_ or active_fnc_err_ as appropriate. See the
126 Programmer's Reference Manual for information on the use of standalone
127 subsystem invocations.
128
129 The format of the message is as follows:
130 subsystem_name request_name: Code message User message
131 or:
132 subsystem_name: Code message User message
133
134
135 The second form without the request name is used when the call is
136 made when no request is currently being executed, such as when it is
137 called by the subsystem command procedure, rather than a request
138 procedure.
139
140 The "Code message" is the error message associated with the status
141 code. If the code argument is omitted or if its value is zero, the
142 "Code message" is omitted, and only the "User message" is printed. The
143 "User message" is formed by the appropriate substitutions in the ioa_
144 control string.
145
146
147 :Entry: add_info_dir: 01/19/83 ssu_$add_info_dir
148
149
150 Function: This entry adds a new directory at the specified location in
151 the list of info directories being searched by this subsystem
152 invocation. Additional information on interactive subsystem
153 self-documentation facilities is contained in the Programmer's
154 Reference Manual.
155
156
157 Syntax:
158 declare ssu_$add_info_dir entry ptr char* fixed bin
159 fixed bin35;
160
161 call ssu_$add_info_dir sci_ptr info_dir position code;
162
163
164 Arguments:
165 sci_ptr
166 is a pointer to the subsystem control structure for this invocation
167 as returned by ssu_$create_invocation. Input
168 info_dir
169 is the pathname of the directory to be added to the list of info
170 directories for this invocation. Input
171 position
172 is the position in the list where the info dir is to be added.
173 Input It can be any positive integer. The new directory will
174 become the Nth entry in the list of info directories i.e. it is
175 added before the directory already present in position N. To add a
176 directory at the end, position should be specified as a large
177 number, such as 100000, which will guarantee its being added after
178 the last info directory.
179
180
181 code
182 is a storage system status code. Output If it is zero, the
183 directory was valid and was added; otherwise, it indicates the
184 nature of difficulty associated with the directory.
185
186
187 Notes: This entry point validates the existence of the specified info
188 directory, and refuses to add it, returning a nonzero status code,
189 unless it is valid. The user must have "s" access to the directory in
190 order to add it as an info directory.
191
192
193 :Entry: add_request_table: 01/19/83 ssu_$add_request_table
194
195
196 Function: This entry adds a new request table at the specified
197 location in the list of request tables being searched by this subsystem
198 invocation. Addition information on the use of interactive subsystem
199 request tables is provided in the Programmer's Reference Manual.
200
201
202 Syntax:
203 declare ssu_$add_request_table entry ptr ptr fixed bin
204 fixed bin35;
205
206 call ssu_$add_request_table sci_ptr request_table_ptr position
207 code;
208
209
210 Arguments:
211 sci_ptr
212 is a pointer to the subsystem control structure for this invocation
213 as returned by ssu_$create_invocation. Input
214 request_table_ptr
215 is a pointer to a valid subsystem request table, to be added to the
216 list searched for this invocation. Input
217 position
218 is the position in the list where the request table is to be added.
219 Input It can be any positive integer. The new request table will
220 be added as the Nth entry in the request tables list i.e. it is
221 added after the request table already present in position N. To add
222 a request table at the end position should be specified as a large
223 number such as 100000 which will guarantee its being added after
224 the last request table.
225
226
227 code
228 is a status code. Output If it is zero the table was valid and
229 was added; or ssu_et_$invalid_request_table if it was not.
230
231
232 Notes: This entry point validates the existence and validity of the
233 specified request table and refuses to add it returning a nonzero
234 status code unless it is valid.
235
236
237 :Entry: apply_request_util: 01/19/83 ssu_$apply_request_util
238
239
240 Function: This entry is a utility procedure for implementing subsystem
241 "apply" requests. The apply request is defined to create a Multics
242 command line out of some or all of its request arguments concatenate
243 the pathname of a segment containing the specified object in the
244 subsystem and call the command processor. It can be used for
245 instance to allow a user to edit a text file with the editor of her
246 choice with a request like "apply ted -pathname" which would be
247 passed to the command processor as:
248
249 ted -pathname PATHNAME_OF_TEMP_SEG
250
251
252 If the apply request can take arguments which are meaningful to the
253 subsystem they must all come before the first argument which is to
254 become part of the command line. It is recommended that the syntax of
255 the apply request be designed so that the first argument which is not a
256 control argument is taken as the beginning of the command line; its
257 index will be passed as first_command_arg below. The temp_seg_ptr
258 should point to a segment on which the bitcount can be set or which is
259 already set. It is recommended that the segment used for this purpose
260 be obtained by calling ssu_$get_temp_segment.
261
262 This entry returns no error code; rather since it is only useful in
263 implementing the apply request it simply calls ssu_$abort_line if it
264 encounters any serious errors and prints a more informative message
265 than could otherwise have been described by an error code.
266
267
268 Syntax:
269 declare ssu_$apply_request_util entry ptr fixed bin ptr
270 fixed bin21 fixed bin21;
271
272 call ssu_$apply_request_util sci_ptr first_command_arg temp_seg_ptr
273 input_lth output_lth;
274
275
276 Arguments:
277 sci_ptr
278 is a pointer to the subsystem control structure for this invocation
279 as returned by ssu_$create_invocation. Input
280 first_command_arg
281 is the index of the first request argument which is to become part
282 of the command line. Input If the subsystem apply request accepts
283 no subsystem arguments this should be 1; otherwise it should be
284 the index of the first non-control argument to the apply request.
285 temp_seg_ptr
286 is a pointer to the segment containing the data to be manipulated by
287 the command line. Input Its pathname will be determined and
288 concatenated onto the end of the command line.
289
290
291 input_lth
292 is the length in characters of the data in the segment or -1.
293 Input If it is non-negative the bitcount of the segment is set to
294 nine times input_lth before the command line is executed; otherwise
295 the bitcount is not altered. If the bitcount is set to correspond
296 to input_lth it will be restored to its previous value after the
297 command line has been executed and after output_lth has been set to
298 reflect its value.
299 output_lth
300 is the length in characters derived from the bitcount of the
301 data in the segment after the command line has been executed.
302 Output
303
304
305 :Entry: arg_count: 01/19/83 ssu_$arg_count
306
307
308 Function: This entry is used to determine how many arguments a
309 subsystem request received.
310
311
312 Syntax:
313 declare ssu_$arg_count entry ptr fixed bin;
314
315 call ssu_$arg_count sci_ptr arg_count;
316
317
318 Arguments:
319 sci_ptr
320 is a pointer to the subsystem control structure for this invocation
321 as returned by ssu_$create_invocation. Input
322 arg_count
323 is the number of arguments the request received. Output
324
325
326 Notes: This entry point should only be used by requests which can not
327 be invoked as an active request. If called by an active request this
328 entrypoint will abort the request line with the message:
329
330 This request can not be used as an active function.
331
332 This is a replaceable procedure. See the Programmer's Reference Manual
333 for information on the use of replaceable procedures within interactive
334 subsystems.
335
336 In a standalone procedure a call to this entry point is translated
337 into a call to cu_$arg_count. See the Programmer's Reference Manual
338 for information on the use of standalone subsystem invocations.
339
340
341 :Entry: arg_list_ptr: 01/19/83 ssu_$arg_list_ptr
342
343
344 Function: This entry can be used by a subsystem request to get a
345 pointer to its request argument list. This argument list is identical
346 to that supplied to a Multics command by the command processor: a
347 series of nonvarying character arguments followed by a varying
348 character string argument if the request is invoked as an active
349 request.
350
351 The argument list can be manipulated with calls to cu_$arg_count_rel
352 cu_$arg_ptr_rel and cu_$af_return_arg_rel which are equivalent to
353 ssu_$arg_count ssu_$arg_ptr and ssu_$return_arg for this application.
354
355
356 Syntax:
357 declare ssu_$arg_list_ptr entry ptr ptr;
358
359 call ssu_$arg_list_ptr sci_ptr arg_list_ptr;
360
361
362 Arguments:
363 sci_ptr
364 is a pointer to the subsystem control structure for this invocation
365 as returned by ssu_$create_invocation. Input
366 arg_list_ptr
367 is a pointer to the request argument list. Output
368
369
370 Notes: This is a replaceable procedure. See the Programmer's
371 Reference Manual for information on the use of replaceable procedures
372 within interactive subsystems.
373
374
375 :Entry: arg_ptr: 01/19/83 ssu_$arg_ptr
376
377
378 Function: This entry is used by the procedure implementing a subsystem
379 request to access its arguments.
380
381
382 Syntax:
383 declare ssu_$arg_ptr entry ptr fixed bin ptr fixed bin21;
384
385 call ssu_$arg_ptr sci_ptr arg_index arg_ptr arg_lth;
386
387
388 Arguments:
389 sci_ptr
390 is a pointer to the subsystem control structure for this invocation
391 as returned by ssu_$create_invocation. Input
392 arg_index
393 is the index of the argument to be accessed. It must be between one
394 and the number of arguments supplied to the request. Input
395 arg_ptr
396 is a pointer to the selected argument as a character string.
397 Output
398 arg_lth
399 is the length of the selected argument as a character string.
400 Output
401
402
403 Notes: If asked for an argument whose index exceeds the request's
404 argument count this entry point will abort the request line with the
405 message: Expected argument missing.
406
407 This is a replaceable procedure. See the Programmer's Reference Manual
408 for information on the use of replaceable procedures within interactive
409 subsystems.
410
411 In a standalone invocation a call to this entry point is translated
412 into a call to cu_$arg_ptr or cu_$af_arg_ptr. See the Programmer's
413 Reference Manual for information on the use of standalone subsystem
414 invocations.
415
416
417 :Entry: create_invocation: 01/19/83 ssu_$create_invocation
418
419
420 Function: This entry is used to create an invocation of a subsystem.
421 The subsystem invocation must later be destroyed by a call to
422 ssu_$destroy_invocation. Additional information on interactive
423 subsystems is provided in the Programmer's Reference Manual.
424
425
426 Syntax:
427 declare ssu_$create_invocation entry char* char* ptr ptr
428 char* ptr fixed bin35;
429
430 call ssu_$create_invocation subsystem_name version_string info_ptr
431 request_table_ptr info_directory sci_ptr code;
432
433
434 Arguments:
435 subsystem_name
436 is the name of the subsystem. Input This name is used in error
437 messages in the output of the "." request if any as the default
438 prompt and as the default exec_com suffix.
439 version_string
440 is the name of the current version of the subsystem such as "4.3j".
441 Input It is used in the output of the "." request.
442 info_ptr
443 is a pointer to the invocation info structure specific to this
444 subsystem. Input It points to a data structure containing all the
445 information which must be passed between the command procedure and
446 the request procedures for this invocation.
447
448
449 request_table_ptr
450 is a pointer to the request table used for this subsystem or null.
451 Input If it is null there are no request tables for the subsystem
452 invocation and if any are desired they must be added by calls to
453 ssu_$add_request_table. At least one request table is required for
454 processing of any requests.
455 info_directory
456 is the name of a directory in which the help and list_help requests
457 if any will look for info files on the subsystem. Input If this
458 is the null string and no info directories are later added by
459 calling ssu_$add_info_directory the help and list_help requests
460 will not operate.
461
462
463 sci_ptr
464 is a pointer to the subsystem control structure created for this
465 invocation. Output
466 code
467 is a status code; if it is nonzero the subsystem invocation could
468 not be created and processing should not continue. Output
469
470
471 :Entry: delete_info_dir: 01/19/83 ssu_$delete_info_dir
472
473
474 Function: This entry is used to delete a directory from the list of
475 info directories being searched. The specified info directory must be
476 in the list. In order to avoid confusion about pathnames the
477 comparison is done by filesystem unique ID if that can be determined
478 otherwise by literal pathname. If the directory is not present a
479 nonzero status code is returned.
480
481
482 Syntax:
483 declare ssu_$delete_info_dir entry ptr char* fixed bin35;
484
485 call ssu_$delete_info_dir sci_ptr info_dir code;
486
487
488 Arguments:
489 sci_ptr
490 is a pointer to the subsystem control structure for this invocation
491 as returned by ssu_$create_invocation. Input
492 info_dir
493 is the name of the directory to be deleted. Input
494 code
495 is a status code. Output It is zero if the specified info
496 directory was found in the list or error_table_$noentry if not.
497
498
499 :Entry: delete_request_table: 01/19/83 ssu_$delete_request_table
500
501
502 Function: This entry is used to delete a request table from the list
503 of tables being searched. The specified request table must be in the
504 list. If it is not present a nonzero status code is returned.
505
506
507 Syntax:
508 declare ssu_$delete_request_table entry ptr ptr fixed bin35;
509
510 call ssu_$delete_request_table sci_ptr request_table_ptr code;
511
512
513 Arguments:
514 sci_ptr
515 is a pointer to the subsystem control structure for this invocation
516 as returned by ssu_$create_invocation. Input
517 request_table_ptr
518 is a pointer to the request table to be deleted. Input It is not
519 checked for validity or whether it points to a valid request table
520 so that invalid request table pointers can be removed from the list.
521 code
522 is a status code. It is zero if the specified request table pointer
523 is found in the list or ssu_et_$request_table_not_found if not.
524 Output
525
526
527 :Entry: destroy_invocation: 01/19/83 ssu_$destroy_invocation
528
529
530 Function: This entry is used to destroy a subsystem invocation created
531 by a previous call to ssu_$create_invocation or
532 ssu_$standalone_invocation.
533
534
535 Syntax:
536 declare ssu_$destroy_invocation entry ptr;
537
538 call ssu_$destroy_invocation sci_ptr;
539
540
541 Arguments:
542 sci_ptr
543 is a pointer to the subsystem control structure for this invocation
544 as returned by ssu_$create_invocation. Input
545
546
547 Notes: If sci_ptr is null on input the call is ignored. This entry
548 point sets sci_ptr to null after destroying the invocation.
549
550
551 :Entry: evaluate_active_string: 01/19/83 ssu_$evaluate_active_string
552
553
554 Function: This entry is used to interpret a single active request
555 string. It is the subsystem equivalent to cu_$evaluate_active_string.
556
557
558 Syntax:
559 declare ssu_$evaluate_active_string entry ptr ptr char*
560 fixed bin char* varying fixed bin35;
561
562 call ssu_$evaluate_active_string sci_ptr rp_options_ptr
563 active_string string_type return_value code;
564
565
566 Arguments:
567 sci_ptr
568 is a pointer to the subsystem control structure for this invocation
569 as returned by ssu_$create_invocation. Input
570 rp_options_ptr
571 if null specifies that the request processor options in effect for
572 this subsystem are used. Otherwise it locates an rp_options
573 structure defining the options to be used to evaluate the active
574 string.
575 active_string
576 is the active string to be evaluated. Input It should not include
577 the outermost brackets.
578
579
580 string_type
581 specifies the type of active string to be evaluated. Input It
582 must be one of the following values defined in the include file
583 cp_active_string_types.incl.pl1:
584
585 NORMAL_ACTIVE_STRING
586 the active string return value should be rescanned for all
587 command processor constructs. ...
588 TOKENS_ONLY_ACTIVE_STRING
589 the active string return value should be rescanned only for
590 whitespace and quotes. |...
591 ATOMIC_ACTIVE_STRING
592 the active string return value should not be rescanned.
593 ||...
594
595
596 return_value
597 is the result of the evaluation of the active string. Output
598 code
599 is a standard status code. If the standard evaluate_active_string
600 procedure is being used it will have one of the following values;
601 if a user supplied procedure is in use the list can be different.
602 Output
603 0
604 indicates that the active string was successfully evaluated.
605 error_table_$command_line_overflow
606 indicates that the return value of the active string was too
607 large to fit in the supplied return_value argument; as much as
608 would fit is returned however.
609
610
611 ssu_et_$request_line_aborted
612 indicates that evaluation of the active string was terminated by
613 a call to ssu_$abort_line. This usually indicates that an error
614 was encountered by one of the active requests; however the error
615 message has already been printed so no message should be printed
616 by the caller of ssu_$evaluate_active_string.
617 ssu_et_$subsystem_aborted
618 indicates that evaluation of the active string was terminated by
619 a call to ssu_$abort_subsystem; this generally indicates that the
620 subsystem should be terminated and no further processing be
621 done. In any case no error message should be printed.
622 anything else
623 indicates a serious error condition occurred while trying to
624 evaluate the active string.
625
626
627 Notes: This is a replaceable procedure. See the Programmer's
628 Reference Manual for information on the use of replaceable procedures
629 within interactive subsystems.
630
631 In a standalone invocation a call to this entrypoint is translated
632 into a call to cu_$evaluate_active_string. See the Programmer's
633 Reference Manual for information on the use of standalone subsystem
634 invocations.
635
636
637 :Entry: execute_line: 01/19/83 ssu_$execute_line
638
639
640 Function: This entry is used to intepret a single request line.
641
642
643 Syntax:
644 declare ssu_$execute_line entry ptr ptr fixed bin21
645 fixed bin35;
646
647 call ssu_$execute_line sci_ptr request_line_ptr request_line_lth
648 code;
649
650
651 Arguments:
652 sci_ptr
653 is a pointer to the subsystem control structure for this invocation
654 as returned by ssu_$create_invocation. Input
655 request_line_ptr
656 is a pointer to the request line to be executed. Input
657 request_line_lth
658 is the length of the request line in characters. Input
659 code
660 is a standard status code. Output If the default execute_line
661 procedure is being used it can have one of the following values;
662 these can be different if a user procedure is being used for this
663 function.
664 0
665 the request line was executed successfully and returned
666 normally.
667
668
669 ssu_et_$null_request_line
670 the request line was "blank" in the command_processor_ sense
671 i.e. contained no requests iteration or brackets but was
672 merely a mixture of whitespace and semi-colons.
673 ssu_et_$request_line_aborted
674 the request line was terminated during its execution by a call to
675 ssu_$abort_line. This usually indicates that an error was
676 encountered by one of the requests; however the error message
677 has already been printed so no message should be printed by the
678 caller of ssu_$execute_line.
679 ssu_et_$subsystem_aborted
680 the request line was terminated normally by a call to
681 ssu_$abort_subsystem; this generally indicates that the subsystem
682 should be terminated and no further processing be done. In any
683 case no error message should be printed.
684
685
686 ssu_$program_interrupt
687 the request line was terminated by the user interrupting its
688 execution and using the program interrupt command. The caller of
689 this entry point need not print a message.
690 anything else
691 indicates a serious error condition occurred while trying to
692 execute the request line.
693
694
695 Notes: This is a replaceable procedure. See the Programmer's
696 Reference Manual for information on the use of replaceable procedures
697 within interactive subsystems.
698
699 In a standalone invocation a call to this entry point is translated
700 into a call to cu_$cp. See the Programmer's Reference Manual for
701 information on the use of standalone subsystem invocations.
702
703
704 :Entry: execute_start_up: 01/19/83 ssu_$execute_start_up
705
706
707 Function: This entry point executes the current subsystem's start_up
708 exec_com.
709
710
711 Syntax:
712 declare ssu_$execute_start_up entry options variable;
713
714 call ssu_$execute_start_up sci_ptr code optional_ec_args;
715
716
717 Arguments:
718 sci_ptr
719 is a pointer to the subsystem control structure for this invocation
720 as returned by ssu_$create_invocation. Input
721 code
722 is a standard system status code. Output It can have one of the
723 following values:
724 0
725 the start_up exec_com was executed successfully.
726 error_table_$noentry
727 there is no start_up exec_com for this subsystem.
728 ssu_et_$exec_com_aborted
729 execution of the exec_com was abnormally terminated.
730 ssu_et_$subsystem_aborted
731 execution of the exec_com was abnormally terminated by a call to
732 ssu_$abort_subsystem.
733
734
735 optional_ec_args
736 are optional arguments to be passed to the start_up exec_com.
737 Input These arguments must be either nonvarying unaligned or
738 varying aligned character strings.
739
740
741 Notes: The subsystem's start_up exec_com is a segment named
742 "start_up.ec_suffix" where ec_suffix is the subsystem's exec_com
743 suffix. See ssu_$set_ec_suffix for a description of how to change the
744 suffix.
745
746 This entrypoint searches for the start_up exec_com first in the the
747 user's home directory then in the user's project directory
748 >udd>Project_id and last in >site The first exec_com found if any is
749 used.
750
751
752 :Entry: execute_string: 01/19/83 ssu_$execute_string
753
754
755 Function: This entry is used to execute a request string usually
756 expressed as an in-line constant or character string variable. It is
757 provided only as a utility function which allows the execution of
758 character strings as strings rather than by pointer and length. It is
759 implemented by a call to ssu_$execute_line; therefore if
760 ssu_$execute_line is changed ssu_$execute_string will change in
761 exactly the same way.
762
763
764 Syntax:
765 declare ssu_$execute_string entry ptr char* fixed bin35;
766
767 call ssu_$execute_string sci_ptr request_string code;
768
769
770 Arguments:
771 sci_ptr
772 is a pointer to the subsystem control structure for this invocation
773 as returned by ssu_$create_invocation. Input
774 request_string
775 is a character string containing the requests to be executed.
776 Input
777 code
778 is a status code. Output It can have any of the values specified
779 for ssu_$execute_line. The list of error codes is only for the
780 default procedure and can be different if a user procedure is
781 substituted.
782
783
784 :Entry: get_area: 01/19/83 ssu_$get_area
785
786
787 Function: This entry is used to obtain an area for use by the
788 subsystem invocation. It calls the define_area_ subroutine to obtain
789 an area in a temporary segment. The difference between using this
790 entry and calling define_area_ directly is that areas acquired by
791 calling ssu_$get_area are released when the subsystem invocation is
792 destroyed regardless of whether the user program had freed them
793 earlier. Areas acquired by calling ssu_$get_area should be released by
794 calling ssu_$release_area.
795
796
797 Syntax:
798 declare ssu_$get_area entry ptr ptr char* ptr;
799
800 call ssu_$get_area sci_ptr area_info_ptr comment area_ptr;
801
802
803 Arguments:
804 sci_ptr
805 is a pointer to the subsystem control structure for this invocation
806 as returned by ssu_$create_invocation. Input
807 area_info_ptr
808 is a pointer to an area_info structure defined in
809 area_info.incl.pl1 describing the area or null. Input If the
810 area_info_ptr is null an area with default characteristics is
811 defined; see below for details. Only the area_control flags in the
812 area_info are used by ssu_$get_area; the area is always put in a
813 temporary segment. The area pointer is returned as the final
814 argument to ssu_$get_area; it is not written into the area_info
815 structure.
816
817
818 comment
819 is a comment identifying the use to which the area will be put.
820 Input It is used in constructing the owner name for the call to
821 define_area_ in the form:
822 subsys_name.N comment
823 where subsys_name is the name of the subsystem N is the invocation
824 level for this invocation and the comment if any follows in
825 parentheses. This is done to make it easier to identify the segment
826 names listed by list_temp_segments.
827 area_ptr
828 is a pointer to the area. Output It will always be valid; if for
829 some reason the area cannot be acquired the current request line
830 or subsystem invocation if there is no request line is aborted
831 with an appropriate message. No errors are ever reflected back to
832 the caller of ssu_$get_area.
833
834
835 Notes: If the area_info_ptr supplied to ssu_$get_area is null an area
836 with default characteristics is created. The area is extensible
837 initially one segment long and is zero_on_free but not
838 zero_on_alloc. All other area_control flags are off.
839
840 If the subsystem is in "debug mode" see description of
841 ssu_$set_debug_mode all areas both user-specified and default are
842 created with the dont_free attribute.
843
844
845 :Entry: get_debug_mode: 01/19/83 ssu_$get_debug_mode
846
847
848 Function: This entry is used to get the current state of debug mode.
849 Debug mode controls several features intended only as an aid to
850 debugging. A description of interactive subsystem debug mode is
851 provided in the Programmer's Reference Manual.
852
853
854 Syntax:
855 declare ssu_$get_debug_mode entry ptr returns bit1 aligned;
856
857 debug_mode = ssu_$get_debug_mode sci_ptr;
858
859
860 Arguments:
861 sci_ptr
862 is a pointer to the subsystem control structure for this invocation
863 as returned by ssu_$create_invocation. Input
864 debug_mode
865 is the current debug mode either on or off. Output
866
867
868 :Entry: get_default_procedure: 01/19/83 ssu_$get_default_procedure
869
870
871 Function: This entry is used to get the default value for a
872 replaceable procedure value. The value returned is the procedure which
873 is called to perform the specified function if no calls to
874 ssu_$set_procedure are ever made for that procedure.
875
876
877 Syntax:
878 declare ssu_$get_default_procedure entry ptr char* entry
879 fixed bin35;
880
881 call ssu_$get_default_procedure sci_ptr procedure_name
882 procedure_value code;
883
884
885 Arguments:
886 sci_ptr
887 is a pointer to the subsystem control structure for this invocation
888 as returned by ssu_$create_invocation. Input
889 procedure_name
890 is the name of the procedure the value of which is to be returned.
891 Input
892 procedure_value
893 is the default value of the specified replaceable procedure value.
894 Output
895 code
896 is a status code. Output It can have the following values:
897 0
898 success.
899 error_table_$noentry
900 procedure_name is not an acceptable value.
901
902
903 Notes: See the Programmer's Reference Manual for the currently defined
904 list of replaceable procedure names.
905
906
907 :Entry: get_default_rp_options: 01/19/83 ssu_$get_default_rp_options
908
909
910 Function: This entrypoint returns the default request processor
911 options for the current subsystem.
912
913
914 Syntax:
915 declare ssu_$get_default_rp_options entry ptr char8 ptr
916 fixed bin35;
917
918 call ssu_$get_default_rp_options sci_ptr version_wanted
919 rp_options_ptr code;
920
921
922 Arguments:
923 sci_ptr
924 is a pointer to the subsystem control structure for this invocation
925 as returned by ssu_$create_invocation. Input
926 version_wanted
927 specifies which version of the rp_options structure is to be
928 returned by this procedure. Input This argument must have the
929 value of the named constant RP_OPIONS_VERSION_1 defined in the
930 system include file ssu_rp_options.incl.pl1.
931 rp_options_ptr
932 is a pointer to an rp_options structure previously allocated by the
933 caller which is to be filled in by this entrypoint. Input This
934 structure is declared in the system include file
935 ssu_rp_options.incl.pl1.
936
937
938 code
939 is a standard system status code. Output It can have one of the
940 following values:
941 0
942 the structure was successfully filled in.
943 error_table_$unimplemented_version
944 the caller requested an unrecognized version of the rp_options
945 structure.
946
947
948 Notes: See the information on the subsystem request language in the
949 Programmer's Reference Manual for a description of the rp_options
950 structure and the request processor options mechanism.
951
952 This is a replaceable procedure. See the Programmer's Reference Manual
953 for information on the use of replaceable procedures within interactive
954 subsystems.
955
956
957 :Entry: get_ec_search_list: 01/19/83 ssu_$get_ec_search_list
958
959
960 Function: This entry returns the name of the search list currently
961 being used to find subsystem exec_com files. By default no search
962 list is used; exec_coms must be specified by full pathname and this
963 value is a null string. See also the description of
964 ssu_$set_ec_search_list.
965
966
967 Syntax:
968 declare ssu_$get_ec_search_list entry ptr returns char32;
969
970 search_list_name = ssu_$get_ec_search_list sci_ptr;
971
972
973 Arguments:
974 sci_ptr
975 is a pointer to the subsystem control structure for this invocation
976 as returned by ssu_$create_invocation. Input
977 search_list_name
978 is the name of the current exec_com search list or a null string if
979 no search list is used by this subsystem invocation. Return
980
981
982 :Entry: get_ec_subsystem_ptr: 01/19/83 ssu_$get_ec_subsystem_ptr
983
984
985 Function: This entry returns the pointer currently used to implement
986 the "referencing_dir" rule in the search list for subsystem exec_coms.
987 By default this pointer is null meaning that the referencing_dir rule
988 has no effect even if the exec_com search list name is non-null. See
989 also the description of ssu_$set_ec_subsystem_ptr.
990
991
992 Syntax:
993 declare ssu_$get_ec_subsystem_ptr entry ptr returns ptr;
994
995 subsystem_ptr = ssu_$get_ec_subsystem_ptr sci_ptr;
996
997
998 Arguments:
999 sci_ptr
1000 is a pointer to the subsystem control structure for this invocation
1001 as returned by ssu_$create_invocation. Input
1002 subsystem_ptr
1003 is a pointer to some segment in the directory being used as the
1004 subsystem's exec_com referencing_dir or null if no such directory is
1005 being used. Output
1006
1007
1008 :Entry: get_ec_suffix: 01/19/83 ssu_$get_ec_suffix
1009
1010
1011 Function: This entry returns the suffix currently being used for
1012 subsystem exec_com files. By default this string is the subsystem
1013 name. See also the description of ssu_$set_ec_suffix.
1014
1015
1016 Syntax:
1017 declare ssu_$get_ec_suffix entry ptr returns char32;
1018
1019 suffix_string = ssu_$get_ec_suffix sci_ptr;
1020
1021
1022 Arguments:
1023 sci_ptr
1024 is a pointer to the subsystem control structure for this invocation
1025 as returned by ssu_$create_invocation. Input
1026 suffix_string
1027 is the current exec_com suffix for this subsystem invocation.
1028 Output
1029
1030
1031 :Entry: get_info_ptr: 01/19/83 ssu_$get_info_ptr
1032
1033
1034 Function: This entry is used to get the info_ptr for this subsystem
1035 invocation. Normally this value is otherwise available either as a
1036 request parameter or as a variable in the command procedure of the
1037 subsystem. This entry is only useful in subroutines which are passed
1038 only the sci_ptr and not the info_ptr as parameters such as user
1039 supplied abort procedures. Additional information on the use of
1040 sci_ptr and info_ptr is provided in the description of interactive
1041 subsystems in the Programmer's Reference Manual.
1042
1043
1044 Syntax:
1045 declare ssu_$get_info_ptr entry ptr returns ptr;
1046
1047
1048 info_ptr = ssu_$get_info_ptr sci_ptr;
1049
1050
1051 Arguments:
1052 sci_ptr
1053 is a pointer to the subsystem control structure for this invocation
1054 as returned by ssu_$create_invocation. Input
1055 info_ptr
1056 is the info_ptr for this subsystem invocation. Output
1057
1058
1059 :Entry: get_invocation_count: 01/19/83 ssu_$get_invocation_count
1060
1061
1062 Function: This entry is used to determine the invocation index of the
1063 current subsystem invocation and also determine how many invocations
1064 of the subsystem are currently active.
1065
1066
1067 Syntax:
1068 declare ssu_$get_invocation_count entry ptr fixed bin fixed bin;
1069
1070 call ssu_$get_invocation_count sci_ptr this_level max_level;
1071
1072
1073 Arguments:
1074 sci_ptr
1075 is a pointer to the subsystem control structure for this invocation
1076 as returned by ssu_$create_invocation. Input
1077 this_level
1078 is the invocation index for this subsystem invocation. Output
1079 max_level
1080 is the invocation index for the highest numbered subsystem
1081 invocation presently active. Output
1082
1083
1084 :Entry: get_level_n_sci_ptr: 01/19/83 ssu_$get_level_n_sci_ptr
1085
1086
1087 Function: This entry is used to examine the state of other invocations
1088 of the subsystem by returning the info_ptr and sci_ptr for the other
1089 invocation. If the level index specifies an invocation which does not
1090 exist the info_ptr and sci_ptr are returned as null. Additional
1091 information on the use of info_ptr and sci_ptr is provided in the
1092 description of interactive subsystems in the Programmer's Reference
1093 Manual.
1094
1095
1096 Syntax:
1097 declare ssu_$get_level_n_sci_ptr entry ptr fixed bin ptr ptr;
1098
1099 call ssu_$get_level_n_sci_ptr sci_ptrlevel_index other_sci_ptr
1100 other_info_ptr;
1101
1102
1103 Arguments:
1104 sci_ptr
1105 is a pointer to the subsystem control structure for this invocation
1106 as returned by ssu_$create_invocation. Input
1107 level_index
1108 is the index invocation number recursion level of the other
1109 invocation of the subsystem for which information is desired.
1110 other_sci_ptr
1111 is the sci_ptr for the specified invocation of the subsystem.
1112 Output
1113 other_info_ptr
1114 is the info_ptr for the specified invocation of the subsystem.
1115 Output
1116
1117
1118 :Entry: get_prev_sci_ptr: 01/19/83 ssu_$get_prev_sci_ptr
1119
1120
1121 Function: This entry is used to examine the state of other invocations
1122 of the subsystem by returning the info_ptr and sci_ptr for the
1123 immediately previous invocation. If there is no previous invocation of
1124 the subsystem the sci_ptr and info_ptr are returned as null.
1125 Additional information on the use of the info_ptr and sci_ptr is
1126 provided the description of interactive subsystems in the Programmer's
1127 Reference Manual.
1128
1129
1130 Syntax:
1131 declare ssu_$get_prev_sci_ptr entry ptr ptr ptr;
1132
1133 call ssu_$get_prev_sci_ptr sci_ptr previous_sci_ptr
1134 previous_info_ptr;
1135
1136
1137 Arguments:
1138 sci_ptr
1139 is a pointer to the subsystem control structure for this invocation
1140 as returned by ssu_$create_invocation. Input
1141 previous_sci_ptr
1142 is the sci_ptr for previous invocation of the subsystem. Output
1143 previous_info_ptr
1144 is the info_ptr for previous invocation of the subsystem. Output
1145
1146
1147 :Entry: get_procedure: 01/19/83 ssu_$get_procedure
1148
1149
1150 Function: This entry is used to get the current value for a
1151 replaceable procedure value in the specified subsystem invocation. The
1152 value returned is the procedure which is called to perform the
1153 specified function.
1154
1155
1156 Syntax:
1157 declare ssu_$get_procedure entry ptr char* entry fixed bin35;
1158
1159 call ssu_$get_procedure sci_ptr procedure_name procedure_value
1160 code;
1161
1162
1163 Arguments:
1164 sci_ptr
1165 is a pointer to the subsystem control structure for this invocation
1166 as returned by ssu_$create_invocation. Input
1167 procedure_name
1168 is the name of the procedure for which the value is to be returned.
1169 Input
1170 procedure_value
1171 is the current value of the specified replaceable procedure value.
1172 Output
1173 code
1174 is a status code. Output It can have the following values:
1175 0 success.
1176 error_table_$noentry
1177 procedure_name is not an acceptable value.
1178
1179
1180 Notes: See the Programmer's Reference Manual for the currently defined
1181 list of replaceable procedure names.
1182
1183
1184 :Entry: get_prompt: 01/19/83 ssu_$get_prompt
1185
1186
1187 Function: This entry is used to get the string currently being used as
1188 a prompt. See the description of request loops for interactive
1189 subsystems in the Programmer's Reference Manual for additional
1190 information on prompts.
1191
1192
1193 Syntax:
1194 declare ssu_$get_prompt entry ptr returns char64 varying;
1195
1196 prompt_string = ssu_$get_prompt sci_ptr;
1197
1198
1199 Arguments:
1200 sci_ptr
1201 is a pointer to the subsystem control structure for this invocation
1202 as returned by ssu_$create_invocation. Input
1203 prompt_string
1204 is the current prompt string. Output
1205
1206
1207 :Entry: get_prompt_mode: 01/19/83 ssu_$get_prompt_mode
1208
1209
1210 Function: This entry is used to get the current state of prompting in
1211 the subsystem. See the description of request loops for interactive
1212 subsystems in the Programmer's Reference Manual for additional
1213 information on prompts.
1214
1215
1216 Syntax:
1217 declare ssu_$get_prompt_mode entry ptr returns bit36 aligned;
1218
1219 prompt_mode = ssu_$get_prompt_mode sci_ptr;
1220
1221
1222 Arguments:
1223 sci_ptr
1224 is a pointer to the subsystem control structure for this invocation
1225 as returned by ssu_$create_invocation. Input
1226 prompt_mode
1227 is the current prompt mode. Output The individual bits are
1228 interpreted as follows:
1229 bit 1 ON suppress all prompts.
1230 bit 2 ON prompt after blank request lines.
1231 bit 3 ON suppress prompts if there is type ahead.
1232 There are named constants in the ssu_prompt_modes.incl.pl1 include
1233 file that may be used to examine this return value.
1234
1235
1236 :Entry: get_ready_mode: 01/19/83 ssu_$get_ready_mode
1237
1238
1239 Function: This entry is used to determine the current state of ready
1240 processing. See the description of request loops for interactive
1241 subsystems in the Programmer's Reference Manual for additional
1242 information on ready processing.
1243
1244
1245 Syntax:
1246 declare ssu_$get_ready_mode entry ptr returns bit1 aligned;
1247
1248 enable_sw = ssu_$get_ready_mode sci_ptr;
1249
1250
1251 Arguments:
1252 sci_ptr
1253 is a pointer to the subsystem control structure for this invocation
1254 as returned by ssu_$create_invocation. Input
1255 enable_sw
1256 is a bit indicating whether or not ready processing is enabled.
1257 Output If it is "1"b, ready processing is being performed; if it
1258 is "0"b, ready processing is not being performed.
1259
1260
1261 :Entry: get_request_name: 01/19/83 ssu_$get_request_name
1262
1263
1264 Function: This entry is used to determine the primary name from the
1265 request table of the subsystem request currently being executed. If
1266 it is the null string, no request is currently being executed.
1267
1268
1269 Syntax:
1270 declare ssu_$get_request_name entry ptr returns char32;
1271
1272 request_name = ssu_$get_request_name sci_ptr;
1273
1274
1275 Arguments:
1276 sci_ptr
1277 is a pointer to the subsystem control structure for this invocation
1278 as returned by ssu_$create_invocation. Input
1279 request_name
1280 is the name of the request currently being executed, or the null
1281 string. Output
1282
1283
1284 :Entry: get_request_processor_options: 01/19/83 ssu_$get_request_processor_options
1285
1286
1287 Function: This entrypoint returns the request processor options
1288 presently in effect for the current subsystem.
1289
1290
1291 Syntax:
1292 declare ssu_$get_request_processor_options entry ptr char8 ptr
1293 fixed bin35;
1294
1295 call ssu_$get_request_processor_options sci_ptr version_wanted
1296 rp_options_ptr code;
1297
1298
1299 Arguments:
1300 sci_ptr
1301 is a pointer to the subsystem control structure for this invocation
1302 as returned by ssu_$create_invocation. Input
1303 version_wanted
1304 specifies which version of the rp_options structure is to be
1305 returned by this procedure. Input This argument must have the
1306 value of the named constant RP_OPIONS_VERSION_1 defined in the
1307 system include file ssu_rp_options.incl.pl1.
1308
1309
1310 rp_options_ptr
1311 is a pointer to an rp_options structure previously allocated by the
1312 caller which is to be filled in by this entry point. Input This
1313 structure is declared in the system include file
1314 ssu_rp_options.incl.pl1.
1315 code
1316 is a standard system status code. Output It can have one of the
1317 following values:
1318 0
1319 the structure was successfully filled in.
1320 error_table_$unimplemented_version
1321 the caller requested an unrecognized version of the rp_options
1322 structure.
1323
1324
1325 Notes: See the information on the subsystem request language in the
1326 Programmer's Reference Manual for a description of the rp_options
1327 structure and the request processor options mechanism.
1328
1329 This is a replaceable procedure. See the Programmer's Reference Manual
1330 for information on the use of replaceable procedures within interactive
1331 subsystems.
1332
1333
1334 :Entry: get_subsystem_and_request_name: 01/19/83 ssu_$get_subsystem_and_request_name
1335
1336
1337 Function: This entry is used to acquire a string identifying the
1338 subsystem and the current request, suitable for use in printing error
1339 messages or asking questions. If no request is currently being
1340 executed, the name returned is the name of the subsystem; otherwise, it
1341 has the following format:
1342
1343 subsystem_name request_name
1344
1345
1346 Syntax:
1347 declare ssu_$get_subsystem_and_request_name entry ptr
1348 returns char72 varying;
1349
1350 name = ssu_$get_subsystem_and_request_name sci_ptr;
1351
1352
1353 Arguments:
1354 sci_ptr
1355 is a pointer to the subsystem control structure for this invocation
1356 as returned by ssu_$create_invocation. Input
1357 name
1358 is the name of the subsystem and request currently being executed,
1359 as described above. Output
1360
1361
1362 :Entry: get_subsystem_name: 01/19/83 ssu_$get_subsystem_name
1363
1364
1365 Function: This entry is used to determine the name, supplied in the
1366 call to ssu_$create_invocation or ssu_$standalone_invocation, of the
1367 subsystem owning the specified invocation.
1368
1369
1370 Syntax:
1371 declare ssu_$get_subsystem_name entry ptr returns char32;
1372
1373 subsystem_name = ssu_$get_subsystem_name sci_ptr;
1374
1375
1376 Arguments:
1377 sci_ptr
1378 is a pointer to the subsystem control structure for this invocation
1379 as returned by ssu_$create_invocation. Input
1380 subsystem_name
1381 is the name of the subsystem owning the current invocation.
1382 Output
1383
1384
1385 :Entry: get_subsystem_version: 01/19/83 ssu_$get_subsystem_version
1386
1387
1388 Function: This entry is used to determine the version number of the
1389 subsystem which was supplied as a parameter in the call to
1390 ssu_$create_invocation or ssu_$standalone_invocation.
1391
1392
1393 Syntax:
1394 declare ssu_$get_subsystem_version entry ptr returns char32;
1395
1396 subsystem_version = ssu_$get_subsystem_version sci_ptr;
1397
1398
1399 Arguments:
1400 sci_ptr
1401 is a pointer to the subsystem control structure for this invocation
1402 as returned by ssu_$create_invocation. Input
1403 subsystem_version
1404 is the version number of the subsystem owning the current
1405 invocation. Output
1406
1407
1408 :Entry: get_temp_segment: 01/19/83 ssu_$get_temp_segment
1409
1410
1411 Function: This entry is used to obtain a temporary segment for use by
1412 the current subsystem invocation. It calls get_temp_segment_ to
1413 acquire the segment. The difference between using this entry and
1414 calling get_temp_segment_ directly is that segments acquired by calling
1415 ssu_$get_temp_segment are released when the subsystem invocation is
1416 destroyed, regardless of whether the user program had freed them
1417 earlier. Segments acquired by calling ssu_$get_temp_segment should be
1418 released by calling ssu_$release_temp_segment.
1419
1420
1421 Syntax:
1422 declare ssu_$get_temp_segment entry ptr char* ptr;
1423
1424 call ssu_$get_temp_segment sci_ptr comment temp_seg_ptr;
1425
1426
1427 Arguments:
1428 sci_ptr
1429 is a pointer to the subsystem control structure for this invocation
1430 as returned by ssu_$create_invocation. Input
1431 comment
1432 is a comment identifying the use to which the segment will be put.
1433 Input It is used in constructing the owner name for the call to
1434 get_temp_segment_, in the form:
1435 subsystem_name.N comment
1436 where subsys_name is the name of the subsystem, N is the invocation
1437 level for this invocation, and the comment if any follows, in
1438 parentheses. This is done to make it easier to identify the segment
1439 names listed by list_temp_segments.
1440
1441
1442 temp_seg_ptr
1443 is a pointer to the temporary segment. Output It will always be
1444 valid. If for some reason a temporary segment cannot be acquired,
1445 the current request line or subsystem invocation if there is no
1446 request line is aborted with an appropriate message. No errors are
1447 ever reflected back to the caller of ssu_$get_temp_segment.
1448
1449
1450 :Entry: list_info_dirs: 01/19/83 ssu_$list_info_dirs
1451
1452
1453 Function: This entry is used to obtain a list of the info directories
1454 currently in use by this subsystem invocation.
1455
1456
1457 Syntax:
1458 declare ssu_$list_info_dirs entry ptr ptr fixed bin ptr
1459 fixed bin35;
1460
1461 call ssu_$list_info_dirs sci_ptr area_ptr info_dirs_list_version
1462 idl_ptr code;
1463
1464
1465 Arguments:
1466 sci_ptr
1467 is a pointer to the subsystem control structure for this invocation
1468 as returned by ssu_$create_invocation. Input
1469 area_ptr
1470 is a pointer to an area in which the returned list of info
1471 directories can be allocated. Input
1472 info_dirs_list_version
1473 is the version of the info_dirs_list structure which the caller
1474 expects. The only version of this structure which can currently be
1475 requested is INFO_DIRS_LIST_VERSION_1. Input
1476
1477
1478 idl_ptr
1479 is a pointer to the info_dirs_list structure described below
1480 allocated by this entrypoint. Output
1481 code
1482 is a standard system status code. If the version of the
1483 info_dirs_list structure requested is not supported, this value will
1484 be error_table_$unimplemented_version. Output
1485
1486
1487 Notes: The info_dirs_list structure and the named constant
1488 INFO_DIRS_LIST_VERSION_1 are defined in the include file
1489 ssu_info_dirs_list.incl.pl1. The info_dirs_list structure is defined
1490 as follows:
1491
1492 dcl 1 info_dirs_list aligned based idl_ptr,
1493 2 header,
1494 3 version fixed bin,
1495 3 n_info_dirs fixed bin,
1496 2 info_dirs 0 refer info_dirs_list.n_info_dirs,
1497 3 info_dirname char168 unaligned,
1498 3 uid bit36,
1499 3 flags,
1500 4 info_dir_valid bit1 unaligned,
1501 4 pad bit35 unaligned;
1502
1503
1504
1505 Structure elements:
1506 version
1507 is the current version of this structure and has the value of the
1508 named constant INFO_DIRS_LIST_VERSION_1.
1509 n_info_dirs
1510 is the number of info directories in use by this subsystem
1511 invocation.
1512 info_dirsi.info_dirname
1513 is the absolute pathname of this directory.
1514 info_dirsi.uid
1515 is the file system unique ID of this directory if it can be
1516 determined; otherwise, it is "0"b.
1517 info_dirsi.info_dir_valid
1518 is "1"b if this info directory is considered valid by the
1519 subsystem utilities; otherwise, it is "0"b.
1520
1521
1522 :Entry: list_request_tables: 01/19/83 ssu_$list_request_tables
1523
1524
1525 Function: This entry is used to obtain a list of the request tables
1526 currently in use by this subsystem invocation.
1527
1528
1529 Syntax:
1530 declare ssu_$list_request_tables entry ptr ptr fixed bin ptr
1531 fixed bin35;
1532
1533 call ssu_$list_request_tables sci_ptr area_ptr
1534 request_tables_list_version rtl_ptr code;
1535
1536
1537 Arguments:
1538 sci_ptr
1539 is a pointer to the subsystem control structure for this invocation
1540 as returned by ssu_$create_invocation. Input
1541 area_ptr
1542 is a pointer to an area in which the returned list of request tables
1543 can be allocated. Input
1544 request_tables_list_version
1545 is the version of the request_tables_list structure which the caller
1546 expects. The only version of this structure which can currently be
1547 requested is REQUEST_TABLES_LIST_VERSION_1. Input
1548
1549
1550 rdl_ptr
1551 is a pointer to the request_tables_list structure described below
1552 allocated by this entrypoint. Output
1553 code
1554 is a standard system status code. If the version of the
1555 request_tables_list structure requested is not supported, this value
1556 will be error_table_$unimplemented_version. Output
1557
1558
1559 Notes: The request_tables_list structure and the named constant
1560 REQUEST_TABLES_LIST_VERSION_1 are defined in the include file
1561 ssu_request_tables_list.incl.pl1.
1562
1563 dcl 1 request_tables_list aligned based rtl_ptr,
1564 2 header,
1565 3 version fixed bin,
1566 3 n_tables fixed bin,
1567 2 tables 0 refer request_tables_list.n_tables,
1568 3 table_ptr ptr,
1569 3 flags,
1570 4 table_valid bit1 unaligned,
1571 4 pad bit35 unaligned,
1572 3 pad bit36;
1573
1574
1575 Structure elements:
1576 version
1577 is the current version of this structure and has the value of the
1578 named constant REQUEST_TABLES_LIST_VERSION_1.
1579 n_tables
1580 is the number of request tables in use by this subsystem
1581 invocation.
1582 tablesi.table_ptr
1583 is a pointer to this request table.
1584 tablesi.table_valid
1585 is "1"b if this request table is considered valid by the
1586 subsystem utilities; otherwise, it is "0"b.
1587
1588
1589 :Entry: listen: 01/19/83 ssu_$listen
1590
1591
1592 Function: This entry implements the subsystem listener. The
1593 interactive subsystem listener is described in the Programmer's
1594 Reference Manual.
1595
1596
1597 Syntax:
1598 declare ssu_$listen entry ptr ptr fixed bin35;
1599
1600 call ssu_$listen sci_ptr iocb_ptr code;
1601
1602
1603 Arguments:
1604 sci_ptr
1605 is a pointer to the subsystem control structure for this invocation
1606 as returned by ssu_$create_invocation. Input
1607 iocb_ptr
1608 is a pointer to the IOCB for the I/O switch from which input lines
1609 are to be read. If it is null, the default I/O switch, user_input,
1610 is used. Input
1611 code
1612 is a status code. It can never be zero for this entrypoint. If it
1613 is ssu_et_$subsystem_aborted, it indicates that the subsystem was
1614 exited normally, by a call to ssu_$subsystem_abort, and is not an
1615 error condition. Any other code indicates an error condition which
1616 prevented the listener from operating. This list of codes is only
1617 valid if the default listen procedure is being used; it can be
1618 different if a user listen procedure is in use. Output
1619
1620
1621 Notes: This is a replaceable procedure. See the Programmer's
1622 Reference Manual for information on the use of replaceable procedure
1623 within interactive subsystems.
1624
1625
1626 :Entry: print_blast: 01/19/83 ssu_$print_blast
1627
1628
1629 Function: This entry is used to print a "blast" message announcing a
1630 new version of the subsystem, if the user running the subsystem has not
1631 yet used the new version more than a certain number of times. This
1632 "threshold" value is provided to give the user several opportunities to
1633 find out what has been changed. See the description of interactive
1634 subsystem usage monitoring in the Programmer's Reference Manual for
1635 additional information.
1636
1637
1638 Syntax:
1639 declare ssu_$print_blast entry ptr ptr fixed bin char* varying
1640 fixed bin35;
1641
1642 call ssu_$print_blast sci_ptr ref_ptr threshold blast_message
1643 code;
1644
1645
1646 Arguments:
1647 sci_ptr
1648 is a pointer to the subsystem control structure for this invocation
1649 as returned by ssu_$create_invocation. Input
1650 ref_ptr
1651 is a pointer used as a referencing_dir argument in the call to
1652 hcs_$make_ptr to find the usage segment. It is usually codeptr of
1653 an entrypoint in the calling procedure. Input
1654 threshold
1655 is the maximum number of times to print a blast message announcing
1656 the new version for any particular user. Input
1657
1658
1659 blast_message
1660 is a blast message to be appended to the version announcement
1661 message. Input This might typically be a brief list of the
1662 changes in this version of the subsystem. If the blast_message is a
1663 null string, only the subsystem name and version number are printed
1664 if anything is printed at all.
1665 code
1666 is a status code indicating whether the usage was successfully
1667 recorded. Output In general, the code should be ignored, since
1668 there is nothing useful the caller can do about it.
1669
1670
1671 :Entry: print_message: 01/19/83 ssu_$print_message
1672
1673
1674 Function: This entry is used by a request procedure or the subsystem
1675 command procedure to print an informational, warning, or nonfatal error
1676 message.
1677
1678
1679 Syntax:
1680 declare ssu_$print_message entry options variable;
1681
1682 call ssu_$print_message sci_ptr status_code ioa_string
1683 optional_args;
1684
1685
1686 Arguments:
1687 sci_ptr
1688 is a pointer to the subsystem control structure for this invocation
1689 as returned by ssu_$create_invocation. Input
1690 status_code
1691 is the status code for printing a message from an error table.
1692 Input If it is zero, no error table message is printed. It can be
1693 any datatype which can be converted to fixed bin35.
1694 ioa_string
1695 is an ioa_ control string which is used to format the user message
1696 portion of the message to be printed. Input optional It can be a
1697 varying or nonvarying character string. If it is not present, no
1698 user message is printed.
1699 optional_args
1700 are arguments to be substituted into the ioa_ control string.
1701 Input optional They can be of any type required by the control
1702 string.
1703
1704
1705 Notes: This is a replaceable procedure. See the Programmer's
1706 Reference Manual for information on the use of replaceable procedures
1707 within interactive subsystems.
1708
1709 In a standalone invocation, a call to this entrypoint is translated
1710 into a call to com_err_ or active_fnc_err_ as appropriate. See the
1711 Programmer's Reference Manual for information on the use of standalone
1712 subsystem invocations.
1713
1714 The format of the message is as follows:
1715 subsystem_name request_name: Code message User message
1716 or:
1717 subsystem_name: Code message User message
1718
1719
1720 The second form without the request name is used when the call is
1721 made when no request is currently being executed, such as when it is
1722 called by the subsystem command procedure, rather than a request
1723 procedure.
1724
1725 The "Code message" is the error message associated with the status
1726 code. If the code is zero, the "Code message" is omitted, and only the
1727 "User message" is printed. The "User message" is formed by the
1728 appropriate substitutions in the ioa_ control string.
1729
1730
1731 :Entry: record_usage: 01/19/83 ssu_$record_usage
1732
1733
1734 Function: This entry is used to make an entry in the usage segment to
1735 record a use of the subsystem, without printing a "blast" message. See
1736 the description of interactive subsystem usage monitoring in the
1737 Programmer's Reference Manual for additional information.
1738
1739
1740 Syntax:
1741 declare ssu_$record_usage entry ptr ptr fixed bin35;
1742
1743 call ssu_$record_usage sci_ptr ref_ptr code;
1744
1745
1746 Arguments:
1747 sci_ptr
1748 is a pointer to the subsystem control structure for this invocation
1749 as returned by ssu_$create_invocation. Input
1750 ref_ptr
1751 is a pointer used as a referencing_dir argument in the call to
1752 hcs_$make_ptr to find the usage segment. Input It is usually
1753 codeptr of an entrypoint in the calling procedure.
1754 code
1755 is a status code indicating whether the usage was successfully
1756 recorded. Output In general, the code should be ignored, since
1757 there is nothing useful the caller can do about it.
1758
1759
1760 :Entry: release_area: 01/19/83 ssu_$release_area
1761
1762
1763 Function: This entry is used to release an area previously obtained by
1764 a call to ssu_$get_area. It can only be used to release areas acquired
1765 for the specified subsystem invocation. It returns no error code
1766 because any errors encountered are simply ignored, and taken care of at
1767 the time the subsystem invocation is destroyed.
1768
1769
1770 Syntax:
1771 declare ssu_$release_area entry ptr ptr;
1772
1773 call ssu_$release_area sci_ptr area_ptr;
1774
1775
1776 Arguments:
1777 sci_ptr
1778 is a pointer to the subsystem control structure for this invocation
1779 as returned by ssu_$create_invocation. Input
1780 area_ptr
1781 is a pointer to the area to be released. Input
1782
1783
1784 :Entry: release_temp_segment: 01/19/83 ssu_$release_temp_segment
1785
1786
1787 Function: This entry is used to release a temporary segment previously
1788 acquired by a call to ssu_$get_temp_segment. It can only be used to
1789 release temporary segments acquired for the specified subsystem
1790 invocation. It returns no error code because any errors encountered
1791 are simply ignored, and taken care of at the time the subsystem
1792 invocation is destroyed.
1793
1794
1795 Syntax:
1796 declare ssu_$release_temp_segment entry ptr ptr;
1797
1798 call ssu_$release_temp_segment sci_ptr temp_seg_ptr;
1799
1800
1801 Arguments:
1802 sci_ptr
1803 is a pointer to the subsystem control structure for this invocation
1804 as returned by ssu_$create_invocation. Input
1805 temp_seg_ptr
1806 is a pointer to the temporary segment to be released. Input
1807
1808
1809 :Entry: reset_procedure: 01/19/83 ssu_$reset_procedure
1810
1811
1812 Function: This entrypoint resets a replaceable procedure in the
1813 current subsystem to its default value. See the Programmer's Reference
1814 Manual for information on the use of replaceable procedures within
1815 interactive subsystems.
1816
1817
1818 Syntax:
1819 declare ssu_$reset_procedure entry ptr char* fixed bin35;
1820
1821 call ssu_$reset_procedure sci_ptr procedure_name code;
1822
1823
1824 Arguments:
1825 sci_ptr
1826 is a pointer to the subsystem control structure for this invocation
1827 as returned by ssu_$create_invocation. Input
1828 procedure_name
1829 is the name of the replaceable procedure which is to be reset.
1830 Input
1831 code
1832 is a standard system status code. Output It can have one of the
1833 following values:
1834 0
1835 the replaceable procedure was successfully reset.
1836 error_table_$noentry
1837 the supplied procedure name is not the name of a replaceable
1838 procedure.
1839
1840
1841 Notes: See the Programmer's Reference Manual for the currently defined
1842 list of replaceable procedure names.
1843
1844
1845 :Entry: reset_request_processor_options: 01/19/83 ssu_$reset_request_processor_options
1846
1847
1848 Function: This entrypoint resets the request processor options
1849 presently in effect for the current subsystem to their default values.
1850
1851
1852 Syntax:
1853 declare ssu_$reset_request_processor_options entry ptr;
1854
1855 call ssu_$reset_request_processor_options sci_ptr;
1856
1857
1858 Arguments:
1859 sci_ptr
1860 is a pointer to the subsystem control structure for this invocation
1861 as returned by ssu_$create_invocation Input
1862
1863
1864 Notes: See the information on the subsystem request language in the
1865 Programmer's Reference Manual for a description of the request
1866 processor options mechanism.
1867
1868 This is a replaceable procedure. See the Programmer's Reference Manual
1869 for information on the use of replaceable procedures within interactive
1870 subsystems.
1871
1872
1873 :Entry: return_arg: 01/19/83 ssu_$return_arg
1874
1875
1876 Function: This entry is used by a subsystem request procedure to
1877 determine whether it has been invoked as an active request, and to get
1878 a pointer and length for its return value if so. The return string
1879 should be declared as:
1880
1881 dcl return_value charrv_lth varying based rv_ptr;
1882
1883
1884 Syntax:
1885 declare ssu_$return_arg entry ptr fixed bin bit1 aligned ptr
1886 fixed bin21;
1887
1888 call ssu_$return_arg sci_ptr arg_count af_sw rv_ptr rv_lth;
1889
1890
1891 Arguments:
1892 sci_ptr
1893 is a pointer to the subsystem control structure for this invocation
1894 as returned by ssu_$create_invocation. Input
1895 arg_count
1896 is the number of arguments supplied to this request, not including
1897 the final return value argument, if any. Output
1898 af_sw
1899 is a bit indicating whether the request was invoked as a command
1900 request or an active request. Output It is "1"b if an active
1901 request, and "0"b otherwise.
1902 rv_ptr
1903 is a pointer to the return string if af_sw is "1"b; otherwise, it is
1904 null. Output
1905 rv_lth
1906 is the maximum length of the return string. Output
1907
1908
1909 Notes: This is a replaceable procedure. See the Programmer's
1910 Reference Manual for information on the use of replaceable procedures
1911 within interactive subsystems.
1912
1913
1914 :Entry: set_debug_mode: 01/19/83 ssu_$set_debug_mode
1915
1916
1917 Function: This entry is used to set debug mode for the subsystem.
1918 Information on the use of interactive subsystem debugging facilities is
1919 provided in the Programmer's Reference Manual.
1920
1921
1922 Syntax:
1923 declare ssu_$set_debug_mode entry ptr bit1 aligned;
1924
1925 call ssu_$set_debug_mode sci_ptr debug_mode;
1926
1927
1928 Arguments:
1929 sci_ptr
1930 is a pointer to the subsystem control structure for this invocation
1931 as returned by ssu_$create_invocation. Input
1932 debug_mode
1933 is the new value for debug mode, either on or off. Input
1934
1935
1936 :Entry: set_ec_search_list: 01/19/83 ssu_$set_ec_search_list
1937
1938
1939 Function: This entry is used to set the name of the search list used
1940 to find subsystem exec_com files. By default, no search list is used,
1941 and subsystem exec_coms must be specified by full pathname. This is
1942 the case if a null string is supplied. See also the descriptions of
1943 ssu_$set_ec_suffix and ssu_$set_ec_subsystem_ptr.
1944
1945
1946 Syntax:
1947 declare ssu_$set_ec_search_list entry ptr char32;
1948
1949 call ssu_$set_ec_search_list sci_ptr search_list_name;
1950
1951
1952 Arguments:
1953 sci_ptr
1954 is a pointer to the subsystem control structure for this invocation
1955 as returned by ssu_$create_invocation. Input
1956 search_list_name
1957 is the name of the search list to use for finding subsystem
1958 exec_coms in this subsystem invocation or a null string if no search
1959 list should be used in this subsystem invocation. Input
1960
1961
1962 :Entry: set_ec_subsystem_ptr: 01/19/83 ssu_$set_ec_subsystem_ptr
1963
1964
1965 Function: This entry sets the directory used to implement the
1966 "referencing_dir" rule in the search list for subsystem exec_coms. By
1967 default, this pointer is null, meaning that the referencing_dir rule
1968 has no effect, even if the search list name is non-null. This value is
1969 ignored if there is no exec_com search list set or if the search list
1970 does not use the referencing_dir rule. The referencing_dir can be used
1971 as a sort of exec_com "subsystem directory" to contain standard
1972 subsystem exec_coms for this subsystem. See also the descriptions of
1973 ssu_$set_ec_suffix and ssu_$set_ec_search_path.
1974
1975
1976 Syntax:
1977 declare ssu_$set_ec_subsystem_ptr entry ptr ptr;
1978
1979 call ssu_$set_ec_subsystem_ptr sci_ptr subsystem_ptr;
1980
1981
1982 Arguments:
1983 sci_ptr
1984 is a pointer to the subsystem control structure for this invocation
1985 as returned by ssu_$create_invocation. Input
1986 subsystem_ptr
1987 is a pointer to a segment which resides in the directory that will
1988 be used as the exec_com subsystem directory in this subsystem
1989 invocation or null if no directory is to be used. Input This
1990 pointer is only used in calls to hcs_$make_ptr and
1991 hcs_$fs_get_path_name.
1992
1993
1994 :Entry: set_ec_suffix: 01/19/83 ssu_$set_ec_suffix
1995
1996
1997 Function: This entry is used to set the suffix for subsystem exec_com
1998 files in this subsystem invocation. By default, this is the name of
1999 the subsystem eg: for the read_mail subsystem subsystem exec_coms
2000 would be named XXX.read_mail by default. See also the descriptions of
2001 ssu_$set_ec_search_path and ssu_$set_ec_subsystem_ptr below.
2002
2003
2004 Syntax:
2005 declare ssu_$set_ec_suffix entry ptr char32;
2006
2007 call ssu_$set_ec_suffix sci_ptr suffix_string;
2008
2009
2010 Arguments:
2011 sci_ptr
2012 is a pointer to the subsystem control structure for this invocation
2013 as returned by ssu_$create_invocation. Input
2014 suffix_string
2015 is the string to use as a suffix for subsystem exec_coms in this
2016 subsystem invocation. Input
2017
2018
2019 :Entry: set_info_dirs: 01/19/83 ssu_$set_info_dirs
2020
2021
2022 Function: This entry is used to set the list of info directories
2023 searched by this subsystem invocation. Additional information on the
2024 use of interactive subsystem self-documentation facilities is provided
2025 in the Programmer's Reference Manual.
2026
2027
2028 Syntax:
2029 declare ssu_$set_info_dirs entry ptr ptr fixed bin35;
2030
2031 call ssu_$set_info_dirs sci_ptr idl_ptr code;
2032
2033
2034 Arguments:
2035 sci_ptr
2036 is a pointer to the subsystem control structure for this invocation
2037 as returned by ssu_$create_invocation. Input
2038 idl_ptr
2039 is a pointer to the info_dirs_list structure which is the new list
2040 of info directories for this subsystem invocation; this structure is
2041 described in detail in the writeup of ssu_$list_info_dirs, above.
2042 The uid and info_dir_valid elements of the caller's structure are
2043 set appropriately by this call. Input
2044
2045
2046 code
2047 is a standard system status code. Output It can be one of the
2048 following:
2049 0
2050 indicates that the supplied info directories list was accepted.
2051 error_table_$unimplemented_version
2052 indicates that the supplied version of the info_dirs_list
2053 structure is not supported by this entry.
2054 any other value
2055 indicates that one or more directories in the list are not valid;
2056 the invalid directories are marked by the info_dir_valid bits in
2057 the caller's structure.
2058
2059
2060 Notes: Each supplied info directory is validated as described above in
2061 the description of ssu_$add_info_dir. This entry also fills in the
2062 values of the info_dir_valid and uid fields of the supplied
2063 info_dirs_list structure.
2064
2065 If all the info directories are valid, the current list is replaced
2066 with the newly supplied list and a zero status code is returned.
2067 Otherwise, if one of the supplied info directories is invalid, a
2068 storage system status code indicating the difficulty with the first
2069 invalid directory on the list is returned. If a non-zero code is
2070 returned, the invalid directories can be identified by examining the
2071 info_dir_valid bits.
2072
2073
2074 :Entry: set_info_ptr: 01/19/83 ssu_$set_info_ptr
2075
2076
2077 Function: This entry is used to set the info_ptr for this subsystem
2078 invocation.
2079
2080
2081 Syntax:
2082 declare ssu_$set_info_ptr entry ptr ptr;
2083
2084 call ssu_$set_info_ptr sci_ptr info_ptr
2085
2086
2087 Arguments:
2088 sci_ptr
2089 is a pointer to the subsystem control structure for this invocation
2090 as returned by ssu_$create_invocation. Input
2091 info_ptr
2092 is the info_ptr to be used for this subsystem invocation. Input
2093
2094
2095 Notes: This entry can be useful, for instance, when the subsystem info
2096 structure does not get set up until it is known that the call to
2097 ssu_$create_invocation succeeded; a null pointer can be passed as the
2098 info_ptr in the call to ssu_$create_invocation, and then when the
2099 subsystem info itself is set up, ssu_$set_info_ptr can be called to
2100 set the info pointer to point to it.
2101
2102
2103 :Entry: set_procedure: 01/19/83 ssu_$set_procedure
2104
2105
2106 Function: This entry is used to set the current value of a replaceable
2107 procedure in this subsystem invocation. It is used when a subsystem
2108 wishes to use a function other than the standard ssu_ provided
2109 interface for the specified function, such as a replacement for the
2110 request processor. See the Programmer's Reference Manual for
2111 information on the use of replaceable procedures within interactive
2112 subsystems.
2113
2114
2115 Syntax:
2116 declare ssu_$set_procedure entry ptr char* entry fixed bin35;
2117
2118 call ssu_$set_procedure sci_ptr procedure_name procedure_value
2119 code;
2120
2121
2122 Arguments:
2123 sci_ptr
2124 is a pointer to the subsystem control structure for this invocation
2125 as returned by ssu_$create_invocation. Input
2126 procedure_name
2127 is the name of the replaceable procedure which is to be set.
2128 Input
2129 procedure_value
2130 is the new value for the specified procedure. Input
2131 code
2132 is a status code. Output It can have the following values:
2133 0
2134 success.
2135 error_table_noentry
2136 procedure_name is not a acceptable name.
2137
2138
2139 Notes: See the Programmer's Reference Manual for the currently defined
2140 list of replaceable procedure names.
2141
2142
2143 :Entry: set_prompt: 01/19/83 ssu_$set_prompt
2144
2145
2146 Function: This entry is used to set the prompt string for the
2147 subsystem. See the description of interactive subsystem request loops
2148 in the Programmer's Reference Manual for additional information on
2149 prompts.
2150
2151
2152 Syntax:
2153 declare ssu_$set_prompt entry ptr char64 varying;
2154
2155 call ssu_$set_prompt sci_ptr prompt_string;
2156
2157
2158 Arguments:
2159 sci_ptr
2160 is a pointer to the subsystem control structure for this invocation
2161 as returned by ssu_$create_invocation. Input
2162 prompt_string
2163 is the string to use as the prompt from now on. Input
2164
2165
2166 :Entry: set_prompt_mode: 01/19/83 ssu_$set_prompt_mode
2167
2168
2169 Function: This entry is used to set the prompting mode for the
2170 subsystem. See the description of interactive subsystem request loops
2171 in the Programmer's Reference Manual for additional information on
2172 prompts.
2173
2174
2175 Syntax:
2176 declare ssu_$set_prompt_mode entry ptr bit*;
2177
2178 call ssu_$set_prompt_mode sci_ptr prompt_mode;
2179
2180
2181 Arguments:
2182 sci_ptr
2183 is a pointer to the subsystem control structure for this invocation
2184 as returned by ssu_$create_invocation. Input
2185 prompt_mode
2186 is the new prompt mode. Input The individual bits are interpreted
2187 as follows:
2188 bit 1 ON suppress all prompts.
2189 bit 2 ON prompt after blank request lines.
2190 bit 3 ON suppress prompts if there is type ahead.
2191 There are named constants in the ssu_prompt_modes.incl.pl1 include
2192 file that can be used to create this value.
2193
2194
2195 :Entry: set_ready_mode: 01/19/83 ssu_$set_ready_mode
2196
2197
2198 Function: This entry is used to turn ready message processing in the
2199 subsystem listener on or off. See the description of interactive
2200 subsystem request loops in the Programmer's Reference Manual for
2201 additional information on ready messages.
2202
2203
2204 Syntax:
2205 declare ssu_$set_ready_mode entry ptr bit1 aligned;
2206
2207 call ssu_$set_ready_mode sci_ptr enable_sw;
2208
2209
2210 Arguments:
2211 sci_ptr
2212 is a pointer to the subsystem control structure for this invocation
2213 as returned by ssu_$create_invocation. Input
2214 enable_sw
2215 is a bit indicating whether or not ready processing is to be
2216 enabled. Input If it is "1"b, ready processing will be performed;
2217 if it is "0"b, ready processing will not be performed.
2218
2219
2220 :Entry: set_request_processor_options: 01/19/83 ssu_$set_request_processor_options
2221
2222
2223 Function: This entrypoint changes the request processor options
2224 presently in effect for the current subsystem.
2225
2226
2227 Syntax:
2228 declare ssu_$set_request_processor_options entry ptr ptr
2229 fixed bin35;
2230
2231 call ssu_$set_request_processor_options sci_ptr rp_options_ptr
2232 code;
2233
2234
2235 Arguments:
2236 sci_ptr
2237 is a pointer to the subsystem control structure for this invocation
2238 as returned by ssu_$create_invocation. Input
2239 rp_options_ptr
2240 is a pointer to the rp_options structure containing the new request
2241 processor options for this subsystem. Input The rp_options
2242 structure is defined in the system include file
2243 ssu_rp_options.incl.pl1.
2244 code
2245 is a standard system status code. Output It can have one of the
2246 following values:
2247 0
2248 the requested options have been accepted and are now in effect
2249 for this subsytem.
2250
2251
2252 error_table_$unimplemented_version
2253 the version of the supplied rp_options structure is not
2254 RP_OPTIONS_VERSION_1.
2255 error_table_$bad_subr_arg
2256 a value other than one of the named constants in the system
2257 include file cp_character_types.incl.pl1 was used in the new
2258 request language.
2259 error_table_$unbalanced_brackets
2260 the new request language defined in the rp_options structure
2261 contains a character defined as a begin or end active string and
2262 no matching end or begin active string exists in the language.
2263 error_table_$unbalanced_parentheses
2264 the new request language defined in the rp_options structure
2265 contains a character defined as a begin or end iteration set and
2266 no matching end or begin iteration set exists in the language.
2267
2268
2269 Notes: See the information on the subsystem request language in the
2270 Programmer's Reference Manual for a description of the rp_options
2271 structure and the request processor options mechanism.
2272
2273 This is a replaceable procedure. See the Programmer's Reference Manual
2274 for information on the use of replaceable procedures within interactive
2275 subsystems.
2276
2277
2278 :Entry: set_request_tables: 01/19/83 ssu_$set_request_tables
2279
2280
2281 Function: This entry is used to set the list of request tables
2282 searched by this subsystem invocation. See the Programmer's Reference
2283 Manual for additional information on the use of interactive subsystem
2284 request tables.
2285
2286
2287 Syntax:
2288 declare ssu_$set_request_tables entry ptr ptr fixed bin35;
2289
2290 call ssu_$set_request_tables sci_ptr rtl_ptr code;
2291
2292
2293 Arguments:
2294 sci_ptr
2295 is a pointer to the subsystem control structure for this invocation
2296 as returned by ssu_$create_invocation. Input
2297 rtl_ptr
2298 is a pointer to the request_tables_list structure which is the new
2299 list of request tables for this subsystem invocation; this structure
2300 is described in detail in the writeup of ssu_$list_request_tables,
2301 above. The table_valid elements of the caller's structure are set
2302 appropriately by this call. Input
2303
2304
2305 code
2306 is a standard system status code. Output
2307 0
2308 the supplied request tables list was accepted.
2309 error_table_$unimplemented_version
2310 the supplied version of the request_tables_list structure is not
2311 supported by this entry.
2312 ssu_et_$invalid_request_table
2313 one or more of the request tables in the list are not valid; the
2314 invalid request tables are marked by the table_valid bits in the
2315 caller's structure.
2316
2317
2318 Notes: Each supplied request table is validated as described above in
2319 the description of ssu_$add_request_table. This entry also fills in
2320 the values of table_valid field of the supplied request_tables_list
2321 structure.
2322
2323 If all the request tables are valid, the current list is replaced with
2324 the newly supplied list and a zero status code is returned.
2325
2326
2327 :Entry: standalone_invocation: 01/19/83 ssu_$standalone_invocation
2328
2329
2330 Function: This entry creates a "standalone" subsystem invocation for
2331 use by Multics commands/active functions which can also be used as
2332 subsytem requests. Additional information on the use of Multics
2333 commands as subsystem requests is provided in the Programmer's
2334 Reference Manual.
2335
2336
2337 Syntax:
2338 declare ssu_$standalone_invocation entry ptr char* char* ptr
2339 entry fixed bin35;
2340
2341 call ssu_$standalone_invocation sci_ptr command_name
2342 command_version arg_list_ptr abort_entry code;
2343
2344
2345 Arguments:
2346 sci_ptr
2347 is a pointer to the subsystem control information created for this
2348 standalone invocation. Output
2349 command_name
2350 is the name of the Multics command/active function on whose behalf
2351 the standalone invocation is created. Input This name is printed
2352 in the message produced by calls to ssu_$print_message,
2353 suu_$abort_line, and ssu_$abort_subsystem.
2354 command_version
2355 is the current version of this command/active function. Input
2356
2357
2358 arg_list_ptr
2359 is a pointer to the command's argument list. Input If a null
2360 pointer is supplied, the subsystem will use the argument list of the
2361 caller of ssu_$standalone_invocation. This argument list can be
2362 examined by calls to ssu_$arg_ptr, ssu_$return_arg, and
2363 ssu_$arg_count.
2364 abort_entry
2365 is a procedure of no arguments which will be invoked by
2366 ssu_$abort_line and ssu_$abort_subsystem after the error message, if
2367 any, has been printed. Input
2368 code
2369 is a system status code. Output
2370
2371
2372 Notes: Calls to ssu_$execute_line and ssu_$evaluate_active_string
2373 within a standalone invocation are translated into calls to cu_$cp and
2374 cu_$evalaute_active_string, respectively.
2375
2376 Calls to ssu_$print_message, ssu_$abort_line and ssu_$abort_subsystem
2377 within a standalone invocation are translated into calls to com_err_ or
2378 active_fnc_err_ depending on whether the program which created the
2379 invocation was invoked as a Multics command or as a Multics active
2380 function. In addition, after the error message is printed,
2381 ssu_$abort_line and ssu_$abort_subsystem will invoke the abort_entry
2382 supplied when the subsystem invocation was created. This entry will
2383 normally perform a non-local goto back to a label in the command's main
2384 procedure so that it can clean up and return to its caller.