Exploring Every Record in a Database (lkt_dbexplore)

Warning: This command is deprecated. The lkt_dbrecnext command should be used instead.

 

This command executes a function explore, supplied by you, for every record in a database.

 

typedef void (*lexplore_t)(lpar_t, void *);
dvkerr_t lkt_dbexplore( lpar_t dbdesc, lpar_t explore_opts, 
                        lexplore_t explore, void *explparam );

The uses of such functionality are many: writing a database dump to a file or a socket, compilation of application-specific statistics, and so on.

Warning: The use of a remote database descriptor with lkt_dbexplore can be very bandwidth intensive if the database is large. The entire database is sent from the server to the client and the explore function is run on the client side.
Note: This command is not supported when working through a gateway. Attempts to use this command with a gateway returns a feature set not supported error. For more information on gateways see Federated Tables and Gateways.

 

Input

dbdesc (required)

is the descriptor of the database (LPAR_STR_DBDESCRIPTOR) to be explored.

For an explanation of descriptors see Communicating with TIBCO Patterns Servers.

explore_opts (optional)

is a list of lpars to control the exploration behavior.

The only supported option is an LPAR_INT_LOCKKEY to allow exploration of a locked database.

explore (required)

is a pointer to the function to be executed. This function is called exactly N times, where N is the number of records in database dbdesc. Explore is called with a record as the first parameter; this record is a copy of a record in dbdesc. This record object might be accessed, modified, and disposed of as you wish.

Note: No modification takes place in database dbdesc if you should modify a record passed to the explore function.

 

You are responsible for releasing the storage associated with the record, e.g., with a call to lpar_destroy.

The second parameter passed to explore is the generic pointer explparam (see next).

explparam (optional)

is a generic pointer (which might be NULL) that is passed through to all invocations of explore. You might use this pointer to pass arbitrary data to the explore function.

 

Error codes and items returned by lkt_dbexplore

FEATURESET

(none)

DBLOCKED

database descriptor

DBNOTFOUND

database descriptor

EXPECTDBDESC

item that should have been a database descriptor

NODBDESC

(none)

NOFUNCTION

(none)

NOSYSINIT

(none)

PARAMVAL

lpar that contains an illegal value