Coding the DFHEIENT macro for AMODE(24) and AMODE(31) assembler language programs

For AMODE(24) and AMODE(31) programs, the DFHEIENT macro calls the PROLOG program, which allocates working storage to hold any user variables and for CICS® use. The PROLOG program sets up the CICS portion of this storage. When the program returns, this code sets up the registers specified by the DFHEIENT parameters. The values provided by the DFHEIENT macro that the translator inserts automatically might be inadequate for application programs that produce a translated output greater than 4095 bytes. In this situation, you can provide your own version of the DFHEIENT macro and specify the NOPROLOG translator option to prevent the translator from automatically inserting its version of the DFHEIENT macro.

For example, by default, the translator sets up only one base register (register 3), which might cause addressability problems for your program. You can provide your own DFHEIENT macro with the CODEREG operand so that you can specify more than one base register. If you code your own version of the DFHEIENT macro with the same label as the CSECT statement, it can replace the CSECT statement in your source program. If you code the DFHEIENT macro without a label, it must immediately follow the CSECT statement.

You can specify the following operands for the DFHEIENT macro:
CODEREG
Specify a value of 0 (the default) to specify relative addressing.
Or specify base registers. Note that registers 13,14,15, and 1 are not allowed.
DATAREG
Specify one or more working storage registers for the application program. The default is register 13, and it is advisable to use register 13 as your first data dynamic-storage register. If you do not, the code generated by the DFHECALL macro adds extra instructions to manipulate register 13. The DFHECALL macro ensures that register 13 addresses the save area that DFHEISTG defined in dynamic storage.
EIBREG
Specify the register to use to address the EXEC interface block (EIB). The default is register 11.
STATREG
Specify one or more static registers for the application program to use. The default is register 3.
STATIC
Specify the assembler label of the start of the static area. You must specify a value; there is no default for this parameter.

Using base registers in your program

You can use the following operands to specify base registers:
  • CODEREG - base registers (registers 13,14,15, and 1 not allowed)
  • DATAREG - dynamic-storage registers
  • EIBREG - register to address the EIB
For example, the following simple assembler language application program uses the BMS command SEND MAP to send a map to a terminal. 
INSTRUCT CSECT
         EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE
         END
The following example code increases the number of base and data registers for this program: 
INSTRUCT DFHEIENT CODEREG=(2,3,4),
         DATAREG=(13,5),
         EIBREG=6
         EXEC CICS SEND
         MAP('DFH$AGA')
         MAPONLY ERASE
         END

The symbolic register DFHEIPLR is equated to the first DATAREG either explicitly specified or obtained by default. The DFHECALL macro ensures that register 13 addresses the save area that DFHEISTG defined in dynamic storage, so it is advisable to use register 13 as your first data dynamic-storage register. If you do not, the code generated by DFHECALL adds extra instructions to manipulate register 13.

DFHEIPLR is assumed by the expansion of a CICS command to contain the value set up by DFHEIENT. You should either dedicate this register or ensure that it is restored before each CICS command.

Using relative addressing in your program

When you use relative addressing, you do not need to use any base registers to address your program instructions, but you must use at least one register to address static data in your program. Specify the following operands on the DFHEIENT macro:
  • CODEREG=0 to specify that no registers are to be used to address program instructions.
  • STATREG to specify one or more registers to address the static data area in your program.
  • STATIC to specify the address of the start of the static data in your program.
If you use relative addressing, use the IEABRCX DEFINE macro (provided by z/OS®) to redefine the assembler mnemonics for branch instructions to use relative branch instructions. Also, ensure that any LTORG statements, and instructions that are the target of EXECUTE instructions, appear after the label specified in the STATIC operand. For example: 
         IEABRCX DEFINE                 Define relative branch mnemonics
RELATIVE DFHEIENT CODEREG=0,STATREG=(8,9),STATIC=MYSTATIC
         ....
         EX    R2,VARMOVE             Execute instruction in static area
         ....

MYSTATIC DS    0D                     Static data area
MYCONST  DC    C'constant'            Static data value
VARMOVE  MVC   WORKA(0),WORKB         Executed instruction
         LTORG ,                      Literal pool

For more information about the IEABRCX macro, see IEABRCX - Relative branch macro extension in z/OS MVS Programming: Assembler Services Reference IAR-XCT.

Where LTORG statements are needed

Assembler language programs that are translated with the DLI option have a DLI initialization call inserted after each CSECT statement. Assembler language programs that are larger than 4095 bytes and that do not use the CODEREG operand of the DFHEIENT macro to establish multiple base registers, must include an LTORG statement to ensure that the literals, generated by either DFHEIENT or a DLI initialization call, fall in the range of the base register.

In general, an LTORG statement is needed for every CSECT that exceeds 4095 bytes in length.

Related information