Reference: |
A user-coded retrieval routine must be written as a standalone DLL program. There are few limitations to the program other than standard C rules and a program name length of 8. It is advisable to write the program in a language that fully supports dynamic memory allocation, such as ASSEMBLER or C. Languages like COBOL can also be used, but with certain limitations in the ability to access extended parameters and set permanent address memory on some platforms.
Note that non-char parameter sizes are stated in terms of longs and pointers: 4 bytes each for 32-bit applications and 8 bytes each for 64-bit applications.
The basic function of a user-coded routine is to provide calling parameters for opening, positioning, reading, and closing in order to populate work areas with records to be passed back. For details, see Calling Parameters and Work Area Control Block Parameters. A sample is also provided for your use (see Sample C Header File Implementation for Calling and Work Area Control Block Parameters).
The parameter list is as follows:
Parameter |
Definition |
---|---|
NCHAR |
Long, posted by the exit; a positive number indicates the length in bytes of the record obtained and being returned; a zero indicates no record retrieved or end-of-file has been reached (there is no functional difference). NCHAR must be set to a non-zero for every successful read that returns data. Used by read options (S), (E), and (G). |
DDN |
Eight-byte character argument, posted by FOCSAM. The value corresponds to the table name for the request. For example, TABLE FILE MYTABLE results in DDN (also known as DDNAME) of MYTABLE, left-justified and blank-padded. Used for all options except (F). Do not modify this parameter. The value is normally used to indicate the desired file to open unless the extended information parameter for filename is available and non-blank. |
ABUF |
Pointer, posted by the exit; the pointer is the absolute address of the record obtained and being returned to FOCSAM. Used with all read options (S), (E), and (G). Do not modify this pointer. Instead, modify the location addressed by the pointer. |
RC |
Long, return code posted by the exit. Zero indicates no error: non-zero indicates some type of error. Specific non zero values do not activate specific error handlers, there is only one handler and it returns a FOC1143 message. Specific text can be passed back in the extended information RETTEXT parameter so that the generic FOC1143 message and specific text may be displayed. Used with all options. |
KEY |
String of 255 bytes posted by FOCSAM, containing the full value of the key for direct or partial keys for generic reads. Not significant for sequential reads. The key value is left justified and limited to 255 bytes. Note that the exit must know the exact key length and its format. For simple cases with a single key, it may suffice to hard-code the value, else information may also be obtained from the extended information parameters. KEY is used with options (E) and (G). Do not modify this parameter. |
OPT |
Four-byte character argument, posted by FOCSAM; the value indicates the type of request. 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 (FOCUS FIN) - final housekeeping step should be done. These control and read arguments must include three trailing blanks. The standard C header file for the exit (getprv.h) may contain additional references for IBI use only and are not supported for customer purposes. |
* (getprv_info) |
Pointer, posted by FOCSAM, pointing to the extended information work area structure (getprv_info). For details, see Work Area Control Block Parameters 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 extension of the basic calling parameters. The list includes:
Parameter |
Definition |
---|---|
EYECATCH |
An eight-byte string, posted by FOCSAM. The value always contains the literal 'PRIVATE '. |
PFMCB |
Pointer, posted by the exit. The value is 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 |
Pointer, posted by the exit. The value is 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 DDN. This is generally used as a physical file context. This parameter is not valid for option (F). |
PFRPL |
Pointer, posted by the exit. The value is 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). |
KEYLEN_FIL |
Long, posted by FOCSAM. The value is set during option (O) processing by the exit and contains the whole key length for the file. |
KEYLEN_REQ |
Long, posted by FOCSAM. The value is set during options (G) and (E) processing by the exit and contains the actual key length for a direct read since it may be less than KEYLENF in a multi-field group key. |
ERRTEXT |
Pointer, posted by the exit. The value is the absolute starting address of an error message to be passed back. A FOC1143 and this message are displayed if the RC parameter returned by the exit is non-zero. |
LERRTEXT |
Long, posted by the exit. The value must contain the length of the above ERRTEXT message. |
INDEX |
Full-word binary integer, posted by FOCSAM, based on the Master Files metadata. This option contains the index # by which to access the file.
|
RESERVED1 |
Pointer, reserved for IBI use. |
USERID |
String of 8 bytes, posted by FOCSAM. The value is the user ID accessing the exit. |
TRACENUM |
Long, posted by the exit. The value must contain the number of lines in the TRACEARR pointer. |
TRACEARR |
Pointer, posted by the exit. The value is the absolute starting address of trace lines to be passed back and inserted into standard trace facilities. |
RESERVED2, RESERVED3 and RESERVE4D |
Set of three pointers, reserved for IBI use. |
FILENAME |
Pointer, posted by FOCSAM. The location of this pointer contains a file name if a FILEDEF or DDNAME has been issued for the table name. For example: FILEDEF MYTABLE DISK /home/ralph/myotherdata.ftm TABLE FILE MYTABLE ... END The pointer contains /home/ralph/myotherdata.ftm, and may be used to as an actual file to open or a flag to indicate a file or a feature. |
INDEXNAM |
String of 8 bytes, posted by FOCSAM. The value is the ALIAS of secondary keys when access is via a secondary key. Only one secondary key may access a given request, although the secondary key may be a GROUP consisting of multiple fields. |
RESERVED5 and RESERVED6 |
Set of two longs, reserved for IBI use. |
RESERVED7 |
Pointer, reserved for IBI use. |
For your convenience, the following file (getprv.h for SUFFIX=PRIVATE) is provided for inclusion in your C program. It contains both calling and work area control block parameters.
If you choose not to include this file, you are required to write and include your own header file in your C program.
typedef struct getprv_inf_s { char eye[8]; /* I: Eye Catcher "PRIVATE " */ void *pfmcb; /* O: Pointer to handle for getprv */ /* Set up by user at first option O */ /* I: Pointer to handle for getprv */ /* Passed to user by all other calls */ void *pfacb; /* O: Pointer to handle for file */ /* Set up by user at option O */ /* I: Pointer to handle for file */ /* Passed to user at option C,R,E,G,S */ void *pfrpl; /* O: Pointer to handle for request */ /* Set up by user at option R */ /* I: Pointer 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: Native db error msg text */ long lrettext; /* O: Length of native db error msg text */ long index; /* I: Index # by which to access file: */ /* 0 = Primary Key, (usually as a GROUP=) */ /* coded in MFD as ALIAS= KEY or DKEY */ /* 1, 2, ... = Secondary Indexes, */ /* coded in MFD as ALIAS = KEYn and INDEX=I */ /* or ALIAS = DKEYn and INDEX=I */
void* reserved1; /* IBI Use Only */ char userid[8]; /* User ID */ long tracenum; /* Number of 0 terminated trace lines */ char *tracearr; /* Array of trace lines */ void *reserved2; /* IBI Use Only */ void* reserved3; /* IBI Use Only */ char *reserved4; /* IBI Use Only */ char const *filename; /* Full path name for UNIX, Windows, OpenVMS, OS400 and USS. */
char indexnam[8]; /* For secondary indexes, ALIAS name from MFD otherwise */ /* blank. Populated prior to O (Open) option in FOCUS 7.2*/ /* and up. Field in MFD must have INDEX=I */ long reserved5; /* IBI Use Only */ long reserved6; /* IBI Use Only */ void* reserved7; /* IBI Use Only */ } getprv_inf_t ;
typedef void getprv_t ( long *nchar /* O: Length of data record read */ /* 0 = EOF or no record found */ /* Used in all read options S,E,G */ ,char *ddn /* I: DDName to read */ /* Used in all options except F */ ,char **abuf /* O: Address buffer to return records */ /* used in all read options S,E,G */ ,long *rc /* O: Return code. 0 if ok else non 0 */ /* Used in all options */ ,char *key /* I: Key value for read */ /* Used in read options E and G */
,char *opt /* I: 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 for extended info above */ );
Although the full sample (which is provided with the product) is too long to include in this document, the included section describes the requirements and steps for building and testing. The actual sample includes extensive annotation to serve as a model.
File |
Description |
---|---|
getprv.c |
The sample itself. |
getprv.h |
The h file used by the sample. |
getprv.mas |
Master file used by test request that call the sample. |
getprv.acx |
Access file used by test request that call the sample. |
getprv.ftm |
Data file used by test request that call the sample. |
getprv.fex |
Focexec test request that calls the table (.mas and .acx) used by the sample. |
If you do not already have the Master File, Access File, data or procedure (focexec), the getprv.c file explains how to create them. If you do not already have the getprv.c and getprv.h files contact Customer Support.
Set the EDAHOME environment variable to allow gencpgm to operate properly on the following platforms:
Platform |
Command |
---|---|
UNIX, USS and OS400 |
export EDAHOME=/home/iadmin/ibi/srv71/home |
OpenVMS |
DEFINE EDAHOME IWAY:[IADMIN.IBI.SRV71.HOME] |
Windows |
set EDAHOME=C:\ibi\srv71\home |
Using the appropriate platform specific path for gencpgm, build the DLL. For example on UNIX:
$EDAHOME/bin/gencpgm.sh -m cpgm getprv.c
For additional information about gencpgm usage and building DLLs if needed, see the Stored Procedures Reference.
Platform |
Command |
---|---|
UNIX, USS and OS400 |
export IBICPG='pwd' |
OpenVMS |
DEFINE IBICPG IWAY:[IWAY] |
Windows |
set IBICPG=C:\ibi |
Alternatively, you can use the EDACONF user directory as the working directory, in which case the DLLs will be picked up automatically.
To exercise with edastart x use an appropriate platform specific path. For instance:
/home/iadmin/ibi/srv71/ffs/bin/edastart -x ex getprv
WebFOCUS |