Calling Assembler programs

Assembler language application programs that contain commands can have their own RDO program definition. Such programs can be invoked by COBOL, C or C++, PL/I, or assembler language application programs using LINK or XCTL commands (see Program control). However, because 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, may 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 details of mixing languages in an application load module, refer to z/OS Language Environment Writing Interlanguage Communications Applications.

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, but if you 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 followed, optionally, 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 8. 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 9. 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:

  1. Assemble and link ASMTEST using the DFHEITAL procedure:
    //ASMPROG EXEC DFHEITAL
    //TRN.SYSIN DD *
        .... program source ...
    /*
    //LKED.SYSIN DD *
      NAME ASMTEST(R)
    /*
  2. 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 was stored in a library included in the SYSLIB dataset concatenation.

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

Start of changeThe 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:End of change

Start of change   ORDER DFHEAI
   INCLUDE SYSLIB(DFHEAI)End of change

Start of changeThe statements are put into a temporary file that is concatenated before the assembled application program in the LKED step of the procedure.End of change

If you are writing your own JCL, you only need to include the DFHELII stub, because this contains the entry points needed for all languages.

An assembler language application program that is called by another begins with the DFHEIENT macro and ends with the DFHEIRET macro. The CICS translator inserts these for you, so if the program contains EXEC CICS commands and is to be passed to the translator, as in the example just given, you do not need to code these macros.

[[ Contents Previous Page | Next Page Index ]]