|
In this section: |
The FOCSAM Interface contains a user exit that can be invoked as an alternative to the lowest-level retrieval routines that are part of the interface. This exit makes it possible to combine user-written code, devoid of any dependence on internal structures, with the logical retrieval functions of the FOCSAM Interface, such as record selection logic, treatment of missing records in multi-record files, JOINS between various types of files, etc. The major features of the GETPRV exit are as follows:
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:
The Dynamic GETPRV exit is linked as a separate module and loaded or called from FOCUS.
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.
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
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:
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).
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.
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.
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.
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.
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.
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.
The parameter list for the work area control block is:
An eight- character string containing the literal 'PRIVATE '.
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.
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).
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).
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.
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.
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).
Full-word binary integer, posted by the exit. It should contain the length of the above ERRTEXT message.
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.
Full-word binary integer, reserved for future use.
Full-word binary integer, posted by FOCSAM. This user ID will only be present if found in the central site security environment.
Full-word binary integer, reserved for future use.
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/*
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