COBOL Parameter Passing

When one COBOL program calls another with CALL ... USING, it must choose how each argument is passed: by reference, by content, or by value. That choice determines whether the called program shares the same storage as the caller or works on a copy, and whether the caller sees any changes the subprogram makes. This page explains the three mechanisms, how they differ, when to use each, and how the LINKAGE SECTION in the called program must match.

Explain Like I'm Five: What Is Parameter Passing?

When you ask a friend to do a task, you might hand them the actual thing (e.g. your notebook) or a copy (e.g. a photocopy). If you hand the real notebook, whatever they write in it is in your notebook too. If you hand a copy, they can scribble on the copy and your original stays the same. Parameter passing in COBOL is like that: BY REFERENCE means the subprogram gets the "real" data (same storage), so changes show up in the caller. BY CONTENT and BY VALUE mean the subprogram gets a copy, so the caller's data does not change no matter what the subprogram does.

The Three Passing Mechanisms

COBOL defines three ways to pass data in the USING phrase of the CALL statement. You can mix them in one CALL: some arguments BY REFERENCE, others BY CONTENT, others BY VALUE. The called program declares the parameters in its LINKAGE SECTION and in PROCEDURE DIVISION USING in the same order. The passing mechanism affects both what the subprogram can do and whether the caller sees updates.

BY REFERENCE (Default)

With BY REFERENCE, the calling program passes the address of the argument. The subprogram does not get a copy; it uses the same storage as the caller. So when the subprogram moves a value into the parameter or modifies it in any way, the change is visible in the calling program as soon as the subprogram returns. If you do not specify BY REFERENCE, BY CONTENT, or BY VALUE for a parameter, BY REFERENCE is assumed. Use BY REFERENCE when the subprogram is meant to update the argument (output or input-output), or when you want to avoid copying large structures. You cannot pass a literal BY REFERENCE because a literal has no address.

1
2
3
4
5
6
7
8
9
10
       *> Caller
       01 WS-AMOUNT  PIC 9(7)V99.
       01 WS-TAX     PIC 9(7)V99.
 
       MOVE 1000.00 TO WS-AMOUNT
       CALL 'CALCTAX' USING WS-AMOUNT, WS-TAX
       *> After return, WS-TAX has been set by CALCTAX (BY REFERENCE)
 
       *> Explicit form (same as default):
       CALL 'CALCTAX' USING BY REFERENCE WS-AMOUNT, BY REFERENCE WS-TAX

In the called program, the LINKAGE SECTION items LNK-AMOUNT and LNK-TAX map to WS-AMOUNT and WS-TAX. A MOVE to LNK-TAX in the subprogram updates the caller's WS-TAX.

BY CONTENT

With BY CONTENT, the calling program passes a copy of the value of the argument. The subprogram receives that copy in its parameter (still defined in LINKAGE SECTION). The subprogram can read and even modify its parameter, but any modification affects only the copy. The caller's original data is never changed. BY CONTENT is useful when you want to pass input-only data that the subprogram must not alter, or when you need to pass a literal (e.g. BY CONTENT "YES" or BY CONTENT 0). Passing BY CONTENT can involve copying data, so for very large items some implementations may still pass an address of a temporary copy; either way, the semantic guarantee is that the caller's data is not modified.

1
2
3
4
5
6
       *> Caller: pass a literal and a copy of a variable
       CALL 'VALIDATE' USING BY CONTENT 'ACTIVE', BY CONTENT WS-CODE
 
       *> In VALIDATE, changing the parameter does not change WS-CODE
       *> LINKAGE SECTION in called program still defines the parameters
       *> but they refer to temporary copies, not the caller's storage

Some compilers support BY CONTENT LENGTH OF identifier to pass the length of a data item (e.g. from the LENGTH special register). That way the subprogram receives both the data (e.g. BY REFERENCE) and a copy of its length (BY CONTENT), which is useful for variable-length or buffer handling.

BY VALUE

With BY VALUE, the value of the argument is passed rather than a reference. The subprogram receives a temporary copy; it can change that copy but the caller's argument is never affected. Semantics can be implementation-dependent. BY VALUE is commonly used when calling non-COBOL programs (e.g. C or C++) that use pass-by-value linkage conventions. It is also valid for passing small values or literals when you do not want the subprogram to modify the caller's data. On some platforms, BY VALUE ADDRESS OF identifier is used to pass a pointer to a C/C++ routine that expects a pointer argument.

1
2
3
4
       *> Caller: pass a numeric literal and a small integer
       CALL 'C-ROUTINE' USING BY VALUE 1, BY VALUE WS-FLAG
 
       *> Subprogram receives copies; changing them does not change WS-FLAG

If you call C or C++ code, check your compiler documentation for how BY VALUE and BY VALUE ADDRESS OF are represented (e.g. in registers or on the stack) so they match the foreign routine's expectations.

Mixing Mechanisms in One CALL

You can specify a different mechanism for each argument. The order of arguments in the CALL must match the order of parameters in the called program's PROCEDURE DIVISION USING and LINKAGE SECTION. The mechanism does not change the order or the number of parameters.

1
2
3
4
5
6
7
8
       CALL 'ERRPROC'
           USING BY REFERENCE WS-BUFFER
                 BY CONTENT LENGTH OF WS-BUFFER
                 BY CONTENT 'ERROR'
 
       *> ERRPROC gets: 1) reference to WS-BUFFER (can update it)
       *>                2) copy of the length (cannot change caller's LENGTH)
       *>                3) copy of the literal 'ERROR'

