COBOL Pointers

In COBOL, a pointer is a data item that holds a memory address instead of a number or character string. You define it with USAGE POINTER and use SET to assign addresses or to make a structure refer to storage at a given address. Pointers are used when you receive an address from a caller (e.g. another program or an API), when working with dynamic storage, or when interfacing with code that passes addresses. This page gives an overview; for the exact verbs and syntax see Pointer Operations.

Explain Like I'm Five: What Is a Pointer?

A pointer is like a sticky note that says "the real data is over there"—it doesn't hold the data itself, it holds the location (address) of the data. When the program needs to use the data, it goes to that address. So a pointer variable doesn't contain a name or a number; it contains "where to find" the name or number.

Key Concepts

Defining and Using a Pointer

In the Data Division you define a pointer with USAGE POINTER and no PICTURE. You do not MOVE character or numeric data into it. You use SET to assign an address (e.g. from ADDRESS OF another item) or to make a LINKAGE SECTION structure refer to the address stored in the pointer. After SET ADDRESS OF your-structure TO pointer, any reference to your-structure accesses the data at that address.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
       WORKING-STORAGE SECTION.
       01 WS-DATA    PIC X(20).
 
       LINKAGE SECTION.
       01 LK-PTR     USAGE POINTER.
       01 LK-BUFFER.
          05 LK-TEXT  PIC X(20).
 
       PROCEDURE DIVISION USING LK-PTR.
       *> Caller passed an address in LK-PTR
           SET ADDRESS OF LK-BUFFER TO LK-PTR
           *> Now LK-TEXT refers to the storage at that address
           MOVE "Hello" TO LK-TEXT
           GOBACK.

When to Use Pointers

Use pointers when you receive an address from outside (e.g. a C or assembler program passes a pointer, or a CICS API returns one), when you need to associate a fixed layout (LINKAGE SECTION) with storage whose address is only known at runtime, or when your implementation supports dynamic allocation (ALLOCATE) and you need to refer to the allocated area. For simple COBOL-to-COBOL parameter passing, BY REFERENCE and the LINKAGE SECTION are usually enough without explicit pointer variables.

Pointers vs BY REFERENCE

With BY REFERENCE, the caller passes the address of a data item and the called program's LINKAGE SECTION name is bound to that address automatically. With a pointer, the caller might pass a single parameter that is an address (e.g. one pointer), and the called program uses SET ADDRESS OF structure TO that pointer so the structure overlays the storage at that address. So BY REFERENCE is one way to pass "the address of this item"; a pointer is an item that holds an address, which you can then use to set up addressability.

Step-by-Step: Receiving an Address and Using It

• Define a LINKAGE SECTION item with USAGE POINTER (and optionally the structure you want to overlay on that address).
• In PROCEDURE DIVISION USING, list the pointer (and any other parameters).
• Use SET ADDRESS OF your-structure TO pointer so the structure refers to the caller's storage.
• Read or update the structure as needed; then GOBACK. Check for NULL or invalid pointer if the environment can pass one.

Related Concepts