About the EXCI channel and containers sample applications

The sample CICS server program

The sample CICS server program, DFH$AXNS, is provided in assembler only and is in source and executable form.

The sample MVS client program

The sample client program shows you how to code a simple MVS client application using the EXCI CALL interface and the EXEC CICS LINK command. The internal design of both client assembler and COBOL sample programs is the same.

Each version of the client is divided into three separate sections as follows:

Section 1

Section 1 uses the EXEC interface to send containers to the server (CICS). The request is in a container called REQUEST_TYPE and will contain either "LINK1" or "LINK2". The server program (DFH£AXNS), described below, uses this container. For the first LINK request, a container called EBCDIC_DATA is set up on channel FIRST_CHANNEL with a simple text string. This is then sent by an EXEC CICS LINK request.

If the request succeeds an EXEC CICS QUERY CHANNEL request is issued to check how many containers are on the channel. There should be three because the server program will have added an EXCI_RESPONSE container to the channel. A browse using EXEC CICS STARTBROWSE CONTAINER, EXEC CICS GETNEXT CONTAINER and EXEC CICS ENDBROWSE CONTAINER requests is then performed to browse the names of the containers on the channel. This query and browse is not necessary but is added to demonstrate how to use the EXCI SPI commands.

The final part of section 1 involves issuing a number of container commands to set up container ASCII_DATA on channel SECOND_CHANNEL. This is sent again by an EXEC CICS LINK request.

Section 2

Section 2 uses the CALL interface. After INIT_USER, ALLOCATE_PIPE, and OPEN_PIPE have been executed, the DPL section is in a loop that executes twice. It repeats the sending of the containers sent in section 1 but uses the CALL interface instead.

In Section 2, the REQUEST_TYPE container will contain "CALL1" or "CALL2", not "LINK1" or "LINK2". The other containers will be as sent for Section 1.

Section 3

Section 3 deletes the channels used. This is not required, but is done to show best practise. Then CLOSE_PIPE and DEALLOCATE_PIPE are executed.

The server program, DFH£AXNS (in assembler) is invoked by both DFH£AXNC and DFH0CXNC. It uses the contents of the REQUEST_TYPE container to know whether this is the first or second invocation by either the EXEC or the CALL interface. If the container cannot be found, the program abends with abend code NCON, which indicates that the REQUEST_TYPE container could not be found. If this succeeds, the server program gets the appropriate container for the indicated request and returns a response in container EXCI_RESPONSE.  This is tested by the client programs to make sure the response contains the text 'OK'. The program writes records to a TS main queue called DFHAXNSQ. This enables execution of the program to be confirmed and shows whether everything worked properly.

The assembler version of the client program is supplied pregenerated in an executable form. Both versions of the program accept two runtime parameters, as follows:

TARGET_SYSTEM

Specifies the server region APPLID.

If you use the pregenerated assembler version, you do not need to reassemble the program to specify the APPLID of your own CICS server region. You can also use the sample client programs with different CICS regions without needing to modify the programs each time.

USERID

Specifies the user ID to be used on the call interface DPL_request.

You specify these positional parameters on the PARM statement, separated by a comma.