Easytrieve Library Section

Role of the Library Section

Broadcom places FILE and DEFINE in the Library section because data description is separate from processing logic. The compiler reads Library first to build symbol tables, then validates JOB and REPORT statements against those symbols. When you type EMPNAME in an IF statement, the compiler checks length, type, and file association defined here. Operations staff can read Library alone to learn which files a program touches and how records are structured without parsing every IF block.

The FILE Statement

A FILE statement names a file and describes its records. The name must match the DD name used in execute JCL unless site conventions map them differently. After the FILE header, each line defines one field: name, starting position, length, type, and optional decimal positions for numeric types. Positions are usually one-based within the record, matching mainframe copybook conventions beginners learn from COBOL or PL/I layouts.

1
2
3
4
5
FILE PERSNL FB(150 1800)
  EMPNO    1   5   N
  EMPNAME  6   8   A
  DEPT    14   3   A
  GROSS   40   7   P 2

PERSNL is the logical file name. FB(150 1800) describes fixed-block organization with record length 150 and block size 1800—values must match the actual dataset DCB. EMPNO starts at byte 1 for length 5 with type N (numeric display/zoned depending on context). EMPNAME is 8 bytes of alphanumeric A. GROSS is 7 bytes packed decimal P with 2 decimal places, so report masks can show 9999999.99 style output.

Common FILE Field Types

Choosing the wrong type is a common source of runtime abends. If GROSS is actually zoned decimal in the file but you code P, arithmetic may corrupt data or raise data exceptions. When in doubt, compare against a known good copybook, file sample, or data dictionary from the data owner—not guesswork from report appearance alone.

The DEFINE Statement

DEFINE creates working storage fields not mapped to a file position. Counters, switch flags, accumulated totals before writing extract files, and temporary hold areas belong here. DEFINE fields follow similar type rules but live in program memory rather than on incoming records.

1
2
3
DEFINE COUNT       N  5
DEFINE WS-TOTAL     P  9 2
DEFINE ERR-FLAG     A  1

COUNT holds a numeric counter. WS-TOTAL is packed with two decimals for money aggregation. ERR-FLAG is a one-byte alphanumeric switch. JOB logic can MOVE values into these fields, add to WS-TOTAL, or SET ERR-FLAG when validation fails. Because they are not in FILE layouts, they never appear in FILE INPUT buffer unless you explicitly MOVE them to output records.

Qualified Field Names

When two files contain similarly named fields, qualify references with the file name to remove ambiguity. Broadcom documents qualified field syntax so DEPT in one file does not collide with DEPT in another. Even when names differ, qualification improves readability in multi-file programs where auditors trace which file supplied a value on a report line.

Macros and Reusable Layouts

Production shops rarely hand-type fifty-field FILE statements in every program. Macros, COPY members, or %include patterns expand standard layouts into Library. When a macro library is missing at compile time, you may see cascades of undefined field errors that clear once STEPLIB or SYSLIB includes the macro source. Treat macro expansion as part of Library maintenance: one corrected layout fixes every program that includes it.

Efficient Definitions

Broadcom recommends coding definitions to avoid unnecessary conversions. If a field is packed in the file, define it packed rather than defining alphanumeric and converting on every arithmetic operation. If you only need a substring, consider whether a smaller defined field or masked reference meets the need without copying entire records into working storage. These choices affect CPU on million-row jobs more than they affect tiny classroom examples.

Library and JCL Relationship

Library names files logically; JCL DD statements connect those names to physical data sets at execute time. A perfect Library with missing PERSNL DD still fails at runtime. Conversely, correct JCL cannot fix wrong start positions—records will read, but fields will show garbage. Developers and operations share responsibility: Library accuracy and DD allocation must align.

Validation Checklist

1. Record length in FILE matches DCB and copybook documentation.
2. Field start plus length minus one does not exceed record size.
3. Types match actual storage in the physical file.
4. All field names are unique or properly qualified.
5. Output files include every field JOB logic writes.
6. Macro libraries are available in compile JCL when used.

Common Library Mistakes

• Off-by-one start positions after copybook conversion from COBOL picture clauses.
• Duplicate field names across two FILE statements without qualification.
• Using DEFINE for fields that actually exist on the record—FILE is the right choice.
• Ignoring decimal positions on packed amounts, causing scaled report errors.
• Defining fields only in REPORT lines instead of Library—compile errors result.

Explain It Like I'm Five

The Library section is like the legend on a treasure map. It says where each clue sits on the page—employee number starts here, name starts there, pay amount is in this box. The JOB section is the walk you take to follow the map. If the legend is wrong, you dig in the wrong place even if you follow directions perfectly. FILE and DEFINE keep the legend accurate.

Exercises

1. Write a FILE statement for a 80-byte record with employee ID, name, and salary fields.
2. Add three DEFINE fields for count, total, and error flag with appropriate types.
3. Explain the difference between type N and type P for a money field.
4. List five validation checks before promoting a Library change to production.
5. Describe how a missing macro library manifests at compile time.