bf_fetch()

Purpose	Retrieves a record from the buffer
Syntax (CCOWN)	BOOLEAN bf_fetch(BF_HANDLE buffer,int flags,short *datarec, int index,int role,ADDITIONAL)
Syntax (DP4DBAPI)	BOOLEAN dp4_bf_fetch(DCONN * dconn,BF_HANDLE buffer,short *datarec,int flags int index,int role,int match_keys)
Parameters	DCONN * dconn	Handle to database connection
	BF_HANDLE buffer	Address of buffer
	int flags	Search method as described below
	short *datarec	Pointer to record variable
	int index	Index number of Index used
	int role	Role number of Index used
	int match_keys	Indicates number of leading key fields which must match the initial values in the record. In the DP4DBAPI implementation you must pass a value for this parameter, even if it will be ignored. In the CCOWN implementation this parameter is optional, and the value is ignored unless you specify the DEPTH value in flags.
Description	This function fetches a record from the buffer using the specified index and role. A system error is generated when the buffer is invalid for the specified table. The first call to the bf_fetch() function after the buffer is created, and subsequent calls where NO_FINDLIST is specified in flags: Discard the current contents, if any, of the buffer Automatically fill the buffer, using the contents of datarec as the key by calling the blk_fetch() Return the data for the first record in the buffer The buffer is ordered in the natural sequence implied by flags. In particular, the REVERSE flag is passed for PREV-type searches to stop the DBMS reordering the data. Subsequent calls to bf_fetch() work like this: If LAST or FIRST is passed (without NO_FINDLIST) and the buffer contains the appropriate record, that record is returned, otherwise processing continues as though NO_FINDLIST had been specified If neither FIRST, LAST, NO_FINDLIST, NEXT nor PREV are passed in flags, the same record is returned regardless of the contents of datarec, the indexes or other flags specified If neither FIRST, LAST nor NO_FINDLIST are passed in flags, but either NEXT or PREV are passed: the record adjacent to the record returned on the previous call is returned regardless of the contents of datarec, the indexes or other flags specified. If an adjacent record is returned but the buffer is exhausted, the buffer is refilled. bf_fetch() automatically determines whether a rec_fetch_main(EQUAL) is required before fetching records in the appropriate direction. This is the case when the buffer was previously filled in the opposite of the current direction It should be noted that the initial contents of the data record and the index passed are ignored for the purposes of extracting a record from the buffer. However, programs using this function cannot rely on this behaviour because they do not know when bf_fetch() will go to the DBMS to read data. Note that with this strategy it is possible to switch the direction of searches with a minimal overhead. For bf_fetch, the global variable depth is extracted from the generation field of records in the buffer; it is placed there by the blk_fetch() function, and there is also set to the return value of the function. Because the index and role parameters are ignored except when the buffer is to be refilled and should always be the same, you may wonder why they are not passed to the bf_open() function and stored as part of the buffer information. The reason is that passing them explicitly to each call to the bf_fetch() function makes it easy to call the rec_fetch() function if no buffer could be allocated at the time the bf_open() function was called.
Return values	Returns TRUE if a record was fetched, and FALSE if there was no matching record or an error occured.
Example	See the example for the cache_find() function