Calling assembler language programs

Assembler language application programs can be invoked by COBOL, C, C++, PL/I, or assembler language application programs by using LINK or XCTL commands.

64-bit addressing mode

AMODE (64) assembler language application programs that contain commands can have their own RDO program definition. Such programs can be invoked by COBOL, C, C++, PL/I, or assembler language application programs by using LINK or XCTL commands.

24-bit and 31-bit addressing mode

AMODE(24) and AMODE(31) assembler language application programs that contain commands can have their own RDO program definition. Such programs can be invoked by COBOL, C, C++, PL/I, or assembler language application programs by using LINK or XCTL commands. However, because AMODE(24) and AMODE(31) programs that contain commands are invoked by a system standard call, they can also be invoked by a COBOL, C, C++, or PL/I CALL statement, or by an assembler language CALL macro.

A single CICS® application program, as defined in an RDO program definition, can consist of separate CSECTs compiled or assembled separately, but linked together.

An assembler language application program that contains commands can be linked with other assembler language programs, or with programs written in one or more high-level languages (COBOL, C, C++, or PL/I). For more information about mixing languages in an application load module, see Mixing languages in Language Environment . For information about programs with different addressing modes, see Using mixed addressing modes.

If an assembler language program (that is link-edited separately) contains command-level calls, and is called from a high-level language program, it requires its own CICS interface stub. If the assembler program is link-edited with the high-level language program that calls it, then the assembler program does not need a stub. If you do provide one, the message MSGIEW024I is issued, but this can be ignored.

Because assembler language application programs containing commands are always passed the parameters EIB and COMMAREA when invoked, the CALL statement or macro must pass these two parameters, optionally followed by other parameters.

For example, the PL/I program in file PLITEST PLI calls the assembler language program ASMPROG, which is in file ASMTEST ASSEMBLE. The PL/I program passes three parameters to the assembler language program: the EIB, the COMMAREA, and a message string.

Figure 1. PLITEST PLI

 PLIPROG:PROC OPTIONS(MAIN);
DCL ASMPROG ENTRY EXTERNAL;
DCL COMA CHAR(20), MSG CHAR(14) INIT('HELLO FROM PLI');
CALL ASMPROG(DFHEIBLK,COMA,MSG);
EXEC CICS RETURN;
END;

The assembler language program performs an EXEC CICS SEND TEXT command, which displays the message string passed from the PL/I program.

Figure 2. ASMTEST ASSEMBLE

DFHEISTG DSECT
MSG DS CL14
MYRESP DS F
ASMPROG CSECT
L 5,8(1)
L 5,0(5)
MVC MSG,0(5)
EXEC CICS SEND TEXT FROM(MSG) LENGTH(14) RESP(MYRESP)
END

You can use JCL procedures supplied by CICS to compile and link the application, as follows:

Assemble and link ASMTEST using the DFHEITAL procedure:

//ASMPROG EXEC DFHEITAL
//TRN.SYSIN DD *
.... program source ...
/*
//LKED.SYSIN DD *
NAME ASMTEST(R)
/*

Compile and link PLITEST using the DFHYITPL procedure, and provide linkage editor control statements that include the ASMTEST load module created by the DFHEITAL procedure:
```
//PLIPROG EXEC DFHYITPL
//TRN.SYSIN DD *
.... program source ...
/*
//LKED.SYSIN DD *
INCLUDE SYSLIB(ASMTEST)
ENTRY CEESTART
NAME PLITEST(R)
/*
```
Note: Step 2 assumes that the ASMTEST load module created by DFHEITAL is stored in a library that is included in the SYSLIB data set concatenation.

The load module created by the DFHYITPL procedure includes both the DFHEAI stub (included by DFHEITAL) and the DFHELII stub (included by DFHYITPL). The linkage editor or binder program issues a warning message because both stubs contain an entry point named DFHEII. This message can be ignored.

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.

If you write your own JCL, you must include the DFHELII stub, because this contains the entry points that are needed for all languages.

An assembler language application program can begin with the DFHEIENT macro and end with the DFHEIRET macro. The CICS translator inserts these for you, so if the program contains EXEC CICS commands and is passed to the translator, as in the example just given, you do not need to code these macros. Note that DFHEIRET changed with CICS TS 2.2 to accommodate relative addressing. If there is no base register, the macro expansion no longer generates an LTORG. Normally, when the END is reached, the assembler generates an automatic LTORG to gather up remaining VCONs. If you have code that results in a private code CSECT at the start of the CSECT concatenation, this can cause issues. When the END statement is reached, the assembler reverts to your first CSECT and cannot resolve the VCON from it. We recommend that you check assembler listings and eliminate this kind of private control section. For details, see Unnamed section information in the HLASM Language Reference.