MainframeMaster
MainframeMaster

COBOL Tutorial

Progress0 of 0 lessons

COBOL LINAGE Clause

The LINAGE clause in COBOL is a powerful feature for controlling page formatting in printed reports. It defines the number of lines per page, designates areas for headings and footings, and enables automatic page overflow handling. Understanding LINAGE is essential for creating professional, well-formatted reports in mainframe COBOL applications.

What is the LINAGE Clause?

The LINAGE clause is specified in the File Description (FD) entry for files assigned to printers or report output devices. It defines the page layout structure, including the total number of lines per page, where footings begin, and how many lines are reserved at the top and bottom of each page. COBOL automatically manages page boundaries and provides the LINAGE-COUNTER special register to track the current line position.

Key benefits of using LINAGE:

  • Automatic Page Management: COBOL automatically handles page breaks when the page limit is reached
  • Consistent Formatting: Ensures uniform page layout across all pages in a report
  • Heading and Footing Control: Designates specific areas for headers and footers
  • Page Overflow Detection: Provides AT END-OF-PAGE clause to handle page boundaries
  • Line Position Tracking: LINAGE-COUNTER automatically tracks current line position

Basic LINAGE Syntax

The LINAGE clause is specified in the FILE SECTION within the FD entry for a report file:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT REPORT-FILE ASSIGN TO PRINTER
               ORGANIZATION IS SEQUENTIAL
               ACCESS MODE IS SEQUENTIAL
               FILE STATUS IS FILE-STATUS-CODE.
       
       DATA DIVISION.
       FILE SECTION.
       FD REPORT-FILE
           LINAGE IS 60 LINES
           WITH FOOTING AT 55
           LINES AT TOP 3
           LINES AT BOTTOM 3.
       01 REPORT-LINE PIC X(132).

In this example:

  • LINAGE IS 60 LINES: Defines 60 lines as the total page size
  • WITH FOOTING AT 55: Designates line 55 as where the footing area begins
  • LINES AT TOP 3: Reserves 3 lines at the top for headings
  • LINES AT BOTTOM 3: Reserves 3 lines at the bottom for footings

Understanding LINAGE Components

Total Lines Per Page

The total lines per page defines the maximum number of lines that can be written on a single page before automatic page overflow occurs. This is typically set based on the physical page size and printer capabilities.

cobol
1
2
3
4
5
6
7
8
       FD STANDARD-REPORT
           LINAGE IS 66 LINES.  *> Standard 11-inch page at 6 lines per inch
       
       FD COMPACT-REPORT
           LINAGE IS 50 LINES.  *> Compact format for shorter pages
       
       FD EXTENDED-REPORT
           LINAGE IS 80 LINES.  *> Extended format for longer pages

Footing Area

The footing area is where page footers are typically written. The WITH FOOTING AT clause specifies the line number where the footing area begins. Lines written at or after this position are considered in the footing area.

cobol
1
2
3
4
5
6
       FD REPORT-FILE
           LINAGE IS 60 LINES
           WITH FOOTING AT 55.
       
       *> Lines 1-54: Body of report
       *> Lines 55-60: Footing area (for page numbers, totals, etc.)

Top and Bottom Reserved Lines

The LINES AT TOP and LINES AT BOTTOM clauses reserve specific areas at the top and bottom of each page. These areas are typically used for page headers and footers that appear on every page.

cobol
1
2
3
4
5
6
7
8
9
10
11
       FD REPORT-FILE
           LINAGE IS 60 LINES
           WITH FOOTING AT 55
           LINES AT TOP 5      *> First 5 lines reserved for headers
           LINES AT BOTTOM 3.  *> Last 3 lines reserved for footers
       
       *> Page structure:
       *> Lines 1-5:   Header area (reserved)
       *> Lines 6-54:  Body area (available for detail lines)
       *> Lines 55-57: Footing area (reserved)
       *> Lines 58-60: Bottom reserved area

LINAGE-COUNTER Special Register

LINAGE-COUNTER is a special register automatically maintained by COBOL when a file has a LINAGE clause. It tracks the current line number on the current page, starting at 1 for each new page and incrementing with each WRITE statement.

