1 :Info: sub_err_:  1986-09-22  sub_err_
  2 
  3 Function: sub_err_ is called by other programs that wish to report
  4 an unexpected situation without usurping the calling environment's
  5 responsibility for the content of and disposition of the error message
  6 and the choice of what to do next.  The caller specifies an identifying
  7 message and may specify a status code.  Switches that describe whether
  8 and how to continue execution and a pointer to further information may
  9 also be passed to this subroutine.  The environment that invoked the
 10 subroutine caller of sub_err_ may intercept and modify the standard
 11 system action taken when this subroutine is called.
 12 
 13 General purpose subsystems or subroutines, which can be called in a
 14 variety of I/O and error handling environments, should report the
 15 errors they detect by calling the sub_err_ subroutine.
 16 
 17 
 18 Syntax:
 19 declare sub_err_ entry options (variable);
 20 call sub_err_ (code, name, flags, info_ptr, retval, ctl_string,
 21      ioa_args);
 22 
 23 
 24 Arguments:
 25 code
 26    is a standard status code describing the reason for calling the
 27    sub_err_ subroutine.  (Input) (It is normally declared fixed
 28    bin(35); but it can be any computational data type.  If not fixed
 29    bin(35), it will be converted to fixed bin(35)).
 30 name
 31    is the name (declared as a nonvarying character string) of the
 32    subsystem or module on whose behalf the sub_err_ subroutine is
 33    called.  (Input)
 34 
 35 
 36 flags
 37    describe options associated with the error.  (Input) The flags
 38    argument should be declared as a nonvarying bit string.  The
 39    following values, located in the include file
 40    sub_err_flags.incl.pl1, are permitted:
 41 
 42         ACTION_CAN_RESTART      init (""b),
 43         ACTION_CANT_RESTART     init ("1"b),
 44         ACTION_DEFAULT_RESTART  init ("01"b),
 45         ACTION_QUIET_RESTART    init ("001"b)
 46         ACTION_SUPPORT_SIGNAL   init ("0001"b)) bit (36) aligned
 47                                 internal static options (constant);
 48 
 49 
 50    Each bit corresponds to one of the action flags in the standard
 51    condition_info_header structure, declared in
 52    condition_info_header.incl.pl1.  If multiple bits are on in the
 53    supplied string, all the specified flags are set.  See the MPM
 54    Reference Guide for definitions of the flags.
 55 
 56 
 57 info_ptr
 58    the info_ptr argument is an aligned pointer to optional information
 59    specific to the situation. (Input)  This argument is used as input
 60    to initialize sub_error_info.info_ptr (see "Notes on the info_ptr"
 61    below).  The standard system environment does not use this pointer,
 62    but it is provided for the convenience of other environments.
 63 retval
 64    is a return value from the environment to which the error was
 65    reported. (Input/Output)  This argument is used as input to
 66    initialize sub_error_info.retval (see "Notes on the info_ptr"
 67    below).  The standard system environment sets this value to zero.
 68    Other environments may set the retval argument to other values,
 69    which may be used to select recovery strategies.  The retval
 70    argument should be declared fixed bin(35).
 71 
 72 
 73 ctl_string
 74    is an ioa_ format control string (declared as a nonvarying character
 75    string) that defines the message associated with the call to the
 76    sub_err_ subroutine.  (Input)  Consult the description of the ioa_
 77    subroutine in the MPM Subroutines.
 78 ioa_args
 79    (Input) are any arguments required for conversion by the ctl_string
 80    argument.
 81 
 82 
 83 Notes on prior interface:  There is an obsolete calling sequence to
 84 this subroutine, in which the flags argument is a character string
 85 instead of a bit string.  In that calling sequence, the legal values
 86 are "s" for ACTION_CAN_RESTART, "h" for ACTION_CANT_RESTART, "q" for
 87 ACTION_QUIET_RESTART, and "c" for ACTION_DEFAULT_RESTART.
 88 
 89 
 90 Notes on operation:
 91 The structure described below is filled in from the arguments to the
 92 sub_err_ subroutine and the signal_ subroutine is called to raise the
 93 sub_error_ condition.  When the standard system environment receives a
 94 sub_error_ signal, it prints a message of the form:
 95 
 96    name error by sub_name|location Status code message.  Message from
 97       ctl_string.
 98 
 99 The standard environment then sets retval to zero and returns, if the
100 value ACTION_DEFAULT_RESTART is specified; otherwise it calls the
101 listener.
102 
103 
104 If the start command is invoked, the standard environment returns to
105 sub_err_, which returns to the subroutine caller of the sub_err_
106 subroutine unless ACTION_CANT_RESTART is specified.  If the value
107 ACTION_CANT_RESTART is specified, the sub_err_ subroutine signals the
108 illegal_return condition.
109 
110 
111 Notes on handlers:
112 All handlers for the any_other condition must either pass the
113 sub_error_ condition on to another handler, or else must handle the
114 condition correctly.  Correct handling consists of printing the error
115 message and of respecting the cant_restart, default_restart, and
116 quiet_restart flags, unless the environment deliberately countermands
117 these actions (for example, for debugging purposes).
118 
119 
120 If an application program wishes to call a subsystem that reports
121 errors by the sub_err_ subroutine and wishes to replace the standard
122 system action for some classes of sub_err_ subroutine calls, the
123 application should establish a handler for the sub_error_ condition by
124 a PL/I on statement.  When the handler is activated as a result of a
125 call to the sub_err_ subroutine by some dynamic descendant, the handler
126 should call the find_condition_info_ subroutine to obtain the
127 sub_error_info_ptr that points to the structure described in "Info
128 Structure" below.
129 
130 
131 Notes on the info_ptr:
132 The structure pointed to by sub_error_ info_ptr is declared as follows
133 in the sub_error_info.incl.pl1 include file:
134 
135      dcl 1 sub_error_info        aligned based,
136          2 header                aligned like condition_info_header,
137          2 retval                fixed bin(35),
138          2 name                  char(32),
139          2 info_ptr              ptr;
140 
141 
142 List of elements:
143 header
144    is a standard header required at the beginning of each
145    information structure provided to an on unit.  See "Information
146    Header Format" in the "MPM Reference Guide" Section 7 for further
147    details.
148 retval
149    is the return value.  The standard environment sets this value to
150    zero.  Another environment handling the sub_error_ condition can
151    return a different error status.  If control returns to the
152    sub_err_ subroutine, the sub_error_info.retval element is returned
153    to the caller as sub_err_'s retval argument.
154 name
155    is the name of the module encountering the condition.
156 
157 
158 info_ptr
159    sub_error_info.info_ptr points to additional information associated
160    with the condition.  The handler should check sub_error_info.name
161    and sub_error_info.code to make sure that this particular call to
162    the sub_err_ subroutine is the one desired and, if not, call the
163    continue_to_signal_ subroutine.  If the handler determines that
164    it wishes to intercept this instance of the sub_error_ condition,
165    the data pointed to can provide details specific to errors reported
166    by the sub_error_info.name module.
167 
168 
169 :hcom:
170 
171 
172 
173 /****^  HISTORY COMMENTS:
174   1) change(2020-05-19,GDixon), approve(2021-02-22,MCR10088),
175      audit(2021-05-27,Swenson), install(2021-05-27,MR12.6g-0056):
176      Fix info seg format errors found by verify_info.
177                                                    END HISTORY COMMENTS */
178 
179 
180