1 :Info: numeric_to_ascii_:  2022-05-07  numeric_to_ascii_
  2 
  3 Function: formats a real decimal floating-point number as a decimal
  4 string.  The string is in integer, fraction, or exponential format
  5 depending on characteristics of the input number.  It begins with an
  6 optional minus sign, followed by 1 to 59 decimal digits, and an
  7 optional exponent field.  A precision argument controls maximum
  8 number of digits in the string.
  9 
 10 To express a value in a numbering system other than base 10, use
 11 the numeric_to_ascii_base_ subroutine.
 12 
 13 
 14 Syntax:
 15 declare numeric_to_ascii_ entry (float dec(59), fixed bin) returns
 16      (char(72) varying);
 17 result = numeric_to_ascii_ (value, precision);
 18 
 19 
 20 Arguments:
 21 value
 22    number to be formatted. (Input)  The PL/I compiler can convert most
 23    numeric values to float dec(59).  Use an extra pair of parentheses
 24    around the value argument to suppress PL/I warning message of this
 25    intended conversion.
 26 precision
 27    maximum number of significant digits placed in the result string.
 28    (Input)  If 0 is given, from 1 to 59 significant digits are placed
 29    in the result string depending on the value being formatted.  If
 30    precision is less than 0, then at most -precision significant
 31    digits are returned with excess digits truncated from the result.
 32    If precision is greater than 0, the excess digits are rounded
 33    upward to form result having at most +precision significant digits.
 34 
 35 
 36 result
 37    character-string representation of value expressed with decimal
 38    digits. (Output)  It contains no spaces.
 39 
 40 
 41 Notes:
 42 To convert integer values, use the PL/I sequence:
 43       result = ltrim (char (value));
 44 If precision equals 0, 59 is used for the precision.  In the following
 45 discussion, P = min( 59, abs(precision) ) where abs returns the
 46 absolute value of the precision argument.
 47 
 48 A number in integer format consists of a string of from 1 to P
 49 significant decimal digits without a decimal point.  Integer format is
 50 used for integers whose absolute value is less than 10**P.
 51 
 52 
 53 A number in fractional format consists of from 1 to P significant
 54 decimal digits with a decimal point.  Trailing zeros in the fractional
 55 part are omitted; digits expressing the integer part appear to the
 56 left of the decimal point; digits expressing the fractional part
 57 appear to the right of the decimal point.
 58 
 59 
 60 A number in exponential format appears as follows.
 61 
 62       MANTISSAe+EXP   or   MANTISSAe-EXP
 63 
 64 MANTISSA gives the significant digits of the value, and EXP is
 65 a power of 10 such that the numeric value being formatted is:
 66 
 67       MANTISSA * 10**EXP
 68 
 69 Exponential format is used whenever integer or fractional format
 70 cannot express the value.
 71 
 72 
 73 Notes on the result:
 74 The result is a numeric string that can represent a wide range of
 75 values.  The numeric_to_ascii_ subroutine converts a float dec(59)
 76 data value directly to a decimal numeric string.  The greatest
 77 magnitude for a data value stored as float decimal(59) real is
 78 10**186.  The smallest magnitude of such data value is 10**-128.
 79 
 80 
 81 :Info: numeric_to_ascii_base_:  2022-03-04  numeric_to_ascii_base_
 82 
 83 Function: formats a real decimal floating-point number as a string
 84 with digits expressed in a numbering system with radix selected from
 85 2 through 16 inclusive.  The result is expressed in integer, fraction,
 86 or exponential format depending on the characteristics of the input
 87 number.
 88 
 89 If base=10 is selected, numeric_to_ascii_base_ calls the
 90 numeric_to_ascii_ subroutine to construct the numeric string using a
 91 more precise algorithm for expressing the decimal mantissa and
 92 exponent of the input value as a string of decimal digits.
 93 
 94 For a non-decimal base, the algorithm repeatedly divides and/or
 95 multiplies the input value by the numeric base to obtain successive
 96 digits expressed in that base.  A radix indicator string is appended
 97 to the result.
 98 
 99 
