N o v .

2 3

CICS Channel and Containers

CICS Channels & Containers

Differentiation between Standards and Guidelines
Standards are Mandatory within all stated areas, whilst guidelines are good advice or best practice that it would be advantageous to do. The Industry practice is to put these together as they cannot sensibly be divided into two documents. This format has been in place for many years, and works well in a standard where the text is dense. For other platforms, and Insurance applications, the document should be treated as a guideline throughout. Note that this distinction cannot be propagated into the table of contents, because in many cases both mandatory and recommended practices fall under the same heading.

N o v . 2 1. 3 1.1

CICS Channel and Containers

Introduction to CICS Channels & Containers

What are Channels & Containers? Introduced in CTS 3.1, Channels & Containers are a method of passing data from one CICS program to another CICS program. They are in effect a replacement for COMMAREAs but with one major difference; the size of the data passed is not restricted to a 32k limit. Channels can contain none, one or several containers. The only restriction on the numbers of channels & containers is the amount of dynamic storage available within the CICS region. Individual instances of Channels & Containers can only be referenced (at least from an Application perspective) by those programs which have either created CHANNELs or have been presented with a CHANNEL. Once CICS establishes that an individual instance of a Channel & its Containers can no longer be referenced (i.e. by an active task) then it will automatically delete them. With this in mind please do not attempt to employ Channels as you would a Temporary Storage Queue (TSQ). As with COMMAREAs, Channels & Containers are not recoverable.

1.2

When should I use Channels & Containers? Channels & containers should be deployed in new applications and functions as an alternative to COMMAREAs. To establish whether you should use Channels & Containers refer to the scenarios detailed below.
Scenario New Application New function within an existing application. Guidance Channels & Containers should be deployed in the new programs. The new programs should be invoked through commands which include CHANNELs (i.e. opposed to COMMAREAs). Existing COMMAREA based APIs, Gateways and other CICS programs invoked by the new programs can still be passed as COMMAREAs. Whether Channels & Containers are deployed clearly depends on the number of programs which will be amended and the nature of the changes. If the changes involve significant changes to COMMAREAs or the nature of the communication between the programs then the COMMAREAs should be replaced with CHANNELs and CHANNEL handling logic introduced. Note do not simply replace the existing COMMAREA with a single CONTAINER. Ensure that the data elements are split into request and return elements. Do not try and enhance the existing programs to receive both CHANNELs and COMMAREAs. Consider carefully the boundary of change so the deployment of CHANNELs does not create a domino effect of change through the whole application. Any deployment of CHANNELs will have the maximum benefit (i.e. in terms of reduction in network traffic) where the communication is cross-region, i.e. via DPLs. Do not enhance to use Channels & Containers. The changes will require changes to other programs to pass or receive Channels.

Major enhancement to an existing function, changes either restricted to existing programs and/or require the development of new program modules..

An amendment to an existing program which currently uses COMMAREAs. Change taking place in isolation and is not associated with other large amendments in the Application.

N o v . 1.3 2 3

CICS Channel and Containers

Why should I use Channels & Containers? In addition to the removal of the 32k limit there are additional benefits associated with deployments using Channel & Containers. Unlike COMMAREAs, (which can be described as monolithic blocks of data), Channels can contain a number of Containers. Hence the data can be passed in a more structured and controlled manner. Data can be logically divided into distinct sub-sets, i.e. containers for request data, containers for returned data, containers for images etc. Channels & Containers support loose coupling. Programs only need to refer to and use the Containers within a channel which they are interested in. Containers can be moved from one CHANNEL to another CHANNEL, hence ensuring that application programs do not have to refer to elementary data elements. CICS automatically deletes Channels when they can no longer be referenced. This means that once finished with, the dynamic storage is released and becomes available to other CICS tasks. In the case of DPLs, network traffic is reduced as CICS will purely transfer the contents of Containers that have either been created or have been amended. Unlike COMMAREAs, programs dont need to know the size of the data being passed. Where appropriate they can use the NODATA option to establish the size of individual containers. This is particularly useful when dealing with larger objects, such as Images.

N o v . 2 2. 3 2.1

CICS Channel and Containers

Elementary Deployment within Applications

Invoking programs using Channels Channels can be used in any of the existing CICS commands listed below. On the left is a command using traditional COMMAREAs whilst on the right is the equivalent command using a Channel. Note, CHANNELs can not be used in External CICS Interfaces (EXCI) or External Call Interfaces (ECI).

CICS Command using COMMAREA option XCTL PROGRAM (WS-PROGA) COMMAREA (WS-COMMAREA-A) LENGTH (LENGTH OF WS-COMMAREA-A) LINK PROGRAM (WS-PROGB) COMMAREA (WS-COMMAREA-B) LENGTH (LENGTH OF WS-COMMAREA-B) RETURN TRANSID (WS-TRANS-C) COMMAREA (WS-COMMAREA-C) LENGTH (LENGTH OF WS-COMMAREA-B) START TRANSID (WS-TRAN-ID-D) FROM (WS-DATA-AREA) LENGTH (LENGTH OF WS-DATA-AREA)

