Using the EXEC interface modules for AMODE(24) and AMODE(31) applications

For AMODE(24) and AMODE(31) applications, the CALL statements that the language translators generate invoke EXEC interface modules that provide communication between your code and the CICS® EXEC interface program, DFHEIP.

A language translator reads your source program and creates a new one. Normal language statements remain unchanged, but CICS commands are translated into CALL statements of the form required by the language in which you are coding. The calls invoke CICS-provided EXEC interface modules or stubs ; that is, function-dependent sections of code used by the CICS high-level programming interface. The stub, which is provided in the SDFHLOAD library, must be link-edited with your application program. These stubs are invoked during execution of EXEC CICS and EXEC DLI commands. Stubs are provided for each programming language.

Table 1. Interface modules (stubs)
Language	Interface module name
Assembler	DFHELII and DFHEAI0
All HLL languages and Assembler MAIN programs that use the LEASM option	DFHELII

The CICS-supplied stub routines work with an internal programming interface, the CICS command-level interface, which is never changed in an incompatible way. Consequently, these stub modules are compatible with earlier and later versions, and CICS application modules never need to be relinked to include a later level of any of these stubs.

Except for DFHEAI0, these stubs all provide the same function, which is to provide a linkage from EXEC CICS commands to the required CICS service. To do this, the stubs provide various entry points that are called from the translated EXEC CICS commands, and then execute a sequence of instructions that pass control to the EXEC interface function of CICS.

DFHELII contains multiple entry points, most of which provide compatibility for old versions of the CICS PL/I translator. It contains the entries DFHEXEC (for C and C++ application programs), DFHEI1 (for COBOL and Assembler), and DFHEI01 (for PL/I).

Each stub begins with an 8 byte eyecatcher in the form DFHY xnnn , where x indicates the language supported by the stub (A indicates Assembler, and I indicates that the stub is language independent), and nnn indicates the CICS release from which the stub was included. The letter Y in the eyecatcher indicates that the stub is read-only. Stubs supplied with very early releases of CICS contained eyecatchers in the form DFHE xxxx , in which the letter E denotes that the stub is not read-only. The eyecatcher for DFHELII in CICS Transaction Server for z/OS®, Version 5 Release 4 is DFHYI 710.

The eyecatcher can be helpful to determine the CICS release at which a CICS application load module was most recently linked.

COBOL

Each EXEC command is translated into a COBOL CALL statement that refers to the entry DFHEI1.

The following example shows the output generated by the translator when processing a simple EXEC CICS RETURN command:

 *EXEC CICS RETURN END-EXEC
Call 'DFHEI1' using by content x'0e0800000600001000'
end-call.

The reference to DFHEI1 is resolved by the inclusion of the DFHELII stub routine in the linkage editor step of the CICS-supplied procedures such as DFHYITVL or DFHZITCL.

PL/I

When translating PL/I programs, each EXEC command generates a call to the entry point DFHEI01. This is done using a variable entry point DFHEI0 that is associated with the entry DFHEI01. The translator enables this by inserting the following statements near the start of each translated program:

 DCL DFHEI0 ENTRY VARIABLE INIT(DFHEI01) AUTO;
DCL DFHEI01 ENTRY OPTIONS(INTER ASSEMBLER);

The translator creates a unique entry name based on DFHEI0 for each successfully translated EXEC command. The following example shows the output generated by the translator when it processes a simple EXEC CICS RETURN command:

 /* EXEC CICS RETURN TRANSID(NEXT) */
DO;
DCL DFHENTRY_B62D3C38_296F2687 BASED(ADDR(DFHEI0)) OPTIONS(INTER ASSEM
BLER) ENTRY(*,CHAR(4));
CALL DFHENTRY_B62D3C38_296F2687('xxxxxxxxxxxxxxxxx' /* '0E 08 80 00 03
00 00 10 00 F0 F0 F0 F0 F0 F0 F1 F0 'X */, NEXT);
END;

In the previous example, DFHENTRY_B62D3C38_296F2687 is based on the entry variable DFHEI0 that is associated with the real entry DFHEI01. This technique allows the translator to create a PL/I data descriptor list for each variable entry name. The PL/I compiler can then check that variable names referenced in EXEC commands are defined with attributes that are consistent with the attributes defined by the translator in the data descriptor list. In this example, ENTRY(*,CHAR(4)) specifies that the variable (named NEXT) associated with the TRANSID option should be a character string with a length of four.

The reference to DFHEI01 is resolved by the inclusion of the DFHELII stub routine in the linkage editor step of one of the CICS-supplied procedures such as DFHYITPL.

C and C++

In a C and C++ program, each EXEC CICS command is translated by the command translator into a call to the function DFHEXEC.

The translator enables this by inserting the following statements near the start of each translated program:

#pragma linkage(DFHEXEC,OS) /* force OS linkage */
void DFHEXEC(); /* function to call CICS */

The following example shows the output generated by the translator when processing a simple EXEC CICS RETURN command:

 /* EXEC CICS RETURN */
{
DFHEXEC(
"\x0E\x08\x00\x2F\x00\x00\x10\x00\xF0\xF0\xF0\xF0\xF1\xF8\xF0\xF0");
}

The reference to DFHEXEC is resolved by the inclusion of the DFHELII stub routine in the linkage editor step of one of the CICS-supplied procedures such as DFHYITDL, DFHZITDL, DFHZITEL, DFHZITFL, or DFHZITGL.

Assembler language

Each EXEC command is translated into an invocation of the DFHECALL macro.

The following example shows the output generated by the translator when processing a simple EXEC CICS RETURN command:

* EXEC CICS RETURN
DFHECALL =X'0E0800000800001000'

The assembly of the DFHECALL macro invocation as shown generates code that builds a parameter list addressed by register 1, loads the address of entry DFHEI1 in register 15, and issues a BALR instruction to call the stub routine.

 DS 0H
LA 1,DFHEITPL
LA 14,=x'0E08000008001000'
ST 14,0(,1)
OI 0(1),x'80'
L 15,=V(DFHEI1)
BALR 14,15

The reference to DFHEI1 is resolved by the inclusion of the DFHEAI stub routine in the linkage editor step of one of the CICS-supplied procedures such as DFHEITAL. The eyecatcher for DFHEAI in CICS Transaction Server for z/OS, Version 5 Release 4 is DFHYA 710 , with the release numbers indicating this stub was supplied with CICS Transaction Server for z/OS, Version 5 Release 4.

The DFHEAI0 stub for assembler application programs is included by the automatic call facility of the linkage editor or binder utility. It is called by code generated by the DFHEIENT and DFHEIRET macros to obtain and free, respectively, an assembler application program's dynamic storage area. This stub is required only in assembler application programs; there are no stubs required or supplied to provide an equivalent function for programs written in the high-level languages.

The DFHEAI stub must be included at the beginning of the program in the output from the link edit. To achieve this, ORDER and INCLUDE statements for DFHEAI must be in the link-edit step of your JCL. When you use the CICS-supplied assembler procedure DFHEITAL in the SDFHPROC library to translate, assemble, and link-edit application programs written in assembler language, the COPYLINK step of this procedure copies SDFHMAC(DFHEILIA). DFHEILIA contains the following statements that must be included:

  ORDER DFHEAI
  INCLUDE SYSLIB(DFHEAI)

The statements are put into a temporary file that is concatenated before the assembled application program in the LKED step of the procedure.