About the EXCI COMMAREA sample applications

The external CICS® interface sample programs include two sample MVS™ client programs and a sample CICS server program. Data is passed between the clients and the server program using a standard CICS communications area (COMMAREA).

Table 1. The external CICS interface sample programs
Language Name Type of program
Assembler1 DFH$AXCC Client program
Assembler1 DFH$ATXC Client program
Assembler1 DFH$AXCS Server program
COBOL2 DFH0CXCC Client program
PL/I2 DFH$PXCC Client program
C2 DFH$DXCC Client program
Notes:
  1. Assembler language programs are in source and executable form.
  2. COBOL, PL/I, and C programs are provided in source form only.

The sample CICS server program

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

The sample MVS client programs

The sample client programs show you how to code a simple MVS client application using the EXCI CALL interface and the EXEC CICS LINK command.

Two sample MVS client programs are supplied:

  • One sample client program, DFH$*XCC, is provided in assembler language, COBOL, C, and PL/I. Each version has basically the same function, but programming methods vary somewhat according to the language used.
  • The other sample client program, DFH$ATXC, is only provided in assembler.
Note:
  1. The assembler versions of the client program use BSAM, which requires the programs to be link-edited in RMODE(24), as a switch to AMODE(24) is made around the BSAM call. The assembler source code includes the required RMODE(24) statement. Normally, EXCI client programs run AMODE(31),RMODE(ANY).
  2. Because of this, the assembler versions of these client programs are unsuitable for use as Language Environment® MAIN programs.
  3. SDFHEXCI and SDFHDLL1 are downwardly compatible with all supported releases of CICS TS.

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

  1. The first section issues a single EXEC CICS LINK command to inquire on the state of the sample VSAM file, FILEA, in the target CICS system.

    If the file is in a suitable state, processing continues to sections two and three, which together provide complete examples of the use of the EXCI CALL interface.

  2. The second section initiates a specific MRO connection to the target CICS system and, when the pipe is open, performs a series of calls that each retrieve a single sequential record from the sample VSAM file, until no more records are available.
  3. The third section is a simple routine to close the target sample file when processing of the data is complete. It also terminates the MRO connection now that the link is no longer required.

Some of the parameters used on the EXCI CALL and EXEC CICS LINK commands in the client program need to be tailored for your own target CICS server region. Change these as required, and then retranslate, compile (or assemble), and link-edit the program.

The variables and their values specified in the sample programs are given in Table 2.

Table 2. Parameters used in the sample client programs
Variable name in sample program Default value
TARGET_FILE FILEA
TARGET_TRANSID EXCI
TARGET_SYSTEM DBDCCICS (applid)
TARGET_PROGRAM DFH$AXCS
TARGET_USERID Defaults to batch region's user ID
APPLICATION BATCHCLI
The assembler versions of the client programs are supplied pregenerated in an executable form. All versions of the program accept two runtime parameters, as follows:
  1. The first (TARGET_SYSTEM) specifies the server region APPLID.

    For the pregenerated assembler versions, this avoids you having to reassemble the programs 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.

  2. The second 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.

Data transmission between clients and the server

A standard CICS communications area (COMMAREA) facilitates data transmission between the programs. The definitions of this COMMAREA are identical on each side of the EXCI link to ensure that data is mapped correctly.

The sample client program DFH$AXCC minimizes data transmission by specifying a specific data length to avoid sending the whole COMMAREA over the link. The data length option specifies a binary value that is the length of a contiguous area of storage, from the start of the COMMAREA, to be passed to the server program. This is because the amount of data being passed to the server is small, but the COMMAREA itself is much larger so that the server can return the requested records from FILEA. Specifying a data length when the amount of data being passed is smaller than the COMMAREA improves performance.

Sample program DFH$ATXC passes the full COMMAREA to the server program because it makes changes to the file records and the whole of the changed record needs to be passed to the server.

The first and third sections of the sample client programs define the COMMAREA as only 18 bytes (no data is requested from the server in these sections). For the second section, the sample client program defines the COMMAREA as 98 bytes, the extra 80 bytes being required for the sample server program to return a record from FILEA. In all sections, the data length is defined as 18 bytes. The COMMAREA structure is defined in the sample programs as follows:

Bytes Data type Field description
0-3 Fullword Call type code.
4-11 Char(8) Target file name.
12-17 Char(6) Ridfield identifier.
18-97 Char(80) FILEA record data area.

Note that, although the COMMAREA structure is described in both the client and server programs, the actual size of the COMMAREA made available by CICS to the server is determined by the client program. If you modify the sample programs to work with one of your own application programs, make sure you specify a COMMAREA large enough to handle the maximum amount of data the server is expected to return to the client. The server must not attempt to return data that is larger than the COMMAREA specified by the client.

For more information about using a COMMAREA for passing data between CICS programs, see Sharing data across transactions.