The Dynamic and Re-Entrant GNTINT Private User Exit in VSAM

Major features of the exit are:

1. Through a CONTEXT parameter, GNTINT supports reentrancy, reducing storage requirements while enhancing performance.
2. Multiple concurrent exit processors are supported through an Access File which permits the naming of user exit modules on a per Master File basis.
3. The GNTINT user exit is called dynamically at execution, thus avoiding the need to modify FOCUS after each upgrade or maintenance run. There is no more need for link-edits to FOCUS.
4. An initialization call enables the exit code to perform initial housekeeping.
5. The QUALIF parameter supports processing options: (O) OPEN file, (R) OPEN request (position), (C) CLOSE, and (F) Fin of FOCUS, in addition to the (S), (G), and (E) read options.
6. The exit supports multiple positions in the same file.

GNTINT Functional Requirements in VSAM

Functionally, the private user exit code replaces retrieval calls typically used against, but not limited to, key-sequenced VSAM files, and can be used against any data source that can be represented as such. The user code need not deal with structures represented by OCCURS clauses, nor with translation of FOCUS IF conditions into lower-level criteria, functions now performed by GNTINT Interface logic.

The user-written code must be able to do the following:

1. Obtain a record, given a full value of the key. Keys are presumed to be unique (direct reads).
2. Obtain a record greater than or equal to a given value of the full or partial key (generic read).
3. Obtain the next logical record, starting from the current position in the file (sequential read). Successive sequential reads must return records in ascending key sequence (bit by bit).
4. 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.
5. For the open file request (O), it must logically or physically open the file.
6. If a logical end-of-file condition results from a sequential read, an end-of-file signal must be returned. Subsequent sequential reads must return end-of-file signals rather than error indications, for example, when processing a JOIN.
7. A 'close' function is required that releases all resources and gives up the current position in the file, enabling subsequent open requests to succeed.
8. Successive close calls must be innocuous (be prepared to close files that are already closed).
9. A unique area must be obtained, for example, GETMAIN, and maintained using the CONTEXT parameter on a per DDNAME basis.
10. The code must be serially reusable and reentrant. It must be linked AMODE 31.

GNTINT Implementation in VSAM

The Dynamic GNTINT User Exit is linked as a separate module and loaded or called from FOCUS.

The GNTINT Master File in VSAM

The Master File for data to be accessed using this user exit is exactly the same as the description of any other data source read by the GNTINT Interface except that the SUFFIX must specify PRIVATE. All other READ ONLY features of the GNTINT Interface are fully supported.

Example: Sample GNTINT Master File in VSAM

FILE=filename,  SUFFIX=PRIVATE,$
SEGNAME=ROOT ,  SEGTYPE=S0,$
GROUP=keyname   , ALIAS=KEY       , USAGE=xx, ACTUAL=xx  ,$
FIELD=fieldname1, ALIAS=aliasname1, USAGE=xx, ACTUAL=xx  ,$
FIELD=fieldname2, ALIAS=aliasname2, USAGE=xx, ACTUAL=xx  ,$

Note: SUFFIX=PRIVATE. No other options will invoke the exit.

The GNTINT Access File in VSAM

An Access File is required and provides a pointer to the actual name of the private exit. The PDS used for the Access File must be allocated to DDNAME ACCESS.

Example: Sample GNTINT Access File in VSAM

MODNAME=pgmname,$

Example: Allocating a GNTINT Access File in VSAM

//ACCESS  DD DSN=access.file.pds.name,DISP=SHR

Calling Sequence in VSAM

The user-coded retrieval routine is written as a standalone program. There are no limitations to program name other than standard IBM rules. We recommend writing the program in a language that supports reentrancy, such as ASSEMBLER or C. The parameter list is as follows:

NCHAR

Full-word binary integer, posted by the exit. A positive number indicates the length in bytes of the record obtained; zero indicates no record or end-of-file (there is no difference). Must be non-zero for every successful read. Used by read options (S), (E), and (G). Do not modify the pointer. Instead, modify the location addressed by the pointer.

DDNAME

8-byte character argument, posted by GNTINT, corresponding to the FOCUS file name for the generated report. For example, TABLE FILE CAR results in DDNAME CAR, left-justified and blank-padded. Used for all options except (F). Do not modify this parameter.

ABUFF

Full-word binary integer, posted by the exit; the absolute address of the record obtained by this call. Used with all read options (S), (E), and (G). Do not modify this pointer. Instead, modify the location addressed by the pointer.

RC

Full-word binary integer return code, posted by the exit. Zero indicates no error: non-zero indicates some type of error. Used with all options. Do not modify the pointer. Instead, modify the location addressed by the pointer.

KEY

Full-word binary integer posted by GNTINT, containing the full value of the key for direct or generic reads. Not significant for sequential reads. The key value is left justified and less than 255 bytes long.

Note that the exit must know the true key length and its format. Used with options (E) and (G). Do not modify this parameter.

OPT

Four-byte character argument, posted by GNTINT, indicating the type of call. Do not modify this parameter. The OPTions are as follows:

READ OPTIONS

'S ' =sequential read.

'E ' =direct read (EQ).

'G ' =generic read (GE).

CONTROL OPTIONS

'O ' =OPEN file.

'R ' =OPEN request (position) used for recursive JOINs.

'C ' =CLOSE file.

'F ' =FIN for FOCUS -- final housekeeping should be done here.

These control and read arguments must include three trailing blanks.

CONTEXT

Full-word binary integer, posted by GNTINT, which points to a work area described below. Do not modify this parameter.

