Handling Natural Access errors

All Natural Access functions return one of the following codes:

• SUCCESS (0), indicating that either the function completed (synchronous functions) or that the function was initiated (asynchronous functions).

• An error code indicating that the function failed. Asynchronous functions that return a non-zero value are never initiated; therefore, no subsequent events are generated.

If an asynchronous function fails after being initiated, Natural Access delivers a DONE event to the application and the event value field contains an error code.

Error codes can also appear in the value field of a DONE event. Use the CTA_IS_ERROR macro to determine if a value is an error. The CTA_IS_ERROR macro is applicable only to DONE events.

Each service defines error codes in its header file. Natural Access error codes are defined in the ctaerr.h header file and are prefixed with CTAERR_. All services providing the same functionality provide consistent error codes. Use ctaGetText to obtain the text representation of an error code.

For a description of the Natural Access error codes, see the Alphabetical error summary.

This topic presents:

• Trapping errors

• Error tracing

• Server tracing

Trapping errors

Use ctaSetErrorHandler to define the action taken when an error is returned from any Natural Access functions, including any Natural Access service functions. If Natural Access encounters an error when executing a function, it performs the error action before returning to the application. The error action is undertaken only when Natural Access functions are invoked; it is not undertaken if an error is returned through an event.

By default, there is no error action. You can specify the following error actions:

• Print an error message to stdout and return to the application.

• Print an error message and exit Natural Access.

• Call a user-defined error handler.

Error tracing

Enable or disable tracing in the call to ctaInitialize. Services and the application can both log trace messages.

Enable service tracing by calling ctaSetTraceLevel and setting a flag to indicate what to trace (for example, events or commands). Based on the flags set, the service logs internal trace information to the ctdaemon.

Enable application tracing by calling ctaLogTrace and passing a trace severity, a format, and the trace value.

ctdaemon must be running to enable tracing. Using ctdaemon, you can specify to send trace messages to a file, to a console in interactive mode, or to a remote display. Refer to Natural Access Server: ctdaemon for more information.

Backtracing on errors

Natural Access provides a tracing option that allows you to receive a backlog of trace information on the context on which the error occurred.

To enable backtrace on error, change the traceflags field in the CTA_INIT_PARMS structure that is passed to ctaInitialize.

Enable this feature if you want to review command and event data leading up to errors. Do not enable this feature if you want to observe trace information for all contexts, whether or not you have errors.

To write all recently logged trace messages on a particular context to the Natural Access daemon, call ctaLogTrace, specifying the context you want to analyze, and set the traceseverity argument to CTA_TRACE_SEVERITY_ERROR.

Server tracing

Applications can use the following functions to start and stop the rtrace trace utility, set the global trace mask, and receive trace messages from Natural Access Server.