Using LINAGE-COUNTER

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
       PROCEDURE DIVISION.
       WRITE-REPORT-LINE.
           WRITE REPORT-LINE FROM DETAIL-LINE
           
           *> Check current line position
           DISPLAY 'Current line: ' LINAGE-COUNTER OF REPORT-FILE
           
           *> Check if approaching page end
           IF LINAGE-COUNTER OF REPORT-FILE >= 50
               DISPLAY 'Approaching end of page'
           END-IF
           
           *> Check if in footing area
           IF LINAGE-COUNTER OF REPORT-FILE >= 55
               DISPLAY 'In footing area'
           END-IF.

LINAGE-COUNTER characteristics:

  • Automatic Management: COBOL automatically increments LINAGE-COUNTER with each WRITE
  • Page Reset: Resets to 1 when a new page begins
  • Read-Only: You cannot directly modify LINAGE-COUNTER
  • File-Specific: Each file with LINAGE has its own LINAGE-COUNTER
  • Reference Syntax: Use LINAGE-COUNTER OF file-name to reference it

Page Overflow Handling

When the page limit is reached, COBOL automatically triggers page overflow. You can handle this using the AT END-OF-PAGE clause in WRITE statements to perform actions when a page is full.

Basic Page Overflow

cobol
1
2
3
4
5
6
7
8
9
10
11
12
       PROCEDURE DIVISION.
       WRITE-DETAIL-LINE.
           WRITE REPORT-LINE FROM DETAIL-LINE
               AT END-OF-PAGE
                   PERFORM HANDLE-PAGE-OVERFLOW
           END-WRITE.
       
       HANDLE-PAGE-OVERFLOW.
           ADD 1 TO PAGE-NUMBER
           DISPLAY 'Page overflow - starting page ' PAGE-NUMBER
           PERFORM WRITE-PAGE-HEADER
           PERFORM WRITE-PAGE-FOOTER.

Automatic Page Break

When LINAGE-COUNTER reaches the footing line or exceeds the page limit, COBOL automatically starts a new page. The AT END-OF-PAGE clause executes before the new page begins, allowing you to write footers and prepare for the next page.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
       PROCEDURE DIVISION.
       PROCESS-RECORDS.
           PERFORM UNTIL END-OF-FILE
               READ INPUT-FILE
                   AT END
                       SET END-OF-FILE TO TRUE
                   NOT AT END
                       PERFORM WRITE-DETAIL-LINE
               END-READ
           END-PERFORM.
       
       WRITE-DETAIL-LINE.
           WRITE REPORT-LINE FROM DETAIL-LINE
               AT END-OF-PAGE
                   *> Write footer for completed page
                   PERFORM WRITE-PAGE-FOOTER
                   *> Start new page with header
                   ADD 1 TO PAGE-NUMBER
                   PERFORM WRITE-PAGE-HEADER
           END-WRITE.

Complete LINAGE Example

