Writing an edit routine in COBOL for CMS without language environment (LE)

The QMF edit exit interface of COBOL consists of these parts:

• Interface control block, which is shipped with QMF as DXEECSC
• Control program, which is shipped with QMF as DSQUXIC
• Control macro, which is supplied by IBM as IGZOPT
• Control module, which is supplied by IBM as IGZERRE
• Your edit exit program, which is named DSQUXDT

Figure 174 shows the program structure of a COBOL edit exit routine

Figure 174. Program structure of a COBOL edit exit routine

Example program DSQUXDTC

The IBM-supplied example edit exit program in COBOL, named DSQUXDTC, is located in the QMF production disk on CMS. The example program is heavily commented; it can be browsed online, printed, or modified to suit your needs. If you plan to use this program, copy it to your program library and change its name to DSQUXDT. If you plan to write your own user edit routine, note that this routine contains a COPY statement for DXEECSC, which is a member of DSQUSERE MACLIB on CMS. It is DXEECSC that defines the input fields, giving them the names we are using in this chapter. It is best to include this in your own user edit routine.

How a COBOL edit routine interacts with QMF

The following statement begins the mainline logic:

PROCEDURE DIVISION USING DXEECS, ECSINPT, ECSRSLT

In this example, DXEECS is the name of the control block, ECSINPT is the name of the value to be formatted, and ECSRSLT is the name of the area reserved for the formatted result. The fields within these parameters are defined in DXEECSC.

The interface control block between QMF and the user edit interface DSQUXDT is DXEECS. It contains the user's edit code 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 edit routine. Return control to QMF with a GOBACK statement.

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

Compiling your program

Compile DSQUXDT (the edit exit program you have written). During the compile, QMF edit exit interface control block DXEECSC, located in in the DSQUSERE MACLIB on the QMF production disk on CMS, must be available in a macro library.

On CMS, you need to access the QMF and COBOL production disks. You also need to make the macro libraries available to the COBOL compiler by issuing a CMS GLOBAL MACLIB command. For example:

GLOBAL MACLIB DSQUSERE VSC2MAC

DXEECSC, as distributed by IBM, uses quotation marks ("") to delimit character literals. If your program uses apostrophes ('), you must either change DXEECSC as distributed by IBM or copy the structure to your program, changing quotes to apostrophes.

Select COBOL compiler options as follows:

• COBOL II

  Specify compiler options RENT, RES, NODYNAM, OBJECT, and LIB.

• COBOL/370 or IBM COBOL for OS/390 and VM

  Specify compiler options OBJECT, LIB, RENT, and NODYNAM.

QMF distributes the user edit routine control block DXEECSC using quotes as literal delimiters. You must use the QUOTE compiler option if you use the DXEECSC control block as distributed by IBM.

Assembling the run time options module

On CMS, use the C2CUSTL exec provided by IBM to assemble IGZOPT. Follow the prompts and add option STAE=NO to the IGZEOPT ASSEMBLE file. The new or changed option file is replaced in VSC2LTXT TXTLIB and VSC2LOAD LOADLIB, or in another TXTLIB and LOADLIB that you specify. Refer to VS COBOL II Installation and Customization for CMS for more information about assembling run time options.

Generating your program on CMS

Before you can create the module file, ensure that you can access the IBM-supplied control module (DSQUXIC). DSQUXIC 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 DSQUXIC. COBOL text libraries must be made available by issuing a CMS GLOBAL TEXTLIB command. Issue the following CMS commands:

      GLOBAL TXTLIB VSC2LTXT
      LOAD DSQUXIC DSQUXDT (RLDSAVE RESET DSQUXIC)

   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:

      GLOBAL TXTLIB VSC2LTXT
      LOAD DSQUXIC DSQUXDT
           (RLDSAVE RESET DSQUXIC AMODE 31 RMODE ANY)

2. 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 replace the DSQUEDIT module file on the QMF production disk or user disk that is available when you start QMF. In order to use the COBOL user edit routine, the COBOL production disk and run-time libraries need to be available when you start QMF.

When running under ISPF and starting QMF using the PGM form of ISPSTART, the COBOL run-time load libraries must be specified using a CMS FILEDEF command for ISPLLIB. For guidelines and considerations about COBOL programs running in ISPF, see the ISPF for VM Dialog Management Services and Examples manual.

When running without ISPF, or running under ISPF and starting QMF using the program segment form of ISPSTART, the COBOL run-time load libraries must be specified using a CMS GLOBAL LOADLIB command.

For detailed information on how to compile and make run-time libraries available for COBOL, see the VS COBOL II Application Programming Guide.