Dynamic and Re-Entrant Private User Exit of the FOCSAM Interface

Functional Requirements

Functionally, the private code is a substitute for retrieval calls typically used against, but not limited to, key-sequenced VSAM data sources and can be used against any data source that can be represented as such a file. The private code need not deal with any intra-record structures represented by OCCURS clauses, nor with the translation of FOCUS IF conditions into lower-level criteria. Both of these functions are performed by the driving logic in the FOCSAM Interface.

The user-written code must conform to following:

Must be able to obtain a record, given a full value of the key. The key is presumed to be unique (direct read).
Must be able to obtain a record greater than or equal to a given value of the full or partial key (generic read).
Must be able to obtain the next logical record, starting from the current position in the file (sequential read). Successive sequential reads must return records in ascending sequence (bit by bit) on the key field.
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.
For the open file request (O), it 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. Subsequent sequential reads must return end-of-file signals rather than error indications, for example, when processing a JOIN.
A 'close' function must be provided that results in the release of all resources and loss of position in the file, so that subsequent open requests succeed.
Successive close calls must be innocuous. Be prepared to close a file that is already closed.
A unique area must be obtained, for example, GETMAIN, and maintained using the CONTEXT parameter on a per DDNAME basis.
The code must be serially reusable and re-entrant. It must be linked AMODE 31.

Implementation

The Dynamic GETPRV exit is linked as a separate module and loaded or called from FOCUS.

Master File

The Master File for data to be accessed using this user exit is the same as the description of any other data source read by the FOCSAM Interface except that the SUFFIX must specify PRIVATE and a GROUP with ALIAS=KEY must be specified. All other READ ONLY features of the FOCSAM Interface are fully supported. For example,

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.

Access File

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.

For example,

MODNAME=pgmname,$

To allocate this Access File, enter:

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

Calling Sequence

The user-coded retrieval routine is written as a standalone program. There are no limitations to the program name other than standard IBM rules. It is recommended that the program be written in a language that fully 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).

DDNAME

Eight-byte character argument, posted by FOCSAM, 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.

KEY

Full-word binary integer posted by FOCSAM, 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 exact key length and its format. Used with options (E) and (G). Do not modify this parameter.

OPT

Four-byte character argument, posted by FOCSAM, 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 FOCSAM, which points to a work area described below. Do not modify this parameter.

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

Work Area Control Block

The parameter list for the work area control block is:

EYECATCH

An eight- 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 FOCSAM 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 FOCSAM 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 (R) processing by the exit program and returned unchanged by subsequent FOCSAM 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 FOCSAM.

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 FOCSAM. This user ID will only be present if found in the central site security environment.

RESERVE2

Full-word binary integer, reserved for future use.

Top of page

Example: Sample Assembler DSECT

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

Top of page

Example: Sample C Declaration Required For Invoking FFUN Function

/*
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