COBOL LINKAGE SECTION

The LINKAGE SECTION is where you describe data that is passed into your program by the caller. It does not allocate storage; it defines the layout of parameters (or communication areas) so that when the program is called with CALL ... USING, those arguments map to the names you define. You can pass by reference (the caller's storage is shared) or by content (a copy is made). This page explains how to define the LINKAGE SECTION and how it ties to the PROCEDURE DIVISION USING clause.

Explain Like I'm Five: What Is the LINKAGE SECTION?

When someone calls your program, they can hand you pieces of data. The LINKAGE SECTION is your list of "what I expect to receive." You do not create that data yourself; the caller provides it. So you only describe the shape (length and type) of each piece. If the caller says "here is a number and here is a name," your LINKAGE SECTION says "first item is a number, second is a name," in the same order.

Why No VALUE in LINKAGE SECTION?

The LINKAGE SECTION describes storage that belongs to the caller (or is a copy created by the system). Your program does not own that storage, so you cannot assign initial values to it with VALUE. The values come from the caller. If you need to initialize or modify data without affecting the caller, move the linkage item to Working-Storage and work there.

Defining the LINKAGE SECTION

You write LINKAGE SECTION. in the Data Division, then define one or more 01-level (or other level) entries with the same layout as the parameters the caller passes. The first parameter in the caller's USING list corresponds to the first linkage item, the second to the second, and so on. Use PICTURE clauses to define length and type; do not use VALUE.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       *> ... working data ...
 
       LINKAGE SECTION.
       01 LK-CUSTOMER-ID    PIC X(8).
       01 LK-ORDER-AMOUNT   PIC 9(7)V99.
       01 LK-RETURN-CODE    PIC 9(2).
 
       PROCEDURE DIVISION
           USING LK-CUSTOMER-ID LK-ORDER-AMOUNT LK-RETURN-CODE.
       *> Caller passes three arguments; they map to these three names
       MAIN.
           MOVE 0 TO LK-RETURN-CODE
           *> ... process LK-CUSTOMER-ID and LK-ORDER-AMOUNT ...
           GOBACK.

BY REFERENCE and BY CONTENT

In the PROCEDURE DIVISION USING clause you can specify BY REFERENCE or BY CONTENT for each parameter. If you omit them, the default is usually BY REFERENCE. The caller can also specify BY REFERENCE or BY CONTENT on the CALL statement; the passing mechanism determines whether the called program sees the same storage or a copy.

1
2
3
4
5
6
7
8
       *> Called program: receive one by reference, one by content
       PROCEDURE DIVISION
           USING BY REFERENCE LK-IN-OUT
                 BY CONTENT LK-INPUT-ONLY.
 
       *> Caller: pass first by reference (can be changed), second by content (copy)
       CALL "SUBPGM" USING BY REFERENCE WS-DATA
                          BY CONTENT WS-VALUE.

Matching Caller and Called Program

The number and order of parameters in CALL ... USING must match the number and order in PROCEDURE DIVISION USING. The lengths and types (e.g. PIC X(8), PIC 9(5)V99) should match so that both sides interpret the data the same way. Using a shared copybook for the linkage layout in both the caller and the called program helps avoid mismatches.

Step-by-Step: Using the LINKAGE SECTION

• Add LINKAGE SECTION in the Data Division and define one entry per parameter, in the same order as the caller will pass them.
• Use PICTURE (and level numbers) to match the caller's layout; do not use VALUE.
• In PROCEDURE DIVISION, write USING and list the linkage names (and optionally BY REFERENCE/BY CONTENT).
• In the program, reference the linkage names like any other data items; for BY REFERENCE, changes are visible to the caller.

Related Concepts