06/17/82 sub_err_ Entry points in sub_err_: (List is generated by the help command) :Entry: sub_err_: 09/22/86 sub_err_ (entry point) Syntax: declare sub_err_ entry options (variable); call sub_err_ (code, name, flags, info_ptr, retval, ctl_string, ioa_args); Function: sub_err_ is called by other programs that wish to report an unexpected situation without usurping the calling environment's responsibility for the content of and disposition of the error message and the choice of what to do next. The caller specifies an identifying message and may specify a status code. Switches that describe whether and how to continue execution and a pointer to further information may also be passed to this subroutine. The environment that invoked the subroutine caller of sub_err_ may intercept and modify the standard system action taken when this subroutine is called. General purpose subsystems or subroutines, which can be called in a variety of I/O and error handling environments, should report the errors they detect by calling the sub_err_ subroutine. Arguments: code is a standard status code describing the reason for calling the sub_err_ subroutine. (Input) (It is normally declared fixed bin(35); but it can be any computational data type. If not fixed bin(35), it will be converted to fixed bin(35)). name is the name (declared as a nonvarying character string) of the subsystem or module on whose behalf the sub_err_ subroutine is called. (Input) flags describe options associated with the error. (Input) The flags argument should be declared as a nonvarying bit string. The following values, located in the include file sub_err_flags.incl.pl1, are permitted: ACTION_CAN_RESTART init (""b), ACTION_CANT_RESTART init ("1"b), ACTION_DEFAULT_RESTART init ("01"b), ACTION_QUIET_RESTART init ("001"b) ACTION_SUPPORT_SIGNAL init ("0001"b)) bit (36) aligned internal static options (constant); Each bit corresponds to one of the action flags in the standard condition_info_header structure, declared in condition_info_header.incl.pl1. If multiple bits are on in the supplied string, all the specified flags are set. See the MPM Reference Guide for definitions of the flags. info_ptr is a pointer (declared as an aligned pointer) to optional information specific to the situation. (Input) This argument is used as input to initialize info.info_ptr (see "Info Structure" below). The standard system environment does not use this pointer, but it is provided for the convenience of other environments. retval is a return value from the environment to which the error was reported. (Input/Output) This argument is used as input to initialize info.retval (see "Info Structure" below). The standard system environment sets this value to zero. Other environments may set the retval argument to other values, which may be used to select recovery strategies. The retval argument should be declared fixed bin(35). ctl_string is an ioa_ format control string (declared as a nonvarying character string) that defines the message associated with the call to the sub_err_ subroutine. (Input) Consult the description of the ioa_ subroutine in the MPM Subroutines. ioa_args (Input) are any arguments required for conversion by the ctl_string argument. Notes: There is an obsolete calling sequence to this subroutine, in which the flags argument is a character string instead of a bit string. In that calling sequence, the legal values are "s" for ACTION_CAN_RESTART, "h" for ACTION_CANT_RESTART, "q" for ACTION_QUIET_RESTART, and "c" for ACTION_DEFAULT_RESTART. Notes on Operation: The structure described below is filled in from the arguments to the sub_err_ subroutine and the signal_ subroutine is called to raise the sub_error_ condition. When the standard system environment receives a sub_error_ signal, it prints a message of the form: name error by sub_name|location Status code message. Message from ctl_string. The standard environment then sets retval to zero and returns, if the value ACTION_DEFAULT_RESTART is specified; otherwise it calls the listener. If the start command is invoked, the standard environment returns to sub_err_, which returns to the subroutine caller of the sub_err_ subroutine unless ACTION_CANT_RESTART is specified. If the value ACTION_CANT_RESTART is specified, the sub_err_ subroutine signals the illegal_return condition. Notes on Handlers: All handlers for the any_other condition must either pass the sub_error_ condition on to another handler, or else must handle the condition correctly. Correct handling consists of printing the error message and of respecting the cant_restart, default_restart, and quiet_restart flags, unless the environment deliberately countermands these actions (for example, for debugging purposes). If an application program wishes to call a subsystem that reports errors by the sub_err_ subroutine and wishes to replace the standard system action for some classes of sub_err_ subroutine calls, the application should establish a handler for the sub_error_ condition by a PL/I on statement. When the handler is activated as a result of a call to the sub_err_ subroutine by some dynamic descendant, the handler should call the find_condition_info_ subroutine to obtain the sub_error_info_ptr that points to the structure described in "Info Structure" below. Info Structure: The structure pointed to by sub_error_info_ptr is declared as follows in the sub_error_info.incl.pl1 include file: dcl 1 sub_error_info aligned based, 2 header aligned like condition_info_header, 2 retval fixed bin(35), 2 name char(32), 2 info_ptr ptr; Structure elements: header is a standard header required at the beginning of each information structure provided to an on unit. See "Information Header Format" in the MPM Reference Guide for further details. retval is the return value. The standard environment sets this value to zero. name is the name of the module encountering the condition. info_ptr is a pointer to additional information associated with the condition. The handler should check sub_err_info.name and sub_err_info.code to make sure that this particular call to the sub_err_ subroutine is the one desired and, if not, call the continue_to_signal_ subroutine. If the handler determines that it wishes to intercept this case of the sub_error_ condition, the information structure provides the message as converted, switches, etc. If control returns to the sub_err_ subroutine, any change made to the value of info.retval is returned to the caller of this subroutine. ----------------------------------------------------------- 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