Pointers and Dynamic Storage

A pointer data item contains a storage address and nothing else. It has no PICTURE, belongs to no class or category, is not numeric and is not a conditional variable. You declare it with USAGE POINTER (the word USAGE IS is optional), and you give it its initial value with VALUE NULL, because NULL is the only value a VALUE clause may give a pointer. NULL (or NULLS) is a figurative constant that means "an invalid address, pointing nowhere".

Enterprise COBOL lists the places a pointer may appear: ALLOCATE, FREE, format 5 of SET, a relation condition, and the USING phrase of CALL, ENTRY and the PROCEDURE DIVISION header. A pointer can have GLOBAL, EXTERNAL, OCCURS and VOLATILE, but never JUSTIFIED, PICTURE or BLANK WHEN ZERO, and it is ignored by CORRESPONDING. It can be written to a file, but the address read back later is not meaningful, so never store pointers in records.

A pointer is as wide as an address. On the 64-bit GnuCOBOL build used here LENGTH OF a pointer is 8 bytes; in Enterprise COBOL it is 4 bytes with LP(32) (the default) and 8 bytes with LP(64), which is why a copybook that holds pointers can change size between compilations (see POINTER-32 and AMODE 64).

ADDRESS OF is a special register, implicitly USAGE POINTER, that exists for every data item. It has two roles:

Because a LINKAGE SECTION item allocates no storage, its description is a template that you can lay over any address. After SET ADDRESS OF BOOK-RECORD TO ptr, a reference to BOOK-ID reads the first six bytes at the address in ptr. The special register ADDRESS OF item can also be tested: for an item that has not been based yet, or has been released with FREE, it compares equal to NULL, which is the reliable way to ask whether the item is currently addressable.

Everything so far used storage that the compiler had already reserved. ALLOCATE asks the run-time system for more, and FREE gives it back. The ALLOCATE statement has two forms:

FREE ptr releases the block that ptr points to. If the allocation could not be satisfied, the receiving pointer (or the based item’s address) is set to NULL, so check it.

The two compilers differ about which items the by-item form accepts, and this is the main portability point of the page.

IBM also uses ALLOCATE and FREE to resize an OCCURS 1 TO UNBOUNDED table (see Tables and OCCURS).

A chained list is the classic reason for pointers: each node holds a pointer to the next, the last node holds NULL, and the list grows one ALLOCATE at a time without any fixed upper limit. IBM’s Programming Guide uses the same pattern, ending the walk when the next pointer is NULL.

The program reads the day’s transactions (LOANTRAN, record LOANREC), appends a node for each checkout (O) at the tail, lists the chain, then frees every node. LOAN-NODE is a LINKAGE item that is re-based on each node in turn; it is only ever a window onto one node at a time. The program needs -std=ibm because it uses ALLOCATE by item on a LINKAGE item (the Enterprise COBOL form).

Three details carry the correctness. First, the NODE-NEXT of a new node is set to NULL explicitly before the node is linked, because the end of the list is recognised by that value. Second, FREE-NODES copies NODE-NEXT into WS-NEXT before FREE, because reading the node afterwards is reading freed storage. Third, the tail pointer makes appending one step instead of a walk of the whole chain. The three return-record transactions (R) are skipped by the IF LOAN-CHECKOUT, so only the three checkouts are chained. A real nightly update would normally use a keyed table or an indexed file instead (see Searching and Sorting Tables); the list is the right tool when order of arrival matters and the volume is unknown.

Source: Enterprise COBOL 6.5 Programming Guide, "Using pointers to process a chained list" and "Example: using pointers to process a chained list"

Each program in this section is deliberately wrong. The compile-time errors are the real cobc 3.2.0 text.

The two run-time mistakes do not stop the compiler at all. A BASED item used before ALLOCATE:

compiles cleanly with cobc -x -Wall, and when run it dies (exit status 139) with:

The same happens when a second program uses the item after FREE FINE-WORK (the second wrong example, BAD2). Compiled with -debug, which turns on run-time checks, the failure is diagnosed at the statement instead:

The GnuCOBOL manual describes the result of referencing unallocated or freed storage as unpredictable; here it is a crash, but on a different platform, or when the storage has been reused by the allocator, it can be silent corruption instead. Habits that prevent it: test ADDRESS OF item = NULL (or the pointer) before using a based item, set every pointer to NULL explicitly after FREE if copies of it exist, and build test runs with -debug. Storage overlays and invalid addresses on z/OS are found with the techniques covered in Debugging and Troubleshooting.

Source: GnuCOBOL Programmer’s Guide, BASED and ALLOCATE and GnuCOBOL Manual, compiler options

A program pointer holds the address of an entry point instead of a data item. Two usages exist, both set with format 6 of SET:

SET ptr TO ENTRY literal-or-identifier sets the pointer; SET ptr TO NULL clears it; CALL ptr USING ... calls through it. The target must be the outermost program of a compilation unit (a nested program cannot be the target on z/OS), and the name is affected by the PGMNAME compiler option. The reason to use a program pointer instead of CALL identifier is to look the program up once and call it many times, to hold a table of programs, or to receive a callback address from another language.

In the example below, the main program selects the fine rule by name (adult or children’s rate), resolves it into a procedure pointer, and calls through the pointer. The two rules are separate outermost programs in the same source file.

