DFHECALL macro

For an assembler language application program, when the CICS® translator detects a CICS command, each command is replaced by an invocation of the DFHECALL macro. The DFHECALL macro sets up the command parameters and calls the initial CICS command processor to handle the command.

This macro expands to a system-standard call sequence that uses registers 15, 14, 0, and 1. The contents of these registers are as follows:

The entry point held in register 15 is resolved in the EXEC interface processor that must be link-edited with your application program. For AMODE(24) and AMODE(31) applications, this EXEC interface processor is DFHEAI; for AMODE(64) applications, it is DFHEAG.

You can specify the exit from the application program by an EXEC CICS RETURN command in your source program. Alternatively, you can use the DFHEIRET macro, which restores the registers and returns control to the address in register 14. The translator inserts the DFHEIRET macro, with no parameters specified, immediately before the END statement, unless you specify the NOEPILOG translator option. You can use this macro to return from a top-level program, but is not advisable from a lower-level program.

During assembly, the DFHECALL macro builds an argument list in dynamic storage, so that the application program is reentrant. Then the macro invokes the EXEC interface program DFHEIP for AMODE(24) or AMODE(31) applications, or DFHEIG for AMODE(64) applications. These programs also obey system standards, as previously described.

For AMODE(64) applications, although the application and the initial command processor run in 64-bit addressing mode, the parameters that the DFHECALL macro sets up and passes to the initial command processor contain 31-bit addresses. Therefore, the storage in which the call parameters are built, the DFHEISTG storage, must be 31-bit storage (above 16 MB but below 2 GB).

In addition to the invocation of the DFHECALL macro, the translator also inserts the following macros into your source program:

DFHEIGBL

This macro sets globals if you are using EXEC DLI in either a batch or an online CICS application program. Within DFHEIGBL, if DFHEIDL is set to 1, this means that the program contains EXEC DLI commands. If DFHEIDB is set to 1, this means that the program is batch DL/I. If you are not using DL/I, it is commented and set to 0.

DFHEIENT

This macro is inserted after the first CSECT or START instruction. It performs prolog code to allocate working storage to hold any user variables and for CICS use:

It saves registers
It gets an initial allocation of the storage that is defined by DFHEISTG
It sets up a base register (default register 3)
It sets up a dynamic storage register (default register 13)
It sets up a register to address the EIB (default register 11)

DFHEIRET

This macro performs epilog code to release the working storage of the application program:

It restores registers.
DFHEIRET RCREG=nn, where nn (any register number other than 13) contains the return code to be placed in register 15 after the registers are restored.
It returns control to the address in register 14.

DFHEISTG and DFHEIEND

These macros define dynamic storage:

They define the storage required for the parameter list
They define a save area.

For further details about these macros with AMODE(64) applications, see Coding the EXEC CICS(r) assembler interface.

A copybook, DFHEIBLK, that contains a DSECT that describes the EIB, is also included automatically.

The program must have an END statement because the translator does not otherwise insert the default macros. Also CSECT or START and END must be in uppercase for the translator to recognize them.

The example in Figure 1 shows a simple assembler language application program that uses the BMS command SEND MAP to send a map to a terminal, followed by the output after program INSTRUCT is translated.

Figure 1. Source program and translated code for a CICS command

Source program
 
INSTRUCT CSECT
         EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE
         END
 
 
This source program is translated to:
 
         DFHEIGBL ,                INSERTED BY TRANSLATOR
INSTRUCT CSECT
         DFHEIENT                  INSERTED BY TRANSLATOR
*        EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE
         DFHECALL =X'1804C0000800000000046204000020',
               (CHA7,=CL7'DFH$AGA*'),(______RF,DFHEIV00)
         DFHEIRET                  INSERTED BY TRANSLATOR
         DFHEISTG                  INSERTED BY TRANSLATOR
         DFHEIEND                  INSERTED BY TRANSLATOR
         END