Row block allocation is required when a producer produces data using the fetch_block method or when the consumer uses the fetch_into method to retrieve data.
udf_utils.cxx contains sample code that illustrates how to allocate and deallocate a row block.
These relevant data structures in the extfnapiv4.h header file are used when allocating a row block:
typedef struct a_v4_extfn_column_data { a_sql_byte *is_null; a_sql_byte null_mask; a_sql_byte null_value; void *data; a_sql_uint32 *piece_len; size_t max_piece_len; void *blob_handle; } a_v4_extfn_column_data; typedef struct a_v4_extfn_row { a_sql_uint32 *row_status; a_v4_extfn_column_data *column_data; } a_v4_extfn_row; typedef struct a_v4_extfn_row_block { a_sql_uint32 max_rows; a_sql_uint32 num_rows; a_v4_extfn_row *row_data; } a_v4_extfn_row_block;
When allocating a row block, the developer must decide how many rows the row block is capable of holding, how many columns each row has, and the number of bytes required for each of those columns.
For a row block of size m, where each row has n columns, the developer must allocate an array of m a_v4_extfn_row structures. For each row in this array, the developer must allocate n a_v4_extfn_column_data structures.
These tables outline allocation requirements for each member of the row block structures:
Field | Requirement |
---|---|
max_rows | Set to the number of rows this row block can hold |
num_rows | Initialize to zero. Is set to the number of actual rows a row block contains during usage |
*row_data | Allocate an array containing max_rows of a_v4_extfn_row structures |
Field | Requirement |
---|---|
*row_status | Allocate enough memory to hold an a_sql_uint32 |
*column_data | Allocate an array containing the number of columns in the result set of a_v4_extfn_column_data structures |
Field | Requirement |
---|---|
*is_null | Allocate enough memory to hold an a_sql_byte |
null_mask | Set to a value such that the formula (*is_null & null_mask) == null_value indicates a column value is NULL |
null_value | Set to a value such that the formula (*is_null & null_mask) == null_value indicates a column value is NULL |
*data | Allocate an array of bytes large enough to hold the data for the data type of the column |
*piece_len | Allocate enough memory to hold an a_sql_uint32 |
max_piece_len | Set to the maximum width for the column |
*blob_handle | Always owned by the server. Initialize to NULL. |