CICS Command using CHANNEL option XCTL PROGRAM (WS-PROGA) CHANNEL (WS-CHANNEL-A)

LINK PROGRAM (WS-PROGB) CHANNEL (WS-CHANNEL-B)

RETURN TRANSID (WS-TRANS-C) CHANNEL (WS-CHANNEL-C)

START TRANSID (WS-TRAN-ID-D) CHANNEL(WS-CHANNEL-D)

INVOKE WEBSERVICE (WS-WEB-SERVICE) CHANNEL (WS-CHANNEL-E) 1 OPERATION (WC-OPER-X)

Where a program is invoked using any of the commands above then it may receive either a COMMAREA or a CHANNEL, it may not receive both in a single invocation. 2.2 Referencing Containers The table below provides a summary of the common commands that can be used to reference Containers within Channels. CICS Command GET CONTAINER Description This will return the contents of the Container, or a pointer to the data; the NODATA option can be used to just determine the length of the data in the Container This will place data into a Container, overwriting any existing data. Where the PUT refers to a new Container or Channel, CICS will create them. This will delete a Container in the Channel specified. (If not specified, then the current Channel.) This will move a Container from one Channel to another Channel, optionally Non normal RESP code(s)
CHANNELERR INVREQ CONTAINERERR LENGERR CCSIDERR CHANNELERR INVREQ CONTAINERERR LENGERR CCSIDERR CHANNELERR INVREQ CONTAINERERR CHANNELERR INVREQ CONTAINERERR

PUT CONTAINER

DELETE CONTAINER MOVE CONTAINER

1

Invoke WebService is only available with the CHANNEL option and is used where CICS is the requestor (i.e. not supplier) of the Web service.

N o v . 2 3

CICS Channel and Containers

CICS Command Rename

Description assigning it a new name. Although there is no specific command for renaming containers this can still be achieved through the MOVE CONTAINER command with no TOCHANNEL specified.

Non normal RESP code(s)

CHANNELERR INVREQ CONTAINERERR

In addition to the commands listed above, the following commands can also be used to browse through the CONTAINERS within a CHANNEL. CICS Command STARTBROWSE CONTAINER Description This starts a browse through the containers within a Channel. It returns a Browse Token that subsequent Browse commands (GETNEXT CONTAINER, ENDBROWSE CONTAINER) must use. This command returns the names of the containers (note: not the contents) for a given Browse Token, in no particular order. Ends a browse. The Browse Token is no longer valid. Non normal RESP code(s)
CHANNELERR IOERR NOTAUTH ACTIVITYERR PROCESSERR

GETNEXT CONTAINER

END ILLOGIC TOKENERR ILLOGIC TOKENERR

ENDBROWSE CONTAINER

Do not rely on the order of CONTAINERs returned by the BROWSE & GETNEXT commands detailed above. The actual order of the CONTAINERs returned can change depending on how the program has been invoked (i.e. DPL or Local LINK) and may also change in subsequent releases of CICS. Always use the CHANNEL option when referencing a CONTAINER. Where you are referring to Containers in the current CHANNEL then use the variable for the CHANNEL established from the ASSIGN command. There are two reasons for this; firstly it avoids any ambiguity as to which CHANNEL is being used, and second it ensures that where the current CHANNEL is being used then it has already been found through the ASSIGN command (see below).

2.3

ASSIGN command with CHANNEL option The CHANNEL option with the ASSIGN command can be used to establish the name of the current channel. Example : The following ASSIGN will return the name of the CHANNEL passed to the program, i.e. the Current CHANNEL.
EXEC CICS ASSIGN CHANNEL (WS-CURRENT-CHANNEL) END-EXEC

If no CHANNEL has been passed then in this case WS-CURRENT-CHANNEL will be spaces. If a CHANNEL has been passed then the WS-CURRENT-CHANNEL will be non spaces. The ASSIGN command using the CHANNEL option will always return a normal CICS response code (i.e. DFHNORMAL). Hence there is no need to include RESP or RESP2 codes in the ASSIGN command with CHANNEL option nor is there any reason to check the 2 RESP codes after the command has been issued.
2

At the time of writing the CICS parser will return a RC=32 for ASSIGN CHANNEL. The parser will need to be enhanced to remove this discrepancy.

N o v . 2 3

CICS Channel and Containers

Example :
DATA DIVISION. . . WORKING-STORAGE SECTION. 01 WS-MISC. 03 WS-CURRENT-CHANNEL . . PROCEDURE DIVISION. . . A010-ASSIGN-CHANNEL SECTION. PIC X(16) VALUE SPACES.

