Calling Parameters and Work Areas

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).


Top of page

x
Reference: Calling 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.



x
Reference: Work Area Control Block Parameters

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.

0

Is the primary key in Master File, where ALIAS=KEY or DKEY.

1, 2, ...

Are secondary indexes in the Master File, where:

ALIAS= KEY1, KEY2 through KEYn and INDEX=I

or

ALIAS= DKEY1, DKEY2 through DKEYn and INDEX=I

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.



Example: Sample C Header File Implementation for Calling and Work Area Control Block Parameters

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


Example: Sample for SUFFIX=PRIVATE (getprv.c)

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.


WebFOCUS