CICS Container Management

Containers are CICS objects that hold data and are used for passing information between programs, transactions, and across CICS regions. They provide a modern, flexible alternative to traditional COMMAREA data passing.

What are CICS Containers?

A container is a named data object that exists within a channel. Containers can hold any type of data - character, binary, or structured - and can be much larger than the 32KB limit of COMMARea. Multiple containers can exist on a single channel, allowing complex data structures to be passed between programs.

Containers vs. COMMAREA

Traditional COMMAREA

The COMMAREA (Communication Area) is limited to 32,767 bytes and can only pass a single data structure between programs. It's defined in the EXEC CICS LINK or XCTL command.

Modern Containers

Containers overcome COMMAREA limitations by allowing:

• Multiple data items on one channel
• Data sizes up to 16MB (or larger with 64-bit addressing)
• Named data items for easier identification
• Different data types in different containers
• Optional containers (not all need to be present)

Container Operations

Creating Containers

Use the PUT CONTAINER command to create a new container or update an existing one:

1
2
3
4
5
EXEC CICS PUT CONTAINER('CUSTOMER-DATA')
    FROM(WS-CUSTOMER-RECORD)
    FLENGTH(LENGTH OF WS-CUSTOMER-RECORD)
    CHANNEL('ORDER-CHANNEL')
END-EXEC.

Retrieving Container Data

Use the GET CONTAINER command to retrieve data from a container:

1
2
3
4
5
EXEC CICS GET CONTAINER('CUSTOMER-DATA')
    INTO(WS-CUSTOMER-RECORD)
    FLENGTH(WS-DATA-LENGTH)
    CHANNEL('ORDER-CHANNEL')
END-EXEC.

Deleting Containers

Remove containers when they're no longer needed:

1
2
3
EXEC CICS DELETE CONTAINER('TEMP-DATA')
    CHANNEL('WORK-CHANNEL')
END-EXEC.

Channels

A channel is a collection of related containers. Channels provide a context for containers and can be passed between programs just like a COMMAREA.

Current Channel

When a program is invoked with a channel, that channel becomes the current channel. You don't need to specify the channel name in container commands if you're working with the current channel.

Creating Channels

Channels are created implicitly when you put the first container or explicitly using:

1
2
EXEC CICS GET CHANNEL('MY-CHANNEL')
END-EXEC.

Container Browsing

You can browse through all containers on a channel to discover what data is available:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
EXEC CICS STARTBROWSE CONTAINER
    BROWSETOKEN(WS-BROWSE-TOKEN)
    CHANNEL('ORDER-CHANNEL')
END-EXEC.
 
PERFORM UNTIL WS-END-OF-CONTAINERS
    EXEC CICS GETNEXT CONTAINER(WS-CONTAINER-NAME)
        BROWSETOKEN(WS-BROWSE-TOKEN)
        RESP(WS-RESPONSE)
    END-EXEC
    
    IF WS-RESPONSE = DFHRESP(END)
        SET WS-END-OF-CONTAINERS TO TRUE
    ELSE
        PERFORM PROCESS-CONTAINER
    END-IF
END-PERFORM.
 
EXEC CICS ENDBROWSE CONTAINER
    BROWSETOKEN(WS-BROWSE-TOKEN)
END-EXEC.

Best Practices

1. Use Meaningful Names

Give containers descriptive names that indicate their purpose. Use a consistent naming convention across your applications.

2. Document Container Structures

Maintain documentation of what containers are used, their data structures, and which programs create or consume them.

3. Check for Container Existence

Before accessing a container, check if it exists to avoid errors:

1
2
3
4
5
6
7
8
9
EXEC CICS GET CONTAINER('OPTIONAL-DATA')
    INTO(WS-DATA)
    RESP(WS-RESPONSE)
END-EXEC.
 
IF WS-RESPONSE = DFHRESP(CONTAINERERR)
    * Container doesn't exist - use default values
    PERFORM SET-DEFAULT-VALUES
END-IF.

4. Clean Up Temporary Containers

Delete containers that are no longer needed to free up storage, especially in long-running transactions.

5. Consider Data Size

While containers can be very large, consider the performance impact of moving large amounts of data between programs. Use appropriate data sizes for your application needs.

Container Scope

Task Lifetime

Containers exist for the lifetime of the task (transaction) unless explicitly deleted. When the task ends, all containers are automatically deleted.

Program Boundaries

Containers can be passed between programs using LINK or XCTL commands. The channel containing the containers is passed as part of the program invocation.

BTS Containers

Business Transaction Services (BTS) provides persistent containers that can survive beyond task termination and be accessed across different activities and processes.

Error Handling

Common container-related errors and how to handle them:

CONTAINERERR

Returned when trying to access a container that doesn't exist. Check for this condition when working with optional containers.

LENGERR

Returned when the target area is too small for the container data. Determine the required length first using the FLENGTH option without specifying INTO.

CHANNELERR

Returned when the specified channel doesn't exist. Ensure the channel was created before accessing its containers.

Advanced Features

64-bit Containers

Use PUT CONTAINER64 and GET CONTAINER64 commands for containers larger than 16MB, taking advantage of 64-bit addressing capabilities.

Container Data Types

Specify DATATYPE(CHAR) or DATATYPE(BIT) to indicate the type of data in a container, which can affect how the data is converted when sent across systems with different codepages.

Container Conversion

CICS can automatically convert character data between different codepages when containers are passed between systems. Use FROMCCSID and TOCCSID options to control conversion.