1 :Info: binary: bin:  2022-05-19  binary, bin
  2 
  3 Syntax as a command:  bin VALUEs
  4 
  5 
  6 Syntax as an active function:  [bin VALUEs]
  7 
  8 
  9 Function:  returns one or more numeric or character strings in binary
 10 (numeric base 2).  Each string is terminated by a radix indicator
 11 sub-field "b" (e.g., 101b).
 12 
 13 
 14 Arguments:
 15 VALUE
 16    an input string to be processed.  It is usually a fixed-point
 17    decimal string (e.g., 21 or 55.9) and may begin with either + or -
 18    sign.  It may end with a radix indicator denoting use of digits in
 19    a non-decimal base.  See "List of radix indicators" below.  It may
 20    be an arbitrary character string (1 to 8 characters long) followed
 21    by a "u" (for "unspec") indicator.  See "Notes on unspec values"
 22    below.
 23 
 24 
 25 List of radix indicators:
 26    Each VALUE may end with one of the following strings which indicate
 27    which numbering system's digits are expressing the value.
 28    Indicator characters may also be given in uppercase.
 29 b, _b
 30    the number is interpreted as a base two number (binary).
 31 q, _q
 32    the number is interpreted as a base four number (quaternary).
 33 o, _o
 34    the number is interpreted as a base eight number (octal).
 35 d, _d
 36    the number is interpreted as a base ten number (decimal).
 37 x, _x
 38    the number is interpreted as a base sixteen number (hexadecimal).
 39 
 40 
 41 rN, _rN
 42    the number is interpreted in the base N where N is a decimal number
 43    between 2 and 16 inclusive.
 44 
 45 
 46 Notes on unspec values:
 47 A VALUE argument ending with a "u" indicator is treated as character
 48 data.  The PL/1 unspec built-in converts each ASCII character to its
 49 binary encoding for the character.  Those binary bits are then
 50 displayed.  VALUE can be from 1 to 8 characters long.  This permits
 51 the user to see the binary encoding for the given characters.
 52 
 53 
 54 Examples:
 55 binary (21 -21)
 56 10101b
 57 -10101b
 58 
 59 binary 55.5
 60 110111.1b
 61 
 62 binary 55.5e20
 63 1.00101100110111011011100011101010110101101111100111111e+72b
 64 
 65 binary 30o
 66 11000b
 67 
 68 
 69 binary AB_x
 70 10101011b
 71 
 72 binary ABCu
 73 001000001001000010001000011b
 74 
 75 binary (A B C)u
 76 001000001b
 77 001000010b
 78 001000011b
 79 
 80 
 81 :Info: octal: oct:  2022-05-19  octal, oct
 82 
 83 Syntax as a command:  oct VALUEs
 84 
 85 
 86 Syntax as an active function:  [oct VALUEs]
 87 
 88 
 89 Function:  returns one or more numeric or character strings in octal
 90 (numeric base 8).  Each string is terminated by a radix indicator
 91 sub-field "o" (e.g., 177o).
 92 
 93 
 94 Arguments:
 95 VALUE
 96    is an input string to be processed.  It is usually a fixed-point
 97    decimal string (e.g., 21 or 55.9) and may begin with either + or -
 98    sign.  It may end with a radix indicator denoting use of digits in
 99    a non-decimal base.  See "List of radix indicators" below.  It may
