Basic examples

Figure 2 shows a COBOL program, CLIENT1, that:

1. Uses PUT CONTAINER(container-name) CHANNEL(channel-name) commands to create
a channel called inqcustrec and add two containers, custno and branchno, to it;
these contain a customer number and a branch number, respectively.
2. Uses a LINK PROGRAM(program-name) CHANNEL(channel-name) command to link to
program SERVER1, passing the inqcustrec channel.
3. Uses a GET CONTAINER(container-name) CHANNEL(channel-name) command to
retrieve the customer record returned by SERVER1. The customer record is in the
custrec container of the inqcustrec channel.
Note that the same COBOL copybook, INQINTC, is used by both the client and server programs.
Line 3 and lines 5 through 7 of the copybook represent the INQUIRY-CHANNEL and its containers.
These lines are not strictly necessary to the working of the programs, because containers and
channels are created simply by being named (on, for example, PUT CONTAINER commands);
they do not have to be defined. However, the inclusion of these lines in the copybook used by both
programs makes for easier maintenance; they record the names of the containers used.
Figure 1. Copybook INQINTC
* copybook INQINTC
* Channel name
01 INQUIRY-CHANNEL PIC X(16) VALUE 'inqcustrec'.
* Container names
01 CUSTOMER-NO PIC X(16) VALUE 'custno'.
01 BRANCH-NO PIC X(16) VALUE 'branchno'.
01 CUSTOMER-RECORD PIC X(16) VALUE 'custrec'.
* Define the data fields used by the program
01 CUSTNO PIC X(8).
01 BRANCHNO PIC X(5).
01 CREC.
02 CUSTNAME PIC X(80).
02 CUSTADDR1 PIC X(80).
02 CUSTADDR2 PIC X(80).
02 CUSTADDR3 PIC X(80).

Recommendation
For ease of maintenance of a client/server application that uses a channel, create a copybook that
records the names of the containers used and defines the data fields that map to the containers.
Include the copybook in both the client and the server program.
Note: This example shows two COBOL programs. The same techniques can be used in any of the
other languages supported by CICS®. However, for COBOL programs only, if the server program
uses the SET option (instead of INTO) on the EXEC CICS GET CONTAINER command, the
structure of the storage pointed to by SET must be defined in the LINKAGE section of the
program. This means that you will require two copybooks rather than one. The first, in the
WORKING-STORAGE section of the program, names the channel and containers used. The
second, in the LINKAGE section, defines the storage structure.
Figure 2. A simple example of a program that creates a channel and passes it to a second
program
IDENTIFICATION DIVISION.
PROGRAM-ID. CLIENT1.

WORKING-STORAGE SECTION.

COPY INQINTC

PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.

*
* INITIALISE CUSTOMER RECORD
*
... CREATE CUSTNO and BRANCHNO
*
 * GET CUSTOMER RECORD
*
EXEC CICS PUT CONTAINER(CUSTOMER-NO) CHANNEL(INQUIRY-
CHANNEL)
FROM(CUSTNO) FLENGTH(LENGTH OF CUSTNO)
END-EXEC
EXEC CICS PUT CONTAINER(BRANCH-NO) CHANNEL(INQUIRY-CHANNEL)
FROM(BRANCHNO) FLENGTH(LENGTH OF BRANCHNO)
END-EXEC

EXEC CICS LINK PROGRAM('SERVER1') CHANNEL(INQUIRY-CHANNEL)

END-EXEC

EXEC CICS GET CONTAINER(CUSTOMER-RECORD) CHANNEL(INQUIRY-

CHANNEL)
INTO(CREC) END-EXEC

*
* PROCESS CUSTOMER RECORD
*
... FURTHER PROCESSING USING CUSTNAME and CUSTADDR1 etc...

EXEC CICS RETURN END-EXEC

EXIT.

Figure 3 shows the SERVER1 program linked to by CLIENT1. SERVER1 retrieves the data from the
custno and branchno containers it has been passed, and uses it to locate the full customer
record in its database. It then creates a new container, custrec, on the same channel, and
returns the customer record in it.

Note that the programmer hasn't specified the CHANNEL keyword on the GET and PUT commands
in SERVER1: if the channel isn't specified explicitly, the current channel is used—that is, the
channel that the program was invoked with.
Figure 3. A simple example of a linked to program that retrieves data from the channel it has been
passed. This program is linked-to by program CLIENT1 shown in Figure 2.
IDENTIFICATION DIVISION.
PROGRAM-ID. SERVER1.

WORKING-STORAGE SECTION.

COPY INQINTC

PROCEDURE DIVISION.
MAIN-PROCESSING SECTION.

EXEC CICS GET CONTAINER(CUSTOMER-NO)

INTO(CUSTNO) END-EXEC
EXEC CICS GET CONTAINER(BRANCH-NO)
INTO(BRANCHNO) END-EXEC

... USE CUSTNO AND BRANCHNO TO FIND CREC IN A DATABASE

EXEC CICS PUT CONTAINER(CUSTOMER-RECORD)

FROM(CREC)
FLENGTH(LENGTH OF CREC) END-EXEC

EXEC CICS RETURN END-EXEC

EXIT.