1 :Info: cv_fixed_point_string_: 2022-05-06 cv_fixed_point_string_
2
3 Function: accepts an ASCII representation of a fixed-point number with
4 optional exponent and radix indicator sub-fields. It returns the
5 float decimal59 representation of that number.
6
7
8 Syntax:
9 declare cv_fixed_point_string_ entry char* fixed bin bit*
10 fixed bin35 returnsfloat dec59;
11 result = cv_fixed_point_string_ fixed_point_string default_base
12 switches code;
13
14
15 Arguments:
16 result
17 a float decimal59 result produced by successfully converting
18 the fixed_point_string to a number. Output
19 fixed_point_string
20 an ASCII representation of a fixed-point number ending with
21 optional exponent and radix indicator sub-fields. See the "Notes
22 on input strings" and "List of radix indicators" sections. If
23 expressed as a decimal number, the string may include up to 59
24 significant digits. If expressed in another numeric base or radix,
25 more digits may be given if base < 10; and fewer if base > 10.
26 Input
27
28
29 default_base
30 is the base in which the fixed_point_string is expressed if no
31 radix indicator ends that string. It must be a number between 2
32 and 16 inclusive. Input
33 switches
34 control the action of this subroutine. See the "Notes on switches"
35 section. Input
36
37
38 code
39 standard status code indicating success of the convert operation.
40 Failure values may be one of the following.
41 error_table_$bad_arg
42 default_base was not in the range: 2 <= default_base <= 16
43 error_table_$bad_conversion
44 an unexpected sign, digit, radix point or exponent was found in
45 fixed_point_string; or more digits were given than will fit in
46 the precision provided by a float dec59 data type.
47 error_table_$bigarg
48 fixed_point_string exceeds implementation restriction of 256
49 characters in length.
50
51
52 error_table_$item_too_big
53 an exponent overflow condition occurred when converting
54 fixed_point_string to a float dec59 value.
55 error_table_$smallarg
56 an exponent underflow condition occurred when converting
57 fixed_point_string to a float dec59 value.
58
59
60 Notes on switches:
61 The switches argument is assigned to a structure whose elements
62 ascribe meaning to the individual bits in switches.
63
64 stringfixed_point_switches = switches;
65
66 dcl 1 fixed_point_switches based,
67 2 signal_errors bit 1 unaligned,
68 2 allow_exponent bit 1 unaligned,
69 2 convert_binary bit 1 unaligned,
70 2 convert_decimal bit 1 unaligned;
71
72 This structure is declared in cv_fixed_point_string_.incl.pl1.
73
74
75 The structure elements are described in the "List of elements" section.
76 See the "List of named constants" section for named constants setting
77 bit values or combinations.
78
79
80 List of elements:
81 signal_errors
82 "1"b: errors encountered during convert operation are signaled as
83 PL/I conditions. See the "Notes on condition handling"
84 section.
85 "0"b: errors are returned as status code values.
86
87 allow_exponent
88 "1"b: fixed_point_string may include an exponent sub-field.
89 See the "Notes on input strings" section.
90 "0"b: an exponent sub-field causes a conversion condition or status
91 code.
92
93
94 convert_binary
95 "1"b: use PL/I convert built-in to convert a fixed_point_string
96 expressed as binary base 2 digits. See the "Notes on
97 convert built-in" section.
98 "0"b: use cv_fixed_point_string_ algorithms for a binary string.
99
100 convert_decimal
101 "1"b: use PL/I convert built-in to convert a fixed_point_string
102 expressed as decimal base 10 digits. See the "Notes on
103 convert built-in" section.
104 "0"b: use cv_fixed_point_string_ algorithms for a decimal string.
105
106
107 List of named constants:
108 The following constants may be OR'd together or used individually
109 as a value for the switches argument.
110 FIXED_POINT_SIGNALS
111 convert operation errors are signaled as PL/I conditions.
112 FIXED_POINT_EXPONENT
113 fixed_point_string may include an exponent sub-field.
114 FIXED_POINT_CONVERT_BIN
115 binary strings are processed using the PL/I convert built-in.
116 FIXED_POINT_CONVERT_DEC
117 decimal strings are processed using the PL/I convert built-in.
118
119
120 FIXED_POINT_EXPONENT_CONVERT_DEC
121 turns on allow_exponents and convert_decimal.
122 FIXED_POINT_EXPONENT_CONVERT
123 turns on allow_exponents, convert_binary and convert_decimal.
124
125 FIXED_POINT_SIG_EXP
126 turns on signal_errors and allow_exponents.
127 FIXED_POINT_SIG_EXP_CONVERT_DEC
128 turns on signal_errors, allow_exponents and convert_decimal.
129 FIXED_POINT_SIG_EXP_CONVERT
130 turns on all four of the bits above.
131
132
133 List of radix indicators:
134 A radix indicator sub-field may appear at the end of a
135 fixed_point_string to indicate the base in which its digits are
136 expressed. Indicator characters may also be given in uppercase.
137 b, _b
138 digits are interpreted as a base two number binary.
139 q, _q
140 digits are interpreted as a base four number quaternary.
141 o, _o
142 digits are interpreted as a base eight number octal.
143 d, _d
144 digits are interpreted as a base ten number decimal.
145 x, _x
146 digits are interpreted as a base sixteen number hexadecimal.
147
148
149 rN, _rN
150 digits are interpreted in the base N which is a decimal number
151 where: 2 <= N <= 16
152
153
154 Notes on input strings:
155 A fixed-point string is an ASCII representation of a float dec59
156 numeric data type. The string consists of three sub-fields:
157
158 +123456700.0034E+02o
159 \_ mantissa__ /\_/ |
160 | |
161 exponent -' '- radix indicator
162
163
164 The fixed_point_string may begin with an optional number of space SP
165 characters. The fixed-point string continues with a mantissa.
166
167
168 By default, the fixed_point_string is assumed to be positive. A
169 leading plus + is allowed. A negative value is specified using a
170 leading minus - character:
171 -23
172
173
174 The fixed_point_string continues with a sequence of digits, and may
175 include one radix point . character separating integer digits
176 preceding the point from fractional digits following the point. This
177 optionally signed sequence of digits with optional radix point is
178 sometimes called the "mantissa" or "significand":
179 -23.004
180
181
182 Digits for numbering system bases 11 through 16 may be entered using
183 letters for digit values beyond 9, with letters accepted in either
184 uppercase or lowercase. Digits for the most common numeric bases are
185 shown in the table below, ordered in ascending value. Digits for a
186 base N lower than 16 use the first N valid digits listed for base 16.
187
188 BASE VALID DIGITS IN THAT BASE
189 ---- -------------------------------
190 2 0 1
191 8 0 1 2 3 4 5 6 7
192 10 0 1 2 3 4 5 6 7 8 9
193 12 0 1 2 3 5 5 6 7 8 9 A B
194 16 0 1 2 3 4 5 6 7 8 9 A B C D E F
195
196
197 If fixed_point_switches.allow_exponent is "1"b, the fixed_point_string
198 begins with a mantissa which may be followed by an exponent sub-field.
199 The exponent begins with one of the exponent indicator letters: E F P
200 in either uppercase or lowercase. The exponent digits are an
201 optionally-signed decimal number EXP. Each fixed point string is
202 expressed in one of the following formats:
203
204 MANTISSA
205 MANTISSAeEXP or MANTISSAe+EXP or MANTISSAe-EXP
206 MANTISSAfEXP or MANTISSAf+EXP or MANTISSAf-EXP
207 MANTISSApEXP or MANTISSAp+EXP or MANTISSAp-EXP
208
209 While MANTISSA gives the integer or integer.fraction representation
210 expressed in digits of the selected numbering system, the EXP exponent
211 is always expressed using decimal digits.
212
213
214 An exponent for a base 15 string must begin with one of the exponent
215 indicator letters: F P in either uppercase or lowercase because 'E'
216 is treated as a mantissa digit in a base 15 number.
217
218 An exponent for a base 16 string must begin with exponent indicator
219 letter: P in either uppercase or lowercase because 'E' and 'F" are
220 treated as a mantissa digit in a base 16 number. However, note that
221 the PL/I convert built-in interprets only binary and decimal numeric
222 strings and therefore has not been modified to accept P as an
223 exponent indicator letter.
224
225
226 No whitespace may appear between sign and digits of the exponent, or
227 between mantissa and the exponent.
228
229 A positive exponent shifts the radix point right EXP places; a
230 negative exponent shifts the radix point left EXP places. The
231 following table shows decimal numbers with an exponent. Numbers
232 expressed in another base would use that base to the power EXP as the
233 multiplier.
234
235 STRING mantissa * BASE**EXP RESULT
236 --------- -------------------- -----------
237 123E-4 123 * 10**-4 0.0123
238 1.23E+1 1.23 * 10**+1 12.3
239 1.23E5_d 1.23 * 10**+5 123000
240 .123E+2d .123 * 10**+2 12.3
241
242
243 A radix indicator sub-field may end the fixed_point_string to specify
244 its numeric base. The default_base specifies the base to assume if no
245 radix indicator is given.
246
247 The indicator sub-field can begin with underscore _ which separates
248 the radix indicator letter that follows from digits of a base 12 or
249 higher mantissa; the underscore prevents a "b" or "d" radix indicator
250 from being treated as a digit of the mantissa.
251
252
253 The following table shows strings expressed in a variety of numbering
254 bases, along with the decimal value of the float dec59 number
255 represented by that string.
256
257 INDICATOR NUMERIC BASE EXAMPLES VALUE base 10
258 --------- ----------------------- ----------- ---------------
259 b or _b base 2 or binary 10001.11b 17.75
260 q or _q base 4 or quaternary 113_q 23
261 o or _o base 8 or octal 21.6o 17.75
262 d or _d base 10 or decimal 17.75d 17.75
263 x or _x base 16 or hexadecimal 11.Cx 17.75
264 rN or _rN N is a decimal base
265 number: 2 <= N <= 16 43r5 23
266 15.9_r12 17.75
267
268
269 The fixed_point_string may end with one or more space SP characters.
270 These characters are ignored by the conversion.
271
272
273 The greatest magnitude for a data value stored as float decimal59
274 real is 10**186. The smallest magnitude of such data value is
275 10**-128.
276
277
278 The range of values supported in the fixed_point_string argument
279 varies according to the numeric base in which the mantissa digits are
280 expressed. The following table summarizes the range of fixed-point
281 string magnitudes accepted for each numbering base.
282
283 BASE MIN MAGNITUDE MAXIMUM MAGNITUDE
284 ---- ------------- -----------------
285 2 0.1E-228b 1.1E+617b
286 3 0.1E-143_r3 2.1E+389_r3
287 4 0.1E-113q 3.2E+308q
288
289 5 0.1E-97_r5 1.0E+266_r5
290 6 0.1E-87_r6 1.0E+239_r6
291 7 0.1E-80_r7 1.1E+220_r7
292 8 0.1E-75o 7.2E+205o
293
294
295 9 0.1E-71_r9 7.4E+194_r9
296 10 0.1E-127 9.9...9E+185 59 significant digits
297
298 11 0.aE-66_r11 4.3E+178_r11
299 12 0.aE-63_r12 2.4E+172_r12
300 13 0.aE-61_r13 c.2E+166_r13
301
302 14 0.aE-60_r14 2.1E+162_r14
303 15 0.aP-58_r15 1.7P+158_r15
304 16 0.aP-57x 3.aP+154x
305
306
307 Accuracy of the conversion algorithm depends upon the selected base.
308 A float dec59 arithmetic may have insufficient precision to
309 represent digits of a non-decimal input string as digits in the float
310 dec59 target value. The maximum value expressible in a decimal
311 fixed_point_string argument is therefore larger than magnitudes
312 expressed as an octal, binary, or other radix representation of a
313 number.
314
315
316 Notes on condition handling:
317 If fixed_point_switches.signal_errors = "1"b, the following PL/1
318 conditions are signaled if an error is encountered during the
319 conversion.
320
321
322 CONDITION EVENT TRIGGERING THE CONDITION
323 ------------ ----------------------------------------------------
324 conversion - whitespace characters other than space " ".
325 - space characters anywhere in the string other than
326 the very beginning or end of string.
327 - more than one sign character + or -
328 in the mantissa or exponent.
329 - an invalid character in the mantissa.
330 - more significant digits in the mantissa than
331 will fit in a float dec59 data type.
332 - using an exponent sub-field when not allowed.
333 - a non-decimal number in an exponent sub-field.
334 - an invalid radix indicator string.
335
336
337 CONDITION EVENT TRIGGERING THE CONDITION
338 ------------ ----------------------------------------------------
339 overflow - a string has significant digits in the mantissa
340 plus an exponent sub-field causing the result
341 exponent to be > +127.
342
343 underflow - a string has significant digits in the mantissa
344 plus an exponent sub-field causing the
345 result exponent to be < -128.
346
347
348 Significant digits in the mantissa are those that follow any leading
349 zero 0 digits. Leading zeroes are ignored. The table below shows
350 how many significant digits can be converted to a float dec59 data
351 type for each numeric base. A mantissa with more significant digits
352 than this number will trigger a conversion condition.
353
354 BASE 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
355 --- --- -- -- -- -- -- -- -- -- -- -- -- -- --
356 MAX_DIGITS_ALLOWED 199 125 99 85 77 70 66 62 59 57 55 53 52 51 49
357
358
359 Just before the underflow or overflow condition is signaled, the
360 current value of the oncode built-in function is pushed down and a
361 fixed bin350 code giving the reason for the signaling the condition
362 is assigned to "oncode". The underflow and overflow conditions may
363 not be restarted.
364
365
366 Just before the conversion condition is signaled, the current values
367 of the oncode, onsource and onchar built-in functions are pushed down.
368 A fixed bin350 code giving the reason for the signaling conversion
369 is assigned to "oncode". The string being converted is assigned to
370 "onsource". The leftmost character for which the conversion failed is
371 assigned to "onchar".
372
373
374 The caller's on-unit for any of these conditions may also call the
375 cv_condition_$message subroutine to get additional information about
376 that condition; or call cv_condition_$display to display such
377 information to the user. For details, type: help cv_condition_
378
379
380 The conversion on-unit may perform a non-local goto to a label in the
381 calling program to abort the failed convert operation. Or the convert
382 operation may be restarted by having the on-unit use the onchar
383 pseudo-variable to change the value of the leftmost failing character;
384 or use the onsource pseudo-variable to change the entire contents of
385 the string being converted. If the on-unit then ends without calling
386 the continue_to_signal_ subroutine, the convert operation is retried
387 using any replaced string values.
388
389
390 Notes on convert built-in:
391 If fixed_point_switches.convert_binary and/or .convert_decimal
392 switches are "1"b, cv_fixed_point_string_ uses the PL/I convert
393 built-in function to convert a binary and/or decimal string to a
394 float dec59 data type.
395
396 The PL/I convert built-in function provides program access to PL/I
397 runtime operators that convert character strings to arithmetic data
398 types. These convert operators accept numeric strings expressed in
399 binary or decimal digits. Binary strings must end with a "b" radix
400 indicator. "b" is the only radix indicator accepted by the PL/I
401 convert operators. cv_fixed_point_string_ will add a "b" radix
402 indicator to an input string with base selected by default_base = 2,
403 or selected by another radix indicator form: _b or _r2 or r2
404
405
406 The PL/I convert built-in is more efficient than the
407 cv_fixed_point_string_ subroutine, and accepts binary and decimal
408 strings in a wider variety of styles than cv_fixed_point_string_.
409 This includes support for complex number strings including both real
410 and imaginary parts e.g. 123.4+32.0i. The convert built-in may
411 employ conversion techniques that generate fewer exponent overflow or
412 underflow conditions than the cv_fixed_point_string_ algorithms.
413
414
415 Support for a wider variety of input styles comes with programming
416 costs. The program must be prepared to: explain accepted input styles
417 in its documentation; and handle additional conversion errors that can
418 occur when converting these added input styles. Also note that the
419 convert built-in does not accept P as an exponent indicator letter,
420 but cv_fixed_point_string_ changes any use of P indicator to E before
421 invoking the convert built-in. These issues are avoided if the PL/I
422 convert built-in bits in switches are off.
423
424
425 :Info: fixed_point_string.gi: fixed_point_string: fixed_point.gi: fixed_point:
426 2022-05-19 fixed-point string
427
428 A fixed-point string is an ASCII representation of a float dec59
429 numeric data type. The string consists of three sub-fields:
430
431 +123456700.0034E+02o
432 \_ mantissa__ /\_/ |
433 | |
434 exponent -' '- radix indicator
435
436
437 The fixed-point string may begin with an optional number of space SP
438 characters. The fixed-point string continues with a mantissa.
439
440
441 By default, the fixed point string is assumed to be positive. A
442 leading plus + is allowed. A negative value is specified using a
443 leading minus - character:
444 -23
445
446
447 The fixed-point string continues with a sequence of digits, and may
448 include one radix point . character separating integer digits
449 preceding the point from fractional digits following the point. This
450 optionally signed sequence of digits with optional radix point is
451 the "mantissa" or "significand":
452 -23.004
453
454
455 Digits for numbering system bases 11 through 16 may be entered using
456 letters for digit values beyond 9, with letters accepted in either
457 uppercase or lowercase. Digits for the most common numeric bases are
458 shown in the table below, ordered in ascending digit value. Digits
459 for a base N lower than 16 use the first N valid digits listed for
460 base 16.
461
462 BASE VALID DIGITS IN THAT BASE
463 ---- -------------------------------
464 2 0 1
465 8 0 1 2 3 4 5 6 7
466 10 0 1 2 3 4 5 6 7 8 9
467 12 0 1 2 3 5 5 6 7 8 9 A B
468 16 0 1 2 3 4 5 6 7 8 9 A B C D E F
469
470
471 The mantissa may be followed by an exponent sub-field. The exponent
472 begins with one of the exponent indicator letters: E F P in either
473 uppercase or lowercase. The exponent digits are an optionally-signed
474 decimal number EXP. Each fixed point string is expressed in one of
475 the following formats:
476
477 MANTISSA
478 MANTISSAeEXP or MANTISSAe+EXP or MANTISSAe-EXP
479 MANTISSAfEXP or MANTISSAf+EXP or MANTISSAf-EXP
480 MANTISSApEXP or MANTISSAp+EXP or MANTISSAp-EXP
481
482 While MANTISSA gives the integer or integer.fraction representation
483 expressed in digits of the selected numbering system, the EXP exponent
484 is always expressed using decimal digits.
485
486
487 An exponent for a base 15 string must begin with one of the exponent
488 indicator letters: F P in either uppercase or lowercase because 'E'
489 is treated as a mantissa digit in a base 15 number.
490
491 An exponent for a base 16 string must begin with exponent indicator
492 letter: P in either uppercase or lowercase because 'E' and 'F" are
493 treated as a mantissa digit in a base 16 number. However, note that
494 the PL/I convert built-in interprets only binary and decimal numeric
495 strings and therefore has not been modified to accept P as an
496 exponent indicator letter. The cv_fixed_point_string_ subroutine
497 accepts exponent letters: E F P
498
499 No whitespace may appear between sign and digits of the exponent, or
500 between mantissa and the exponent sub-fields.
501
502
503 A positive EXP value shifts the radix point right EXP places; a
504 negative EXP shifts the radix point left EXP places. The
505 following table shows decimal numbers with an exponent. Numbers
506 expressed in another base would use that base to the power EXP as the
507 multiplier.
508
509 STRING mantissa * BASE**EXP RESULT
510 --------- -------------------- -----------
511 123E-4 123 * 10**-4 0.0123
512 1.23E+1 1.23 * 10**+1 12.3
513 1.23E5_d 1.23 * 10**+5 123000
514 .123E+2d .123 * 10**+2 12.3
515
516
517 A radix indicator sub-field may end the fixed-point string to specify
518 its numeric base. If no radix indicator appears, the string is
519 assumed to be expressed as decimal digits unless the program accepting
520 the numeric string documents a different default numbering base.
521
522 The indicator sub-field can begin with underscore _ which separates
523 the radix indicator letter that follows from digits of a base 12 or
524 higher mantissa; the underscore prevents a "b" or "d" radix indicator
525 from being treated as a digit of the mantissa.
526
527
528 The following table shows strings expressed in a variety of numbering
529 bases, along with the decimal value of the float dec59 number
530 represented by that string.
531
532 INDICATOR NUMERIC BASE EXAMPLES VALUE base 10
533 --------- ----------------------- ----------- ---------------
534 b or _b base 2 or binary 10001.11b 17.75
535 q or _q base 4 or quaternary 113_q 23
536 o or _o base 8 or octal 21.6o 17.75
537 d or _d base 10 or decimal 17.75d 17.75
538 x or _x base 16 or hexadecimal 11.Cx 17.75
539 rN or _rN N is a decimal base
540 number: 2 <= N <= 16 43r5 23
541 15.9_r12 17.75
542
543
544 The fixed-point string may end with one or more space SP characters.
545 These characters are ignored by the conversion.
546
547
548 List of radix indicators:
549 A radix indicator sub-field may appear at the end of a
550 fixed-point string to indicate the base in which its digits are
551 expressed. Indicator characters may also be given in uppercase.
552 b, _b
553 digits are interpreted as a base two number binary.
554 q, _q
555 digits are interpreted as a base four number quaternary.
556 o, _o
557 digits are interpreted as a base eight number octal.
558 d, _d
559 digits are interpreted as a base ten number decimal.
560 x, _x
561 digits are interpreted as a base sixteen number hexadecimal.
562
563
564 rN, _rN
565 digits are interpreted in the base N which is a decimal number
566 where: 2 <= N <= 16
567
568
569 Notes on the range of values:
570 Numeric strings can represent a wide range of values. The specific
571 range depends on the numbering base in which mantissa digits are
572 expressed.
573
574 Conversion from a numeric string to a float dec59 data value
575 supports the widest range of input strings. The
576 cv_fixed_point_string_ subroutine performs such conversions.
577
578
579 Conversion from a data value to a numeric string supports a narrower
580 range of values. The numeric_to_ascii_ subroutine converts a float
581 dec59 data value to a decimal numeric string. The
582 numeric_to_ascii_base_ subroutine converts a float dec59 data value
583 to a numeric string in which mantissa digits are expressed in one of
584 the numbering bases: 2 <= BASE <= 16; the program which calls this
585 subroutine specifies which numbering system to use.
586
587
588 The greatest magnitude for a data value stored as float decimal59
589 real is 10**186. The smallest magnitude of such data value is
590 10**-128.
591
592
593 The following table summarizes the range of fixed-point string
594 magnitudes accepted for each numbering base.
595
596 MAXIMUM MAGNITUDE
597 BASE MIN MAGNITUDE float dec-to-character char-to-float dec
598 ---- ------------- ---------------------- -----------------
599 2 0.1E-228b 1.1E+198b 1.1E+617b
600 3 0.1E-143_r3 2.0E+124_r3 2.1E+389_r3
601 4 0.1E-113q 2.0E+100q 3.2E+308q
602
603 5 0.1E-97_r5 3.4E+86_r5 1.0E+266_r5
604 6 0.1E-87_r6 4.2E+76_r6 1.0E+239_r6
605 7 0.1E-80_r7 1.5E+70_r7 1.1E+220_r7
606 8 0.1E-75o 2.0E+65o 7.2E+205o
607
608
609 9 0.1E-71_r9 1.7E+62_r9 7.4E+194_r9
610 10 0.1E-127 9.9...9E+185 9.9...9E+185
611 up to 59 significant digits
612
613 11 0.aE-66_r11 4.aE+57_r11 4.3E+178_r11
614 12 0.aE-63_r12 7.0E+55_r12 2.4E+172_r12
615 13 0.aE-61_r13 b.bE+53_r13 c.2E+166_r13
616
617 14 0.aE-60_r14 3.8E+52_r14 2.1E+162_r14
618 15 0.aP-58_r15 1.bP+51_r15 1.7P+158_r15
619 16 0.aP-57x f.fP+49x 3.aP+154x
620
621
622 :hcom:
623 /****^ HISTORY COMMENTS:
624 1) change2021-12-26GDixon, approve2022-07-13MCR10101,
625 audit2022-07-27Swenson:
626 Initial documentation for the cv_fixed_point_string_ subroutine.
627 2) change2022-05-19GDixon, approve2022-07-13MCR10101,
628 audit2022-07-27Swenson:
629 A) Document use of the 'P' and 'p' exponent indicator letters to
630 permit base 15 and 16 numbers to support numbers with exponents.
631 B) Add fixed_point_string.gi.info description of fixed-point strings
632 accepted by cv_fixed_point_string_ subroutine.
633 END HISTORY COMMENTS */