Here's a comprehensive example demonstrating LINAGE usage in a complete report program:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
       IDENTIFICATION DIVISION.
       PROGRAM-ID. LINAGE-EXAMPLE.
       AUTHOR. MAINFRAME MASTER.
       
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
           SELECT EMPLOYEE-FILE ASSIGN TO EMPFILE
               ORGANIZATION IS SEQUENTIAL
               ACCESS MODE IS SEQUENTIAL
               FILE STATUS IS EMP-FILE-STATUS.
           
           SELECT REPORT-FILE ASSIGN TO PRINTER
               ORGANIZATION IS SEQUENTIAL
               ACCESS MODE IS SEQUENTIAL
               FILE STATUS IS RPT-FILE-STATUS.
       
       DATA DIVISION.
       FILE SECTION.
       FD EMPLOYEE-FILE
           RECORD CONTAINS 80 CHARACTERS.
       01 EMPLOYEE-RECORD PIC X(80).
       
       FD REPORT-FILE
           LINAGE IS 60 LINES
           WITH FOOTING AT 55
           LINES AT TOP 5
           LINES AT BOTTOM 3.
       01 REPORT-LINE PIC X(132).
       
       WORKING-STORAGE SECTION.
       01 FILE-STATUS-FIELDS.
           05 EMP-FILE-STATUS PIC XX.
           05 RPT-FILE-STATUS PIC XX.
       
       01 PAGE-CONTROL.
           05 PAGE-NUMBER PIC 9(4) VALUE 1.
           05 LINES-WRITTEN PIC 9(3) VALUE 0.
       
       01 REPORT-HEADERS.
           05 PAGE-HEADER-1.
              10 FILLER PIC X(50) VALUE SPACES.
              10 FILLER PIC X(20) VALUE 'EMPLOYEE REPORT'.
              10 FILLER PIC X(10) VALUE SPACES.
              10 FILLER PIC X(5) VALUE 'PAGE '.
              10 PAGE-NUM-DISP PIC Z(3)9.
              10 FILLER PIC X(44) VALUE SPACES.
           
           05 COLUMN-HEADER.
              10 FILLER PIC X(5) VALUE 'ID   '.
              10 FILLER PIC X(30) VALUE 'EMPLOYEE NAME'.
              10 FILLER PIC X(15) VALUE 'DEPARTMENT'.
              10 FILLER PIC X(12) VALUE 'SALARY'.
              10 FILLER PIC X(70) VALUE SPACES.
           
           05 UNDERLINE-HEADER PIC X(132) VALUE ALL '-'.
       
       01 DETAIL-LINE.
           05 DET-EMP-ID PIC 9(6).
           05 FILLER PIC X(4) VALUE SPACES.
           05 DET-EMP-NAME PIC X(30).
           05 FILLER PIC X(3) VALUE SPACES.
           05 DET-EMP-DEPT PIC X(15).
           05 FILLER PIC X(3) VALUE SPACES.
           05 DET-EMP-SALARY PIC $,$$$,$$9.99.
           05 FILLER PIC X(70) VALUE SPACES.
       
       01 PAGE-FOOTER.
           05 FILLER PIC X(60) VALUE SPACES.
           05 FILLER PIC X(6) VALUE 'PAGE: '.
           05 FOOTER-PAGE-NUM PIC Z(3)9.
           05 FILLER PIC X(63) VALUE SPACES.
       
       01 END-OF-FILE-FLAG PIC X VALUE 'N'.
           88 END-OF-FILE VALUE 'Y'.
       
       PROCEDURE DIVISION.
       MAIN-PROCESSING.
           OPEN INPUT EMPLOYEE-FILE
           OPEN OUTPUT REPORT-FILE
           
           IF RPT-FILE-STATUS NOT = '00'
               DISPLAY 'Error opening report file: ' RPT-FILE-STATUS
               STOP RUN
           END-IF
           
           PERFORM WRITE-PAGE-HEADER
           PERFORM PROCESS-EMPLOYEES
           PERFORM WRITE-PAGE-FOOTER
           
           CLOSE EMPLOYEE-FILE
           CLOSE REPORT-FILE
           
           STOP RUN.
       
       WRITE-PAGE-HEADER.
           *> Write header lines
           MOVE PAGE-NUMBER TO PAGE-NUM-DISP
           WRITE REPORT-LINE FROM PAGE-HEADER-1
           WRITE REPORT-LINE FROM SPACES
           WRITE REPORT-LINE FROM COLUMN-HEADER
           WRITE REPORT-LINE FROM UNDERLINE-HEADER
           WRITE REPORT-LINE FROM SPACES
           
           *> Reset line counter tracking
           MOVE 5 TO LINES-WRITTEN.
       
       PROCESS-EMPLOYEES.
           PERFORM UNTIL END-OF-FILE
               READ EMPLOYEE-FILE
                   AT END
                       SET END-OF-FILE TO TRUE
                   NOT AT END
                       PERFORM WRITE-EMPLOYEE-DETAIL
               END-READ
           END-PERFORM.
       
       WRITE-EMPLOYEE-DETAIL.
           *> Parse employee record (simplified)
           MOVE EMPLOYEE-RECORD(1:6) TO DET-EMP-ID
           MOVE EMPLOYEE-RECORD(7:30) TO DET-EMP-NAME
           MOVE EMPLOYEE-RECORD(37:15) TO DET-EMP-DEPT
           MOVE EMPLOYEE-RECORD(52:8) TO DET-EMP-SALARY
           
           *> Write detail line with page overflow handling
           WRITE REPORT-LINE FROM DETAIL-LINE
               AT END-OF-PAGE
                   PERFORM HANDLE-PAGE-OVERFLOW
           END-WRITE
           
           ADD 1 TO LINES-WRITTEN.
       
       HANDLE-PAGE-OVERFLOW.
           *> Write footer for completed page
           PERFORM WRITE-PAGE-FOOTER
           
           *> Start new page
           ADD 1 TO PAGE-NUMBER
           PERFORM WRITE-PAGE-HEADER
           
           DISPLAY 'Page overflow - new page started: ' PAGE-NUMBER.
       
       WRITE-PAGE-FOOTER.
           *> Position at footing area if not already there
           PERFORM UNTIL LINAGE-COUNTER OF REPORT-FILE >= 55
               WRITE REPORT-LINE FROM SPACES
           END-PERFORM
           
           *> Write page number in footer
           MOVE PAGE-NUMBER TO FOOTER-PAGE-NUM
           WRITE REPORT-LINE FROM PAGE-FOOTER.