LINKAGE SECTION and Parameter Order

The called program must define every parameter it receives in the LINKAGE SECTION. Each 01- or 77-level item corresponds to one argument in the CALL, in the same order. The LINKAGE SECTION does not allocate storage; it describes the layout of the data that the caller passed. So the first LINKAGE item maps to the first USING argument, the second to the second, and so on. The PICTURE (and length) of each linkage item should match the caller's argument to avoid misinterpretation of data. If the caller passes BY REFERENCE, the linkage item describes the shared storage; if BY CONTENT or BY VALUE, the linkage item typically describes the temporary copy provided by the system.

1
2
3
4
5
6
7
8
9
10
11
12
       *> Called program ERRPROC
       DATA DIVISION.
       LINKAGE SECTION.
       01 LNK-BUFFER    PIC X(100).
       01 LNK-LEN       PIC 9(4).
       01 LNK-MESSAGE   PIC X(5).
 
       PROCEDURE DIVISION
           USING LNK-BUFFER, LNK-LEN, LNK-MESSAGE.
       MAIN.
           *> Use LNK-BUFFER, LNK-LEN, LNK-MESSAGE in order
           GOBACK.

Some compilers allow you to specify the passing mechanism in the called program as well (e.g. PROCEDURE DIVISION USING BY REFERENCE LNK-BUFFER BY CONTENT LNK-LEN). When specified, it should match the caller; when omitted, the default BY REFERENCE applies. Check your compiler manual.

Passing Literals and LENGTH OF

Literals (numeric or alphanumeric) have no storage address in the caller, so they cannot be passed BY REFERENCE. Use BY CONTENT or BY VALUE. For example, BY CONTENT "ACTIVE" or BY VALUE 0 passes a copy of the literal. The LENGTH OF special register (on compilers that support it) gives the length in bytes of a data item. To pass that length to a subprogram, use BY CONTENT LENGTH OF identifier so the subprogram receives a copy of the length value. That is useful when the subprogram needs to know how long a buffer is without modifying the caller's data.

RETURNING and Parameter Passing

The CALL statement can include RETURNING identifier so the caller receives a single return value from the subprogram. RETURNING is separate from USING: USING passes arguments in and out (depending on mechanism); RETURNING is the function-style result. The subprogram sets the return value (in the item named in PROCEDURE DIVISION ... RETURNING) before executing GOBACK or EXIT PROGRAM, and that value is copied back to the caller's RETURNING identifier. So the subprogram can return one value via RETURNING and optionally modify multiple arguments via BY REFERENCE parameters.

Comparison: When Each Mechanism Affects the Caller

• BY REFERENCE: Subprogram reads and writes the same storage as the caller. All changes are visible to the caller. Use for output or input-output parameters.
• BY CONTENT: Caller passes a copy. Subprogram can change its copy; caller's data is unchanged. Use for input-only data or literals.
• BY VALUE: Value (copy) is passed. Subprogram gets a temporary copy; caller's data is unchanged. Use for literals, small values, or C/C++ interop.

Step-by-Step: Choosing the Right Mechanism

1. Identify each parameter: is it input-only, output-only, or both? Must the caller see changes?
2. For output or input-output: use BY REFERENCE (or omit; it is the default).
3. For input-only or literals: use BY CONTENT or BY VALUE so the caller's data cannot be changed.
4. When calling C/C++ or other non-COBOL code: follow the foreign routine's convention (often BY VALUE for scalars, BY VALUE ADDRESS OF for pointers).
5. In the called program, define each parameter in the LINKAGE SECTION and list them in PROCEDURE DIVISION USING in the same order as the CALL.

Step-by-Step: Implementing a Subprogram with Mixed Parameters

1. In the called program's DATA DIVISION, add a LINKAGE SECTION. Define one 01 (or 77) per parameter, with PICTURE and length matching the caller. Order must match the CALL.
2. Write PROCEDURE DIVISION USING param1, param2, ... in the same order. Do not allocate or initialize linkage items; they are provided by the caller (or by the system for BY CONTENT/BY VALUE copies).
3. Use the parameters in your logic. Remember: only BY REFERENCE parameters allow the caller to see changes; BY CONTENT and BY VALUE parameters are copies.
4. Return with GOBACK (or EXIT PROGRAM). If using RETURNING, set the return value before returning.

Common Pitfalls

• Passing a literal with BY REFERENCE: not allowed; use BY CONTENT or BY VALUE.
• Assuming the caller sees changes when you passed BY CONTENT or BY VALUE: they do not; only BY REFERENCE shares storage.
• Mismatched order or type between CALL and LINKAGE SECTION: wrong data or abends. Keep order and definitions in sync.
• Using STOP RUN in a subprogram: that can end the whole run unit. Use GOBACK or EXIT PROGRAM to return to the caller.

Best Practices

• Document each parameter as input, output, or input-output and which passing mechanism you use.
• Prefer BY CONTENT or BY VALUE for input-only data so the subprogram cannot accidentally change the caller's data.
• Use BY REFERENCE for large structures when you need to avoid copying, and when the subprogram is designed to update the argument.
• Keep LINKAGE SECTION definitions aligned with the caller (same order, compatible PICTURE and length).

Test Your Knowledge