Easytrieve Formatting Functions

Role of Formatting in Batch Programs

Batch Easytrieve jobs read files, compute totals, write reports. Numeric integrity lives in packed fields through arithmetic. Formatting is the last mile before human eyes or downstream systems expecting character layouts. TITLE lines show run dates formatted pleasantly. LINE statements list currency right-aligned via edited strings. DISPLAY during development shows readable diagnostics without attaching a hex dump tool. Skipping formatting produces technically correct numbers in wrong clothes—auditors reject reports even when totals reconcile.

EDIT and Picture Mask Patterns

The EDIT family—exact invocation spelling varies by release—applies a picture string to a numeric source. Picture characters mirror COBOL conventions: 9 for digit, Z for zero suppress, comma and period as punctuation, $ or currency symbol, S or CR for sign control. A mask Z,ZZZ,ZZ9.99- turns 1234567.8 into 1,234,567.80- when field width accommodates output. Masks must be wide enough; overflow often prints asterisks filling the field—a signal to widen OUT-AMT A 20 before blaming arithmetic.

1
2
3
4
5
* Illustrative pattern—verify EDIT syntax on your compiler
GROSS-EDIT = EDIT(GROSS, 'ZZ,ZZZ,ZZ9.99')
NET-EDIT   = EDIT(NET,   '$$$,$$$,$$9.99CR')
 
LINE GROSS-EDIT NET-EDIT EMP-NAME

Representative Formatting Function Families

Picture Character Reference for Beginners

Each picture character controls one aspect of output. Combining them builds the display template. Wrong character in one position shifts every column right on the report.

Separate Compute Fields From Display Fields

Define GROSS P 2 for math. Define GROSS-DISP A 18 for EDIT output. After NET = GROSS - TAX, assign GROSS-DISP = EDIT(GROSS, mask). Never round-trip: editing NET into a display field then adding tax back in arithmetic without reconverting corrupts totals. Report LINE lists GROSS-DISP; internal SUM accumulators stay numeric. This pattern prevents the most common formatting bug—accidentally using edited strings in IF GROSS GT LIMIT comparisons where collating order replaces numeric order.

Formatting in REPORT Versus JOB Logic

JOB procedural logic prepares working display fields before PRINT selects records. REPORT LINE may reference those fields by name. Some releases allow edit specifications on LINE directly; others require pre-formatted Library fields. TITLE often concatenates literals with formatted date fields: TITLE 'PAYROLL AS OF ' RUN-DATE-EDIT. Keep TITLE within LINESIZE; long masks widen lines and wrap unexpectedly when LINESIZE is tight.

Implied Decimals and Mask Alignment

P 2 stores cents in the last two digit positions. Mask must include two 9 or Z positions after decimal point for cents to appear. P 0 amounts need no decimal portion in mask—or use .99 only when policy shows fractional dollars. Misaligned implied decimal produces 100x errors visible only on formatted output while packed math remains internally consistent—a dangerous split-brain state during debugging.

International and Legacy Variations

European sites may swap comma and period roles in masks. Legacy programs hard-code dollar sign when multi-currency was not required. When migrating, grep all EDIT masks and verify against business requirements document—not just compile success. EBCDIC display characters for currency differ from ASCII tools used in open-systems editors; test on z/OS spool or viewer matching production code page.

Performance Considerations

Formatting per record on million-row files adds CPU versus printing raw packed—but human reports require it. Hoist run-date formatting once before JOB loop. Avoid re-editing unchanged fields inside inner IF chains. Cache formatted department name when DEPT code maps to long text via table lookup plus format step. I/O still dominates runtime; clarity of separate DISP fields saves more maintainer time than micro-optimizing EDIT calls.

Alternatives When EDIT Builtin Unavailable

• Manual division and MOVE of digit subfields—legacy but portable.
• TABLE-driven picture selection for multiple report layouts.
• CALL to COBOL or assembler edit routine when shop standard permits.
• Post-process spool with DFSORT OUTREC overlay—outside Easytrieve but common ops pattern.

Common Formatting Mistakes

• Mask too narrow—asterisk overflow on large amounts.
• Using edited A field in numeric IF or ADD.
• Implied decimal mismatch between source P field and mask.
• Formatting inside loop when value unchanged since last format.
• Assuming SQL CAST or COBOL INSPECT equivalents exist with same names.
• Negative values with wrong sign picture—parentheses omitted on credits.

Explain It Like I'm Five

Formatting is dressing up numbers for a photo. The amount in the piggy bank is the real number. The label you stick on the jar—with dollar sign, commas, and two decimal places—is formatting so grown-ups can read it quickly. You do not pay for candy using the label; you use the coins inside. Easytrieve keeps coins in packed fields and makes labels in character fields before showing them on the report picture.

Exercises

1. Define GROSS P 2 and GROSS-EDIT A 16; describe assignment order before PRINT.
2. Explain why asterisks appear when amount exceeds mask width.
3. Write a TITLE using a formatted date field name placeholder.
4. Contrast formatting function with conversion function in one paragraph.
5. List three picture characters and what each controls on output.