Purpose
Allocates a control scratchpad to propagate data from the table function control copy to all other copies running on all other AMP vprocs.
Syntax
void *
FNC_TblAllocCtrlCtx(int length)
- int length
- the size, in bytes, to allocate to the control scratchpad.
Return Value
FNC_TblAllocCtrlCtx returns the address of the control scratchpad that the control copy of the table function can use to propagate data to all other copies of the table function.
The return value is a NULL pointer if the control copy of the table function already allocated a control scratchpad or the scratchpad could not be allocated.
Valid Invocation Mode
Use this library function when the return value of FNC_GetPhase is TBL_MODE_CONST, indicating that the SELECT statement invoked the table function with constant expression input arguments. For example:
SELECT *
FROM TABLE (table_function_1('STRING_CONSTANT'))
AS table_1;
Usage Notes
Use the control scratchpad to keep track of what a table function is supposed to be doing and what it has left to do.
- The table function calls FNC_GetPhase and gets a value of TBL_PRE_INIT for the processing phase
- This copy of the table function establishes itself as the control copy of the table function by calling FNC_TblControl
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.
After the control copy of the table function completes the TBL_PRE_INIT processing phase, all copies of the table function (including the control copy) can gain access to the data that the control copy of the table function stores in the control scratchpad by calling FNC_TblGetCtrlCtx in any processing phase except for the TBL_PRE_INIT phase. Subsequent changes to the control scratchpad are considered local and are retained in the scratchpad for the next iterations of the local table function copy.
Restrictions
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.
- TBL_MODE_CONST for the mode
- TBL_PRE_INIT for the processing phase
Example Using FNC_TblAllocCtrlCtx
typedef struct {
unsigned short cntrl_fnc_AMP
int qfd;
...
} ctrl_ctx;
ctrl_ctx *options;
AMP_Info_t *LocalConfig;
FNC_Phase Phase;
if (FNC_GetPhase(&Phase) == TBL_MODE_CONST)
{
switch(Phase)
{
case TBL_PRE_INIT:
{
LocalConfig = FNC_AMPInfo();
if ( FNC_TblControl() )
{
options = FNC_TblAllocCtrlCtx(sizeof(ctrl_ctx));
options->ctrl_fnc_AMP = LocalConfig->AMPId;
...
}
}
...
}
}
...