Scalar UDF Context Structure

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;

Note: The get_piece callback is valid in v3 and v4 scalar and aggregate UDFs. For v4 table UDFs and TPFs, use the Blob (a_v4_extfn_blob) and Blob Input Stream (a_v4_extfn_blob_istream) structures instead.

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.

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), 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;
```

Scalar External Function Context: a_v3_extfn_scalar_context
Method of a_v3_extfn_scalar_context structure	Description
void set_cannot_be_distributed(a_v3_extfn_scalar_context * cntxt )	Distribution can be disabled at the UDF level, even if distribution criteria are met at the library level. By default, the UDF is assumed to be distributable if the library is distributable. It is the responsibility of the UDF to push the decision to disable distribution to the server.