100    be an arbitrary character string (1 to 8 characters long) followed
101    by a "u" (for "unspec") indicator.  See "Notes on unspec values"
102    below.
103 
104 
105 List of radix indicators:
106    Each VALUE may end with one of the following strings which indicate
107    which numbering system's digits are expressing the value.
108    Indicator characters may also be given in uppercase.
109 b, _b
110    the number is interpreted as a base two number (binary).
111 q, _q
112    the number is interpreted as a base four number (quaternary).
113 o, _o
114    the number is interpreted as a base eight number (octal).
115 d, _d
116    the number is interpreted as a base ten number (decimal).
117 x, _x
118    the number is interpreted as a base sixteen number (hexadecimal).
119 
120 
121 rN, _rN
122    the number is interpreted in the base N which is a decimal number
123    between 2 and 16 inclusive.
124 
125 
126 Notes on unspec values:
127 A VALUE argument ending with a "u" indicator is treated as character
128 data.  The PL/1 unspec built-in converts each ASCII character to its
129 octal encoding for the character.  Those octal digits are then
130 displayed.  VALUE can be from 1 to 8 characters long.  This permits
131 the user to see the octal encoding for the given characters.
132 
133 
134 Examples:
135 octal (21 -21)
136 25o
137 -25o
138 
139 oct 55.4
140 67.4o
141 
142 oct 30d
143 36o
144 
145 oct AB_x
146 253o
147 
148 
149 oct 1.E2
150 144o
151 
152 octal 55.5e20
153 1.131566707255337176e+24o
154 
155 oct ABCu
156 101102103o
157 
158 
159 :Info: decimal: dec:  1983-03-31  decimal, dec
160 
161 Syntax as a command:  dec VALUEs
162 
163 
164 Syntax as an active function:  [dec VALUEs]
165 
166 
167 Function:  returns one or more numeric or character strings in decimal
168 (numeric base 10).
169 
170 
171 Arguments:
172 VALUE
173    is an input string to be processed.  It may be a fixed-point
174    decimal string (e.g., 21 or 55.9), but is often a numeric string
175    ending with a radix indicator which specifies a non-decimal base.
176    See "List of radix indicators" below.
177 
178 
179 List of radix indicators:
180    Each VALUE may end with one of the following strings which indicate
181    which numbering system's digits are expressing the value.
182    Indicator characters may also be given in uppercase.
183 b, _b
184    the number is interpreted as a base two number (binary).
185 q, _q
186    the number is interpreted as a base four number (quaternary).
187 o, _o
188    the number is interpreted as a base eight number (octal).
189 d, _d
190    the number is interpreted as a base ten number (decimal).
191 x, _x
192    the number is interpreted as a base sixteen number (hexadecimal).
193 
194 
195 rN, _rN
196    the number is interpreted in the base N which is a decimal number
197    between 2 and 16 inclusive.
198 
199 
200 Examples:
201 decimal 21_d
202 21
203 
204 dec 55.7o
205 45.875
206 
207 dec 33q
208 15
209 
210 decimal AB_x
211 171
212 
213 dec 55.5e20
214 5.55e+21
215 
216 
217 :Info: hexadecimal: hex:  1983-03-31  hexadecimal, hex
218 
219 Syntax as a command:  hex VALUEs
220 
221 
222 Syntax as an active function:  [hex VALUEs]
223 
224 
225 Function:  returns one or more numeric or character strings in
226 hexadecimal (numeric base 16).    Each string is terminated by a radix
227 indicator sub-field "x" (e.g., 1e5x).
228 
229 
230 Arguments:
231 VALUE
232    an input string to be processed.  It is usually a fixed-point
233    decimal string (e.g., 21 or 55.9) and may begin with either + or -
234    sign.  It may end with a radix indicator denoting use of digits in
235    a non-decimal base.  See "List of radix indicators" below.
236 
237 
238 List of radix indicators:
239    Each VALUE may end with one of the following strings which indicate
240    which numbering system's digits are expressing the value.
241    Indicator characters may also be given in uppercase.
242 b, _b
243    the number is interpreted as a base two number (binary).
244 q, _q
245    the number is interpreted as a base four number (quaternary).
246 o, _o
247    the number is interpreted as a base eight number (octal).
248 d, _d
249    the number is interpreted as a base ten number (decimal).
250 x, _x
251    the number is interpreted as a base sixteen number (hexadecimal).
252 
253 
254 rN, _rN
255    the number is interpreted in the base N which is a decimal number
256    between 2 and 16 inclusive.
257 
258 
259 Examples:
260 hexadecimal 21
261 15x
262 
263 hex 55.7o
264 2d.ex
265 
266 hex 33q
267 fx
268 
269 hex AB_x
270 abx
271 
272 
273 hex (55.5e20 55.5e40)
274 12cddb8ead6f9f80000x
275 6.5eff97e9da95b78dbad0b2878p+34x
276 
277 
278 :Info: radix:  2022-05-12  radix
279 
280 Syntax as a command:  radix BASE VALUEs
281 
282 
283 Syntax as an active function:  [radix BASE VALUEs]
284 
285 
286 Function:  returns one or more numeric strings in expressed in digits
287 of a specified numbering system.  Each non-decimal string is
288 terminated by a radix indicator sub-field.  See "Notes on result"
289 below for further details.
290 
291 
292 Arguments:
293 BASE
294    is the radix of the numbering system digits in which each numeric
295    value is to be expressed as a string.  It must be a number between
296    2 and 16.
297 VALUE
298    is an input string to be processed.  It may be a fixed-point or
299    floating point decimal string (e.g., 21 or 55.9), but is often a
300    numeric string ending with a radix indicator which specifies a
301    non-decimal base.  See "List of radix indicators" below.
302 
303 
304 List of radix indicators:
305    Each VALUE may end with one of the following strings which indicate
306    which numbering system's digits are expressing the value.
307    Indicator characters may also be given in uppercase.
308 b, _b
309    the number is interpreted as a base two number (binary).
310 q, _q
311    the number is interpreted as a base four number (quaternary).
312 o, _o
313    the number is interpreted as a base eight number (octal).
314 d, _d
315    the number is interpreted as a base ten number (decimal).
316 x, _x
317    the number is interpreted as a base sixteen number (hexadecimal).
318 
319 
320 rN, _rN
321    the number is interpreted in the base N which is a decimal number
322    between 2 and 16 inclusive.
323 
324 
325 Notes on result:
326 The result returned by the radix command or active function is the
327 ascii representation of input value in the selected numbering system.
328 The result uses one of the following formats:
329 
330    MANTISSA   OR   MANTISSAe+EXP   OR   MANTISSAe-EXP
331 
332 While MANTISSA gives the integer or integer.fraction representation
333 expressed in digits of the selected numbering system, the EXP exponent
334 is always expressed using decimal digits.
335 
336 
337 For results expressed in base 15 or 16, any exponent is preceded by
338 the 'p' exponent indicator letter because 'e' is a valid digit that
339 can appear in the MANTISSA of these numbering bases.
340 
341    MANTISSA   OR   MANTISSAp+EXP   OR   MANTISSAp-EXP
342 
343 
344 Mantissa digits for bases 11 through 16 represent values beyond 9
345 using lowercase letters.  Digits for the most common numeric bases are
346 shown in the table below, ordered in ascending value.  Digits for a
347 base N lower than 16 use the first N valid digits listed for base 16.
348 
349   BASE      VALID DIGITS IN THAT BASE        COMMON NAME
350   ----   -------------------------------    -------------
351     2    0 1                                    binary
352     4    0 1 2 3                              quaternary
353     8    0 1 2 3 4 5 6 7                         octal
354    10    0 1 2 3 4 5 6 7 8 9                    decimal
355    12    0 1 2 3 5 5 6 7 8 9 a b
356    16    0 1 2 3 4 5 6 7 8 9 a b c d e f      hexadecimal
357 
358 
359 The MANTISSA includes all significant radix places selected by the
360 precision argument.  If the MANTISSA includes too few radix places to
361 represent the magnitude of the value, an exponent is added.  The EXP
362 sub-field is a signed decimal integer representing a multiplier for
363 the MANTISSA:
364 
365    MANTISSA * (base ** EXP)
366 
367 That is, a positive exponent (E+n) shifts the point n radix-places
368 to the right, while a negative exponent (E-n) shifts the point n
369 radix-places to the left of any point displayed in the mantissa.
370 For an integer mantissa, the point is not displayed; it is assumed to
371 follow the last radix-place of the displayed integer.
372 
373 
374 A radix indicator sub-field appears at the end of each non-decimal
375 result to indicate the base in which its digits are expressed.  The
376 following shows which sub-field value is appended for each base.
377 
378 
379    BASE   radix indicator sub-field
380    ----   ------------------------------------------
381      2     b    (stands for binary)
382      3     _r3
383      4     q    (stands for quaternary)
384      5     _r5
385      6     _r6
386      7     _r7
387      8     o    (stands for octal)
388      9     _r9
389     10          (no indicator appended for decimal base)
390     11     _r11
391     12     _r12
392     13     _r13
393     14     _r14
394     15     _r15
395     16     x    (stands for hexadecimal)
396 
397 
398 All result strings are in one of the formats accepted by the
399 cv_fixed_point_string_ subroutine.  Integer results are in a format
400 accepted by the cv_integer_string_ subroutine.  Also, binary and
401 decimal result strings are in a format acceptable to the PL/I convert
402 built-in function and PL/I character-string-to-number conversion
403 rules.
404 
405 A string expressing a large input value using a small base such as
406 binary may require 200 or more characters to hold all significant
407 digits and exponent.  The PL/I runtime reserves up to 256 characters
408 to hold numeric strings representing the largest values in binary
409 digits.  The radix return value follows that maximum string length
410 policy.
411 
412 
413 Examples:
414 radix 5 21
415 41_r5
416 
417 radix 16 55.7o
418 2d.ex
419 
420 radix 10 33q
421 15
422 
423 radix 16 55.5e40
424 6.5eff97e9da95b78dbad0b2878p+34x
425 
426 
427 :hcom:
428 /****^  HISTORY COMMENTS:
429   1) change(2021-12-05,GDixon), approve(2022-07-13,MCR10101),
430      audit(2022-07-27,Swenson):
431       A) Combine binary.info octal.info decimal.info and hexadecimal.info
432          into a single multi-block info segment.  All these commands share
433          same interface and should be documented together.
434       B) Remove documentation for "u" input format indicator from
435          decimal.info and hexadecimal.info.  The unspec(char_string)
436          functionality doesn't have much meaning in dec/hex output base.
437   2) change(2022-05-19,GDixon), approve(2022-07-13,MCR10101),
438      audit(2022-07-27,Swenson):
439       A) Add initial documentation for the new radix command/af.
440       B) Update bin, oct and hex to describe addition of radix indicator
441          to result string.
442                                                    END HISTORY COMMENTS */
443