Description of the sample applications

The sample external CICS® interface programs are included on the CICS Transaction Server for z/OS® distribution tape.

Two sample MVS™ client programs are supplied. One is provided in assembler language, COBOL, C, and PL/I. The other is only provided in assembler. The sample CICS server program is provided in assembler only. Assembler language programs are in source and executable form. COBOL, PL/I, and C programs are provided in source form only. Each version of the client program has basically the same function, but programming methods vary somewhat according to the language used.

The sample programs, shown in Table 1, are supplied in source form in CICSTS53.CICS.SDFHSAMP. The sample assembler server program is also supplied in executable form in CICSTS53.CICS.SDFHLOAD. The assembler client program is supplied in CICSTS53.CICS.SDFHEXCI.

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.
Table 1. The external CICS interface sample programs
Language Name Type of program
Assembler DFH$AXCC Client program
Assembler DFH$ATXC Client program
Assembler DFH$AXCS Server program
COBOL DFH0CXCC Client program
PL/I DFH$PXCC Client program
C DFH$DXCC Client program

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.

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, once 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 once 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, 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 run-time 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.