Easytrieve Field Definition: Name, Position, Length, and Type

An Easytrieve report prints the wrong value when a field starts at the wrong byte. Field definitions tell Easytrieve where each value begins, how many bytes it occupies, and whether the data is alphanumeric, numeric, packed decimal, unsigned packed, or binary.

Define bytes first.

What is an Easytrieve field definition?

An Easytrieve field definition names one item inside a file record or a working storage area. For an input file, the definition normally gives the field name, start position, length, data type, and optional decimal positions. Report options such as HEADING and MASK can be added when the field is printed.

The field definition is usually coded below the FILE statement. Easytrieve uses it when the job reads the file, tests values, calculates totals, or prints report columns.

Basic syntax

field-name   start-location   field-length   data-type   [decimal-positions] +
             [HEADING 'literal'] [MASK 'edit-mask']

The old post listed the same parts, but the rewrite below shows how each part affects a real report.

Field definition parts

Part	Meaning	Example
field-name	The name used later in IF, MOVE, DISPLAY, LINE, and calculations.	PAY-NET
start-location	The byte position in the record, counted from position 1.	90
field-length	The number of bytes occupied by the field.	4
data-type	How Easytrieve should read and process the bytes.	P for packed decimal
decimal-positions	The implied number of decimal places for numeric fields.	2

Simple input file example

This example defines a fixed personnel record. The fields are then used in a report line.

FILE PERSNL FB(150 1800)
     DEPT        1   3 N
     EMPNO       9   5 N
     NAME       17  20 A
     PAY-NET    90   4 P 2

JOB INPUT PERSNL
    IF DEPT = 910
        PRINT PAYRPT
    END-IF

REPORT PAYRPT LINESIZE 100
    TITLE 1 'DEPARTMENT 910 NET PAY'
    LINE DEPT EMPNO NAME PAY-NET

If PAY-NET starts at byte 91 instead of byte 90, the report can show bad packed data or fail when Easytrieve tries to treat the wrong bytes as a packed amount.

Choosing field names

Use field names that match the business meaning of the data. PAY-NET is easier to read than FIELD-4. A field name also needs to be unique enough for the program. When two files contain the same field name, qualify it with the file name, such as PERSNL:DEPT.

Start location and length

The start location is counted from the first byte of the record. The length is the storage length, not the display width that appears on a printed report.

NAME       17  20 A
ADDRESS    37  39 A
PAY-NET    90   4 P 2

In this layout, NAME uses bytes 17 through 36. ADDRESS starts at byte 37. That clean byte boundary is what prevents fields from bleeding into each other.

Easytrieve data types

Type	Use it for	Practical note
A	Names, codes, descriptions, and other character data.	Best for values that should print exactly as stored.
N	Zoned/display numeric fields.	Common for readable numeric fields in flat files.
P	Packed decimal fields.	Common for money and quantity values from COBOL files.
U	Unsigned packed decimal fields.	Use only when the field is not signed.
B	Binary fields.	Broadcom notes that Easytrieve binary fields are defined as B fields and should be 4 bytes or less in the cited sample.

Decimal positions

Decimal positions are implied. They are not stored as a visible decimal point in the input record. In the next example, AMOUNT is a five-byte numeric field with two decimal positions.

AMOUNT     40   5 N 2

A stored value of 00123 represents 1.23 when the field is treated as having two decimal places. Use decimal positions only for fields that are really numeric quantities. Do not define account numbers, employee numbers, or product codes with decimal positions just because they contain digits.

HEADING for report columns

HEADING gives a better column title when the field prints on a report. You can define it with the field or in the report section.

FILE PERSNL FB(150 1800)
     EMPNO       9   5 N HEADING 'EMPLOYEE NUMBER'
     PAY-NET    90   4 P 2 HEADING 'NET PAY'

Broadcom documents report-level heading syntax as the field name followed by heading literals in parentheses. Keep the field name outside the parentheses.

REPORT PAYRPT
    HEADING EMPNO ('EMPLOYEE' 'NUMBER')
    HEADING PAY-NET ('NET' 'PAY')
    LINE EMPNO PAY-NET

MASK for printed values

MASK controls how a value appears when it is printed. It is useful for commas, decimal points, signs, and leading zero suppression.

PAY-NET    90   4 P 2 HEADING 'NET PAY' MASK 'ZZZ,ZZ9.99'

Broadcom notes that MASK applies to fields printed through report output. It is not a general data conversion rule for every move to a non-printer file.

Working field definitions

You can also define working fields for calculations. These fields are not pulled directly from the input record position. They hold values created by the program.

DEFINE TAX-AMT    W  7 P 2
DEFINE NET-AFTER  W  7 P 2

JOB INPUT PERSNL
    TAX-AMT = PAY-NET * .20
    NET-AFTER = PAY-NET - TAX-AMT
    PRINT PAYRPT

Use working fields when a report needs a calculated value, a temporary total, or a reformatted copy of an input field.

Common mistakes

Using display length as storage length

A packed decimal amount may print as several characters but use fewer bytes in the record. Define the storage bytes, then use MASK for the printed look.

Defining identifiers as numeric quantities

A department code or employee number may contain only digits, but it is still an identifier. Avoid decimal positions and automatic totaling for identifier fields.

Putting the field name inside HEADING parentheses

For report-level headings, code HEADING EMPNO ('EMPLOYEE' 'NUMBER'). Coding HEADING (EMPNO 'EMPLOYEE') can produce a field-name expected error.

Copying a record layout without checking byte positions

A one-byte shift can damage every field after it. Check start position, length, and type against the copybook or file layout before using the field in production output.

Quick checklist

• Confirm the field starts at the correct byte position.
• Confirm the length is the storage length in bytes.
• Use A for text and identifiers that should not calculate.
• Use N, P, U, or B only when the field is truly numeric.
• Add decimal positions only when the value has implied cents, rates, quantities, or similar scale.
• Use HEADING for report column names.
• Use MASK for printed formatting, not as a substitute for the correct data type.

Related Easytrieve guides

For nearby topics, read Easytrieve Basic Reporting, Easytrieve Basic Report Edit Field Definition, Easytrieve Report Calculation, Easytrieve Basic Conditions, Easytrieve Sorting, and Easytrieve VSAM File Handling.

External references

Technical notes in this refresh were checked against Broadcom binary field guidance, Broadcom HEADING syntax guidance, Broadcom MASK parameter guidance, and Broadcom field heading notes.

FAQ

What are the required parts of an Easytrieve field definition?

The usual required parts are field name, start location, field length, and data type. Numeric fields can also include decimal positions.

What does the start location mean in Easytrieve?

The start location is the byte position where the field begins in the input record, counted from position 1.

When should I use HEADING in Easytrieve?

Use HEADING when the printed report needs a clearer column name than the field name.

What is MASK used for in Easytrieve?

MASK controls how a printed value appears, such as commas, decimal points, signs, and leading zero suppression.