The following sections describe various elements, options, and codes used to control editing patterns and special editing characters.
Edit words are patterns or masks that are specified in RPG output specifications. They are used to create ad hoc edits for numeric values, such as phone numbers, social security numbers, sales figures, and the time of day. Table 2.23 lists various edit-word masks.
Edit Word | |||
---|---|---|---|
Description | *...v....1....v... | Unedited Value | Edited Output |
Large value | ' ,.' | 00654321 | 6,543.21 |
Stop zero suppression | ' , 0 . ' | 00000027 | 0.27 |
Time of day | '0 : :' | 071223 | 07:12:23 |
Social Security number | '0 - - ' | 023456789 | 023-45-6789 |
Phone number | '0( )& - ' | 8005551212 | (800) 555-1212 |
Floating currency symbol | ' , , $0. ' | 000009402 | $94.02 |
The number of blanks plus the zero suppression control code (i.e., the leading zero or asterisk) within an edit word must be greater than or equal to the number of digits for the field or named constant being edited.
Because editing a numeric value often changes the overall size of the value, RPG uses ending positions for the output location of fields in the output specification. This allows the right sides of numeric values to be aligned properly after editing.
Tip | To prevent zero suppression of output, specify a leading zero in the first (i.e., left-most) position of the edit word. This is typically used for editing values such as phone numbers where zero suppression is not desired. |
The currency symbol and zero suppression character do not displace numbers within the edit word. The currency symbol, however, requires an additional position. This additional position is usually allocated as the left-most position of the edit word. Figure 2.19 illustrates the edit mask required to edit a numeric field with a floating currency symbol, commas, a decimal point, and zero suppression. The size of this numeric field is nine positions with two decimal positions.
Figure 2.19: An edit-word example with the floating currency symbol.
Edit words consist of four optional elements:
Body. The body is the area of the edit word where the numeric value is positioned.
Status. The status is the area of the edit word consisting of the letters CR or a - (minus) sign. The status is used to indicate whether the value is negative or positive.
Expansion. The expansion area follows the body and status (usually literal values).
Literal values. Literal values can appear anywhere in the edit word. Literal values are included in the output only when significant digits appear to the left of the literal value. Note: While a named constant can be used as an edit word, named constants cannot be used within (i.e., as part of) the edit word itself.
There are several control codes that can be inserted into an edit word to control zero suppression, leading asterisks, floating currency symbol, blanks, and decimal notation. The first occurrence of a control code is used as the control code. Except for the ampersand (&), which is always used as a control code, subsequent occurrences are treated as literal values. Table 2.24 contains a description of the edit word control codes that can be used in an edit word.
Control Code | Description |
---|---|
$ | Currency Symbol If the currency symbol is followed immediately by a zero, the currency symbol precedes the first significant digit. This is referred to as a floating currency sign. If the currency symbol is not followed by a zero, the currency symbol's position is fixed. When using the floating currency symbol, an available blank position is displaced. Typically, the displaced blank is shifted to the left of the currency symbol. The character used as the currency symbol is specified by the CURSYM keyword on the header specification. |
* | Asterisk. Leading zeros are replaced with asterisks to the position of the asterisk. Zero suppression ends at the position of the asterisk. |
& | Ampersand. Always replaced with a blank when output. |
0 | Zero. Ends zero suppression at the position of the zero. The zero is used as one of the output positions for digits to appear. |
(period) , (comma) | Decimal Notation. These characters are not actual control codes; they are treated as literal values. They are traditionally used for decimal notation and thousands notation. |
| Blanks. Identifies available positions for the numeric value. |
CR | Status. The literal value CR is output if the value is negative. |
- | Status. The - (minus) sign is output if the value is negative. |
Tip | Be careful when using literal values in an edit word. Literal values can be any characters, including the letters CR. The first occurrence of the letters CR, however, is interpreted as the status code and will not appear when the number is greater than or equal to zero. |
To use an edit word, place the desired edit word—left justified—into output constant/edit word positions of the output specification for the field being edited. The RPG output specification accepts edit word literal values of up to 48 positions. For edit words that exceed 48 positions, the entry can be continued onto a second output line or a named constant can be used. Edit words can be up to 115 positions in length and can be specified—left justified—into output constant/edit word positions of the output specification. Figure 2.20 contains examples of edit-word usage.
.....FFileName++IFEASFRlen+LKeylnKFDevice+.Functions++++++++++++++++++++++++++++ FQPRINT O F 132 PRINTER OFLIND(*INOV) .....DName+++++++++++EUDS.......To/Len+TDc.Functions++++++++++++++++++++++++++++ D PhoneEdit C Const('0( )& - ') .....CSRn01Factor1+++++++OpCode(ex)Factor2+++++++Result++++++++Len++DcHiLoEq C TIME Time 6 0 C Z-ADD *DATE TodayIs 9 0 C Z-ADD 8005551212 Phone 10 0 C Z-ADD 654321 Sales 10 2 C MOVE 023456789 SSNBR 9 0 C EXCEPT C SETON LR .....OFormat++++DAddn01n02n03Except++++SpbSpaSkbSka OQPRINT E 1 .....O..............n01n02n03Field+++++++++YB?End++PConstant/Editword+++++++++++ O +0 'Soc Sec Nbr:' O SSNBR +2 '0 - - ' OQPRINT E 1 O +0 'Phone:' O PhoneNum +2 PhoneEdit OQPRINT E 1 O +0 'Date/Time:' O TodayIs Y +2 O Time +2 '0 & & ' OQPRINT E 1 O +0 'Salary:' O Sales +2 '$ , , *. CR'
Edit codes are single-character codes that represent predefined editing patterns. These edit patterns are simply specific edit word masks that automatically adapt to the size of the numeric field or named constant being edited. This allows numeric fields of any size to be edited without concern for the particular semantics involved in using edit words.
To edit using an edit code, place the desired edit code into the edit-code position of the output specification for the field to be edited. Edit codes can be combined with special edit characters, such as the $ (floating currency) symbol and * (leading asterisk), to further edit numeric output. These special characters can be specified—left justified—into output constant/edit word positions of the output specification. The characters must be enclosed in single quotes (i.e., apostrophes), and only one of these characters can be specified for a field edited with an edit code.
To illustrate the output of numeric values edited with edit codes, three versions of edited output are listed in Table 2.25. The first version uses only the edit code, the second version uses the edit code and the floating currency symbol, and the third version uses the edit code with leading asterisks.
Edit Code | Thousands Notation | Output Zeros | Negative Sign | Positive Output | Negative Output | Zero Output |
---|---|---|---|---|---|---|
1 | Yes | Yes | No | 4,567.89 | 4,567.89 | .00 |
1 $ | $4,567.89 | $4,567.89 | $.00 | |||
1 * | ****4,567.89 | ****4,567.89 | *********.00 | |||
2 | Yes | No | No | 4,567.89 | 4,567.89 | |
2 $ | $4,567.89 | $4,567.89 | ||||
2 * | ****4,567.89 | ****4,567.89 | ************ | |||
3 | No | Yes | No | 4567.89 | 4567.89 | .00 |
3 $ | $4567.89 | $4567.89 | $.00 | |||
3 * | ****4567.89 | ****4567.89 | *********.00 | |||
4 | No | No | No | 4567.89 | 4567.89 | |
4 $ | $4567.89 | $4567.89 | ||||
4 * | ****4567.89 | ****4567.89 | ********** | |||
A | Yes | Yes | Yes CR | 4,567.89 | 4,567.89CR | .00 |
A $ | $4,567.89 | $4,567.89CR | $.00 | |||
A * | ****4,567.89 | ****4,567.89CR | *********.00 | |||
B | Yes | No | Yes CR | 4,567.89 | 4,567.89CR | |
B $ | $4,567.89 | $4,567.89CR | ||||
B * | ****4,567.89 | ****4,567.89CR | ************ | |||
C | No | Yes | Yes CR | 4567.89 | 4567.89CR | .00 |
C $ | $4567.89 | $4567.89CR | $.00 | |||
C * | ****4567.89 | ****4567.89CR | *******.00 | |||
D | No | No | Yes CR | 4567.89 | 4567.89CR | |
D $ | $4567.89 | $4567.89CR | ||||
D * | ****4567.89 | ****4567.89CR | ************ | |||
J | Yes | Yes | Yes - | 4,567.89 | 4,567.89- | .00 |
J $ | $4,567.89 | $4,567.89- | $.00 | |||
J * | ****4,567.89 | ****4,567.89- | *********.00 | |||
K | Yes | No | Yes - | 4,567.89 | 4,567.89- | |
K $ | $4,567.89 | $4,567.89- | ||||
K * | ****4,567.89 | ****4,567.89- | ************ | |||
L | No | Yes | Yes - | 4567.89 | 4567.89- | .00 |
L $ | $4567.89 | $4567.89- | $.00 | |||
L * | ****4567.89 | ****4567.89- | *******.00 | |||
M | No | No | Yes - | 4567.89 | 4567.89- | |
M $ | $4567.89 | $4567.89- | ||||
M * | ****4567.89 | ****4567.89- | ************ | |||
N | Yes | Yes | Yes - | 4,567.89 | -4,567.89 | .00 |
N $ | $4,567.89 | -$4,567.89 | $.00 | |||
N * | ****4,567.89 | ****-4,567.89 | *********.00 | |||
O | Yes | No | Yes - | 4,567.89 | -4,567.89 | |
O $ | $4,567.89 | -$4,567.89 | ||||
O * | ****4,567.89 | ****-4,567.89 | ************ | |||
P | No | Yes | Yes - | 4567.89 | -4567.89 | .00 |
P $ | $4567.89 | -$4567.89 | $.00 | |||
P * | ****4567.89 | ****-4567.89 | *******.00 | |||
Q | No | No | Yes - | 4567.89 | -4567.89 | |
Q $ | $4567.89 | -$4567.89 | ||||
Q * | ****4567.89 | ****-4567.89 | ************ | |||
X | No | Yes | No | 000456789 | 00045678R | 000000000 |
Y | No | Yes | N/A | 45/67/89 | N/A | 0/00/00 |
Z | No | No | No | 456789 | 456789 |
In each example, the data being output is a nine-digit numeric field with two decimal positions. For positive numbers, the value 0004567.89 is used; for negative output, the value -0004567.89 is used; and for zero output, the value 0000000.00 is used.
The RPG header specification is used to control global editing values. The currency symbol, date format, date separator, and decimal notation are controlled by the header specification.
The character used as the currency symbol is controlled by the CURSYM keyword on the header specification. The character specified for the currency symbol can be used within edit words and with edit codes. For example, if the "at" sign (@) is specified, the @ symbol must be used wherever the currency symbol is normally used. Figure 2.21 illustrates the use of the @ symbol as the currency symbol.
Figure 2.21: An example using the custom currency symbol.