Allocates a general scratchpad to retain data between iterations of a local table function copy.
FNC_TblAllocCtx returns the address of the general scratchpad that a local table function copy can use to retain data between iterations.
The return value is a NULL pointer if the table function already allocated a general scratchpad or the scratchpad could not be allocated.
- TBL_MODE_CONST, when the SELECT statement invoked the table function with constant expression input arguments
- TBL_MODE_VARY, when the SELECT statement invoked the table function using the columns from a derived table as input arguments
Syntax
void *
FNC_TblAllocCtx(int length)
Syntax Elements
- length
- the size, in bytes, to allocate to the general scratchpad.
The maximum length is 64 KB.
Usage Notes
Subsequent invocations of the table function can gain access to the scratchpad by calling FNC_TblGetCtx.
Do not store pointers in the scratchpad that reference other structures in the scratchpad, because the returned address of the scratchpad is not the same for subsequent invocations of the table function. Instead, use relative addressing, such as offsets from the current address of the scratchpad.
The general scratchpad is local to each copy of the table function for the current transaction or request running on each AMP vproc. It is not retained for subsequent transactions or requests.
The control copy of a table function can place a flag in the general scratchpad to remember that it is the control copy.
To get around the 64 KB maximum length of the scratch pad, call FNC_malloc and save the address in the scratchpad so that you can refer to it in subsequent calls. Remember to call FNC_free during the FNC_END or FNC_ABORT phase or you will get a memory not freed error.
This function can only be called from within a table function. Calling this function from a scalar function, aggregate function, UDM, or external stored procedure results in an exception on the transaction.
This function can only be called once.
Example Using FNC_TblAllocCtx
typedef struct {
unsigned short control_flag;
int qfd;
...
} scratchpad;
scratchpad *options;
FNC_Phase Phase;
if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)
{
switch(Phase)
{
case TBL_PRE_INIT:
{
if ( FNC_TblControl() )
{
options = FNC_TblAllocCtx(sizeof(scratchpad));
options->control_flag = 1;
...
}
}
...
}
}
...