This example demonstrates:

  • LINAGE definition: 60 lines per page with footing at line 55
  • Page headers: Written at the start of each page
  • Detail lines: Written with automatic page overflow detection
  • Page footers: Written when page overflow occurs or at end of report
  • LINAGE-COUNTER usage: Used to position footers correctly

LINAGE Best Practices

1. Choose Appropriate Page Sizes

Select page sizes based on your printer capabilities and report requirements. Standard sizes include:

  • 66 lines: Standard 11-inch paper at 6 lines per inch
  • 60 lines: Common business report format
  • 50 lines: Compact format for shorter reports
  • 80 lines: Extended format for detailed listings

2. Reserve Adequate Space for Headers and Footers

Always reserve enough lines at the top and bottom for headers and footers. Typical allocations:

cobol
1
2
3
4
5
6
7
8
       *> Standard report format
       FD REPORT-FILE
           LINAGE IS 60 LINES
           WITH FOOTING AT 55
           LINES AT TOP 5      *> 5 lines for headers
           LINES AT BOTTOM 3.  *> 3 lines for footers
       
       *> Available for detail: 60 - 5 - 3 = 52 lines

3. Use AT END-OF-PAGE for Page Breaks

Always use the AT END-OF-PAGE clause to handle page boundaries gracefully:

cobol
1
2
3
4
5
6
       WRITE REPORT-LINE FROM DETAIL-LINE
           AT END-OF-PAGE
               PERFORM WRITE-PAGE-FOOTER
               ADD 1 TO PAGE-NUMBER
               PERFORM WRITE-PAGE-HEADER
       END-WRITE.

4. Check LINAGE-COUNTER for Positioning

Use LINAGE-COUNTER to check current position and make decisions about spacing and formatting:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
       *> Check if in header area
       IF LINAGE-COUNTER OF REPORT-FILE <= 5
           *> Still in header area
       END-IF
       
       *> Check if approaching page end
       IF LINAGE-COUNTER OF REPORT-FILE >= 50
           *> Near end of page, prepare for overflow
       END-IF
       
       *> Check if in footing area
       IF LINAGE-COUNTER OF REPORT-FILE >= 55
           *> In footing area, write footer information
       END-IF.

5. Handle First Page Separately

The first page may need special handling since LINAGE-COUNTER starts at 1. Ensure headers are written correctly on the first page:

cobol
1
2
3
4
5
6
7
8
9
10
       PROCEDURE DIVISION.
       INITIALIZE-REPORT.
           MOVE 1 TO PAGE-NUMBER
           PERFORM WRITE-PAGE-HEADER.
       
       WRITE-PAGE-HEADER.
           *> Always write header at start of page
           MOVE PAGE-NUMBER TO PAGE-NUM-DISP
           WRITE REPORT-LINE FROM PAGE-HEADER-1
           *> ... write other header lines ...

Common LINAGE Patterns

