Definition

Registers a user-defined function as the 'callback' function to be called when the given status code is about to be returned by the given Level 0 API function. This user-defined function must be defined to match SE_Error_Handling_Function_Signature (see).

This is the most specific type of callback - a specific status code for a specific function. This callback has priority over a general function callback for the same function (if one is currently defined), and it also has priority over the general callback function (if one is currently defined). 'Has priority over' means that if a specific status code/specific function callback is defined, then it is the only callback which will be called when that particular status code is about to be returned from that particular function.

When an SEDRIS Level 0 API function returns, it will return the the appropriate SE_Status_Code status code. If the user has defined a callback to be called when that particular status code is about to be returned by that particular function, then that user-defined callback function will be called immediately before the function returns the status code. After the user-defined callback has been called, the Level 0 API function will still return the status code it was about to return. The user-defined callback has no effect on the status code returned. Instead, the user-defined callback simply provides the user a method for tracking the return values of the Level 0 API functions without explicitly checking each return value with an 'if' or 'switch' statement.

Returns

SE_RET_CODE_SUCCESS	and the callback function is set.
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS

set if valid parameters were passed in.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_INACTIONABLE_FAILURE

set if function_to_catch and/or status_code_to_catch contained invalid values, or the call fails for any reason

Parameters Notes

user_defined_function

 a pointer to a user-defined callback
    function. If NULL, then this 'clears' the specific function/specific
    status code callback capability for the given function and the given
    status code.

function_to_catch

 the specific function for which user_defined_function
    is designed to be a callback.

status_code_to_catch

 the specific status_code which will trigger a
    call to the user_defined_function when that status_code is about to
    be returned by the function_to_catch function.

Prev: SE_SetSecondErrorMessage. Next: SE_SetTransmittalName. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™