EXEC CICS ASSIGN CHANNEL (WS-CURRENT-CHANNEL) END-EXEC IF WS-CURRENT-CHANNEL = SPACES MOVE A010-ASSIGN-CHANNEL TO ABC-SECTION-NAME. PERFORM Z010-NO-CHAN-RECEIVED ELSE PERFORM A200-MAIN-PROCESS END-IF

2.4

Current CHANNEL Programs may only have a single current CHANNEL. This is the CHANNEL provided when the program was invoked. Although the program may create further channels the Current CHANNEL will never change. Where a program is invoked with a CHANNEL, then always use the ASSIGN command with CHANNEL option to establish the current channel. The rationale is to ensure that a CHANNEL has been received where one is expected.

2.5

Receiving COMMAREAs and Channels in the same program. Do not attempt to write individual programs which can receive either COMMAREAs or CHANNELs. Whilst this practice is detailed in at least one IBM redbook, its deployment can introduce a significant level of additional complexity into the Application Programs. If you have a CICS Gateway Program or other CICS program which you need to enhance to support CHANNEL functionality, then clone the existing program and amend it to use CHANNEL functionality.

2.6

Channel & Container Names CICS currently allows for Channel & Container names of 16 characters. Names can include characters and numbers and some additional characters (e.g. underscores, hyphens etc.) Whilst CICS also allows for Channel Names with lowercase characters they should always be defined as UPPERCASE. A channel named DIRECT-DEBIT is not the same as one named Direct-Debit. Full IBM Character set allowed in Channel & Container Names AZ az 09 $ @ # / % & ? ! : | = , ; < > . _

Character set for Channel & Container Names

N o v . 2 3

CICS Channel and Containers

Please use only those characters listed below. In particular, please avoid using Channel & Container names with lower-case characters. A- 0- # & - _ < @ Z 9 >

Where explicit references are required on Channel & Container names then code them as Working Storage variables in your program. All the examples described use literals defined in Working Storage. Another alternative is to place all the Container and Channel names used in an application into a copybook member. Container names should always be prefixed with the identifier of the sub-system using the container Channel names should always be prefixed with the identifier of the sub-system which created the Channel.

N o v . 2 3. 3 3.1

CICS Channel and Containers

Scope & Lifetimes of Channels

Current Channels References to CHANNELs are determined by the scope of a channel. As stated previously, when a program is invoked through a CICS command with the CHANNEL option (e.g. LINK, XCTL etc) then the current CHANNEL is that used to invoke the program. In the example below, when invoked from TYV12K, TYU86T will have a current channel of TYDEBIT-CARD.
WORKING-STORAGE SECTION 01 WC-THIS-PROGRAM PIC X(8) VALUE TYV12K.

01 WC-CICS-LITERALS. 03 WC-TYU86T PIC X(8) VALUE TYU86T. 03 WC-DEBIT-CHANNEL PIC X(16) VALUE TYDEBIT-CARD. . . EXEC CICS XCTL PROGRAM (WC-TYU86T) CHANNEL (WC-DEBIT-CHANNEL) RESP (WS-RESP-CODE) RESP2 (WS-RESP2-CODE) END-EXEC

N o v . 3.2 2 3

CICS Channel and Containers

Channel Scope The diagram below highlights the scope of two channels.
Program A EXEC CICS LINK PROGRAM(PROGRAMB) CHANNEL(UIINFO)

Current Channel: none

Program B EXEC CICS LINK PROGRAM(PROGRAMC) CHANNEL(UIINFO)

Current Channel: UIINFO

Scope of UNINFO

Program C EXEC CICS LINK PROGRAM(PROGRAMD) COMMAREA(WS-COMMAREA)

Current Channel: UIINFO

Program D EXEC CICS LINK PROGRAM(PROGRAME) CHANNEL(BRINFO)

Current Channel: none

Scope of BRINFO

Program E EXEC CICS RETURN

Current Channel: BRINFO

3.3

Lifetime of a Channel It is important to appreciate the difference between the Lifetime of a Channel and the Scope of a Channel. The scope of a channel consists of those CICS applications programs which reference a given CHANNEL. In the previous example the scope of Channel UIINFO consists of Programs A, B & C. The Lifetime of a Channel is the time that a given instance of a CHANNEL is in existence. Where the CHANNEL is only passed in XCTL and local LINK commands then the Lifetime of the Channel will finish when the task is complete. Where the CHANNEL is used in START, RETURN and DPLs then the lifetime of the channel may extend beyond the existence of the current task (i.e. into the task which was subsequently initiated by the START, RETURN or DPL). Critically, once CICS knows that an instance of a CHANNEL can no longer be referenced then it will automatically delete that CHANNEL instance. Unlike CONTAINERs, CHANNELs can not be deleted by Application Programs.

