The scalar UDF context structure, a_v3_extfn_scalar_context that is passed to each of the functions specified within the scalar UDF descriptor structure, is defined as:
typedef struct a_v3_extfn_scalar_context { //-------- Callbacks available via the context -------- // short (SQL_CALLBACK *get_value)( void *arg_handle, a_sql_uint32 arg_num, an_extfn_value *value ); short (SQL_CALLBACK *get_piece)( void * arg_handle, a_sql_uint32 arg_num, an_extfn_value *value, a_sql_uint32 offset ); short (SQL_CALLBACK *get_value_is_constant)( void * arg_handle, a_sql_uint32 arg_num, a_sql_uint32 * value_is_constant ); short (SQL_CALLBACK *set_value)( void * arg_handle, an_extfn_value *value, short append ); a_sql_uint32 (SQL_CALLBACK *get_is_cancelled)( a_v3_extfn_scalar_context * cntxt ); short (SQL_CALLBACK *set_error)( a_v3_extfn_scalar_context * cntxt, a_sql_uint32 error_number, const char * error_desc_string ); void (SQL_CALLBACK *log_message)( const char *msg, short msg_length ); short (SQL_CALLBACK *convert_value)( an_extfn_value *input, an_extfn_value *output //---------- Data available from the context ---------- void * _user_data; // read-write field //---------- For Server Internal Use Only ------------- void * _for_server_internal_use; } a_v3_extfn_scalar_context;
The _user_data field within the scalar UDF context structure can be populated with data the UDF requires. Usually, it is filled in with a heap allocated structure by the _start_extfn function, and deallocated by the _finish_extfn function.
When you are allocating memory, make sure UDF libraries do not overload the C++ new operator. On some platforms, overloading the new operator has a global effect that may adversely affect the proper operation of the server.
The rest of the scalar UDF context structure is filled with the set of callback functions, supplied by the engine, for use within each of the user's UDF functions. Most of these callback functions return a success status through a short result value; a true return indicates success. Well-written UDF implementations should never cause a failure status, but during development (and possibly in all debug builds of a given UDF library), Sybase recommends that you check that the return status values from the callbacks. Failures can come from coding errors within the UDF implementation, such as asking for more arguments than the UDF is defined to take.
The common set of arguments used by most of the callbacks includes:
arg_handle – A pointer received by all forms of the evaluation methods, through which the values for input arguments passed to the UDF are available, and through which the UDF result value can be set.
arg_num – An integer indicating which input argument is being accessed. Input arguments are numbered left to right in ascending order starting at one.
cntxt – A pointer to the context structure that the server passes to all UDF entry points.
value – A pointer to an instance of the an_extfn_value structure that is used to either get an input argument value from the server or to set the result value of the function. The an_extfn_value structure has this form:
typedef struct an_extfn_value { void * data; a_SQL_uint32 piece_len; union { a_SQL_uint32 total_len; a_SQL_uint32 remain_len; } len; a_SQL_data_type type; } an_extfn_value;