Coding Specialized Routines › User-Modules

User-Modules

This section describes the coding requirements of a user-supplied File Access Module (user-module) on the FILE command.

You can write user-modules in either Assembler or COBOL. Follow standard IBM linkage conventions when writing a user-module. Each module must save the general registers at entry and restore them at exit. In COBOL, the compiler provides these functions when ENTER LINKAGE, ENTRY, or RETURN is specified. In Assembler, use the SAVE and RETURN macros.

You must link edit the user-module and catalog it to a system Load Library with a unique phase name assigned to it. This phase name is then specified in the Reporting Facility program on the FILE command associated with the input file.

The system calls the user-module once for each GET command, or (in the case of the primary file) once per cycle. On return from the user-module, the Reporting Facility expects a single logical record to be made available for processing. The user-module must assume complete responsibility for the integrity of the file, including its opening and closing.

Two-way communication between the Reporting Facility and the user-module is established by the 80-byte Communications Area set up when the file is defined. On entry to the user-module from the Reporting Facility, register 1 points to a parameter list containing five fullwords. Each parameter is designed for a specific purpose and must be used accordingly.

A(I/O Area)

Is the address of the I/O area, where the user-module is expected to place a record for processing. This area is as large as specified in the RECORD= parameter of the FILE command.

A(Comm Area)

Is the address of the 80-byte Communications Area automatically allocated when the file is defined. This is the area to be used for communication between the Reporting Facility and the user-module.

A(filename)

Is the address of the file name, as specified on the FILE command, padded to a length of eight characters with blanks. If multiple files are read using the same user-module, this parameter enables the user-module to determine which file name was coded on the GET command for the current call.

Original R1

Contains the original contents of register 1. On initial entry to the Reporting Facility, this is required to process IMS-DL/I files.

A(recordlength)

Is the address of a two-byte binary record length field in the GSA that contains the value specified in the RECORD= parameter of the FILE command for this file. Use this parameter to edit against the size of a data record to avoid a core overlay condition.

Examples

The following example illustrates the linkage conventions to follow when coding a user-module in Assembler language:

csect  START 0
	SAVE (14,12)                 Store callers registers
       BALR  11,0                   Set up base addressability
       USING *,11
       ST    13,ST13                Store savearea pointer
       LM    2,6,0(1)               Load RPT Facility parameters
       .
       .                            Program body
       .
       L     13,ST13                Restore savearea address
       RETURN (14,12)               Restore callers registers and return
       .
       .
       .
       ST13 DS F
       .
       .
       END

The following example illustrates the linkage conventions for coding a user-module in COBOL:

         IDENTIFICATION DIVISION
	  PROGRAM-ID.      'modulename'
           .
           .
         DATA DIVISION
           .
           .
         LINKAGE SECTION.
         01  IO-BUFFER
                               PIC X(nnn).      ** RECORD=nnn **
         01  COMMUNICATION-AREA
                               PIC X(80).
         01  FILE-NAME
                               PIC X(4).
         01  DUMMY
                               PIC X(4).
         01  RECORD-LENGTH
                               PIC 99 COMP.
           .
           .
         PROCEDURE DIVISION.
         ENTER LINKAGE.
         ENTRY 'modulename' USING IO-BUFFER
                                 COMMUNICATION-AREA
                                 FILE-NAME
                                 DUMMY
                                 RECORD-LENGTH
         ENTER COBOL.
           .
           .
         ENTER LINKAGE.
         RETURN.
         ENTER COBOL.

Note the following:

• When operating in a VS or z/VSE environment, the user-module should be link edited to the Core Image Library specifying a phase origin of * (asterisk). However, one module in a run of the Reporting Facility cannot be coded as self-relocating. If you do have one that is not self-relocating, you must catalog it immediately following the Reporting Facility root phase.
• When OPTION MAP is specified, the size of the root phase prints on the last line of the compile diagnostics. Link your non-self relocating module as PLUS that number.
• You can load multiple copies of a user-module during a single run of the Reporting Facility; each is processed separately. You can accomplish this by specifying multiple FILE commands that have the same module name, but a unique file name.