Pattern 1: Simple Report with Headers and Footers

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
       FD SIMPLE-REPORT
           LINAGE IS 60 LINES
           WITH FOOTING AT 55.
       
       PROCEDURE DIVISION.
       WRITE-DETAIL.
           WRITE REPORT-LINE FROM DETAIL-LINE
               AT END-OF-PAGE
                   PERFORM NEW-PAGE
           END-WRITE.
       
       NEW-PAGE.
           ADD 1 TO PAGE-NUMBER
           PERFORM WRITE-HEADER.

Pattern 2: Multi-Section Report

cobol
1
2
3
4
5
6
7
8
9
       PROCEDURE DIVISION.
       WRITE-SECTION-HEADER.
           *> Check if enough space for section
           IF LINAGE-COUNTER OF REPORT-FILE > 45
               PERFORM NEW-PAGE
           END-IF
           
           WRITE REPORT-LINE FROM SECTION-HEADER
           WRITE REPORT-LINE FROM SPACES.

Pattern 3: Conditional Page Breaks

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
       PROCEDURE DIVISION.
       WRITE-DETAIL-WITH-BREAK.
           *> Force page break before important sections
           IF CONTROL-BREAK OR SECTION-START
               IF LINAGE-COUNTER OF REPORT-FILE > 10
                   PERFORM NEW-PAGE
               END-IF
           END-IF
           
           WRITE REPORT-LINE FROM DETAIL-LINE
               AT END-OF-PAGE
                   PERFORM HANDLE-OVERFLOW
           END-WRITE.

LINAGE vs Manual Page Control

While you can manually control pages using line counters and page breaks, LINAGE provides automatic management:

AspectWith LINAGEManual Control
Page OverflowAutomatic detection and handlingMust manually check line counts
Line TrackingLINAGE-COUNTER automatically maintainedMust manually increment counters
Page BreaksAutomatic with AT END-OF-PAGEMust use AFTER ADVANCING PAGE
Footing AreaAutomatically defined and trackedMust manually calculate positions
Code ComplexitySimpler, less code requiredMore complex, more code required

Summary

The LINAGE clause is an essential feature for professional report formatting in COBOL. Key points to remember:

  • LINAGE defines page structure: Total lines, footing position, and reserved areas
  • LINAGE-COUNTER tracks position: Automatically maintained special register for current line
  • AT END-OF-PAGE handles overflow: Execute code when page limit is reached
  • Automatic page management: COBOL handles page breaks automatically
  • Reserve space appropriately: Allocate adequate lines for headers and footers
  • Use LINAGE-COUNTER for decisions: Check position for conditional formatting
  • Handle first page correctly: Ensure proper initialization and header writing

Proper use of LINAGE results in well-formatted, professional reports with consistent page layouts and automatic page management.

Test Your Knowledge

1. What is the primary purpose of the LINAGE clause in COBOL?

  • To define file organization
  • To control page formatting and line management in printed reports
  • To specify record lengths
  • To define file access modes

2. What does LINAGE-COUNTER track?

  • The total number of pages written
  • The current line number on the current page
  • The total number of lines written
  • The file status code

3. What happens when LINAGE-COUNTER reaches the footing line?

  • The program stops
  • Nothing happens automatically
  • COBOL automatically triggers page overflow and the AT END-OF-PAGE clause executes
  • The footing area is cleared

4. What is the purpose of the WITH FOOTING AT clause?

  • To define the total page size
  • To specify the line number where the footing area begins
  • To reserve lines at the top of the page
  • To define record length

5. How do you reference LINAGE-COUNTER for a specific file?

  • LINAGE-COUNTER
  • LINAGE-COUNTER OF file-name
  • file-name.LINAGE-COUNTER
  • LINAGE-COUNTER(file-name)

Related Concepts

COBOL Report Writer

Learn about COBOL Report Writer feature for structured report generation with automatic page control

COBOL Page Control

Understanding page control techniques, page breaks, and page formatting in COBOL reports

COBOL Advancing

Learn about AFTER ADVANCING and BEFORE ADVANCING clauses for line positioning

COBOL Output Formatting

Understanding output formatting techniques and report generation in COBOL

Related Pages