100 Syntax:
101 declare numeric_to_ascii_base_ entry (float dec(59), fixed bin,
102    fixed bin) returns (char(256) varying);
103 
104 result = numeric_to_ascii_base_ (value, precision, base);
105 
106 
107 Arguments:
108 value
109    number to be formatted. (Input)  See "Notes on value argument"
110    below for more information.
111 precision
112    maximum number of significant digits placed in the result string.
113    (Input)  If a 0 or negative precision is given, all significant
114    digits are represented in the result.  A positive precision
115    limits number of significant digits to that precision.  See
116    "Notes on precision argument" below for more information.
117 base
118    radix of the numbering system in which the result mantissa is
119    expressed. (Input)  For example, base=2 produces a binary
120    representation and base=8 produces an octal string.  The domain
121    supported for base is:    2 <= base <= 16
122 
123 
124 result
125    character-string representation of value using digits of the
126    base numbering system in the mantissa. (Output)  See
127    "Notes on result" below for more information.
128 
129 
130 Notes on result:
131 The result returned by the numeric_to_ascii_base_ function is the
132 ascii representation of input value in the selected numbering system.
133 The result uses one of the following formats:
134 
135    MANTISSA   OR   MANTISSAe+EXP   OR   MANTISSAe-EXP
136 
137 While MANTISSA gives the integer or integer.fraction representation
138 expressed in digits of the selected numbering system, the EXP exponent
139 is always expressed using decimal digits.
140 
141 
142 For results expressed in base 15 or 16, any exponent is preceded by
143 the 'p' exponent indicator letter because 'e' is a valid digit that
144 can appear in the MANTISSA of these numbering bases.
145 
146    MANTISSA   OR   MANTISSAp+EXP   OR   MANTISSAp-EXP
147 
148 
149 Mantissa digits for bases 11 through 16 represent values beyond 9
150 using lowercase letters.  Digits for the most common numeric bases are
151 shown in the table below, ordered in ascending value.  Digits for a
152 base N lower than 16 use the first N valid digits listed for base 16.
153 
154   BASE      VALID DIGITS IN THAT BASE        COMMON NAME
155   ----   -------------------------------    -------------
156     2    0 1                                    binary
157     4    0 1 2 3                              quaternary
158     8    0 1 2 3 4 5 6 7                         octal
159    10    0 1 2 3 4 5 6 7 8 9                    decimal
160    12    0 1 2 3 5 5 6 7 8 9 a b
161    16    0 1 2 3 4 5 6 7 8 9 a b c d e f      hexadecimal
162 
163 
164 The MANTISSA includes all significant radix places selected by the
165 precision argument.  If the MANTISSA includes too few radix places to
166 represent the magnitude of the value, an exponent is added.  The EXP
167 sub-field is a signed decimal integer representing a multiplier for
168 the MANTISSA:
169 
170    MANTISSA * (base ** EXP)
171 
172 That is, a positive exponent (E+n) shifts the point n radix-places
173 to the right, while a negative exponent (E-n) shifts the point n
174 radix-places to the left of any point displayed in the mantissa.
175 For an integer mantissa, the point is not displayed; it is assumed to
176 follow the last radix-place of the displayed integer.
177 
178 
179 A radix indicator sub-field appears at the end of each non-decimal
180 result to indicate the base in which its digits are expressed.  The
181 following sub-field value is appended.
182 
183    BASE   radix indicator sub-field
184    ----   ------------------------------------------
185      2     b    (stands for binary)
186      3     _r3
187      4     q    (stands for quaternary)
188 
189      5     _r5
190      6     _r6
191      7     _r7
192      8     o    (stands for octal)
193 
194 
195      9     _r9
196     10          (no indicator used for decimal base)
197 
198     11     _r11
199     12     _r12
200     13     _r13
201 
202     14     _r14
203     15     _r15
204     16     x    (stands for hexadecimal)
205 
206 
207 All result strings are in one of the formats accepted by the
208 cv_fixed_point_string_ subroutine.  Also, binary and decimal result
209 strings are in a format acceptable to the PL/I convert built-in
210 function and PL/I number character-string-to-number conversion rules.
211 
212 
213 A string expressing a large input value using a small base such as
214 binary may require 200 or more characters to hold all significant
215 digits and exponent.  The PL/I runtime reserves up to 256 characters
216 to hold numeric strings representing the largest values in binary
217 digits.  The numeric_to_ascii_base_ return value follows that maximum
218 string length precedent.
219 
220 
221 The result is a numeric string that can represent a wide range of
222 values.  The specific range depends on the numbering base in which
223 mantissa digits are expressed.
224 
225 The numeric_to_ascii_base_ subroutine converts a float dec(59) data
226 value to a numeric string in which mantissa digits are expressed in
227 one of the numbering bases: 2 <= BASE <= 16; the program which calls
228 this subroutine specifies which numbering system to use.
229 
230 
231 The following table summarizes the range of fixed-point string
232 magnitudes representable for each numbering base.
233 
234    BASE   MIN MAGNITUDE    MAXIMUM MAGNITUDE
235    ----   -------------    -----------------
236      2     0.1E-228b         1.1E+198b
237      3     0.1E-143_r3       2.0E+124_r3
238      4     0.1E-113q         2.0E+100q
239 
240      5     0.1E-98_r5        3.4E+86_r5
241      6     0.1E-87_r6        4.2E+76_r6
242      7     0.1E-80_r7        1.5E+70_r7
243      8     0.1E-75o          2.0E+65o
244 
245 
246      9     0.1E-71_r9        1.7E+62_r9
247     10     0.1E-127          9.9...9E+185  (59 significant digits)
248 
249     11     0.1E-65_r11       4.aE+57_r11
250     12     0.aE-63_r12       7.0E+55_r12
251     13     0.aE-61_r13       b.bE+53_r13
252 
253     14     0.aE-60_r14       3.8E+52_r14
254     15     0.aP-58_r15       1.bP+51_r15
255     16     0.aP-57x          f.fP+49x
256 
257 
258 Notes on value argument:
259 The maximum input value supported by the numeric_to_ascii_base_
260 conversion algorithm depends upon the selected base.  A float dec(59)
261 value may have insufficient precision to calculate digits of an input
262 value in a non-decimal numbering system.  The maximum value which may
263 be converted to a decimal string is therefore larger than input limits
264 for an octal, binary, or other radix representation of a number.
265 
266 The following table shows the approximate maximum value supported for
267 each base.  An attempt to use a larger input value may signal the
268 sub_error_ condition with an appropriate message.  The caller can
269 establish an on-unit for that condition if extremely large input
270 numbers are expected.
271 
272 
273    BASE   MAXIMUM value
274    ----   -------------------------------------------------------------
275      2     1.0e+84
276      3     3.0e+59
277      4     2.0e+84
278 
279      5     9.99999999999999999999999999999999999999999999999999999e+185
280      6     6.0e+59
281      7     3.2e+59
282      8     2.0e+85
283 
284 
285      9     5.0e+59
286     10     9.99999999999999999999999999999999999999999999999999999e+185
287 
288     11     1.6e+60
289     12     1.6e+60
290     13     1.4e+60
291 
292     14     1.5e+60
293     15     1.5e+60
294     16     2.1e+84
295 
296 
297 A reasonably-correct numeric string can be generated in any supported
298 numeric base for the smallest possible input value:  0.1e-127.
299 
300 However, PL/I decimal support operations for float dec(59) arithmetic
301 lack the precision needed to convert very small non-decimal fractional
302 strings back to a number.
303 
304  - A non-decimal string can be converted back to a float dec(59)
305    number only if it represents a numeric value: >= 1.0e-68.
306 
307  - Any attempt to convert a smaller fraction will result in an
308    exponent underflow condition.
309 
310 
311 Notes on precision argument:
312 A float dec(59) input value precisely stores up to 59 radix places of
313 precision in a base=10 representation of that number.  More radix
314 places are needed to represent a 59-digit value when base is less than
315 10; and fewer radix places are needed when base is greater than 10.
316 
317 The following table shows the maximum precision (significant digits)
318 supported for each base representation of an input number.  This
319 precision is used when the input precision = 0.
320 
321 
322    BASE   MAXIMUM precision
323            (radix places)
324    ----   -----------------
325      2          199
326      3          125
327      4           99
328 
329      5           85
330      6           77
331      7           70
332      8           66
333 
334 
335      9           62
336     10           59
337 
338     11           57
339     12           55
340     13           53
341 
342     14           52
343     15           51
344     16           49
345 
346 
347 Notes on base argument:
348 A sub_error_ condition is signalled if the given base falls outside of
349 the range:  2 <= base <= 16
350 
351 
352 :hcom:
353 /****^  HISTORY COMMENTS:
354   1) change(2022-05-07,GDixon), approve(2022-07-13,MCR10101),
355      audit(2022-07-27,Swenson):
356       A) Join numeric_to_ascii_.info and numeric_to_ascii_base_.info
357          in the same info segment.
358       B) Change numeric_to_ascii_base_.info to describe the revised
359          calling sequence for this subroutine, and to specify limits
360          on size of the input value, and domain for the precision
361          argument.
362                                                    END HISTORY COMMENTS */
363