Adapters > Dynamic Private User Exit > FOCSAM and the GETPRV User Exit

FOCSAM and the GETPRV User Exit

Topics:

How to:

FOCSAM is the underlying logic for accessing keyed and sequential data sources within Information Builders products using a variety of low-level physical retrieval modules. FOCSAM contains a user exit that can be invoked as an alternative to the standard low-level retrieval routines that are part of FOCSAM. The exit makes it possible to combine user-written code (as a DLL) devoid of any dependence on the internal structures used within IBI products with the logical retrieval functions of FOCSAM, such as record selection logic, treatment of missing records in multi-record files, JOINS between various types of files, etc.

An Access File with a MODNAME= value determines the specific physical DLL loadable library to be used for a given table. The DLL itself must have a matching entry point by the same name as dictated by IBI standards for user written subroutines. The DLL must be physically in the EDACONF user directory, or the IBICPG environment variable must be set to indicate an alternate (directory) location. Any additional entry points within the same module may also be accessed, however, if other modules with additional entry points are needed the Private User Exit module must include "loader" logic to make the entry points available. (Note that these are the same rules used for all customers writing loadable DLL subroutines, as described in the Store Procedures Reference, which you can consult for the finer points of physically building a proper DLL.)

Procedure: How to Use the Dynamic Private Exit User Exit

This is an overview of the steps for using the Dynamic Private User Exit:

  1. Determine a record layout for the interaction between FOCSAM, the DLL, and any required keys. From the FOCSAM perspective this is the metadata layout within a given Master File. From the DLL perspective this is the structure of the record data being returned within one of the API pointers.
  2. Create a Master File with metadata that matches the chosen record layout.
  3. Create an Access File that specifies the DLL that will be used to access and return the record data.
  4. Design and create the DLL that will perform the data access and return the record data.
  5. Set the IBICPG environment variable to indicate the (directory) location of the DLL before server start up, or place the DLL in the EDACONF user directory.
  6. Access data as if it were just another table (although the actual specifics of the metadata and DLL are more involved).

General Features of the GETPRV Exit

The general features of the exit are:

  • The CONTEXT parameter, which supports reentrancy, reduces storage requirements, and enhances invocation performance.
  • Support for multiple concurrent exit processors provided through an Access File where a specific user exit module can be named on a per Master File basis.
  • Dynamic invocation of the user exit at execution time, without the need to recompile or re-link between major releases.

    Note: Since the exposed parts of the API are stable, the need for application code changes, re-compilation, or re-linking is unlikely between major releases. However, IBI reserves the right to make such changes and customers using the exits should safeguard their source code so that it will be available should such changes be required or should the application need to move to a new platform.

  • Initialization and shutdown calls that allow the exit to perform initial and final housekeeping.
  • Control and Read options:
    • Control options: (O) OPEN file, (R) OPEN request (position), (C) CLOSE, and (F) FIN (FOCUS FIN or WebFOCUS Agent Exit)
    • Read options: (S) Sequential Read, (G) Generic (GE) Read, and (E) Direct (EQ) Read options.
  • Maintain multiple positions on the same file for recursive Joins.

Functional Requirements for Using the GETPRV Exit

Functionally, the exit is a substitute for retrieval calls typically used against key-sequenced VSAM data sources or any data source that can be represented as such a file. The exit need not deal with intra-record structures represented by OCCURS phrases, nor with the translation of FOCUS IF/WHERE conditions into lower-level criteria. Both of these functions are performed by the driving logic within FOCSAM.

The user-written code must conform to the following rules:

  • The code must be able to obtain and return a record, given a full value of the key. The key is presumed to be unique (E Direct (EQ) Read) and only one access is attempted (no successive reads).
  • The code must be able to obtain and return a record greater than or equal to a given value of the full or partial key (G Generic (GE) Read) for initial positioning and retrieval purposes. After the initial retrieval, access switches to a sequential read until a change in key is detected and the position/retrieve (generic read) logic is repeated for any successive keys (for example, IF COUNTRY EQ ENGLAND OR ITALY) else ends retrieval (CLOSE). It is assumed the records being access and retrieved are in sort order to allow proper positioning and detection of key changes. If the exit application code uses an API to do retrieval specifics, sort order specifics may be masked or irrelevant, but the need for sort order retrieval becomes obvious when used in the context of a plain text file such as used in the reference sample.
  • The code must be able to obtain the next logical record, starting from the current position in the file (S Sequential Read). Successive sequential reads must return records in ascending sequence (bit by bit). No key or non-key information is passed except for subsequent sequential reads after a Generic (GE) Read on a secondary key. For simplicity (but not efficiency), the passed key information can also be ignored and the record returned as FOCSAM will be applying screening conditions also.
  • Direct and Generic Reads that retrieve records must establish the starting position in the file for subsequent sequential reads. Direct reads that fail to retrieve the requested records need not establish these positions as only the initial request is attempted.
  • For the open file request (O), the code must logically or physically open the file.
  • If the logical end-of-file is reached as a result of a sequential read, an end-of-file signal must be returned by setting the record return length to zero. Subsequent sequential reads must return end-of-file signals rather than error indications, for example, when processing a JOIN. Error condition handling variable should not be used to indicate end-of-file.
  • A close function must be provided that will result in the release of all resources and loss of position in the file, so that subsequent open requests will succeed.
  • Successive close calls must be innocuous. For example, they must be prepared to handle conditions such as a close of a file that is already closed, without generating error conditions.
  • A unique area may be obtained and maintained using the CONTEXT parameters on a per DDNAME basis.
  • The code must be serially reusable and re-entrant. This is the norm for modern compilers and linkers, but on MVS this would be linking as AMODE 31.

WebFOCUS

Feedback