Translated code for EXEC CICS commands

Application programs can be written in COBOL, C®, PL/I, or assembler language, and contain EXEC CICS commands. CICS® translates these programs and creates an equivalent source program where each command is now translated into a call macro or statement in the language of the original source program.

Translation considerations: LENGTH options in EXEC CICS commands

In COBOL, PL/I, and Assembler language, the translator defaults certain lengths, if the NOLENGTH translator option is not specified. This means they are optional in programs that specify data areas. In C, all LENGTH options must be specified.

The LENGTH option specifies a halfword binary value that is the length in bytes of the COMMAREA (communication area). If the request is a DPL to a region at the level of CICS TS 5.5 or earlier, or a DPL over an ISC connection, this value should not exceed 24 KB. This limit allows for the COMMAREA and space for headers.

This advisory 24 KB limit does not apply to the FLENGTH option on CICS commands (except for terminal-related SEND and RECEIVE commands, because of architectural limitations). The FLENGTH option is used on commands that relate to containers and journals, among others.

For temporary storage, transient data, and file control commands, the data set definitions themselves might impose further restrictions.

COBOL translation output

EXEC CICS commands are converted to calls to the CICS interface DFHEI1.

Figure 1 shows an example EXEC statement.
Figure 1. Example EXEC statement
EXEC CICS RETURN TRANSID('fred')
     COMMAREA(mycommarea) END-EXEC.
It is translated to: 
Move length of mycommarea to dfhb0020
Call 'DFHEI1' using by content
          x'0e08e0000700001000f0f0f0f2f7404040'
          by content 'fred' by reference mycommarea
          by reference dfhb0020 end-call.

C translation output

For a C application program, each command is replaced by reassignment statements followed by a DFHEXEC statement that passes the parameters.

PL/I translation output

For a PL/I application program, each command is always replaced by a DO statement, a declaration of a generated entry name, a CALL statement, and an END statement. The ENTRY declaration ensures that the appropriate conversions for argument values take place.

If a PL/I on-unit consists of a single EXEC CICS command, the command should be inside a BEGIN block, as in the following example.
Example
ON ERROR BEGIN;
         EXEC CICS RETURN;
         END;
In a similar way, if an EXEC CICS command is associated with a PL/I condition prefix, the command should be inside a BEGIN block, as in the following example.
Example
(NOZERODIVIDE): BEGIN;
                EXEC CICS GETMAIN
                SET(ptr-ref)
                LENGTH(data-value);
                END;

If OPTIONS(MAIN) is specified, the translator modifies the parameter list by inserting the EIB structure pointer as the first parameter. If OPTIONS(MAIN) is not specified (that is, if the program is to be link-edited to the main module), the parameter list is not modified, and it is the application programmer's responsibility to address the EIB structure in the link-edited program if access to it is required. In either case, where a program commences with a valid PL/I PROCEDURE statement, the translator inserts the declaration of the EIB structure.

Assembler translation output

The invocation of a CICS assembler language application program obeys system standards.

On entry to the application program, registers 1, 15, 14, and 13 contain the following addresses:
  • Register 1 contains the address of the parameter list. This list has at least two entries:
    • Address of the EIB (EXEC interface block)
    • Address of the COMMAREA; if no COMMAREA, entry is X'00000000'
  • Register 15 contains the address of the entry point.
  • Register 14 contains the address of the return point.
  • Register 13 contains the address of the save area.

All other registers are undefined.

For an assembler language application program, when the CICS translator detects an EXEC 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. For details, see DFHECALL macro.

In addition to the invocation of the DFHECALL macro, the translator also inserts the following macros into your source program:
  • The DFHEIGBL 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.
  • The DFHEIENT 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. For details, see 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. For more information, see Coding DFHEIENT for AMODE(24) and AMODE(31) assembler language programs.

    For AMODE(64) programs, you must specify the DFHEIENT macro parameters to specify that your program uses relative addressing instructions, because only relative addressing is supported. For more information, see Coding DFHEIENT for AMODE(64) assembler language programs.

  • The DFHEIRET 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. For more information, see Coding DFHEIRET for assembler language programs.

    • It returns control to the address in register 14.

    For reference information, see DFHEIRET macro.

  • The DFHEISTG and DFHEIEND macros define dynamic storage, including the storage required for the parameter list and a save area. For more information, see Extending dynamic storage for assembler language programs. For reference information, see DFHEISTG macro and DFHEIEND macro.

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.

Example

This example 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 2 shows the source program code.

Figure 2. Source program

INSTRUCT CSECT
         EXEC CICS SEND MAP('DFH$AGA') MAPONLY ERASE
         END

This source program is translated to the output shown in Figure 3.

Figure 3. Translated code

         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