1 :Info: cv_condition_:  2021-12-26  cv_condition_
  2 
  3 Function: a convenience utility for PL/I on-units, this subroutine
  4 obtains and optionally displays information about conditions that may
  5 occur when converting the ASCII representation of a number to an
  6 arithmetic data type.
  7 
  8 
  9 :Entry: display:  2021-12-26  cv_condition_$display
 10 
 11 Function: a convenience utility for PL/I on-units, this subroutine
 12 obtains and displays information about the most recently-signaled
 13 condition.  Information is displayed on the user_output switch.
 14 
 15 The subroutine calls find_condition_info_ to obtain information about
 16 the most recent signal.  If a condition from the following list was
 17 signaled, then detailed information will be displayed.
 18    conversion       overflow     underflow
 19    fixedoverflow    size
 20 
 21 For other condition names, the condition_interpreter_ subroutine is
 22 called to obtain a detailed message to display.
 23 
 24 
 25 Syntax:
 26    declare cv_condition_$display entry (char(*), char(32) var);
 27    call cv_condition_$display (caller_name, condition_name);
 28 
 29 
 30 Arguments:
 31 caller_name
 32    string that identifies the caller.  If not an empty string, the
 33    string followed by a colon begins the displayed message. (Input)
 34 condition_name
 35    names a specific condition whose signaling information is to be
 36    displayed.  Nothing is displayed for other conditions.  Input an
 37    string to display information for any condition name.  Upon return,
 38    it is set to the name of the condition that was found.  If an empty
 39    string is returned, no message was found/displayed. (Input/Output)
 40 
 41 
 42 Notes on displayed message:
 43 This subroutine is designed to display detailed information about
 44 signals occurring when converting a numeric string to an arithmetic
 45 data type.  For other conditions, it calls condition_interpreter_ to
 46 obtain a detailed description of the condition.
 47 
 48 The following restartable conditions normally return to the point of
 49 error with no message displayed.  This subroutine also displays
 50 nothing for these errors.
 51 
 52    command_error       finish
 53    command_question    stringsize
 54 
 55 
 56 Examples:
 57 For conversion-related signals, the message includes an oncode number
 58 and description, the onsource string being converted, and the onchar
 59 digit or symbol being processed when then condition occurred.  For
 60 example, when caller_name is "plus", the command might display the
 61 following message when trying to convert the string:  123.4*9
 62 
 63 plus:  conversion condition:  oncode: 403  Invalid character follows a numeric field.
 64   onsource: "123.4*9"  onchar: "*"  onchar_index:  6
 65                   ^
 66 Notice the caret (^) pointing to the onchar character which was
 67 identified as significant in triggering the conversion error.  It
 68 points to pl1_info.onchar_index, the onsource character index for
 69 the onchar built-in function value.
 70 
 71 
 72 An overflow error occurs when trying to convert the
 73 string:  123E+200
 74 
 75 plus:  overflow  condition:  oncode: 705  exponent overflow condition
 76 
 77 Such conditions stem from arithmetic expressions that are usually
 78 trapped by the hardware.  Neither onsource nor onchar values are
 79 available.
 80 
 81 
 82 :Entry: message:  2021-12-26  cv_condition_$message
 83 
 84 Function: a convenience utility for PL/I on-units, this subroutine
 85 obtains information about the most recently-signaled condition.
 86 
 87 The subroutine calls find_condition_info_ to obtain information about
 88 the most recent signal.  If the condition was signaled while
 89 converting an ASCII representation of a numeric string to an
 90 arithmetic data type, details from the pl1_info structure attached to
 91 that signal are formatted as a message.
 92 
 93 For other conditions, the condition_interpreter_ subroutine is called
 94 to obtain a message.
 95 
 96 
 97 Syntax:
 98 declare cv_condition_$message entry options(variable);
 99 call cv_condition_$message (message, condition_name,
100    oncode, oncode_message, onsource, onchar_index, onchar,
101    condition_info_ptr);
102 
103 
104 Arguments:
105    All arguments are positional.  All arguments except message are
106    optional.  Include only arguments for the information needed.
107    Use empty string or 0 placeholder values for intervening arguments
108    whose values are not needed.
109 message
110    a char(600) varying variable returning a multi-line string
111    describing the most recently-signaled condition.  Message text
112    includes the oncode, oncode_message, onsource, onchar_index, and
113    onchar values if such information is provided for the signaled
114    condition.  (Output)
115 condition_name
116    a char(32) varying variable naming the most recently-signaled
117    condition. (Output)
118 
119 
120 oncode
121    a fixed bin(35) numeric code identifying the type of error that
122    caused the condition to be signaled.  For error types not diagnosed
123    by PL/I runtime code or support procedures, this value is 0.
124    This is the same value returned by the PL/I oncode built-in
125    function. (Output)
126 oncode_message
127    a char(150) varying variable returning a descriptive string
128    associated with the oncode value.  For error types not diagnosed by
129    PL/I runtime code or support procedures, this is set to an empty
130    string. (Output)
131 
132 
133 onsource
134    a char(256) varying variable.  For a conversion condition, this
135    contains the character string being converted to an arithmetic data
136    type when the conversion condition occurred.  For other conditions,
137    an empty string is returned.  This is the same string returned by
138    the PL/I onsource built-in function. (Output)
139 
140 
141 onchar_index
142    a fixed bin(17) variable.  For a conversion condition, it is the
143    index within onsource of the character being processed when the
144    conversion condition was diagnosed.  For an oncode affecting the
145    entire string being converted, it is the index of the final
146    character in the string.  For other condition names, it is 0.
147    (Output)
148 onchar
149    a char(1) varying variable.  For a conversion condition, this is
150    the character within the onsource being processed when the
151    conversion condition was diagnosed.  For other condition names, it
152    is an empty string.  This is the same character returned by the
153    PL/I onchar built-in function. (Output)
154 
155 
156 condition_info_ptr
157    a pointer variable pointing to the condition_info structure
158    returned by the find_condition_info_ subroutine for the most
159    recently-signaled condition.  This structure is declared in
160    condition_info.incl.pl1. (Output)
161 
162 
163 Notes on message:
164 
165 This subroutine returns detailed information about signals occurring
166 when converting a numeric string to an arithmetic data type.  For
167 other conditions, it returns information provided by
168 condition_interpreter_ for the condition.
169 
170 The following restartable conditions normally return to the point of
171 error without displaying a message.  An empty string is returned for
172 these conditions:
173 
174      command_error
175      command_question
176      finish
177      stringsize
178 
179 
180 Examples:
181 For conversion-related signals, the message includes an oncode number
182 and description, the onsource string being converted, and the onchar
183 digit or symbol being processed when then condition occurred.  For
184 example, for a conversion condition while trying to convert the
185 string:  123.4*9
186 
187 conversion condition:  oncode: 403  Invalid character follows a numeric field.
188   onsource: "123.4*9"  onchar: "*"  onchar_index:  6
189                   ^
190 Notice the caret (^) pointing to the onchar character which was
191 identified as significant in triggering the conversion error.  It
192 points to pl1_info.onchar_index, the onsource character index for
193 the onchar built-in function value.
194 
195 
196 An overflow error occurs when trying to convert the
197 string:  123E+200
198 
199 overflow  condition:  oncode: 705  exponent overflow condition
200 
201 Such conditions stem from arithmetic expressions that are usually
202 trapped by the hardware.  Neither onsource nor onchar values are
203 available.
204 
205 
206 :hcom:
207 /****^  HISTORY COMMENTS:
208   1) change(2021-12-26,GDixon), approve(2022-07-13,MCR10101),
209      audit(2022-07-27,Swenson):
210      Initial description of the cv_condition_ subroutine.
211                                                    END HISTORY COMMENTS */
212