On z/OS the same source needs the programs available at run time under those names (compiled together in one batch compilation as here, or as separate load modules found by the Language Environment search). IBM’s own example makes the same point with SET FP TO ENTRY "subp1" followed by CALL FP.

GnuCOBOL 3.2.0 implements PROCEDURE-POINTER as a synonym of its PROGRAM-POINTER usage, but does not implement FUNCTION-POINTER or, as the next section shows, POINTER-32. This program, which uses both on purpose, produces the real messages:

With -std=ibm the second message becomes 'POINTER-32' is a reserved word, but isn't supported. The first message is misleading: cobc reads FUNCTION-POINTER as the start of an intrinsic-function reference and reports a syntax error where it expects a function name. In GnuCOBOL, use PROCEDURE-POINTER (or PROGRAM-POINTER) for the same job; to call a C function through its address, call it by name and let the linker resolve it, as in the C example below.

Source: Enterprise COBOL 6.5 Language Reference: SET statement (format 6) and Language Reference, "PROCEDURE-POINTER phrase" and "FUNCTION-POINTER phrase"

By default Enterprise COBOL generates AMODE 31 code (LP(32)), in which every address is 4 bytes. Since Enterprise COBOL 6.3 the LP(64) compiler option generates AMODE 64 code that can use storage above the 2 GB bar. The effect on this page’s topics:

POINTER-32 exists so that a copybook shared between LP(32) and LP(64) programs, or a record layout that a 31-bit program must also read, keeps the same size. The Programming Guide adds that PROCEDURE-POINTER items are 8 bytes whatever the LP setting, unlike FUNCTION-POINTER items. A POINTER can be set from a POINTER-32 (the high-order word is cleared), and the reverse is a programming error if the 64-bit value does not fit in 32 bits. The two can be compared in a relation condition, and they are synonyms under LP(32).

Other consequences of LP(64) that matter to this page: the ALLOCATE LOC 64 phrase is only valid under LP(64), LOC 24 and LOC 31 ask for storage below the line and below the bar, and a diagnostic is issued when the combination is impossible (for example LOC 64 with LP(32)). Language Environment does not support mixing AMODE 64 and AMODE 31 programs in one application, AMODE 64 programs cannot run in CICS or IMS, and an LP(64) program cannot contain GO TO or ALTER, among other restrictions listed with the option. Compiling and binding AMODE 64 programs is a Language Environment and binder topic; see Compiling, Linking and Language Environment.

GnuCOBOL has no POINTER-32. On a 64-bit build its USAGE POINTER is 8 bytes (shown above), on a 32-bit build 4 bytes, and the diagnostics for POINTER-32 are shown in the previous section.

Source: Enterprise COBOL 6.5 Programming Guide: LP compiler option and Programming Guide, "Pointer data items with AMODE 64 programs"

A dynamic-length elementary item is a data item whose logical length changes at run time, from zero up to a limit, with storage managed by the run time. It was added by the COBOL 2014 standard and by Enterprise COBOL 6.3 (z/OS; not run here: GnuCOBOL 3.2 has no DYNAMIC LENGTH). It is the COBOL answer to a string that has no sensible fixed size, such as a free-text note on a loan record.

The clause is DYNAMIC [LENGTH] [LIMIT [IS] integer] on an elementary item whose PICTURE is a single X (class alphanumeric) or a single U (class UTF-8). Without LIMIT the maximum is 999999999 characters (bytes for U) or whatever memory permits; characters beyond the limit are truncated on the right at a character boundary.

This fragment (z/OS; not run here) shows the rules that follow. After the MOVE, the length of LOAN-NOTE is that of the sender (22), and LENGTH OF LOAN-NOTE is the current byte length, not the limit. SET LENGTH OF LOAN-NOTE TO 7 is format 8 of SET: the receiver must be a dynamic-length elementary item and the sender a numeric integer item or integer literal of zero or more. A value below the current length truncates on the right; a value above it extends the item without padding or initialising the new positions, which are therefore undefined until you move data in. A negative value sets the length to zero.

Summary of the rules in Enterprise COBOL 6.5:

GnuCOBOL 3.2.0 rejects the clause and the SET. Compiling this program (deliberately wrong for that compiler):

gives the real messages:

The nearest GnuCOBOL feature is ANY LENGTH on a LINKAGE SECTION item, which lets a subprogram accept an alphanumeric argument of any size and ask for its length with FUNCTION LENGTH. It does not let the item change length, but it covers the common use "this subprogram takes a text of unknown size". In Enterprise COBOL, ANY LENGTH does not exist; use a dynamic-length parameter or pass the length explicitly.

Strings and dynamic items are used together in Strings: STRING, UNSTRING and INSPECT, and UTF-8 items (PIC U) are explained in National, UTF-8 and Code Pages.

Source: Enterprise COBOL 6.5 Language Reference, "DYNAMIC LENGTH clause", "Dynamic-length items" and "Format 8: SET for length of dynamic-length elementary items"

Most Circulation programs never touch an address. The cases that do:

For the Java and Python side of the same boundary, which uses the Java Native Interface and ctypes rather than raw addresses, see Interoperability with C, Java and Python.

The general advice is to reach for a pointer only when the language gives no named way to do the job, to keep the ALLOCATE and the FREE in the same program where possible, to set freed pointers to NULL, and to wrap the pointer logic in one small subprogram so the rest of the application never sees an address.