D2PIC

Syntax:

D2PIC(rexxnum,picstr[,national][,synerrval])

Arguments:

rexxnum: the REXX decimal number to be converted. The number may have a sign and a decimal point. Exponential format is not supported. The total number of characters in rexxnum (including sign, decimal point and blanks) cannot exceed 256.
picstr: a string representing the formatting to be applied to rexxnum. This string cannot exceed 256 bytes in length, and may not contain embedded blanks. See Picture String Symbols" below for more information on this argument.
national: a 3 byte string containing the characters to be used for the currency symbol, the decimal point, and the hundreds separator, respectively. The default national string is '$.,' (where the dollar sign is the currency symbol, the period is the decimal point character, and the comma is the hundreds separator). This string, if coded, must be exactly 3 bytes in length and cannot contain blanks or any of the other valid picture symbols.
synerrval: indicates the value to be returned if a syntax error is detected. This argument can be used to handle normally occurring, but invalid, data. For example, null strings.

Module Name:

SWXD2PIC

Service Description:

The D2PIC function is used to convert REXX decimal numbers into a format suitable for printing reports. The D2PIC function is especially helpful for formatting numbers that represent currency amounts.

Formatting is performed -- under the control of the picstr argument -- in a manner similar to that of COBOL numeric-edited fields. The national argument permits customization of D2PIC's algorithm to account for local differences in currency formats.

Conceptually, the operation of D2PIC is as follows:

The REXX number is validated and its precision (total digits) and scale (fractional digits) are determined.
The picture string is validated and its precision and scale are determined.
The REXX number is sized to fit the picture specification. If the REXX number's scale is smaller than that of the picture specification, trailing zeros are appended to the number. If the REXX number's scale is too large to fit the picture specification, some or all of the fractional digits may be truncated. If the whole number digits of the REXX number are fewer than those of the picture specification, leading zeros are appended to the number. However, it is an error if the picture specification does not contain enough whole number digit positions to accommodate the REXX number.
Finally, the picture specification is processed one symbol at a time, working from left to right. As each picture symbol is recognized, a determination is made as to whether a result byte is to be generated and, if so, what its value will be. The processing of some picture symbols involves the selection of the next digit from the REXX number.

Note: Each picture symbol's operation depends, in some part, on whether or not the symbol lies within the significant portion of the result. Significance is said to be "started" whenever a significant digit is encountered in the REXX number, or when a '9', 'V' or decimal point symbol is encountered in the picture string.

Picture String Symbols:

The picstr argument specifies the manner in which the REXX decimal number given in rexxnum is to be formatted. The following symbols are permitted in picstr:

9: indicates a position that will always contain a numeric digit (0-9), regardless of significance. This symbol is counted when determining the size of the result.
Z

Notes:

The alphabetic symbols may be coded in lower case. However, the resulting numeric-edited number will contain only uppercase characters.
In the examples below, the lowercase letter "b" is used to indicate a blank position in the result.
A repetition factor, contained in parentheses, may immediately follow a picture symbol. For example, the following picture strings are equivalent:
```
99999.99
9(5).99
```
The "V" is the only symbol that does not produce a position in the result.

Simple Insertion Editing:

The characters 'B', '0', '/' and the hundreds separator (default: ',') are simple insertion symbols. These characters are replaced, one-for-one, with the indicated character in the result. For example:

picstr              rexxnum             Result
 
999B99/9            123                 000b12/3
99,999              12345               12,345
99/99/99999         01021995            01/02/1995

Note: Simple insertion symbols may also be used in floating insertion editing. Their use in this context is described in "Floating Insertion Editing" below.

Decimal Point Editing:

The decimal point symbol (default: '.') or the 'V' is used to specify the location of the decimal point in picstr. The value in rexxnum is aligned on the decimal point location in picstr. For example:

picstr              rexxnum             Result
 
999.999             12.34               012.340
999.99              1.234               001.23
999V9999            12.345              0123450

Fixed Insertion Editing:

The currency symbol (default: '$') and the '+', '-', 'CR' and 'DB' symbols are used to indicate the currency and sign of the number. When used in fixed insertion editing, only one occurrence of any of these symbols is permitted. Fixed insertion characters will appear in the result in exactly the same location as they are found in picstr. The currency symbol will always appear as coded. The resulting representation of the other fixed insertion characters depends upon the sign of rexxnum (refer to the symbol definitions above for the exact translation that takes place). Below are some examples of fixed insertion editing:

picstr              rexxnum             Result
 
999.99+             0                   000.00+
$999.99CR           22.45               $022.45bb
$999.99CR           -27                 $027.00CR
-99.99              42                  b42.00
-99.99              -79.4               -79.40

Floating Insertion Editing:

Floating insertion editing is used to specify both numeric digit positions and an insertion character to place to the left of the resulting number. For example, in the picture string

++++.99

the '+' symbol -- a floating insertion character -- is used to reserve 4 whole number positions, and indicates that a sign is to be inserted to the left of the most significant digit. If the number 22 were to be formatted using this picture string, the result would be:

b+22.00

Notice that the sign is placed immediately to the left of the leftmost '2', and that the whole number position to the left of the sign is blank.

The rules for floating insertion are as follows:

Only the currency symbol (default: '$') and the '+' and '-' symbols may be used as floating insertion characters. The use of these characters in floating insertion is distinguished from their use in fixed insertion by the repetition of the character to be "floated". For example, in the string '$999.99' the currency symbol is used as a fixed insertion character, but in '$$$$.99' it is used as a floating insertion character. The collection of floating insertion characters in a picture string is referred to as the floating string.

