Writing an edit routine in Assembler for CICS

The QMF edit exit interface for Assembler in CICS consists of these parts:

• Interface control block, which is shipped with QMF as DXEECSA
• CICS prolog and epilog macros, which are shipped with CICS as DFHEIENT and DFHEIRET
• CICS command interface modules, which are shipped with CICS as DFHEAI and DFHEAI0
• Your edit exit program, which is named DSQUECIC

Figure 162 shows the program structure of an Assembler edit exit routine for CICS.

Figure 162. Program structure of an Assembler edit exit routine for CICS

How an Assembler edit routine interacts with CICS

The user edit program is called by using the standard CICS LINK command interface. Your program is executing on a different program level than the main QMF program. On entry to your edit exit program, the following conditions exist:

• Register 1 contains the address of a standard CICS parameter list suitable for processing by CICS supplied macros DFHEIENT and DFHEIRET.
  
• Register 13 contains the address of a standard CICS working storage area as described by CICS supplied macro DFHEISTG.

An Assembler DSECT for DXEECS is shipped with QMF as DXEECSA, located in library QMF720.SDSQSAPE. Include this DSECT into your program using the Assembly COPY statement.

Return control to QMF by using the standard CICS RETURN command.

Translating your program

You must translate your program using the CICS translator for Assembler. When you translate your program, CICS normally supplies the standard CICS prologue (DFHEIENT) which sets up addressability, saves registers in the standard CICS working storage area, and provides a standard CICS epilogue (DFHEIRET).

Return control to QMF by using the CICS RETURN command; for example, EXEC CICS RETURN.

Assembling your program

During assembly, QMF edit exit interface control block DXEECSA, located in QMF sample library QMF720.SDSQUSRE, and the CICS macro library must be available.

Link-editing your program

Create a new QMF edit exit module DSQUECIC by including your edit program DSQUXCTA with EXEC CICS interface control modules DFHEAI and DFHEAI0, which are both located in the CICS module library as distributed by the CICS product. The EXEC CICS module DFHEAI must be the first module in the edit exit module and the entry point must be DSQUECIC.

The module DSQUECIC must be executable in 31-bit addressing mode.

Example JCL statements for translating, assembling and link-editing for CICS on OS/390

The following are example statements for translating, assembling, and link-editing your job for CICS.

 //SAMPASM  JOB ...
//* Add a parameter PROGLIB to procedure DFHEITAL
//*      PROGLIB=&PROGLIB,
//TRNCOMLK EXEC PROC=DFHEITAL,PROGLIB='QMF720.SDSQLOAD'
//TRN.SYSIN DD *
      .
      Your program or modified copy of QMF sample DSQUXCTA
      .
/*
//* Provide access to QMF Edit Macro DXEECSA
//ASM.SYSLIB DD  DSN=QMF720.SDSQUSRE,DISP=SHR
//LKED.SYSIN  DD  *
    INCLUDE SYSLIB(DFHEAI)
    INCLUDE CICSLOAD(DFHEAI0)
    ORDER DFHEAI,DFHEAI0
    ENTRY DSQUECIC
    MODE AMODE(31) RMODE(ANY)
    NAME DSQUECIC(R)
/*                                                        

Example program DSQUXCTA

The IBM-supplied example edit program in Assembler, named DSQUXCTA, is located in QMF sample library QMF720.SDSQSAPE on OS/390. The example program is heavily commented; you can print it, browse it online, or modify it to meet your needs. If you plan to use this program, copy it to your program library and change its name to DSQUECIC.

How an Assembler edit routine interacts with QMF

The interface control block between QMF and the user edit interface DSQUEDIT is DXEECS. It contains the user's edit code, identifies the source data and the target location for the edited result, and provides a scratchpad area for the user edit routine's use. The control block is persistent between calls to the user edit routine. The scratchpad area is not modified by QMF after the initial invocation of the exit routine.

Please refer to the DXEECSA file provided by QMF as a sample Assembly version of the DXEECS control block. This file is located in library QMF720.SDSQSAPE on OS/390, on the QMF production disk on CMS, or in the QMF sublibrary as DXEECSA.A on VSE.