The fetch_into v4 API method fetches data into a specified row block.
short fetch_into( a_v4_extfn_table_context *cntxt, a_v4_extfn_row_block *)
The fetch_into method is useful when the producer does not know how data should be arranged in memory. This method is used as an entry point when the consumer has a transfer area with a specific format. The fetch_into() function writes the fetched rows into the provided row block. This method is part of the a_v4_extfn_table_context structure.
Use fetch_into when the consumer owns the memory for the data transfer area and requests that the producer use this area. You use the fetch_into method when the consumer cares about how the data transfer area is set up and it is up to the producer to perform the necessary data copying into this area.
| Parameter | Description |
|---|---|
| cntxt | The table context object obtained from the open_result_set API |
| row_block | The row block object to fetch into |
1 if successful, 0 otherwise.
If the UDF returns 1, the consumer knows that there are more rows left and the fetch_into method should be called again. However, a UDF returning a value of 0 indicates that there are no more rows and a call to the fetch_into 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_into method. Input tables are fetched from by the called entity, in this case the TPF. The TPF 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_into API and fetches the rows.
a_v4_extfn_row_block *rb = // get a row block to hold a series of INT values. rs->fetch_into( 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;
In the following example, each time a row is produced, current_row is incremented until the number of rows to be generated is reached, when fetch_into returns false to indicate end-of-file. The consumer executes the fetch_into API implemented by the table UDF. As part of the call to the fetch_into method, the consumer provides the table context, as well as the row block to fetch into.
rs->fetch_into( rs, &rb )
short UDF_CALLBACK my_table_func_fetch_into(
a_v4_extfn_table_context *tctx,
a_v4_extfn_row_block *rb)
/*******************************************/
{
my_table *myTable = tctx->table;
if( rgTable->current_row < rgTable->rows_to_generate ) {
// Produce the row...
rgTable->current_row++;
return 1;
}
return 0;
}