A picture string may contain only one floating string, and that string may be composed of only one of the valid floating insertion characters. Thus, '+$$$9.99' is a valid picture string, while '++$$9.99' and '$$99.$$' are not. Moreover, a symbol may not be used for both floating and fixed insertion in the same picture string.

Floating insertion may not be used in any picture string that contains the '*' or the 'Z' characters (see "Zero Suppression and Replacement Editing" below).
A floating insertion character's influence on its corresponding result byte is determined as follows:
1. If significance has not started, the result byte will contain a blank.
2. If significance has not started, but the position lies immediately to the left of the start of significance, the result byte will contain the floating insertion character (remember that with '+' and '-' the actual result depends on the sign of the REXX number).
3. If significance has started, the result byte will contain the corresponding REXX number digit.
If simple insertion characters ('B' '0' '/' and the hundreds separator) or the decimal point are contained within or immediately to the right of a floating string, they are considered to be part of the floating string. The behavior of simple insertion characters within a floating string is different from their behavior elsewhere:
1. If significance has not started, the result byte will contain a blank.
2. If significance has not started, but the position lies immediately to the left of the start of significance, the result byte will contain the floating insertion character.
3. If significance has started, the result byte will contain the value specified by the simple insertion character.
A special rule for floating insertion is applied whenever:
1. all numeric positions in picstr are occupied by the floating insertion character, and
2. the value of rexxnum is zero.
In this situation, the entire result will be filled with spaces. So for example, if the picture string:
```
$$,$$$.$$
```
is applied to a zero REXX number, the result will be:
```
bbbbbbbbb    (9 blanks)
```

The following examples demonstrate the operation of floating insertion editing:

picstr              rexxnum             Result
 
$$$$9.99            123.45              b$123.45
+++++.++            22.9                bb+22.90
+++++.++            0.01                bbbb+.01
+++++.++            0                   bbbbbbbb
-----.99            23.72               bbb23.72
$$,$$9.99           432.97              bb$432.97
$$,$$9.99           2195.49             $2,195.49

Zero Suppression and Replacement Editing:

Zero suppression and replacement editing is a special case of floating insertion editing. The two symbols used for this type of editing -- 'Z' and '*' -- reserve numeric digit positions, and specify the value that will be used to replace leading (non-significant) zeros in the result.

The rules governing the use of zero suppression and replacement editing are as follows:

Either 'Z' or '*', but not both may appear in a picture string. Unlike the floating insertion symbols, the appearance of only one of these symbols indicates that zero suppression and replacement editing is in effect.
Zero suppression and replacement editing is mutually exclusive with floating insertion editing. However, the currency symbol, and the '+' and '-' symbols may be used as fixed insertion characters (i.e., only one occurrence of any of the fixed insertion characters may appear in a picture string that contains 'Z' or '*'. For example, under this rule '$zzz.zz+' is permissible).
A 'Z' or '*' character's influence on its corresponding result byte is determined as follows:
1. If significance has not started, the result byte will contain a blank, if the character is a 'Z'; or an asterisk, if the character is a '*'.
2. If significance has started, the result byte will contain the corresponding REXX number digit.
If simple insertion characters (B 0 / and the hundreds separator) or the decimal point are contained within or immediately to the right of a string of 'Z' or '*' characters, they are considered to be part of that string. The behavior of simple insertion characters within a string of 'Z' or '*' characters is different from their behavior elsewhere:
1. If significance has not started, the result byte will contain a blank, if the string contains 'Z' characters; or an asterisk, if the string contains '*' characters.
2. If significance has started, the result byte will contain the value specified by the simple insertion character.
A special rule for zero suppression and replacement editing is applied whenever:
1. all numeric positions in picstr are occupied by 'Z' or '*' characters, and
2. the value of rexxnum is zero.
If the string is composed of 'Z' characters, the entire result will be filled with spaces. If the string is composed of '*' characters, the entire result will be filled with asterisks, except that if a decimal point is present, it will be placed in its specified position.

The following examples demonstrate the operation of zero suppression and replacement editing:

picstr              rexxnum             Result
 
ZZZZ9.99            123.45              bb123.45
ZZZZZ.ZZ            22.9                bbb22.90
*****.**            0.01                *****.01
ZZZZZ.ZZ            0                   bbbbbbbb
*****.**            0                   *****.**
*****.99            0                   *****.00
ZZZZZ.99            0                   bbbbb.00
Z,ZZZ.ZZ            2194.973            2,194.97
Z,ZZZ.ZZ            46.92               bbb46.92
$*,***.**           46.92               $***46.92

Returned Information:

The D2PIC function returns the edited representation of rexxnum. If you CALL the D2PIC function, the returned value is contained in the RESULT special variable. The RC special variable is unchanged.

Examples:

Call the D2PIC function to convert the REXX decimal number 100.42 to a formatted dollar value:
```
dollar = d2pic(100.42,'$$,$$9.99')
/* dollar = '  $100.42' */
```

Convert the packed decimal number 100.42 to a formatted dollar value:

dollar = d2pic(p2d('000010042c'x,2),'$$,$$9.99')
/* dollar = '  $100.42' */

Convert the number 1958.21 to a formatted value using the comma as the decimal point, and the period as the hundreds separator (French currency notation):
```
amount = d2pic(1958.21,'ff.ff9,99','f,.')
/* amount = 'f1.958,21'*/
```