CICS Storage Control: GETMAIN, FREEMAIN, and DSA Management Guide

Introduction: How CICS Manages Memory

Every COBOL program that runs in CICS — whether it does a READ, a SEND MAP, or a simple calculation — exists in memory. CICS manages this memory through the Dynamic Storage Area (DSA), a pool of virtual storage carved into sub-areas for different purposes. Understanding how CICS storage is structured, how programs get and release storage, and how storage violations occur is critical knowledge for writing reliable CICS programs and for diagnosing production storage problems.

Most CICS COBOL developers never need to explicitly call GETMAIN or FREEMAIN — CICS handles task storage automatically. But understanding what is happening beneath the surface explains why certain patterns (large WORKING-STORAGE, deep LINK chains, forgotten SHARED allocations) can lead to region-wide storage exhaustion.

The CICS Storage Architecture

Below the 16 MB Line

When CICS was designed, 24-bit addressing limited storage to 16 MB. Legacy CICS programs and data still reside below the line:

CDSA (CICS Dynamic Storage Area): CICS system storage — nucleus, system control blocks, CSA (Common System Area). Managed entirely by CICS; application programs should never allocate here.

UDSA (User Dynamic Storage Area): Application task storage. Each task's WORKING-STORAGE is allocated here when the task starts. Most CICS COBOL programs that run in user key (the default) have their WORKING-STORAGE in UDSA.

Above the 16 MB Line (31-bit)

ECDSA (Extended CDSA): Extended CICS system storage above the 16 MB line. CICS nucleus objects that support 31-bit addressing live here.

EUDSA (Extended UDSA): Extended user task storage. Modern COBOL programs compiled with DATA(31) use EUDSA for WORKING-STORAGE, freeing up limited below-the-line storage.

Above the Bar (64-bit)

GCDSA / GUDSA: 64-bit storage areas introduced in CICS TS 4.1 for very large data buffers. Accessed via 64-bit pointer techniques in assembler or high-level language programs compiled with 64-bit support.

Storage Keys

CICS storage is divided by protection key:

• CICS key (key 8): Protected CICS storage. Application programs cannot overwrite it without a storage violation trap.
• User key (key 9): Application storage. Programs running in user key can read and write their own key-9 storage.

The key distinction matters for storage violations: a program writing outside its own storage boundaries will either hit CICS-key storage (trapped immediately, ASRA) or another task's user-key storage (corrupts that task's data, detected later or not at all — these are the hardest bugs to diagnose).

EXEC CICS GETMAIN: Allocating Dynamic Storage

GETMAIN allocates a block of storage from the CICS DSA. The most common use is allocating a buffer of variable length at runtime:

WORKING-STORAGE SECTION.
01  WS-BUFFER-PTR    USAGE IS POINTER.
01  WS-BUFFER-LEN    PIC S9(8) COMP VALUE +0.

LINKAGE SECTION.
01  LK-BUFFER        PIC X(32767).

PROCEDURE DIVISION.
ALLOCATE-BUFFER.
    COMPUTE WS-BUFFER-LEN = WS-RECORD-COUNT * 80

    EXEC CICS GETMAIN
              SET(WS-BUFFER-PTR)
              FLENGTH(WS-BUFFER-LEN)
              INITIMG(LOW-VALUES)
              RESP(WS-RESP)
    END-EXEC

    IF WS-RESP NOT = DFHRESP(NORMAL)
        MOVE 'GETMAIN FAILED - INSUFFICIENT STORAGE.' TO WS-ERR-MSG
        PERFORM LOG-ERROR
        GO TO END-PROGRAM
    END-IF

    *── Address the allocated storage via LINKAGE SECTION ────────
    SET ADDRESS OF LK-BUFFER TO WS-BUFFER-PTR

    *── Use the buffer ───────────────────────────────────────────
    PERFORM BUILD-BUFFER-CONTENT.

GETMAIN Options

Task Storage vs SHARED Storage

Task storage (no SHARED option): automatically freed when the task ends. Used for temporary buffers within a task.

SHARED storage: persists after task termination and can be passed between tasks via a pointer held in a CICS-managed area (such as the CSA or a global userdata area). Must be explicitly freed:

*── Allocate shared buffer ───────────────────────────────────────
EXEC CICS GETMAIN
          SET(WS-SHARED-PTR)
          FLENGTH(WS-SHARED-LEN)
          SHARED
          INITIMG(SPACES)
          RESP(WS-RESP)
END-EXEC.

*── Later, when done with shared buffer ──────────────────────────
EXEC CICS FREEMAIN
          DATA(WS-SHARED-AREA)
          RESP(WS-RESP)
END-EXEC.

EXEC CICS FREEMAIN: Releasing Dynamic Storage

FREEMAIN releases storage that was previously allocated with GETMAIN. For task storage, FREEMAIN before task end is optional (CICS cleans up automatically). For SHARED storage, FREEMAIN is mandatory:

