Scalar and Aggregate UDF Callback Functions

The set of callback functions are supplied by the engine through the a_v3_extfn_scalar_context structure and used within the user's UDF functions.

get_value – The function used within an evaluation method to retrieve the value of each input argument. For narrow argument data types (smaller than 256 bytes), a call to get_value is sufficient to retrieve the entire argument value. For wider argument data types, if the piece_len field within the an_extfn_value structure passed to this callback comes back with a value smaller than the value in the total_len field, use the get_piece callback to retrieve the rest of the input value.
get_piece – The function used to retrieve subsequent fragments of a long argument input value.
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.
get_is_constant – A function that determines whether the specified input argument value is a constant. This can be useful for optimizing a UDF, for example, where work can be performed once during the first call to the _evaluate_extfn function, rather than for every evaluation call.
set_value – The function used within an evaluation function to tell the server the result value of the UDF for this call. If the result data type is narrow, one call to set_value is sufficient. However, if the result data value is wide, then multiple calls to set_value are required to pass the entire value, and the append argument to the callback should be true for each fragment except the last. To return a NULL result, the UDF should set the data field within the result value's an_extfn_value structure to the null pointer.
get_is_cancelled – A function to determine whether the statement has been cancelled. If a UDF entry point is performing work for an extended period of time (many seconds), then it should, if possible, call the get_is_cancelled callback every second or two to see if the user has interrupted the current statement. The return value is 0 if the statement has not been interrupted.
SAP Sybase IQ can handle extremely large data sets, and some queries can run for long periods of time. Occasionally, a query takes an unusually long time to execute. The SQL client lets the user cancel a query if it is taking too long to complete. Native functions track when a user has canceled a query. UDFs must also be written in a manner that tracks whether a query has been canceled by the user. In other words, UDFs should support the ability for users to cancel long-running queries that invoke UDFs.
set_error – A function that can be used to communicate an error back to the server, and eventually to the user. Call this callback routine if a UDF entry point encounters an error that should result in an error message being sent back to the user. When called, set_error rolls back the current statement, and the user receives Error from external UDF: error_desc_string, and the SQLCODE is the negated form of the supplied error_number. To avoid collisions with existing errors, UDFs should use error_number values between 17000 and 99999. The maximum length of “error_desc_string” is 140 characters.
log_message – The function used to send a message to the server's message log. The string must be a printable text string no longer than 255 bytes.
convert_value – The function allows data conversion between data types. The primary use is the conversion between DT_DATE, DT_TIME, and DT_TIMESTAMP, and DT_TIMESTAMP_STRUCT. An input and output an_extfn_value is passed to the function.