A report field can contain the right value and still print badly: an unclear column name, unwanted leading zeros, a missing currency sign, or a zero amount that clutters every detail line. Easytrieve separates the stored value from its printed form, so you can correct the report without changing the input record.
What HEADING and MASK change
HEADING supplies the text printed above a field. MASK supplies the pattern used when the field is printed. BWZ, or blank when zero, can remove a zero-valued numeric field from the visible line. These choices affect report presentation; they do not rewrite the source bytes.
This page concentrates on report-field editing. For field name, start position, length, data type, and decimal-place syntax, begin with the Easytrieve field definition guide.
Define a column heading on the field
Add HEADING to a field definition when the same label should follow that field into reports. A quoted literal keeps spaces together:
EMP-NAME 20 20 A HEADING 'EMPLOYEE NAME'
NET-PAY 40 6 P 2 HEADING 'NET PAY'
The heading describes the printed column, while EMP-NAME and NET-PAY remain the field names used by program statements. Keep headings short enough for the report width and clear enough for someone reading a spool listing without the program source.
Create a multi-line heading
Easytrieve can print more than one heading literal for a field. This is useful when a descriptive label is wider than the column:
SOCIAL-NO 60 9 N 0
MASK '999-99-9999'
HEADING ('SOCIAL' 'SECURITY' 'NUMBER')
Each literal forms a heading line. Test the result with the report’s spacing and printer width because a narrow field, long literal, and adjacent column can produce an awkward layout.
Override a heading in the REPORT section
A report can supply a local heading without changing the reusable field definition. In a report-level HEADING statement, code the field name before the parentheses:
REPORT SALES-RPT
LINE EMP-NAME NET-PAY
HEADING NET-PAY ('TAKE-HOME' 'PAY')
Use MASK for printed output
A mask tells Easytrieve how to display a report field. It is a presentation rule, not a data-conversion statement. For example, a packed value holding 123450 with two implied decimal places can print as $1,234.50 while its stored representation remains packed decimal.
NET-PAY 40 6 P 2
HEADING 'NET PAY'
MASK '$,$$$,$$9.99'
The exact pattern must fit the numeric field and the output required at your site. If you move the field to a non-printer output file, do not assume its report mask becomes the file format. Define the receiving layout and conversion rules explicitly.
Understand common numeric edit characters
| Character | Typical report use | Point to check |
|---|---|---|
9 | Reserves a digit position and prints a zero where that position requires one. | Useful for fixed digit layouts such as identifiers. |
Z | Suppresses an insignificant leading zero, normally leaving a blank. | Use enough positions to cover the field. |
* | Replaces suppressed leading positions with asterisks. | Often used for protected financial print. |
- | Provides a sign position for negative values. | Confirm whether the required sign is leading or trailing. |
$ | Prints or floats a currency symbol according to the mask pattern. | Confirm local currency and punctuation rules. |
| Comma, period, slash, hyphen | Print punctuation or separators in the chosen positions. | A literal separator does not change the stored value. |
Mask behavior can depend on the installed Easytrieve release and option settings. Use a small test report when converting an old program or moving code between sites.
Count storage digits before mask positions
A mask needs room for every numeric digit. For an N field, the digit count matches the field length. For packed P, it is normally twice the byte length minus one because one half-byte holds the sign. For unsigned packed U, it is normally twice the byte length. A sign or currency character can add another printed position.
Format currency, signs, and decimals
Build the pattern from the stored field’s digits and decimal places, then add the report punctuation:
AMOUNT 10 5 P 2 HEADING 'AMOUNT'
MASK '$$$,$$9.99-'
This pattern reserves positions for currency, grouped digits, two decimal places, and a trailing negative sign. Do not copy it blindly: validate positive, negative, zero, maximum, and smallest non-zero values. The test should prove alignment as well as the digits shown.
Blank an all-zero field with BWZ
BWZ requests blank output when the numeric value is zero. It is useful in sparse reports where rows of zeros hide the values that matter.
ADJUSTMENT 30 5 P 2
HEADING 'ADJUSTMENT'
MASK 'ZZZ,ZZ9.99-'
BWZ
BWZ blanks the field for a zero value; it is different from suppressing only leading zeros. Decide whether a blank could be mistaken for missing data. If zero carries business meaning, printing 0.00 may be safer.
Use site-defined edit masks carefully
Easytrieve option settings can define named edit masks, often selected by a mask letter. They help a site apply a repeated numeric style consistently. Their meaning is local, so the same letter can produce a different result—or be undefined—after a program moves to another installation.
Check the local option table before using a named mask. If portability matters more than a shared installation convention, an explicit mask literal makes the intended output visible in the source.
Format identifiers and dates without changing data
Fixed numeric identifiers can be printed with separators, as in 999-99-9999. A date stored as eight digits can be displayed with slashes by defining an appropriate field view and print pattern. Keep identifiers as identifiers: do not perform arithmetic on account, telephone, postal, or reference numbers merely because every character is numeric.
For dates, first confirm the stored order—such as YYYYMMDD or MMDDYYYY. A mask can add separators, but it cannot detect a wrongly assumed component order.
Build a complete report example
The following fragment brings the field heading, mask, and blank-when-zero choices together. File names and record positions are examples and must match the actual input layout.
FILE EMPFILE
EMP-ID 1 6 N HEADING 'EMP ID' MASK '999999'
EMP-NAME 7 20 A HEADING 'EMPLOYEE NAME'
GROSS-PAY 27 6 P 2 HEADING 'GROSS PAY' MASK '$$$,$$9.99'
DEDUCTION 33 6 P 2 HEADING 'DEDUCTION' MASK 'ZZZ,ZZ9.99-' BWZ
JOB INPUT EMPFILE
PRINT PAY-RPT
REPORT PAY-RPT
TITLE 1 'PAYROLL SUMMARY'
LINE EMP-ID EMP-NAME GROSS-PAY DEDUCTION
Run the report against boundary values before production use. Include blank names, zero deductions, negative amounts if allowed, the largest valid amount, and a record at the minimum valid length.
Create an alternate field view by position
Easytrieve has no COBOL-style hierarchy levels, but a field’s start location can name another field and add an offset. This creates another view of existing bytes without allocating new record storage:
TRANS-DATE 80 8 N
TRANS-YEAR TRANS-DATE 4 N
TRANS-MONTH TRANS-DATE +4 2 N
TRANS-DAY TRANS-DATE +6 2 N
If TRANS-DATE contains YYYYMMDD, the three component fields refer to its year, month, and day positions. This is useful for selection, sorting, or report columns. It does not validate that the bytes form a real calendar date.
Define working fields explicitly
A working field stores a calculated or temporary value rather than bytes read directly from the input record. Define it before use and select a length, type, and decimal count that can hold the result.
NET-PAY-W W 6 P 2 HEADING 'NET PAY'
MASK '$$$,$$9.99-'
JOB INPUT EMPFILE
NET-PAY-W = GROSS-PAY - DEDUCTION
PRINT PAY-RPT
When a JOB can see fields from more than one file, qualify record fields as required by the program and release. The Easytrieve calculations guide covers assignment and arithmetic examples.
Protect variable-length record access
A field view is safe only when the current record is long enough to contain all referenced positions. With variable-length input, test RECORD-LENGTH before referencing a field near the end of the layout. A heading or mask does not protect the program from reading beyond the current record.
Common HEADING and MASK errors
| Symptom | Likely cause | Check |
|---|---|---|
| Heading statement rejected | Field name is missing or placed inside the literal list. | At report level, put the field name before the parentheses. |
| Digits missing or shifted | The mask has too few digit positions. | Count N, P, or U digits and allow for sign and currency positions. |
| Zero prints as blanks | BWZ is active. | Remove BWZ if zero must remain visible. |
| Output file lacks punctuation | A report mask was expected to convert file data. | Define the output-file layout and conversion separately. |
| Named mask changes after migration | Option-table definitions differ. | Compare site-defined mask settings or use an explicit literal. |
| Field location error | The base field, offset, or current record length is invalid. | Review the definition and guard variable-length access. |
Report formatting checklist
- Confirm the field’s storage type, byte length, digits, and decimal places.
- Write a short heading that fits the intended column.
- Count every digit position in the mask.
- Allow space for punctuation, currency, and sign characters.
- Choose deliberately between leading-zero suppression and BWZ.
- Test positive, negative, zero, minimum, and maximum values.
- Confirm that report presentation is not being mistaken for file conversion.
- Check local named-mask settings before moving code between systems.
Related Easytrieve guides
See Easytrieve basic reporting for TITLE, LINE, SEQUENCE, CONTROL, and summary concepts. Review Easytrieve program structure to place FILE, JOB, and REPORT statements correctly, and use the Easytrieve library section guide for record layouts. The Easytrieve JOB guide adds input and processing context.
Official Broadcom references
- Broadcom report-level HEADING syntax
- Broadcom MASK behavior for printed fields
- Broadcom field heading and mask examples
- Broadcom mask digit-count guidance
- Broadcom site-defined edit-mask options
- Broadcom field start locations and offsets
- Broadcom variable-length record safeguards
Easytrieve HEADING and MASK FAQ
Does an Easytrieve MASK change the stored field?
No. MASK controls how a field is shown in printed report output. Use an assignment, conversion, or defined output-file layout when you need to change the value or write formatted file data.
What is the difference between Z and BWZ?
Z suppresses insignificant leading zeros within the mask. BWZ blanks the entire displayed numeric field when its value is zero. Test both with zero and non-zero values to confirm the intended report appearance.
Can a report override a field’s HEADING?
Yes. A REPORT section can supply a heading for a named field. Code the field name before the parenthesized heading literals, and use separate literals when a multi-line heading is needed.
Why does a numeric mask lose digits?
The mask probably has fewer digit positions than the field can contain. Count the digits represented by the N, P, or U definition, then include any added positions needed for a sign, currency symbol, and punctuation.
Excellent.
ReplyDelete