RELEASE-BUFFER.
    IF WS-BUFFER-PTR NOT = NULL
        EXEC CICS FREEMAIN
                  DATA(LK-BUFFER)
                  RESP(WS-RESP)
        END-EXEC
        SET WS-BUFFER-PTR TO NULL
    END-IF.

Note: FREEMAIN uses the DATA option pointing to the storage area itself (via the LINKAGE SECTION alias), not the pointer variable. Alternatively, use the PTR option with a pointer:

EXEC CICS FREEMAIN PTR(WS-BUFFER-PTR) RESP(WS-RESP) END-EXEC.

Working Storage vs GETMAIN: When to Use Each

Most CICS COBOL programs should use WORKING-STORAGE for all data needs. Here is the decision framework:

Use WORKING-STORAGE when:

• Storage size is known at compile time
• Storage is only needed for the current task invocation
• You want CICS to manage allocation and cleanup automatically

Use GETMAIN when:

• Storage size depends on runtime data (e.g., number of records × record size)
• Storage must persist beyond the current task (SHARED)
• You need to pass a large data area by pointer to another program via LINK
• You are writing a CICS exit or system-level module requiring specific storage keys

Never use GETMAIN for: small fixed-size buffers, COMMAREA structures, map areas — WORKING-STORAGE handles these efficiently without programmer involvement.

Storage Violations: Causes, Detection, and Prevention

Storage violations are among the most damaging CICS bugs because they corrupt other programs' data without immediately ABENDing the offending program. The corruption may not be detected until much later, making root cause diagnosis extremely difficult.

Common Causes of Storage Violations

MOVE overflow: Moving a value longer than the target field's PIC size. In COBOL, this silently truncates in some cases and overwrites adjacent storage in others (depending on optimisation and alignment).

*── DANGER: If WS-INPUT is longer than WS-TARGET, overflow ──────
01  WS-TARGET  PIC X(10).
01  WS-PADDING PIC X(5) VALUE 'CICS\!'. *> Will be overwritten

MOVE WS-INPUT(1:15) TO WS-TARGET.   *> OVERFLOW if WS-INPUT > 10

Invalid pointer: Setting ADDRESS OF LK-AREA to a null or uninitialised pointer, then accessing LK-AREA.

*── DANGER: pointer not initialised ─────────────────────────────
01  WS-PTR USAGE IS POINTER.   *> Value is garbage at start
*── ... (forgot to GETMAIN) ...
SET ADDRESS OF LK-DATA TO WS-PTR.  *> LK-DATA now points to garbage
MOVE 'DATA' TO LK-DATA.            *> WRITES TO RANDOM STORAGE

Array bounds exceeded: Accessing an OCCURS table beyond its defined limit.

*── DANGER: index goes beyond OCCURS 10 ─────────────────────────
01  WS-TABLE OCCURS 10 TIMES PIC X(8).
MOVE 'OVERFLOW' TO WS-TABLE(11).    *> Writes into adjacent storage

CICS Storage Violation Detection

CICS provides several mechanisms to detect violations:

Storage cushions: CICS places a check pattern above and below allocated storage areas. If a program overwrites these patterns, CICS detects the violation on the next storage operation and generates a storage check message in the CICS job log.

Storage isolation: When CICS storage isolation (STGPROT=YES) is active, each task's storage is protected with hardware storage keys. A write to another task's storage generates an immediate ASRA program check rather than silent corruption.

SDUMP analysis: CICS storage violation dumps include storage layout maps that show which task owned the corrupted area.

Preventing Storage Violations

Use STRING and MOVE CORRESPONDING carefully, always verify OCCURS subscripts are within bounds before use, initialise all pointers before dereferencing, and enable CICS STGPROT=YES in non-production regions to detect violations immediately.

Storage Shortage: A2xx ABENDs and DSA Tuning

When the CICS DSA fills up, tasks cannot allocate storage and ABEND with codes like:

These are usually caused by: too many concurrent tasks (increase MAXACTIVE task limit), very large WORKING-STORAGE programs (refactor or move storage to ECDSA), or SHARED storage leaks (audit GETMAIN SHARED without corresponding FREEMAIN).

Monitor DSA utilisation with CICS CEMT INQUIRE DSAS or the CICS monitoring facility to catch trends before storage exhaustion occurs in production.

Key Takeaways

CICS storage control operates largely transparently for application COBOL programs — CICS allocates WORKING-STORAGE automatically and frees it at task end. GETMAIN and FREEMAIN are needed only for variable-length buffers, SHARED persistent storage, or system-level modules. Storage violations are the most dangerous class of CICS bugs, causing silent data corruption that is difficult to diagnose. Always initialise pointers before use, check EIBCALEN before accessing DFHCOMMAREA, and keep OCCURS subscripts within bounds to avoid them. Enable STGPROT=YES in test environments to convert silent corruption into immediate ASRA ABENDs.

To learn how CICS manages named in-memory queues for task-to-task communication, continue with CICS Temporary Storage Queues. For the complete CICS course, visit the CICS Mastery Course.