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 bin35; but it can be any computational data type. If not fixed
29 bin35 it will be converted to fixed bin35.
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 bin35.
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 bin35,
138 2 name char32,
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) change2020-05-19GDixon, approve2021-02-22MCR10088,
175 audit2021-05-27Swenson, install2021-05-27MR12.6g-0056:
176 Fix info seg format errors found by verify_info.
177 END HISTORY COMMENTS */
178
179
180