The set of callback functions supplied by the engine through the a_v3_extfn_scalar_context structure and used within the user's UDF functions include:
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.
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.
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.