01/24/83 ssu_ The ssu_ subroutine provides a set of standard functions for use by application writers in developing their own subsystems. Use of ssu_ functions will enable the application builder to provide subsystems which are consistent in terms of user interface and system response. For detailed instructions on creating subsystems, see "Interactive Subsystem Programming Environment" in Section 4 of the Programmer's Reference Manual. Entry points in ssu_: (List is generated by the help command) :Entry: abort_line: 01/19/83 ssu_$abort_line Function: This entry is used to print an error message and abort the execution of the current request line. Additional information on interactive subsystem error handling is contained in the Programmer's Reference Manual. Syntax: declare ssu_$abort_line entry () options (variable); call ssu_$abort_line (sci_ptr, status_code, ioa_string, optional_args); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) It must be an aligned (unpacked) pointer. status_code is the status code for printing a message from an error table. (Input) If it is zero, no error table message is printed. It can be any datatype which can be converted to fixed bin(35). This argument is optional. ioa_string is an ioa_ control string used to generate the user message portion of the message to be printed. (Input, optional) It can be a varying or nonvarying character string. If it is not present, no user message is printed. optional_args are arguments to be substituted into the ioa_ control string. (Input, optional) They can be of any type required by the control string. Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entry point is translated into a call to com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. The format of the message is as follows: subsystem_name (request_name): Code message User message or: system_name: Code message User message The second form (without the request name) is used when the call is made when no request is currently being executed, such as when it is called by the subsystem command procedure, rather than a request procedure. The "Code message" is the error message associated with the status code. If the code argument is omitted or if its value is zero, the "Code message" is omitted, and only the "User message" is printed. The "User message" is formed by the appropriate substitutions in the ioa_ control string. :Entry: abort_subsystem: 01/19/83 ssu_$abort_subsystem Function: This entry is used to abort the current invocation of the subsystem, and optionally print an error message. Additional information on interactive subsystem error handling is contained in the Programmer's Reference Manual. Syntax: declare ssu_$abort_subsystem entry () options (variable); call ssu_$abort_subsystem (sci_ptr, status_code, ioa_string, optional_args); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) It must be an aligned (unpacked) pointer. status_code is the status code for printing a message from an error table. (Input, optional) If it is zero or omitted, no error table message is printed. It can be any datatype which can be converted to fixed bin(35). ioa_string is an ioa_ control string which will be used to generate the user message portion of the message to be printed. (Input, optional) It can be a varying or nonvarying character string. If it is not present, no user message is printed. optional_args are arguments to be substituted into the ioa_ control string. (Input, optional) They can be of any type required by the control string. Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entrypoint is translated into a call to com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. The format of the message is as follows: subsystem_name (request_name): Code message User message or: subsystem_name: Code message User message The second form (without the request name) is used when the call is made when no request is currently being executed, such as when it is called by the subsystem command procedure, rather than a request procedure. The "Code message" is the error message associated with the status code. If the code argument is omitted or if its value is zero, the "Code message" is omitted, and only the "User message" is printed. The "User message" is formed by the appropriate substitutions in the ioa_ control string. :Entry: add_info_dir: 01/19/83 ssu_$add_info_dir Function: This entry adds a new directory at the specified location in the list of info directories being searched by this subsystem invocation. Additional information on interactive subsystem self-documentation facilities is contained in the Programmer's Reference Manual. Syntax: declare ssu_$add_info_dir entry (ptr, char(*), fixed bin, fixed bin(35)); call ssu_$add_info_dir (sci_ptr, info_dir, position, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) info_dir is the pathname of the directory to be added to the list of info directories for this invocation. (Input) position is the position in the list where the info dir is to be added. (Input) It can be any positive integer. The new directory will become the Nth entry in the list of info directories (i.e., it is added before the directory already present in position N). To add a directory at the end, position should be specified as a large number, such as 100000, which will guarantee its being added after the last info directory. code is a storage system status code. (Output) If it is zero, the directory was valid and was added; otherwise, it indicates the nature of difficulty associated with the directory. Notes: This entry point validates the existence of the specified info directory, and refuses to add it, returning a nonzero status code, unless it is valid. The user must have "s" access to the directory in order to add it as an info directory. :Entry: add_request_table: 01/19/83 ssu_$add_request_table Function: This entry adds a new request table at the specified location in the list of request tables being searched by this subsystem invocation. Addition information on the use of interactive subsystem request tables is provided in the Programmer's Reference Manual. Syntax: declare ssu_$add_request_table entry (ptr, ptr, fixed bin, fixed bin(35)); call ssu_$add_request_table (sci_ptr, request_table_ptr, position, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) request_table_ptr is a pointer to a valid subsystem request table, to be added to the list searched for this invocation. (Input) position is the position in the list where the request table is to be added. (Input) It can be any positive integer. The new request table will be added as the Nth entry in the request tables list (i.e., it is added after the request table already present in position N. To add a request table at the end, position should be specified as a large number, such as 100000, which will guarantee its being added after the last request table. code is a status code. (Output) If it is zero, the table was valid and was added; or ssu_et_$invalid_request_table if it was not. Notes: This entry point validates the existence and validity of the specified request table, and refuses to add it, returning a nonzero status code, unless it is valid. :Entry: apply_request_util: 01/19/83 ssu_$apply_request_util Function: This entry is a utility procedure for implementing subsystem "apply" requests. The apply request is defined to create a Multics command line out of some or all of its request arguments, concatenate the pathname of a segment containing the specified object in the subsystem, and call the command processor. It can be used, for instance, to allow a user to edit a text file with the editor of her choice, with a request like "apply ted -pathname", which would be passed to the command processor as: ted -pathname PATHNAME_OF_TEMP_SEG If the apply request can take arguments which are meaningful to the subsystem, they must all come before the first argument which is to become part of the command line. It is recommended that the syntax of the apply request be designed so that the first argument which is not a control argument is taken as the beginning of the command line; its index will be passed as first_command_arg below. The temp_seg_ptr should point to a segment on which the bitcount can be set, or which is already set. It is recommended that the segment used for this purpose be obtained by calling ssu_$get_temp_segment. This entry returns no error code; rather, since it is only useful in implementing the apply request, it simply calls ssu_$abort_line if it encounters any serious errors, and prints a more informative message than could otherwise have been described by an error code. Syntax: declare ssu_$apply_request_util entry (ptr, fixed bin, ptr, fixed bin(21), fixed bin(21)); call ssu_$apply_request_util (sci_ptr, first_command_arg, temp_seg_ptr, input_lth, output_lth); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) first_command_arg is the index of the first request argument which is to become part of the command line. (Input) If the subsystem apply request accepts no subsystem arguments, this should be 1; otherwise, it should be the index of the first non-control argument to the apply request. temp_seg_ptr is a pointer to the segment containing the data to be manipulated by the command line. (Input) Its pathname will be determined, and concatenated onto the end of the command line. input_lth is the length, in characters, of the data in the segment, or -1. (Input) If it is non-negative, the bitcount of the segment is set to nine times input_lth before the command line is executed; otherwise, the bitcount is not altered. If the bitcount is set to correspond to input_lth, it will be restored to its previous value after the command line has been executed and after output_lth has been set to reflect its value. output_lth is the length, in characters, (derived from the bitcount) of the data in the segment, after the command line has been executed. (Output) :Entry: arg_count: 01/19/83 ssu_$arg_count Function: This entry is used to determine how many arguments a subsystem request received. Syntax: declare ssu_$arg_count entry (ptr, fixed bin); call ssu_$arg_count (sci_ptr, arg_count); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) arg_count is the number of arguments the request received. (Output) Notes: This entry point should only be used by requests which can not be invoked as an active request. If called by an active request, this entrypoint will abort the request line with the message: This request can not be used as an active function. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone procedure, a call to this entry point is translated into a call to cu_$arg_count. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. :Entry: arg_list_ptr: 01/19/83 ssu_$arg_list_ptr Function: This entry can be used by a subsystem request to get a pointer to its request argument list. This argument list is identical to that supplied to a Multics command by the command processor: a series of nonvarying character arguments followed by a varying character string argument if the request is invoked as an active request. The argument list can be manipulated with calls to cu_$arg_count_rel, cu_$arg_ptr_rel, and cu_$af_return_arg_rel, which are equivalent to ssu_$arg_count, ssu_$arg_ptr, and ssu_$return_arg for this application. Syntax: declare ssu_$arg_list_ptr entry (ptr, ptr); call ssu_$arg_list_ptr (sci_ptr, arg_list_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) arg_list_ptr is a pointer to the request argument list. (Output) Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: arg_ptr: 01/19/83 ssu_$arg_ptr Function: This entry is used by the procedure implementing a subsystem request to access its arguments. Syntax: declare ssu_$arg_ptr entry (ptr, fixed bin, ptr, fixed bin(21)); call ssu_$arg_ptr (sci_ptr, arg_index, arg_ptr, arg_lth); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) arg_index is the index of the argument to be accessed. It must be between one and the number of arguments supplied to the request. (Input) arg_ptr is a pointer to the selected argument, as a character string. (Output) arg_lth is the length of the selected argument, as a character string. (Output) Notes: If asked for an argument whose index exceeds the request's argument count, this entry point will abort the request line with the message: Expected argument missing. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entry point is translated into a call to cu_$arg_ptr or cu_$af_arg_ptr. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. :Entry: create_invocation: 01/19/83 ssu_$create_invocation Function: This entry is used to create an invocation of a subsystem. The subsystem invocation must later be destroyed by a call to ssu_$destroy_invocation. Additional information on interactive subsystems is provided in the Programmer's Reference Manual. Syntax: declare ssu_$create_invocation entry (char(*), char(*), ptr, ptr, char(*), ptr, fixed bin(35)); call ssu_$create_invocation (subsystem_name, version_string, info_ptr, request_table_ptr, info_directory, sci_ptr, code); Arguments: subsystem_name is the name of the subsystem. (Input) This name is used in error messages, in the output of the "." request (if any), as the default prompt, and as the default exec_com suffix. version_string is the name of the current version of the subsystem, such as "4.3j". (Input) It is used in the output of the "." request. info_ptr is a pointer to the invocation info structure specific to this subsystem. (Input) It points to a data structure containing all the information which must be passed between the command procedure and the request procedures for this invocation. request_table_ptr is a pointer to the request table used for this subsystem, or null. (Input) If it is null, there are no request tables for the subsystem invocation, and if any are desired, they must be added by calls to ssu_$add_request_table. At least one request table is required for processing of any requests. info_directory is the name of a directory in which the help and list_help requests (if any) will look for info files on the subsystem. (Input) If this is the null string, and no info directories are later added by calling ssu_$add_info_directory, the help and list_help requests will not operate. sci_ptr is a pointer to the subsystem control structure created for this invocation. (Output) code is a status code; if it is nonzero, the subsystem invocation could not be created, and processing should not continue. (Output) :Entry: delete_info_dir: 01/19/83 ssu_$delete_info_dir Function: This entry is used to delete a directory from the list of info directories being searched. The specified info directory must be in the list. In order to avoid confusion about pathnames, the comparison is done by filesystem unique ID, if that can be determined, otherwise by literal pathname. If the directory is not present, a nonzero status code is returned. Syntax: declare ssu_$delete_info_dir entry (ptr, char(*), fixed bin(35)); call ssu_$delete_info_dir (sci_ptr, info_dir, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) info_dir is the name of the directory to be deleted. (Input) code is a status code. (Output) It is zero if the specified info directory was found in the list, or error_table_$noentry if not. :Entry: delete_request_table: 01/19/83 ssu_$delete_request_table Function: This entry is used to delete a request table from the list of tables being searched. The specified request table must be in the list. If it is not present, a nonzero status code is returned. Syntax: declare ssu_$delete_request_table entry (ptr, ptr, fixed bin(35)); call ssu_$delete_request_table (sci_ptr, request_table_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) request_table_ptr is a pointer to the request table to be deleted. (Input) It is not checked for validity, or whether it points to a valid request table, so that invalid request table pointers can be removed from the list. code is a status code. It is zero if the specified request table pointer is found in the list, or ssu_et_$request_table_not_found if not. (Output) :Entry: destroy_invocation: 01/19/83 ssu_$destroy_invocation Function: This entry is used to destroy a subsystem invocation created by a previous call to ssu_$create_invocation or ssu_$standalone_invocation. Syntax: declare ssu_$destroy_invocation entry (ptr); call ssu_$destroy_invocation (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) Notes: If sci_ptr is null on input, the call is ignored. This entry point sets sci_ptr to null after destroying the invocation. :Entry: evaluate_active_string: 01/19/83 ssu_$evaluate_active_string Function: This entry is used to interpret a single active request string. It is the subsystem equivalent to cu_$evaluate_active_string. Syntax: declare ssu_$evaluate_active_string entry (ptr, ptr, char(*), fixed bin, char(*) varying, fixed bin(35)); call ssu_$evaluate_active_string (sci_ptr, rp_options_ptr, active_string, string_type, return_value, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) rp_options_ptr if null, specifies that the request processor options in effect for this subsystem are used. Otherwise, it locates an rp_options structure defining the options to be used to evaluate the active string. active_string is the active string to be evaluated. (Input) It should not include the outermost brackets. string_type specifies the type of active string to be evaluated. (Input) It must be one of the following values defined in the include file cp_active_string_types.incl.pl1: NORMAL_ACTIVE_STRING the active string return value should be rescanned for all command processor constructs. ([...]) TOKENS_ONLY_ACTIVE_STRING the active string return value should be rescanned only for whitespace and quotes. (|[...]) ATOMIC_ACTIVE_STRING the active string return value should not be rescanned. (||[...]) return_value is the result of the evaluation of the active string. (Output) code is a standard status code. If the standard evaluate_active_string procedure is being used, it will have one of the following values; if a user supplied procedure is in use, the list can be different. (Output) 0 indicates that the active string was successfully evaluated. error_table_$command_line_overflow indicates that the return value of the active string was too large to fit in the supplied return_value argument; as much as would fit is returned, however. ssu_et_$request_line_aborted indicates that evaluation of the active string was terminated by a call to ssu_$abort_line. This usually indicates that an error was encountered by one of the active requests; however, the error message has already been printed, so no message should be printed by the caller of ssu_$evaluate_active_string. ssu_et_$subsystem_aborted indicates that evaluation of the active string was terminated by a call to ssu_$abort_subsystem; this generally indicates that the subsystem should be terminated, and no further processing be done. In any case, no error message should be printed. anything else indicates a serious error condition occurred while trying to evaluate the active string. Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entrypoint is translated into a call to cu_$evaluate_active_string. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. :Entry: execute_line: 01/19/83 ssu_$execute_line Function: This entry is used to intepret a single request line. Syntax: declare ssu_$execute_line entry (ptr, ptr, fixed bin(21), fixed bin(35)); call ssu_$execute_line (sci_ptr, request_line_ptr, request_line_lth, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) request_line_ptr is a pointer to the request line to be executed. (Input) request_line_lth is the length of the request line, in characters. (Input) code is a standard status code. (Output) If the default execute_line procedure is being used, it can have one of the following values; these can be different if a user procedure is being used for this function. 0 the request line was executed successfully, and returned normally. ssu_et_$null_request_line the request line was "blank", in the command_processor_ sense, i.e., contained no requests, iteration or brackets, but was merely a mixture of whitespace and semi-colons. ssu_et_$request_line_aborted the request line was terminated during its execution by a call to ssu_$abort_line. This usually indicates that an error was encountered by one of the requests; however, the error message has already been printed, so no message should be printed by the caller of ssu_$execute_line. ssu_et_$subsystem_aborted the request line was terminated normally by a call to ssu_$abort_subsystem; this generally indicates that the subsystem should be terminated, and no further processing be done. In any case, no error message should be printed. ssu_$program_interrupt the request line was terminated by the user interrupting its execution and using the program interrupt command. The caller of this entry point need not print a message. anything else indicates a serious error condition occurred while trying to execute the request line. Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entry point is translated into a call to cu_$cp. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. :Entry: execute_start_up: 01/19/83 ssu_$execute_start_up Function: This entry point executes the current subsystem's start_up exec_com. Syntax: declare ssu_$execute_start_up entry () options (variable); call ssu_$execute_start_up (sci_ptr, code, optional_ec_args); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) code is a standard system status code. (Output) It can have one of the following values: 0 the start_up exec_com was executed successfully. error_table_$noentry there is no start_up exec_com for this subsystem. ssu_et_$exec_com_aborted execution of the exec_com was abnormally terminated. ssu_et_$subsystem_aborted execution of the exec_com was abnormally terminated by a call to ssu_$abort_subsystem. optional_ec_args are optional arguments to be passed to the start_up exec_com. (Input) These arguments must be either nonvarying unaligned or varying aligned character strings. Notes: The subsystem's start_up exec_com is a segment named "start_up.ec_suffix" where ec_suffix is the subsystem's exec_com suffix. See ssu_$set_ec_suffix for a description of how to change the suffix. This entrypoint searches for the start_up exec_com first in the the user's home directory, then in the user's project directory >udd>Project_id, and last in >site The first exec_com found, if any, is used. :Entry: execute_string: 01/19/83 ssu_$execute_string Function: This entry is used to execute a request string, usually expressed as an in-line constant or character string variable. It is provided only as a utility function which allows the execution of character strings as strings, rather than by pointer and length. It is implemented by a call to ssu_$execute_line; therefore, if ssu_$execute_line is changed, ssu_$execute_string will change in exactly the same way. Syntax: declare ssu_$execute_string entry (ptr, char(*), fixed bin(35)); call ssu_$execute_string (sci_ptr, request_string, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) request_string is a character string containing the requests to be executed. (Input) code is a status code. (Output) It can have any of the values specified for ssu_$execute_line. The list of error codes is only for the default procedure, and can be different if a user procedure is substituted. :Entry: get_area: 01/19/83 ssu_$get_area Function: This entry is used to obtain an area for use by the subsystem invocation. It calls the define_area_ subroutine to obtain an area in a temporary segment. The difference between using this entry and calling define_area_ directly is that areas acquired by calling ssu_$get_area are released when the subsystem invocation is destroyed, regardless of whether the user program had freed them earlier. Areas acquired by calling ssu_$get_area should be released by calling ssu_$release_area. Syntax: declare ssu_$get_area entry (ptr, ptr, char(*), ptr); call ssu_$get_area (sci_ptr, area_info_ptr, comment, area_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) area_info_ptr is a pointer to an area_info structure (defined in area_info.incl.pl1) describing the area, or null. (Input) If the area_info_ptr is null, an area with default characteristics is defined; see below for details. Only the area_control flags in the area_info are used by ssu_$get_area; the area is always put in a temporary segment. The area pointer is returned as the final argument to ssu_$get_area; it is not written into the area_info structure. comment is a comment identifying the use to which the area will be put. (Input) It is used in constructing the owner name for the call to define_area_, in the form: subsys_name.N (comment) where subsys_name is the name of the subsystem, N is the invocation level for this invocation, and the comment (if any) follows, in parentheses. This is done to make it easier to identify the segment names listed by list_temp_segments. area_ptr is a pointer to the area. (Output) It will always be valid; if for some reason the area cannot be acquired, the current request line (or subsystem invocation, if there is no request line) is aborted with an appropriate message. No errors are ever reflected back to the caller of ssu_$get_area. Notes: If the area_info_ptr supplied to ssu_$get_area is null, an area with default characteristics is created. The area is extensible, initially one segment long, and is zero_on_free (but not zero_on_alloc). All other area_control flags are off. If the subsystem is in "debug mode" (see description of ssu_$set_debug_mode), all areas (both user-specified and default) are created with the dont_free attribute. :Entry: get_debug_mode: 01/19/83 ssu_$get_debug_mode Function: This entry is used to get the current state of debug mode. Debug mode controls several features intended only as an aid to debugging. A description of interactive subsystem debug mode is provided in the Programmer's Reference Manual. Syntax: declare ssu_$get_debug_mode entry (ptr) returns (bit(1) aligned); debug_mode = ssu_$get_debug_mode (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) debug_mode is the current debug mode, either on or off. (Output) :Entry: get_default_procedure: 01/19/83 ssu_$get_default_procedure Function: This entry is used to get the default value for a replaceable procedure value. The value returned is the procedure which is called to perform the specified function if no calls to ssu_$set_procedure are ever made for that procedure. Syntax: declare ssu_$get_default_procedure entry (ptr, char(*), entry, fixed bin(35)); call ssu_$get_default_procedure (sci_ptr, procedure_name, procedure_value, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) procedure_name is the name of the procedure the value of which is to be returned. (Input) procedure_value is the default value of the specified replaceable procedure value. (Output) code is a status code. (Output) It can have the following values: 0 success. error_table_$noentry procedure_name is not an acceptable value. Notes: See the Programmer's Reference Manual for the currently defined list of replaceable procedure names. :Entry: get_default_rp_options: 01/19/83 ssu_$get_default_rp_options Function: This entrypoint returns the default request processor options for the current subsystem. Syntax: declare ssu_$get_default_rp_options entry (ptr, char(8), ptr, fixed bin(35)); call ssu_$get_default_rp_options (sci_ptr, version_wanted, rp_options_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) version_wanted specifies which version of the rp_options structure is to be returned by this procedure. (Input) This argument must have the value of the named constant RP_OPIONS_VERSION_1 defined in the system include file ssu_rp_options.incl.pl1. rp_options_ptr is a pointer to an rp_options structure previously allocated by the caller which is to be filled in by this entrypoint. (Input) This structure is declared in the system include file ssu_rp_options.incl.pl1. code is a standard system status code. (Output) It can have one of the following values: 0 the structure was successfully filled in. error_table_$unimplemented_version the caller requested an unrecognized version of the rp_options structure. Notes: See the information on the subsystem request language in the Programmer's Reference Manual for a description of the rp_options structure and the request processor options mechanism. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: get_ec_search_list: 01/19/83 ssu_$get_ec_search_list Function: This entry returns the name of the search list currently being used to find subsystem exec_com files. By default, no search list is used; exec_coms must be specified by full pathname, and this value is a null string. See also the description of ssu_$set_ec_search_list. Syntax: declare ssu_$get_ec_search_list entry (ptr) returns (char(32)); search_list_name = ssu_$get_ec_search_list (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) search_list_name is the name of the current exec_com search list or a null string if no search list is used by this subsystem invocation. (Return) :Entry: get_ec_subsystem_ptr: 01/19/83 ssu_$get_ec_subsystem_ptr Function: This entry returns the pointer currently used to implement the "referencing_dir" rule in the search list for subsystem exec_coms. By default, this pointer is null, meaning that the referencing_dir rule has no effect, even if the exec_com search list name is non-null. See also the description of ssu_$set_ec_subsystem_ptr. Syntax: declare ssu_$get_ec_subsystem_ptr entry (ptr) returns (ptr); subsystem_ptr = ssu_$get_ec_subsystem_ptr (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) subsystem_ptr is a pointer to some segment in the directory being used as the subsystem's exec_com referencing_dir or null if no such directory is being used. (Output) :Entry: get_ec_suffix: 01/19/83 ssu_$get_ec_suffix Function: This entry returns the suffix currently being used for subsystem exec_com files. By default, this string is the subsystem name. See also the description of ssu_$set_ec_suffix. Syntax: declare ssu_$get_ec_suffix entry (ptr) returns (char(32)); suffix_string = ssu_$get_ec_suffix (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) suffix_string is the current exec_com suffix for this subsystem invocation. (Output) :Entry: get_info_ptr: 01/19/83 ssu_$get_info_ptr Function: This entry is used to get the info_ptr for this subsystem invocation. Normally, this value is otherwise available, either as a request parameter, or as a variable in the command procedure of the subsystem. This entry is only useful in subroutines which are passed only the sci_ptr and not the info_ptr as parameters, such as user supplied abort procedures. Additional information on the use of sci_ptr and info_ptr is provided in the description of interactive subsystems in the Programmer's Reference Manual. Syntax: declare ssu_$get_info_ptr entry (ptr) returns (ptr); info_ptr = ssu_$get_info_ptr (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) info_ptr is the info_ptr for this subsystem invocation. (Output) :Entry: get_invocation_count: 01/19/83 ssu_$get_invocation_count Function: This entry is used to determine the invocation index of the current subsystem invocation, and also determine how many invocations of the subsystem are currently active. Syntax: declare ssu_$get_invocation_count entry (ptr, fixed bin, fixed bin); call ssu_$get_invocation_count (sci_ptr, this_level, max_level); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) this_level is the invocation index for this subsystem invocation. (Output) max_level is the invocation index for the highest numbered subsystem invocation presently active. (Output) :Entry: get_level_n_sci_ptr: 01/19/83 ssu_$get_level_n_sci_ptr Function: This entry is used to examine the state of other invocations of the subsystem by returning the info_ptr and sci_ptr for the other invocation. If the level index specifies an invocation which does not exist, the info_ptr and sci_ptr are returned as null. Additional information on the use of info_ptr and sci_ptr is provided in the description of interactive subsystems in the Programmer's Reference Manual. Syntax: declare ssu_$get_level_n_sci_ptr entry (ptr, fixed bin, ptr, ptr); call ssu_$get_level_n_sci_ptr (sci_ptr,level_index, other_sci_ptr, other_info_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) level_index is the index (invocation number, recursion level) of the other invocation of the subsystem for which information is desired. other_sci_ptr is the sci_ptr for the specified invocation of the subsystem. (Output) other_info_ptr is the info_ptr for the specified invocation of the subsystem. (Output) :Entry: get_prev_sci_ptr: 01/19/83 ssu_$get_prev_sci_ptr Function: This entry is used to examine the state of other invocations of the subsystem by returning the info_ptr and sci_ptr for the immediately previous invocation. If there is no previous invocation of the subsystem, the sci_ptr and info_ptr are returned as null. Additional information on the use of the info_ptr and sci_ptr is provided the description of interactive subsystems in the Programmer's Reference Manual. Syntax: declare ssu_$get_prev_sci_ptr entry (ptr, ptr, ptr); call ssu_$get_prev_sci_ptr (sci_ptr, previous_sci_ptr, previous_info_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) previous_sci_ptr is the sci_ptr for previous invocation of the subsystem. (Output) previous_info_ptr is the info_ptr for previous invocation of the subsystem. (Output) :Entry: get_procedure: 01/19/83 ssu_$get_procedure Function: This entry is used to get the current value for a replaceable procedure value in the specified subsystem invocation. The value returned is the procedure which is called to perform the specified function. Syntax: declare ssu_$get_procedure entry (ptr, char(*), entry, fixed bin(35)); call ssu_$get_procedure (sci_ptr, procedure_name, procedure_value, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) procedure_name is the name of the procedure for which the value is to be returned. (Input) procedure_value is the current value of the specified replaceable procedure value. (Output) code is a status code. (Output) It can have the following values: 0 success. error_table_$noentry procedure_name is not an acceptable value. Notes: See the Programmer's Reference Manual for the currently defined list of replaceable procedure names. :Entry: get_prompt: 01/19/83 ssu_$get_prompt Function: This entry is used to get the string currently being used as a prompt. See the description of request loops for interactive subsystems in the Programmer's Reference Manual for additional information on prompts. Syntax: declare ssu_$get_prompt entry (ptr) returns (char(64) varying); prompt_string = ssu_$get_prompt (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) prompt_string is the current prompt string. (Output) :Entry: get_prompt_mode: 01/19/83 ssu_$get_prompt_mode Function: This entry is used to get the current state of prompting in the subsystem. See the description of request loops for interactive subsystems in the Programmer's Reference Manual for additional information on prompts. Syntax: declare ssu_$get_prompt_mode entry (ptr) returns (bit(36) aligned); prompt_mode = ssu_$get_prompt_mode (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) prompt_mode is the current prompt mode. (Output) The individual bits are interpreted as follows: bit 1 ON suppress all prompts. bit 2 ON prompt after blank request lines. bit 3 ON suppress prompts if there is type ahead. There are named constants in the ssu_prompt_modes.incl.pl1 include file that may be used to examine this return value. :Entry: get_ready_mode: 01/19/83 ssu_$get_ready_mode Function: This entry is used to determine the current state of ready processing. See the description of request loops for interactive subsystems in the Programmer's Reference Manual for additional information on ready processing. Syntax: declare ssu_$get_ready_mode entry (ptr) returns (bit(1) aligned)); enable_sw = ssu_$get_ready_mode (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) enable_sw is a bit indicating whether or not ready processing is enabled. (Output) If it is "1"b, ready processing is being performed; if it is "0"b, ready processing is not being performed. :Entry: get_request_name: 01/19/83 ssu_$get_request_name Function: This entry is used to determine the primary name (from the request table) of the subsystem request currently being executed. If it is the null string, no request is currently being executed. Syntax: declare ssu_$get_request_name entry (ptr) returns (char(32)); request_name = ssu_$get_request_name (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) request_name is the name of the request currently being executed, or the null string. (Output) :Entry: get_request_processor_options: 01/19/83 ssu_$get_request_processor_options Function: This entrypoint returns the request processor options presently in effect for the current subsystem. Syntax: declare ssu_$get_request_processor_options entry (ptr, char(8), ptr, fixed bin(35)); call ssu_$get_request_processor_options (sci_ptr, version_wanted, rp_options_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) version_wanted specifies which version of the rp_options structure is to be returned by this procedure. (Input) This argument must have the value of the named constant RP_OPIONS_VERSION_1 defined in the system include file ssu_rp_options.incl.pl1. rp_options_ptr is a pointer to an rp_options structure previously allocated by the caller which is to be filled in by this entry point. (Input) This structure is declared in the system include file ssu_rp_options.incl.pl1. code is a standard system status code. (Output) It can have one of the following values: 0 the structure was successfully filled in. error_table_$unimplemented_version the caller requested an unrecognized version of the rp_options structure. Notes: See the information on the subsystem request language in the Programmer's Reference Manual for a description of the rp_options structure and the request processor options mechanism. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: get_subsystem_and_request_name: 01/19/83 ssu_$get_subsystem_and_request_name Function: This entry is used to acquire a string identifying the subsystem and the current request, suitable for use in printing error messages or asking questions. If no request is currently being executed, the name returned is the name of the subsystem; otherwise, it has the following format: subsystem_name (request_name) Syntax: declare ssu_$get_subsystem_and_request_name entry (ptr) returns (char(72) varying); name = ssu_$get_subsystem_and_request_name (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) name is the name of the subsystem and request currently being executed, as described above. (Output) :Entry: get_subsystem_name: 01/19/83 ssu_$get_subsystem_name Function: This entry is used to determine the name, supplied in the call to ssu_$create_invocation or ssu_$standalone_invocation, of the subsystem owning the specified invocation. Syntax: declare ssu_$get_subsystem_name entry (ptr) returns (char(32)); subsystem_name = ssu_$get_subsystem_name (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) subsystem_name is the name of the subsystem owning the current invocation. (Output) :Entry: get_subsystem_version: 01/19/83 ssu_$get_subsystem_version Function: This entry is used to determine the version number of the subsystem which was supplied as a parameter in the call to ssu_$create_invocation or ssu_$standalone_invocation. Syntax: declare ssu_$get_subsystem_version entry (ptr) returns (char(32)); subsystem_version = ssu_$get_subsystem_version (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) subsystem_version is the version number of the subsystem owning the current invocation. (Output) :Entry: get_temp_segment: 01/19/83 ssu_$get_temp_segment Function: This entry is used to obtain a temporary segment for use by the current subsystem invocation. It calls get_temp_segment_ to acquire the segment. The difference between using this entry and calling get_temp_segment_ directly is that segments acquired by calling ssu_$get_temp_segment are released when the subsystem invocation is destroyed, regardless of whether the user program had freed them earlier. Segments acquired by calling ssu_$get_temp_segment should be released by calling ssu_$release_temp_segment. Syntax: declare ssu_$get_temp_segment entry (ptr, char(*), ptr); call ssu_$get_temp_segment (sci_ptr, comment, temp_seg_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) comment is a comment identifying the use to which the segment will be put. (Input) It is used in constructing the owner name for the call to get_temp_segment_, in the form: subsystem_name.N (comment) where subsys_name is the name of the subsystem, N is the invocation level for this invocation, and the comment (if any) follows, in parentheses. This is done to make it easier to identify the segment names listed by list_temp_segments. temp_seg_ptr is a pointer to the temporary segment. (Output) It will always be valid. If for some reason a temporary segment cannot be acquired, the current request line (or subsystem invocation, if there is no request line) is aborted with an appropriate message. No errors are ever reflected back to the caller of ssu_$get_temp_segment. :Entry: list_info_dirs: 01/19/83 ssu_$list_info_dirs Function: This entry is used to obtain a list of the info directories currently in use by this subsystem invocation. Syntax: declare ssu_$list_info_dirs entry (ptr, ptr, fixed bin, ptr, fixed bin(35)); call ssu_$list_info_dirs (sci_ptr, area_ptr, info_dirs_list_version, idl_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) area_ptr is a pointer to an area in which the returned list of info directories can be allocated. (Input) info_dirs_list_version is the version of the info_dirs_list structure which the caller expects. The only version of this structure which can currently be requested is INFO_DIRS_LIST_VERSION_1. (Input) idl_ptr is a pointer to the info_dirs_list structure described below allocated by this entrypoint. (Output) code is a standard system status code. If the version of the info_dirs_list structure requested is not supported, this value will be error_table_$unimplemented_version. (Output) Notes: The info_dirs_list structure and the named constant INFO_DIRS_LIST_VERSION_1 are defined in the include file ssu_info_dirs_list.incl.pl1. The info_dirs_list structure is defined as follows: dcl 1 info_dirs_list aligned based (idl_ptr), 2 header, 3 version fixed bin, 3 n_info_dirs fixed bin, 2 info_dirs (0 refer (info_dirs_list.n_info_dirs)), 3 info_dirname char(168) unaligned, 3 uid bit(36), 3 flags, 4 info_dir_valid bit(1) unaligned, 4 pad bit(35) unaligned; Structure elements: version is the current version of this structure and has the value of the named constant INFO_DIRS_LIST_VERSION_1. n_info_dirs is the number of info directories in use by this subsystem invocation. info_dirs(i).info_dirname is the absolute pathname of this directory. info_dirs(i).uid is the file system unique ID of this directory if it can be determined; otherwise, it is "0"b. info_dirs(i).info_dir_valid is "1"b if this info directory is considered valid by the subsystem utilities; otherwise, it is "0"b. :Entry: list_request_tables: 01/19/83 ssu_$list_request_tables Function: This entry is used to obtain a list of the request tables currently in use by this subsystem invocation. Syntax: declare ssu_$list_request_tables entry (ptr, ptr, fixed bin, ptr, fixed bin(35)); call ssu_$list_request_tables (sci_ptr, area_ptr, request_tables_list_version, rtl_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) area_ptr is a pointer to an area in which the returned list of request tables can be allocated. (Input) request_tables_list_version is the version of the request_tables_list structure which the caller expects. The only version of this structure which can currently be requested is REQUEST_TABLES_LIST_VERSION_1. (Input) rdl_ptr is a pointer to the request_tables_list structure described below allocated by this entrypoint. (Output) code is a standard system status code. If the version of the request_tables_list structure requested is not supported, this value will be error_table_$unimplemented_version. (Output) Notes: The request_tables_list structure and the named constant REQUEST_TABLES_LIST_VERSION_1 are defined in the include file ssu_request_tables_list.incl.pl1. dcl 1 request_tables_list aligned based (rtl_ptr), 2 header, 3 version fixed bin, 3 n_tables fixed bin, 2 tables (0 refer (request_tables_list.n_tables)), 3 table_ptr ptr, 3 flags, 4 table_valid bit(1) unaligned, 4 pad bit(35) unaligned, 3 pad bit(36); Structure elements: version is the current version of this structure and has the value of the named constant REQUEST_TABLES_LIST_VERSION_1. n_tables is the number of request tables in use by this subsystem invocation. tables(i).table_ptr is a pointer to this request table. tables(i).table_valid is "1"b if this request table is considered valid by the subsystem utilities; otherwise, it is "0"b. :Entry: listen: 01/19/83 ssu_$listen Function: This entry implements the subsystem listener. The interactive subsystem listener is described in the Programmer's Reference Manual. Syntax: declare ssu_$listen entry (ptr, ptr, fixed bin(35)); call ssu_$listen (sci_ptr, iocb_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) iocb_ptr is a pointer to the IOCB for the I/O switch from which input lines are to be read. If it is null, the default I/O switch, user_input, is used. (Input) code is a status code. It can never be zero for this entrypoint. If it is ssu_et_$subsystem_aborted, it indicates that the subsystem was exited normally, by a call to ssu_$subsystem_abort, and is not an error condition. Any other code indicates an error condition which prevented the listener from operating. This list of codes is only valid if the default listen procedure is being used; it can be different if a user listen procedure is in use. (Output) Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedure within interactive subsystems. :Entry: print_blast: 01/19/83 ssu_$print_blast Function: This entry is used to print a "blast" message announcing a new version of the subsystem, if the user running the subsystem has not yet used the new version more than a certain number of times. This "threshold" value is provided to give the user several opportunities to find out what has been changed. See the description of interactive subsystem usage monitoring in the Programmer's Reference Manual for additional information. Syntax: declare ssu_$print_blast entry (ptr, ptr, fixed bin, char(*) varying, fixed bin(35)); call ssu_$print_blast (sci_ptr, ref_ptr, threshold, blast_message, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) ref_ptr is a pointer used as a referencing_dir argument in the call to hcs_$make_ptr to find the usage segment. It is usually codeptr of an entrypoint in the calling procedure. (Input) threshold is the maximum number of times to print a blast message announcing the new version for any particular user. (Input) blast_message is a blast message to be appended to the version announcement message. (Input) This might typically be a brief list of the changes in this version of the subsystem. If the blast_message is a null string, only the subsystem name and version number are printed (if anything is printed at all). code is a status code indicating whether the usage was successfully recorded. (Output) In general, the code should be ignored, since there is nothing useful the caller can do about it. :Entry: print_message: 01/19/83 ssu_$print_message Function: This entry is used by a request procedure or the subsystem command procedure to print an informational, warning, or nonfatal error message. Syntax: declare ssu_$print_message entry () options (variable); call ssu_$print_message (sci_ptr, status_code, ioa_string, optional_args); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) status_code is the status code for printing a message from an error table. (Input) If it is zero, no error table message is printed. It can be any datatype which can be converted to fixed bin(35). ioa_string is an ioa_ control string which is used to format the user message portion of the message to be printed. (Input, optional) It can be a varying or nonvarying character string. If it is not present, no user message is printed. optional_args are arguments to be substituted into the ioa_ control string. (Input, optional) They can be of any type required by the control string. Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. In a standalone invocation, a call to this entrypoint is translated into a call to com_err_ or active_fnc_err_ as appropriate. See the Programmer's Reference Manual for information on the use of standalone subsystem invocations. The format of the message is as follows: subsystem_name (request_name): Code message User message or: subsystem_name: Code message User message The second form (without the request name) is used when the call is made when no request is currently being executed, such as when it is called by the subsystem command procedure, rather than a request procedure. The "Code message" is the error message associated with the status code. If the code is zero, the "Code message" is omitted, and only the "User message" is printed. The "User message" is formed by the appropriate substitutions in the ioa_ control string. :Entry: record_usage: 01/19/83 ssu_$record_usage Function: This entry is used to make an entry in the usage segment to record a use of the subsystem, without printing a "blast" message. See the description of interactive subsystem usage monitoring in the Programmer's Reference Manual for additional information. Syntax: declare ssu_$record_usage entry (ptr, ptr, fixed bin(35)); call ssu_$record_usage (sci_ptr, ref_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) ref_ptr is a pointer used as a referencing_dir argument in the call to hcs_$make_ptr to find the usage segment. (Input) It is usually codeptr of an entrypoint in the calling procedure. code is a status code indicating whether the usage was successfully recorded. (Output) In general, the code should be ignored, since there is nothing useful the caller can do about it. :Entry: release_area: 01/19/83 ssu_$release_area Function: This entry is used to release an area previously obtained by a call to ssu_$get_area. It can only be used to release areas acquired for the specified subsystem invocation. It returns no error code because any errors encountered are simply ignored, and taken care of at the time the subsystem invocation is destroyed. Syntax: declare ssu_$release_area entry (ptr, ptr); call ssu_$release_area (sci_ptr, area_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) area_ptr is a pointer to the area to be released. (Input) :Entry: release_temp_segment: 01/19/83 ssu_$release_temp_segment Function: This entry is used to release a temporary segment previously acquired by a call to ssu_$get_temp_segment. It can only be used to release temporary segments acquired for the specified subsystem invocation. It returns no error code because any errors encountered are simply ignored, and taken care of at the time the subsystem invocation is destroyed. Syntax: declare ssu_$release_temp_segment entry (ptr, ptr); call ssu_$release_temp_segment (sci_ptr, temp_seg_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) temp_seg_ptr is a pointer to the temporary segment to be released. (Input) :Entry: reset_procedure: 01/19/83 ssu_$reset_procedure Function: This entrypoint resets a replaceable procedure in the current subsystem to its default value. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. Syntax: declare ssu_$reset_procedure entry (ptr, char(*), fixed bin(35)); call ssu_$reset_procedure (sci_ptr, procedure_name, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) procedure_name is the name of the replaceable procedure which is to be reset. (Input) code is a standard system status code. (Output) It can have one of the following values: 0 the replaceable procedure was successfully reset. error_table_$noentry the supplied procedure name is not the name of a replaceable procedure. Notes: See the Programmer's Reference Manual for the currently defined list of replaceable procedure names. :Entry: reset_request_processor_options: 01/19/83 ssu_$reset_request_processor_options Function: This entrypoint resets the request processor options presently in effect for the current subsystem to their default values. Syntax: declare ssu_$reset_request_processor_options entry (ptr); call ssu_$reset_request_processor_options (sci_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation (Input) Notes: See the information on the subsystem request language in the Programmer's Reference Manual for a description of the request processor options mechanism. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: return_arg: 01/19/83 ssu_$return_arg Function: This entry is used by a subsystem request procedure to determine whether it has been invoked as an active request, and to get a pointer and length for its return value if so. The return string should be declared as: dcl return_value char(rv_lth) varying based (rv_ptr); Syntax: declare ssu_$return_arg entry (ptr, fixed bin, bit(1) aligned, ptr, fixed bin(21)); call ssu_$return_arg (sci_ptr, arg_count, af_sw, rv_ptr, rv_lth); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) arg_count is the number of arguments supplied to this request, not including the final return value argument, if any. (Output) af_sw is a bit indicating whether the request was invoked as a command request or an active request. (Output) It is "1"b if an active request, and "0"b otherwise. rv_ptr is a pointer to the return string if af_sw is "1"b; otherwise, it is null. (Output) rv_lth is the maximum length of the return string. (Output) Notes: This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: set_debug_mode: 01/19/83 ssu_$set_debug_mode Function: This entry is used to set debug mode for the subsystem. Information on the use of interactive subsystem debugging facilities is provided in the Programmer's Reference Manual. Syntax: declare ssu_$set_debug_mode entry (ptr, bit(1) aligned); call ssu_$set_debug_mode (sci_ptr, debug_mode); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) debug_mode is the new value for debug mode, either on or off. (Input) :Entry: set_ec_search_list: 01/19/83 ssu_$set_ec_search_list Function: This entry is used to set the name of the search list used to find subsystem exec_com files. By default, no search list is used, and subsystem exec_coms must be specified by full pathname. This is the case if a null string is supplied. See also the descriptions of ssu_$set_ec_suffix and ssu_$set_ec_subsystem_ptr. Syntax: declare ssu_$set_ec_search_list entry (ptr, char(32)); call ssu_$set_ec_search_list (sci_ptr, search_list_name); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) search_list_name is the name of the search list to use for finding subsystem exec_coms in this subsystem invocation or a null string if no search list should be used in this subsystem invocation. (Input) :Entry: set_ec_subsystem_ptr: 01/19/83 ssu_$set_ec_subsystem_ptr Function: This entry sets the directory used to implement the "referencing_dir" rule in the search list for subsystem exec_coms. By default, this pointer is null, meaning that the referencing_dir rule has no effect, even if the search list name is non-null. This value is ignored if there is no exec_com search list set or if the search list does not use the referencing_dir rule. The referencing_dir can be used as a sort of exec_com "subsystem directory" to contain standard subsystem exec_coms for this subsystem. See also the descriptions of ssu_$set_ec_suffix and ssu_$set_ec_search_path. Syntax: declare ssu_$set_ec_subsystem_ptr entry (ptr, ptr); call ssu_$set_ec_subsystem_ptr (sci_ptr, subsystem_ptr); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) subsystem_ptr is a pointer to a segment which resides in the directory that will be used as the exec_com subsystem directory in this subsystem invocation or null if no directory is to be used. (Input) This pointer is only used in calls to hcs_$make_ptr and hcs_$fs_get_path_name. :Entry: set_ec_suffix: 01/19/83 ssu_$set_ec_suffix Function: This entry is used to set the suffix for subsystem exec_com files in this subsystem invocation. By default, this is the name of the subsystem (eg: for the read_mail subsystem, subsystem exec_coms would be named XXX.read_mail by default.) See also the descriptions of ssu_$set_ec_search_path and ssu_$set_ec_subsystem_ptr below. Syntax: declare ssu_$set_ec_suffix entry (ptr, char(32)); call ssu_$set_ec_suffix (sci_ptr, suffix_string); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) suffix_string is the string to use as a suffix for subsystem exec_coms in this subsystem invocation. (Input) :Entry: set_info_dirs: 01/19/83 ssu_$set_info_dirs Function: This entry is used to set the list of info directories searched by this subsystem invocation. Additional information on the use of interactive subsystem self-documentation facilities is provided in the Programmer's Reference Manual. Syntax: declare ssu_$set_info_dirs entry (ptr, ptr, fixed bin(35)); call ssu_$set_info_dirs (sci_ptr, idl_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) idl_ptr is a pointer to the info_dirs_list structure which is the new list of info directories for this subsystem invocation; this structure is described in detail in the writeup of ssu_$list_info_dirs, above. The uid and info_dir_valid elements of the caller's structure are set appropriately by this call. (Input) code is a standard system status code. (Output) It can be one of the following: 0 indicates that the supplied info directories list was accepted. error_table_$unimplemented_version indicates that the supplied version of the info_dirs_list structure is not supported by this entry. any other value indicates that one or more directories in the list are not valid; the invalid directories are marked by the info_dir_valid bits in the caller's structure. Notes: Each supplied info directory is validated as described above in the description of ssu_$add_info_dir. This entry also fills in the values of the info_dir_valid and uid fields of the supplied info_dirs_list structure. If all the info directories are valid, the current list is replaced with the newly supplied list and a zero status code is returned. Otherwise, if one of the supplied info directories is invalid, a storage system status code indicating the difficulty with the first invalid directory on the list is returned. If a non-zero code is returned, the invalid directories can be identified by examining the info_dir_valid bits. :Entry: set_info_ptr: 01/19/83 ssu_$set_info_ptr Function: This entry is used to set the info_ptr for this subsystem invocation. Syntax: declare ssu_$set_info_ptr entry (ptr, ptr); call ssu_$set_info_ptr (sci_ptr, info_ptr) Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) info_ptr is the info_ptr to be used for this subsystem invocation. (Input) Notes: This entry can be useful, for instance, when the subsystem info structure does not get set up until it is known that the call to ssu_$create_invocation succeeded; a null pointer can be passed as the info_ptr in the call to ssu_$create_invocation, and then when the subsystem info itself is set up, ssu_$set_info_ptr can be called to set the info pointer to point to it. :Entry: set_procedure: 01/19/83 ssu_$set_procedure Function: This entry is used to set the current value of a replaceable procedure in this subsystem invocation. It is used when a subsystem wishes to use a function other than the standard ssu_ provided interface for the specified function, such as a replacement for the request processor. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. Syntax: declare ssu_$set_procedure entry (ptr, char(*), entry, fixed bin(35)); call ssu_$set_procedure (sci_ptr, procedure_name, procedure_value, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) procedure_name is the name of the replaceable procedure which is to be set. (Input) procedure_value is the new value for the specified procedure. (Input) code is a status code. (Output) It can have the following values: 0 success. error_table_noentry procedure_name is not a acceptable name. Notes: See the Programmer's Reference Manual for the currently defined list of replaceable procedure names. :Entry: set_prompt: 01/19/83 ssu_$set_prompt Function: This entry is used to set the prompt string for the subsystem. See the description of interactive subsystem request loops in the Programmer's Reference Manual for additional information on prompts. Syntax: declare ssu_$set_prompt entry (ptr, char(64) varying); call ssu_$set_prompt (sci_ptr, prompt_string); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) prompt_string is the string to use as the prompt from now on. (Input) :Entry: set_prompt_mode: 01/19/83 ssu_$set_prompt_mode Function: This entry is used to set the prompting mode for the subsystem. See the description of interactive subsystem request loops in the Programmer's Reference Manual for additional information on prompts. Syntax: declare ssu_$set_prompt_mode entry (ptr, bit(*)); call ssu_$set_prompt_mode (sci_ptr, prompt_mode); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) prompt_mode is the new prompt mode. (Input) The individual bits are interpreted as follows: bit 1 ON suppress all prompts. bit 2 ON prompt after blank request lines. bit 3 ON suppress prompts if there is type ahead. There are named constants in the ssu_prompt_modes.incl.pl1 include file that can be used to create this value. :Entry: set_ready_mode: 01/19/83 ssu_$set_ready_mode Function: This entry is used to turn ready message processing in the subsystem listener on or off. See the description of interactive subsystem request loops in the Programmer's Reference Manual for additional information on ready messages. Syntax: declare ssu_$set_ready_mode entry (ptr, bit(1) aligned); call ssu_$set_ready_mode (sci_ptr, enable_sw); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) enable_sw is a bit indicating whether or not ready processing is to be enabled. (Input) If it is "1"b, ready processing will be performed; if it is "0"b, ready processing will not be performed. :Entry: set_request_processor_options: 01/19/83 ssu_$set_request_processor_options Function: This entrypoint changes the request processor options presently in effect for the current subsystem. Syntax: declare ssu_$set_request_processor_options entry (ptr, ptr, fixed bin(35)); call ssu_$set_request_processor_options (sci_ptr, rp_options_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) rp_options_ptr is a pointer to the rp_options structure containing the new request processor options for this subsystem. (Input) The rp_options structure is defined in the system include file ssu_rp_options.incl.pl1. code is a standard system status code. (Output) It can have one of the following values: 0 the requested options have been accepted and are now in effect for this subsytem. error_table_$unimplemented_version the version of the supplied rp_options structure is not RP_OPTIONS_VERSION_1. error_table_$bad_subr_arg a value other than one of the named constants in the system include file cp_character_types.incl.pl1 was used in the new request language. error_table_$unbalanced_brackets the new request language defined in the rp_options structure contains a character defined as a begin or end active string and no matching end or begin active string exists in the language. error_table_$unbalanced_parentheses the new request language defined in the rp_options structure contains a character defined as a begin or end iteration set and no matching end or begin iteration set exists in the language. Notes: See the information on the subsystem request language in the Programmer's Reference Manual for a description of the rp_options structure and the request processor options mechanism. This is a replaceable procedure. See the Programmer's Reference Manual for information on the use of replaceable procedures within interactive subsystems. :Entry: set_request_tables: 01/19/83 ssu_$set_request_tables Function: This entry is used to set the list of request tables searched by this subsystem invocation. See the Programmer's Reference Manual for additional information on the use of interactive subsystem request tables. Syntax: declare ssu_$set_request_tables entry (ptr, ptr, fixed bin(35)); call ssu_$set_request_tables (sci_ptr, rtl_ptr, code); Arguments: sci_ptr is a pointer to the subsystem control structure for this invocation as returned by ssu_$create_invocation. (Input) rtl_ptr is a pointer to the request_tables_list structure which is the new list of request tables for this subsystem invocation; this structure is described in detail in the writeup of ssu_$list_request_tables, above. The table_valid elements of the caller's structure are set appropriately by this call. (Input) code is a standard system status code. (Output) 0 the supplied request tables list was accepted. error_table_$unimplemented_version the supplied version of the request_tables_list structure is not supported by this entry. ssu_et_$invalid_request_table one or more of the request tables in the list are not valid; the invalid request tables are marked by the table_valid bits in the caller's structure. Notes: Each supplied request table is validated as described above in the description of ssu_$add_request_table. This entry also fills in the values of table_valid field of the supplied request_tables_list structure. If all the request tables are valid, the current list is replaced with the newly supplied list and a zero status code is returned. :Entry: standalone_invocation: 01/19/83 ssu_$standalone_invocation Function: This entry creates a "standalone" subsystem invocation for use by Multics commands/active functions which can also be used as subsytem requests. Additional information on the use of Multics commands as subsystem requests is provided in the Programmer's Reference Manual. Syntax: declare ssu_$standalone_invocation entry (ptr, char(*), char(*), ptr, entry, fixed bin(35)); call ssu_$standalone_invocation (sci_ptr, command_name, command_version, arg_list_ptr, abort_entry, code); Arguments: sci_ptr is a pointer to the subsystem control information created for this standalone invocation. (Output) command_name is the name of the Multics command/active function on whose behalf the standalone invocation is created. (Input) This name is printed in the message produced by calls to ssu_$print_message, suu_$abort_line, and ssu_$abort_subsystem. command_version is the current version of this command/active function. (Input) arg_list_ptr is a pointer to the command's argument list. (Input) If a null pointer is supplied, the subsystem will use the argument list of the caller of ssu_$standalone_invocation. This argument list can be examined by calls to ssu_$arg_ptr, ssu_$return_arg, and ssu_$arg_count. abort_entry is a procedure of no arguments which will be invoked by ssu_$abort_line and ssu_$abort_subsystem after the error message, if any, has been printed. (Input) code is a system status code. (Output) Notes: Calls to ssu_$execute_line and ssu_$evaluate_active_string within a standalone invocation are translated into calls to cu_$cp and cu_$evalaute_active_string, respectively. Calls to ssu_$print_message, ssu_$abort_line and ssu_$abort_subsystem within a standalone invocation are translated into calls to com_err_ or active_fnc_err_ depending on whether the program which created the invocation was invoked as a Multics command or as a Multics active function. In addition, after the error message is printed, ssu_$abort_line and ssu_$abort_subsystem will invoke the abort_entry supplied when the subsystem invocation was created. This entry will normally perform a non-local goto back to a label in the command's main procedure so that it can clean up and return to its caller. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved