COBOL Pointer Operations

In COBOL, a pointer is a data item that holds a memory address. You define it with USAGE POINTER, and you use SET ADDRESS OF and ADDRESS OF to connect data structures to that address or to pass addresses to other programs. Pointer operations are used when you receive an address from a caller (e.g. CICS, another program), when you use callable services that pass pointers, or when you work with based storage. This page explains how to define and use pointers and how they relate to BY REFERENCE and ADDRESS OF.

Explain Like I'm Five: Pointers

A pointer is like a slip of paper that says "the data you want is in box number 42." The number (address) does not tell you what is inside the box; it just tells you where to look. In COBOL, you put that "box number" into a pointer variable. Then you say: "from now on, when I use this structure name, use the data in that box." That is SET ADDRESS OF structure TO pointer. After that, reading or writing the structure reads or writes the data at that address.

Defining a Pointer

A pointer is defined with USAGE POINTER. It has no PICTURE clause. It is usually in the LINKAGE SECTION when the program receives an address from a caller, or in WORKING-STORAGE when you hold an address for later use (check your compiler for support).

1
2
3
4
5
6
7
8
9
10
11
12
       LINKAGE SECTION.
       01  IN-PTR           USAGE POINTER.
       01  RECORD-AREA.
           05  REC-KEY      PIC X(10).
           05  REC-DATA     PIC X(70).
       
       PROCEDURE DIVISION USING IN-PTR.
           *> Make RECORD-AREA refer to the storage at IN-PTR
           SET ADDRESS OF RECORD-AREA TO IN-PTR
           *> Now REC-KEY and REC-DATA access that storage
           MOVE 'VALUE' TO REC-KEY
           GOBACK.

SET ADDRESS OF

SET ADDRESS OF data-name TO pointer-variable makes data-name refer to the memory location stored in the pointer. The data-name must be a valid data item (often a group or elementary in LINKAGE SECTION). After the SET, any MOVE to or from data-name, or any reference to its subfields, uses that storage. This is how you "attach" your layout to an address passed from outside.

ADDRESS OF

ADDRESS OF identifier is an expression that represents the address of that identifier. You use it in SET to put the address into a pointer (SET ptr TO ADDRESS OF my-item), or in CALL to pass the address to another program: CALL 'subprog' USING BY REFERENCE ADDRESS OF my-item. The called program can then receive it as a pointer and use SET ADDRESS OF ... TO that pointer to access the data.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
       *> Caller: pass address of WS-BUFFER to subprogram
       WORKING-STORAGE SECTION.
       01  WS-BUFFER        PIC X(80).
       
       PROCEDURE DIVISION.
           MOVE 'DATA' TO WS-BUFFER
           CALL 'SUBPROG' USING BY REFERENCE ADDRESS OF WS-BUFFER
           ...
       
       *> Called program: receive pointer, attach structure
       LINKAGE SECTION.
       01  IN-PTR            USAGE POINTER.
       01  BUFFER-AREA       PIC X(80).
       
       PROCEDURE DIVISION USING IN-PTR.
           SET ADDRESS OF BUFFER-AREA TO IN-PTR
           *> BUFFER-AREA now refers to caller's WS-BUFFER
           DISPLAY BUFFER-AREA
           GOBACK.

Pointers and LINKAGE SECTION

When a program is called with an address (e.g. BY REFERENCE ADDRESS OF x), the runtime passes that address. If the called program declares the parameter as USAGE POINTER, it receives the address in that pointer. It can then SET ADDRESS OF a structure TO that pointer so the structure overlays the caller's data. The structure in LINKAGE SECTION does not allocate new storage; it just describes the layout of the storage at the address.

When to Use Pointers

• APIs or environments (e.g. CICS) that pass a pointer to a communication area or buffer.
• Calling a program and passing the address of a large area so the called program can read or update it without copying.
• Working with based storage (ADDRESS OF a based item) or callable sort/other services that use addresses.

Step-by-Step: Using a Pointer Passed from a Caller

• In the called program, define a LINKAGE SECTION item with USAGE POINTER (e.g. 01 PTR USAGE POINTER) and list it in PROCEDURE DIVISION USING.
• Define a structure (group or elementary) that matches the layout of the data at that address.
• At the start of the procedure, execute SET ADDRESS OF structure TO PTR.
• Use the structure and its subfields normally; they now refer to the caller's storage.

Best Practices

• Ensure the structure you attach with SET ADDRESS OF matches the layout and length of the data at that address; otherwise you may corrupt memory or read garbage.
• Do not use the pointer or the structure after the referenced storage might have been freed or invalidated.
• Document when a parameter is a pointer and what layout the program expects at that address.

Related Concepts