Writing an edit routine for VM

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

• Interface control block, which is shipped with QMF as DXEECSA
• Control program, which is shipped with QMF as DSQUXIA
• Your edit exit program, which is named DSQUXDT

Figure 163 shows the program structure of an Assembly edit exit routine for VM.

Figure 163. Program structure of an Assembler edit exit routine for VM

Example program DSQUXDTA

The IBM-supplied sample edit program for Assembler, DSQUXDTA, is located in the QMF production disk. The sample program is commented so that you can modify it to suit your needs. If you plan to use this example program, copy it to your program library and change its name to DSQUXDT. Near the bottom of this file is a COPY statement for DXEECSA. which is a member of DSQUSERE MACLIB on OS/390. DXEECSA defines the input fields, giving them the names we are using in this chapter.

How an Assembler edit routine interacts with CMS

Linkage obeys the standard IBM calling conventions. On entry to your edit exit program, the following conditions exist:

• The parameter list contains three four-byte addresses. The addresses point to:
  • the control block
  • the value to be formatted
  • the storage reserved for the formatted results
  
• Register 13 contains the address of a standard SAVE area.
• Register 14 contains the caller's (QMF) return address.

An Assembler DSECT for DXEECS is shipped with QMF as DXEECSA, located in DSQUSERE MACLIB on CMS. Include this DSECT in your program using the Assembly COPY statement.

In the example program, the addresses are placed in registers 8, 9, and 10 through the statements:

ECSPTR    EQU R10
          L         ECSPTR,0(R1)
          USING     DXEECS,ECSPTR
ECSINPTP  EQU R9
          L         ECSINPTP,4(R1)
          USING     ECSINPT,ECSINPTP
ECSRSLTP  EQU R8
          L         ECSRSLTP,8(R1)
          USING     ECSRSLT,ECSRSLTP

The USING statements refer to the DSECTs defined in DXEECSA. These define the three parameters and their input-field components.

It follows that registers 10, 9, and 8 point, respectively, at the control block, the value to be formatted, and the storage reserved for the formatted results.

Return control to QMF using the standard convention by restoring the registers to their value at the time of the call, and returning to the address in register 14.

How an Assembler edit routine interacts with QMF

The interface control block between QMF and the user edit interface DSQUXDT 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. This 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.

Assembling and generating your program on CMS

Before you assemble your program, ensure that you can access the IBM-supplied control block DXEECSA, which is located in the QMF library DSQUSERE MACLIB on the QMF production disk. You need to access the QMF production disk and issue the CMS command GLOBAL MACLIB for the QMF macro library. For example:

GLOBAL MACLIB DSQUSERE

Assemble your edit program, DSQUXDT, using HLASM or the Assembly supplied with CMS.

Before you create the DSQUEDIT module file to generate your program, ensure that you can access the IBM-supplied control module (DSQUXIA). DSQUXIA is located on the QMF production disk. You need to access this disk prior to creating the module file.

To create the DSQUEDIT module file, use the CMS LOAD and GENMOD commands as follows:

1. Load the text files that make up the DSQUEDIT module. The DSQUEDIT module must be relocatable. To be relocatable, the module must be loaded with RLD entries. You do this by specifying the RLDSAVE option on the CMS LOAD command. The entry point to the DSQUEDIT module must be DSQUXIA. Issue the following CMS LOAD command:

   LOAD DSQUXIA DSQUXDT (RLDSAVE RESET DSQUXIA)

   You can run your edit routine in either 24-bit or 31-bit addressing mode. QMF manages address switching as required. You can specify 31-bit addressing on the CMS LOAD command. For example:

   LOAD DSQUXIA DSQUXDT (RLDSAVE RESET DSQUXIA AMODE 31 RMODE ANY)

2. Generate the DSQUEDIT module. Issue the CMS GENMOD command to generate the DSQUEDIT module from the text files just loaded by the CMS LOAD command:

   GENMOD DSQUEDIT (AMODE 31 RMODE ANY)

Once the user edit routine is tested it can be placed on the QMF production disk or user disk that is available when you start QMF.