N o v . 2 4. 3 4.1

CICS Channel and Containers

Error Handling
ASSIGN CHANNEL Where a routine is invoked and a Channel is expected then the Current channel should be established from an ASSIGN command. If the current CHANNEL name returned is spaces then carry out CICS error processing and then issue an ABEND with an abend code of NOCH. In addition ensure that the ABEND command includes the CANCEL option to nullify any previous HANDLE ABEND statements.

4.2

Response Codes in Container commands To assist in error handling, always include RESP and RESP2 options and associated variables in Container commands. Always interrogate the RESP code passed back from CICS after issuing a CONTAINER command.

4.3

GET Container Errors GET CONTAINER commands can fail for a number of reasons. The common faults are that either the CONTAINER referenced or the CHANNEL referenced does not exist. Where a GET CONTAINER fails (e.g. the RESP code is INVREQ or CONTAINERERR) or the GET CONTAINER fails to find an anticipated Container then log the details using an Error CONTAINER.

4.4

PUT Container Errors Whilst, PUT CONTAINER commands can fail for a number of reasons (i.e. invalid name for a Container) another possible cause is that CICS is short on storage (SOS). Where a PUT fails then record and log the errors using error container and then abend with a PUTF abend code. If the PUT is on a non-error container then do not attempt to do a PUT to the error container as this will probably fail too.

4.5

MOVE Container Errors Where a MOVE CONTAINER unexpectedly fails then log the problem and then attempt to create (i.e. PUT) an error container.

4.6

DELETE Container Errors Where a DELETE CONTAINER unexpectedly fails then log the problem and then attempt to create (i.e. PUT) an error container.

4.7

Length Definitions and Length Errors The FLENGTH parameter is used in a number of the CONTAINER commands to specify the length of the data item. An example is shown below.
EXEC CICS GET CONTAINER CHANNEL INTO FLENGTH RESP RESP2 END-EXEC

(WC-INSTANCE-CONTAINER) (WS-TASK-ASSIGNED-CHANNEL) (WS-INSTANCE-DATA) (WS-INSTANCE-LEN) (WS-RESP) (WS-RESP2)

Where variables are required for FLENGTHs then ensure that they are coded as a binary fullword and signed (i.e. S9(9) COMP).

N o v . 2 3

CICS Channel and Containers

Where the length of the CONTAINER is known then set the FLENGTH to LENGTH OF <data-value>, where <data-value> is the name of the area of data (usually working storage) being referenced. Where the length is unknown then the NODATA option can be employed. This option is useful when the size of the data in the container is unknown, e.g. where the container has an Image object in it.

4.8

CICS response codes and Condition references DFHRESP symbolic values should be used in response code checks. There are of course a number of new symbolics (some examples below) introduced with CTS 3.1. CHANNELERR CONTAINERERR CCSIDERR Example: To establish whether a program has returned an Error CONTAINER the calling program can check for the existence of the Error CONTAINER and then check the EIB response code as shown below. Always use the DFHRESP symbolic values when checking response codes. [The CICS translator will convert them into the actual response codes.]
EVALUATE WS-RESP-CODE WHEN DFHRESP(NORMAL) PERFORM ZMK010-RECD-ERROR WHEN DFHRESP(CONTAINERERR) PERFORM JAB010-ALL-IS-OK WHEN OTHER

. .

N o v . 4.9 2 3

CICS Channel and Containers

Error Containers [Deployment Models for Error Containers have generated a high level of debate. Two models have been documented although the author suggests the first model is deployed. ] 4.9.1 Model 1 : Separate Validation and Error (Fault) Containers Error Containers are only created where the called program runs into an unexpected problem , i.e. a fault, (e.g. non-normal CICS RESP codes, abnormal MQ return code, unanticipated DB2 SQLCODE, ON EXCEPTION in a COBOL CALL, expected data not found etc). As the name suggests; Validation Containers are used to relay details relating to validation errors and associated information. After the standard EIBRESP code checks, the invoking program should then check for the presence of an Error Container. If the program is a CICS WS Wrapper program then it should use the presence of an Error Container to create a SOAPFAULT. Where appropriate the invoking program will also check for the existence of a Validation Container. This approach requires the application programs to create/handle both Error and Validation Containers. This model provides a clear delineation or isolation between the two classes of data. 4.9.2 Model 2 : Error Containers only

With this approach only Error Containers are created. The Error Containers include an extra field placed within the data. The extra field indicates whether the error information is an unexpected error (i.e. fault) or whether it is simply a Validation Error. The requesting program needs to check for both the existence of an Error Container and to interrogate its contents before deciding on the course of action to take. Whilst this approach results in fewer Containers and hence easier programming it fails to isolate the two separate classes of data. One of the clear benefits of CONTAINERs is that data can be segmented and hence looser coupling implemented.