FOCSAM and the GETPRV User Exit
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.)
x
Procedure: How to Use the Dynamic Private Exit User Exit
This is an overview of the steps for
using the Dynamic Private User Exit:
-
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.
-
Create a Master File with metadata that matches the chosen
record layout.
-
Create an Access File that specifies the DLL that will
be used to access and return the record data.
-
Design and create the DLL that will perform the data
access and return the record data.
-
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.
-
Access data as if it were just another table (although
the actual specifics of the metadata and DLL are more involved).
xGeneral 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.
xFunctional 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.