Writing an edit routine in Assembler for CICS/VSE

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

• Interface control block, which is shipped with QMF as DXEECSA.A Use a COPY statement to include the interface control block in your source deck.
• CICS prolog macro DFHEIENT, which is shipped with CICS. The CICS epilog macro DFHEIRET is not needed for an EXEC CICS RETURN.
• CICS command interface modules, which are shipped with CICS as DFHEAI and DFHEAI0.
• Your edit exit program, which is named DSQUECIC

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

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

Example program DSQUXCTA

The IBM-supplied example edit program in Assembler, named DSQUXCTA.A, is located in the QMF sublibrary on VSE as DSQUXCTA.Z. 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 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.
  
• Register 13 contains the address of a standard CICS working storage area as described by CICS supplied macro DFHEISTG.

An Assembly DSECT for DXEECS is shipped with QMF as DXEECSA.A, located in the sublibrary where QMF is installed. Include DXEECSA.A into your program using the Assembler COPY statement.

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

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.

Refer to the DXEECSA file provided by QMF as a sample Assembler version of the DXEECS control block. This file is located in the QMF sublibrary as DXEECSA.A on VSE.

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.

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

Assembling your program on VSE

When you assemble your program, ensure the LIBDEF search chain includes the CICS and QMF sublibraries so that the CICS macros and the edit exit interface control block (DXEECSA.A) can be found. Use the following Assembler compiler options to assemble the routine:

'LIBMAC,USING(NOLIMIT,NOWARN),EXIT(LIBEXIT(EDECKXIT(ORDER=EA)))'

These compiler options require that you specify an E-deck exit. EDECKXIT is a library exit for Assembler that enables the processing of E-decks. This exit is required here to process CICS E-decks.

VSE/ESA provides a skeleton to help you set up the E-deck exit. You can use the skeleton without modifying it; however, before you use the skeleton, ensure you enable the exit according to instructions provided in the VSE Guide to System Functions.

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 VSE

Figure 67 on page 174 shows the sample job DSQ3XCTA.Z, which is shipped with QMF. This job translates, compiles, and link-edits the example Assembler program (DSQUXCTA.Z), which is also shipped with QMF. Use the sample job as a starting point to create JCL that translates, assembles, and link-edits your own edit exit routine. For more information on installing an Assembler program in CICS, see the CICS System Definition Guide.

// JOB DSQ3XCTA Install  QMF Edit Exit for COBOL                           
*  ---------------------------------------------------------------------------      
*  Install QMF Edit Exit (HLASM)                                                          
*  ----------------------------------------------------------------------------     
// SETPARM VOLID=volid   *-- update volid for syspch                                  
//  SETPARM START=rtrk     *-- update start track/block (syspch)                        
//  SETPARM SIZE=ntrks   *-- update number of tracks/blocks (syspch)
*------------------------------------------------------------------------------
//  DLBL   IJSYSPH,'ASM.TRANSLATION',0
//  EXTENT SYSPCH,,1,0,&STARTL,&SIZE.
    ASSIGN SYSPCH,DISK,VOL=&VOLID.,SHR
*   Library search chain must contain the QMF, CICS and HLASM sublibraries
//  LIBDEF *,SEARCH=(PRD2,PROD,PRD1.BASE,PRD2.CONFIG)
//  LIBDEF PHASE,CATALOG=PRD2.PROD
*------------------------------------------------------------------------------
//  STEP 1: Translate Edit ExitQMF720 program
*------------------------------------------------------------------------------
//  EXEC    DFHEAP1$
    :
    Assembly source program here
    :
/*
*-----------------------------------------------------------------------------
*   Step 2: Assemble Edit Exit program
CLOSE SYSPCH,00d
// DLBL   IJSYSIN,'ASM,TRANSLATION',0
// EXTENT SYSIPT
ASSGN SYSIPT,DISK,VOL=&VOLID.,SHR
// OPTION CATAL,DECK,SYM,ERRS

   PHASE DSQUECIC,*,SVA

         INCLUDE DFHEAI
         INCLUDE DFHEAI0

// EXEC ASMA90,SIZE=(ASMA90,50K),                                      C
               PARM='LIBMAC,USING(NOLIMIT,NOWARN),EXIT(LIBEXIT(EDECKXITC
               (ORDER=EA)))'
CLOSE SYSIPT,SYSRDR
/*
*------------------------------------------------------------------------
*  Step 3: Link-dit Edit Exit program
*------------------------------------------------------------------------
// EXEC LNKEDT,PARM='AMODE=31,RMODE=ANY'
/*
/&
// JOB  RESET
ASSGN SYSIPT,SYSRDR    IF 1A93D, CLOSE SYSIPT,SYSRDR
ASSGN SY;SPCH,00D      IF 1A93D, CLOSE SYSPCH,00D
/&