get_value

Declaration

 short get_value(
		void *          arg_handle,
		a_sql_uint32    arg_num,
		an_extfn_value *value
		)

Usage

The get_value API is used in an evaluation method to retrieve the value of each input argument to the UDF. For narrow argument data types (>32K), a call to get_value is sufficient to retrieve the entire argument value.

The get_value API can be called from any API that has access to the arg_handle pointer. This includes API functions that take a_v4_table_context as a parameter. The a_v4_table_context has an args_handle member variable that can be used for this purpose.

For all fixed-length data types, the data is available in the returned value and no further calls are necessary to obtain all of the data. The producer can decide what the maximum length is that is returned entirely in the call to get_value method. All fixed length data types should be guaranteed to fit in a single contiguous buffer. For variable-length data, the limit is producer-dependant.

For nonfixed-length data types, and depending on the length of the data, a blob may need to be created using the get_blob method to get the data. You can use the macro EXTFN_IS_INCOMPLETE on the value returned by get_value to determine whether a blob object is required. If EXTFN_IS_INCOMPLETE evaluates to true, a blob is required.

For input arguments that are tables, the type is AN_EXTFN_TABLE. For this type of argument, you must create a result set using the open_result_set method to read values in from the table.

If a UDF requires the value of an argument prior to the _evaluate_extfn API being called, then the UDF should implement the _describe_extfn API. From the _describe_extfn API, the UDF can obtain the value of constant expressions using the describe_parameter_get method.

Parameters

Returns

1 if successful, 0 otherwise.

an_extfn_value Structure

The an_extfn_value structure represents the value of an input argument returned by the get_value API.

This code shows the declaration of the an_extfn_value structure:

 short typedef struct an_extfn_value {
		void*           data;
		a_sql_uint32    piece_len,
		an_extfn_value *value {
		                       a_sql_uint32    total_len;
		                       a_sql_uint32    remain_len;
		} len;
		a_sql_data_type    type;
} an_extfn_value;

This table describes what the returned values of an_extfn_value object look like after calling the get_value method:

The type field of an_extfn_value contains the data type of the value. For UDFs that have tables as input arguments, the data type of that argument is DT_EXTFN_TABLE. For v4 Table UDFs, the remain_len field is not used.