Coding the EXEC CICS assembler interface

For AMODE(24) and AMODE(31) assembler language programs, you can optionally specify your own DFHEIENT macro. To declare that an assembler language programs is AMODE(64), you use the z/OS® Assembler SYSSTATE macro. For AMODE(64) assembler language programs, you must specify the DFHEIENT macro, and you can optionally specify your own DFHEIRET macro.

AMODE(24) and AMODE(31) assembler language programs

DFHEIENT macro

For AMODE(24) and AMODE(31) programs, 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. To prevent the translator from automatically inserting its version of the DFHEIENT macro, specify the NOPROLOG translator option.

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 use the following operands to specify base registers:

CODEREG - base registers (registers 13,14,15, 0 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.

You can also use the DFHEIENT macro to specify that you want to use relative addressing instructions 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.

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.

DFHEIRET macro

For AMODE(24) and AMODE(31) programs, the DFHEIRET macro calls the EPILOG program to release the working storage of the application program.

You can specify the following parameter for the DFHEIRET macro:

RCREG: Specify the register into which the return code is placed. If you do not specify a value, a return code is not passed back to the caller of the program. There is no default value.

The translator inserts the DFHEIRET macro, with no parameters specified, immediately before the END statement (unless you specify the NOEPILOG translator option to prevent this). END must be in uppercase for the translator to recognize it. If the DFHEIRET macro is invoked before this translator-inserted DFHEIRET macro, the translator-inserted macro does not generate any code.

AMODE(64) assembler language programs

CICS Transaction Server supports non- Language Environment® assembler language programs that run in 64-bit addressing mode.

SYSSTATE macro

To declare that an application is AMODE(64), you use the z/OS Assembler SYSSTATE (Identify system state) macro.

Include a SYSLIB statement for the SYS1.MACLIB macro library (which contains the SYSSTATE macro) in your compile JCL.
Ensure one of the following:
- The SYSSTATE macro with parameter AMODE64=YES is placed immediately after the CICS translator options statement. For example:
```
*ASM   XOPTS(NOPROLOG NOEPILOG)
       SYSSTATE AMODE64=YES 
```
- If the program does not specify CICS translator options, the SYSSTATE macro with parameter AMODE64=YES is the first statement.
The SYSSTATE statement must be on one line, because CICS does not support continuation for this statement. For more information about the SYSSTATE macro, see SYSSTATE- Identify system state in z/OS MVS Programming: Assembler Services Reference IAR-XCT.

If the application is declared as AMODE(64) in this way, the following CICS-supplied macros generate AMODE(64) code:

DFHEIENT
DFHEISTG
DFHEIRET
DFHECALL

If the SYSSTATE macro is not specified, or is specified without parameter AMODE64=YES when any of these CICS-supplied macros first generates code, these macros generate AMODE(24) or AMODE(31) code.

DFHEIENT macro

For AMODE(64) programs, the DFHEIENT macro calls the AMODE(64) 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 PROLOG program returns, this code sets up the registers specified by the DFHEIENT parameters.

You must specify the DFHEIENT macro parameters to specify that your program uses relative addressing instructions, because only relative addressing is supported. For relative addressing, you do not need any base registers to address your program instructions, but you must use at least one register to address static data in your program. Use the STATREG and STATIC parameters to set up one or more static registers.

You can specify the following parameters for the DFHEIENT macro:

CODEREG: Specify a value of 0 (the default) to specify relative addressing.
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.

Use the NOPROLOG translator option and specify the DFHEIENT macro with the appropriate parameters for relative addressing. If you do not specify the DFHEIENT macro, the translator inserts a DFHEIENT macro without the required parameters and the following error occurs:

12,DFHEIENT - AMODE 64 - STATIC REQUIRED

The following two example DFHEIENT statements generate the same code. In the first statement, all the parameters are coded (specifying the default values). In the second statement, only the parameter that does not have a default value is coded.

DFHEIENT CODEREG=0,DATAREG=13,EIBREG=11,STATREG=3,STATIC=STAT

DFHEIENT STATIC=STAT

DFHEIRET macro

For AMODE(64) programs, the DFHEIRET macro calls the AMODE(64) EPILOG program to release the working storage of the application program.

You can specify the following parameter for the DFHEIRET macro:

RCREG: Specify the register into which the return code is placed. If you do not specify a value, a return code is not passed back to the caller of the program. There is no default value.

For more information about the DFHEISTG storage, see Extensions to dynamic storage. For more information about the DFHECALL and DFHEIRET macros, see DFHECALL macro.