ctaSetErrorHandler

Defines the action taken when an error is returned from any Natural Access functions, including any Natural Access service functions.

Prototype

DWORD ctaSetErrorHandler ( CTA_ERROR_HANDLER handler, CTA_ERROR_HANDLER *oldhandler)

Argument	Description
handler	Application error action. See the Details section for valid values.
oldhandler	Pointer to the returned previous application error action.

Return values

SUCCESS

Details

ctaSetErrorHandler defines how the application program traps programming errors. If an error is encountered when executing any Natural Access or Natural Access service command, Natural Access performs the error action before returning to the application.

Note: Do not call any functions from the application's error handler unless the code first sets a different error handler.

The error action is undertaken only when Natural Access functions or service functions are invoked; it is not undertaken if an error is returned by way of a CTA_EVENT structure.

By default, there is no error action. The application can specify any of the following error actions:

Error	Action
NULL	Restores the error handling action to the default of no action.
CTA_REPORT_ERRORS	Prints a brief message to stdout. The error code is then returned from the function to the application.
CTA_EXIT_ON_ERRORS	Prints the error as defined in CTA_REPORT_ERRORS and then invokes exit with a -1 exit code.
yourhandler	Pointer to an application call back function called by Natural Access.

The error handling function prototype is:

DWORD NMSSTDCALL yourhandler ( CTAHD ctahd, DWORD error, char *errtxt, char *func)

Argument	Description
ctahd	Context handle.
error	Error code as detected by Natural Access.
errtxt	Pointer to an error text description (see ctaGetText).
func	Pointer to the function name in which the error occurred.

Natural Access returns to the application whatever is returned from yourhandler. It is recommended that the errcode received is returned.

Refer to Handling Natural Access errors for more information.

Example

DWORD NMSSTDCALL myErrorHandler( CTAHD  ctahd, DWORD errorcode,
                                 char *errtxt, char *func )
{
    /* print out the error and exit */
    printf( "myErrorHandler: %s on ctahd=%#x, %s\n", errtxt, ctahd, func );
    exit(errorcode);
}
/* This makes more sense if we assume the main program called
* ctaSetErrorHandler(myErrorHandler, NULL); before calling this function. */
void DemoInitTrace()
{
    DWORD             ret;
    CTA_INIT_PARMS    initparms = { 0 };
    CTA_ERROR_HANDLER hdlr;

    /* Initialize size of init parms structure */
    initparms.size = sizeof(CTA_INIT_PARMS);

    /* If daemon running then initialize tracing */
    initparms.traceflags = CTA_TRACE_ENABLE;

    /* Set error handler to NULL and remember old handler */
    ctaSetErrorHandler(NULL, &hdlr);

    if ((ret = ctaInitialize(InitServices,
                             sizeof(InitServices)/sizeof(InitServices[0]),
                             &initparms)) != SUCCESS)
    {
        initparms.traceflags = 0; /* clear trace flags */

        ctaSetErrorHandler(hdlr, NULL); /* restore error handler */

        /* try to initialize again - will exit on failure */
        ctaInitialize(InitServices,
                      sizeof(InitServices)/sizeof(InitServices[0]),
                      &initparms);

        printf("Tracing disabled. Check that the daemon is running.");
    }
    else
        ctaSetErrorHandler(hdlr, NULL);  /* restore error handler */

    /* . . . */
}