User-coded Data Access Modules in VSAM

You can write a user routine to provide records to the FOCUS report writer from any non-standard data source not directly describable to FOCUS using the Master File. FOCUS treats the record, which can come from any data source, exactly as if it came from a FOCUS data source. The user routine must be coded as a subroutine in FORTRAN, COBOL, BAL, or PL/I, and must pass data to the FOCUS calling program through arguments in the subroutine.

The user program is loaded automatically by the report writer and is identified by the file suffix, in the Master File. If, for example, the Master File contains:

FILE = ABC, SUFFIX = MYREAD

FOCUS will load and call the program MYREAD to obtain data whenever a TABLE, TABLEF, MATCH, or GRAPH command is issued against file ABC.

The record returned to FOCUS must correspond to a segment instance in the Master File. The layout of the fields must correspond to the ACTUAL formats specified.

The user program is responsible for determining which segment to pass to FOCUS if the Master File has more than one segment. FOCUS will traverse the hierarchy in a top-to-bottom, left-to-right sequence; if the user routine can anticipate which segment FOCUS expects, the number of rejected segments will decrease and retrieval efficiency will improve.

In FORTRAN, the subroutine MYREAD would be coded as follows:

SUBROUTINE MYREAD (LCHAR, BUF, OFFSET, RECTYP, NERRX, CSEG, REGI, NFIND, MATCH, IGNOR, NUMFLD, NUMLEV, CVT)

where:

LCHAR

(4 byte integer) If LCHAR > 0, LCHAR is the number of characters in the record passed back to FOCUS. If LCHAR = 0, the user routine is telling FOCUS that an end-of-file has been encountered and the retrieval is complete. If LCHAR = -N, the user routine is telling FOCUS that the buffer contains an error message of length N, to be printed out, and that the user routine should not be called again. LCHAR = -1 is reserved for Information Builders use.

BUF

This parameter is a 4096 byte buffer provided by FOCUS to receive the record from the user routine.

OFFSET

(4-byte integer) If the user routine puts data in BUF, OFFSET should be set to 0 each time the user routine is called. If the user routine provides its own buffer or buffers, OFFSET is the address of the user's buffer minus the address of BUF. A utility called IADDR is provided to compute an address. In FORTRAN, for example, one could code:

OFFSET = IADDR (MYBUF) - IADDR (BUF)

RECTYP

(4-byte integer) The number of the FOCUS segment corresponding to the record being presented to FOCUS, set by the routine. These numbers correspond to either the list obtained by issuing '? FILE filename' or the field SEGNO resulting from a CHECK FILE filename HOLD.

NERRX

(4 byte integer) Flag set by FOCUS. If NERRX < 0, FOCUS is directing the user routine to shut down (for example, close all files) and not provide any more records. On return, FOCUS will not call the subroutine again.

CSEGX REGI NFIND MATCH

Reserved for use by Information Builders.

IGNOR

(4-byte integer) FOCUS will reject any segment whose number (see RECTYP) is greater than or equal to IGNOR. IGNOR is set by FOCUS, based on the segments referenced in the request, but may be reset by the user routine.

NUMFLD NUMLEV

Reserved for Information Builders. Use CVT.

On CMS, FOCUS looks for MYREAD TEXT on any accessed CMS minidisk. If MYREAD TEXT is not found, FOCUS next looks for member MYREAD within all TXTLIB files currently pointed at by a GLOBAL TXTLIB command.

On TSO, the MYREAD object code, and any other routine that it calls, must be link-edited into a load module in the load library with member name MYREAD. This load library can be allocated as ddname USERLIB or concatenated with the STEPLIB program library.