Note: The parameters passed to the exit are not delimited with the final parameter having the high-order bit set on. Make sure that your program does not scan for this high-order bit.

Work Area Control Block in VSAM

EYECATCH

An 8-character string containing the literal 'PRIVATE '.

PFMCB

Full-word binary integer, posted by the exit. Generally set during OPTion (O) processing by the exit program and returned unchanged by subsequent GNTINT calls. This parameter is generally used to point to the dynamic work areas used to maintain reentrancy.

PFACB

Full-word binary integer, posted by the exit. Generally set during OPTion (O) processing by the exit program and returned unchanged by subsequent GNTINT calls for OPTions (C), (R), (E), (G), and (S) and is unique by DDNAME. This is generally used as a physical file context. This parameter is not valid for OPTion (F).

PFRPL

Full-word binary integer, posted by the exit. Generally set during option (OPT=R) processing by the exit program and returned unchanged by subsequent GNTINT calls for OPTions (E), (G), and (S) and is unique for each view within the above PFACB parameter. This is generally used for logical file context.

This parameter is not valid for OPTion (F).

KEYLENF

Full-word binary integer, posted by the exit. Generally set during OPTion (O) processing by the exit program and should contain the whole key length for the file.

KEYLENR

Full-word binary integer, posted by the exit. Generally set during OPTions (G) and (E) processing by the exit program and should contain the actual key length for a direct read.

ERRTEXT

Full-word binary integer, posted by the exit. Should contain the absolute starting address of a message. FOCUS displays this message if the RC parameter returned by the exit is non-zero and for OPTions (E), (G), and (S).

ERRTEXTL

Full-word binary integer, posted by the exit. It should contain the length of the above ERRTEXT message.

INDEX

Full-word binary integer, posted by GNTINT.

This option contains the index # by which to access the file.

0	Primary key in Master File in Master -- KEY-DKEY
1,2,e	Secondary indexes in the Master File
tc	KEY1-DKEY1 or KEY2-DKEY2, and so on, and INDEX=I

RESERVE1

Full-word binary integer, reserved for future use.

USERID

Full-word binary integer, posted by GNTINT. This userid will only be present if found in the central site security environment.

RESERVE2

Full-word binary integer, reserved for future use.

Example: Sample Assembler DSECT in VSAM

GETPRVPL DS    0F
NCHAR@   DS    A
DDN@     DS    A
ABUF@    DS    A
RC@      DS    A
KEY@     DS    A
OPT@     DS    A
CONTEXT@ DS    A
         TITLE 'GETPRV CONTEXT'
CONTEXTD DSECT
EYE      DS    CL8   eye catcher literal
PFMCB@   DS    A     handle
PFACB@   DS    A     file open handle
PFRPL@   DS    A     file retrieval handle
KEYLEN_F DS    F     key length for file
KEYLEN_R DS    F     key length for this request
RETTEXT@ DS    A     pointer to returned message
LRETTEXT DS    F     length of returned message
INDEX    DS    F     index for file access - 0 primary  1... secondary
         DS    A     reserved
USERID   DS    CL8
         DS    2F    reserved
         SPACE 1

Example: Sample C Declaration Required For Invoking FFUN Function in VSAM

/*
control block for additional info
*/
typedef struct getprv_inf_s {
char         eye[8];     /* I: eye catcher "PRIVATE "*/
Pvoid        pfmcb;      /* o: p' to handle forgetprv   */
                         /*    set up by user at first option O */
                         /* I: p' to handle for getprv   */
                         /*    passed to user by all other calls*/
Pvoid        pfacb;      /* o: p' to handle for file */
                         /*    set up by user at option O       */
                         /* i: p' to handle for file */
                         /*    passed to user at option C,R,E,G,S */
Pvoid        pfrpl;      /* o: p' to handle for request  */
                         /*    set up by user at option R       */
                         /* i: p' to handle for request  */
                         /*    passed to user at option E,G,S */
long         keylen_fil; /* I: key length (whole) for the file . */
                         /*    used at option O . */
long         keylen_req; /* I: key length for the direct read request*/
                         /*    used at direct read options  G,E  */
char        *rettext;    /* O: a'native db error msg text */
long         lrettext;   /* O: l'native db error msg text */

long         index;      /* I:index # by which to access file :
                             = 0    - primary key  
                                      in master - KEY|DKEY 
                             = 1,2,... - secondary indexes 
                                      in master - KEY1|DKEY1 or KEY2|DKEY2 ...
                                      and INDEX=I */
long         res1[1];    /* reserved */
char         userid[8];  /* user id */
long         res2[2];    /* reserved* /
} getprv_inf_t;
/*

*/
typedef  void FFUN getprv_t (
 long       *nchar      /* out: length of data record read. =0  */
                        /*      if eof or no rec found         {*/
                        /*     used in all read options S,E,G   */
,char       *ddn        /* in : ddname to read    */
                        /*     used in all options except F     */
,char       **abuf      /* out: a' buffer */
                        /*     used in all read options S,E,G   */
,long       *rc         /* out" return code. = 0 if ok */
                        /*     used in all options         */
,char       *key        /* in: key value for read */
                        /*     used in read options E,G   */

,char       *opt        /* in: read option : */
                        /*    S sequential read */
                        /*    G     GE read */
                        /*    E     EQ read */
                        /*     control options */
                        /*    O  open file */
                        /*    R  open request (position)*/
                        /*    C  close file */
                        /*    F  fin of focus */
,getprv_inf_t  *        /* in/out other info .see above */
);
#endif