ADM-XRC SDK 2.8.1 User Guide (Linux)
© Copyright 2001-2009 Alpha Data


ADMXRC_InstallErrorHandler

Prototype

ADMXRC_STATUS
ADMXRC_InstallErrorHandler(
    ADMXRC_HANDLER_FUNCTION Routine)

Arguments

Argument Type Purpose
Routine In The error handler routine to install

Return value

Value Meaning
ADMXRC_SUCCESS The error handler routine was successfully installed or uninstalled
ADMXRC_FAILED The error handler routine could not be installed because another thread held the error Mutex for an excessive period of time

Description

This function is used to install a user-defined error handler function that will be called whenever the ADM-XRC function must return an error condition. The error handler function should be of type ADMXRC_HANDLER_FUNCTION:

void
MyErrorHandler(
    const char*   FunctionName,
    ADMXRC_STATUS Code);

If Routine is non-NULL, it must point to a function of the same type as MyErrorHandler above. If Routine is NULL, any error handler function currently installed will be uninstalled.

A failed call to the ADMXRC_InstallErrorHandler function does not result in any currently installed handler function being called.

The error handler function is always called just before the API function generating the error returns. When the error handler is called, FunctionName will point to a NULL terminated string containing the name of the API function which failed and Code will contain the error code.

Due to the multithreaded nature of the API, mutual exclusion is enforced when the error handler is installed or called. When the error handler is installed, the API attempts to take a Win32 Mutex object, waiting for at most 1000 milliseconds for the wait to succeed. If the mutex wait fails due to timeout, ADMXRC_InstallErrorHandler returns ADMXRC_FAILED.

When the API calls the user specified error handler, the API attempts to take the same mutex in order to prevent the error handler being entered in a reentrant fashion. Therefore, the error handler routine should:

 


 Top of page