The fetch_block v4 API method fetches a block of rows.
short fetch_block( a_v4_extfn_table_context *cntxt, a_v4_extfn_row_block **row_block)
The fetch_block method is used as an entry point when the consumer does not need the data in a particular format. fetch_block requests that the producer create a data transfer area and provide a pointer to that area. The consumer owns the memory and takes responsibility for copying data from this area.
The fetch_block is more efficient if the consumer does not require a specific layout. The fetch_block call sets a fetch_block to a block that can be consumed, and this block should be passed on the next fetch_block call. This method is part of the a_v4_extfn_table_context structure.
| Parameter | Description |
|---|---|
| cntxt | The table context object. |
| row_block | An in/out parameter. The first call should always point to a NULL row_block. |
When fetch_block is called and row_block points to NULL, the UDF must allocate a a_v4_extfn_row_block structure.
1 if successful, 0 otherwise.
If the UDF returns 1, the consumer knows that there are more rows left and calls the fetch_block method again. However, a UDF returning a value of 0 indicates that there are no more rows and a call to the fetch_block method is unnecessary.
Consider the following procedure definition, which is an example of a TPF function that consumes an input parameter table and produces it as a result table. Both are instances of SQL values that are obtained and returned through the get_value and set_value v4 API methods, respectively.
CREATE PROCEDURE FETCH_EX( IN a INT, INT b TABLE( c1 INT ) )
RESULT SET ( rc INT )
The following example shows how output tables are fetched from by the caller, in this case, the server. The server might decide to use the fetch_block method. Input tables are fetched from by the called entity, in this case the TPF, which decides which fetch API to use.
SELECT rc from FETCH_EX( 1, TABLE( SELECT c1 from TABLE ) )
The example shows that prior to fetching/consuming from an input table, a table context must be established via the open_result_set API on the a_v4_extfn_proc structure. The open_result_set requires a table object, which can be obtained through the get_value API.
an_extfn_value arg;
ctx->get_value( args_handle, 3, &arg );
if( arg.type != DT_EXTFN_TABLE ) {
// handle error
}
a_v4_extfn_table_context *rs = NULL;
a_v4_extfn_table *inTable = arg.data;
ctx->open_result_set( ctx, inTable, &rs );
After the table context is created, the rs structure executes the fetch_block API and fetches the rows.
a_v4_extfn_row_block *rb = // get a row block to hold a series of INT values. rs->fetch_block( rs, &rb ) // fetch the rows.
Prior to producing rows to a result table, a table object must be created and returned to the caller via the set_value API on the a_v4_extfn_proc_context structure.
This example shows that a table UDF must create an instance of the a_v4_extfn_table structure. Each invocation of the table UDF should return a separate instance of the a_v4_extfn_table structure. The table contains the state fields to keep track of the current row and the number of rows to generate. State for a table can be stored as a field of the instance.
typedef struct rg_table : a_v4_extfn_table {
a_sql_uint32 rows_to_generate;
a_sql_uint32 current_row;
} my_table;