# dispError

Logs an error to the Natural Access trace log.

#### Prototype

DWORD dispError (CTAHD ctahd, DWORD errcode, unsigned svcid, char *func, char *file, unsigned lineno, char *info, unsigned logerror)

Argument | Description
ctahd | Context handle.
errcode | Error code.
svcid | ID of the service that is reporting the error.
func | Pointer to the name of the function reporting the error.
file | Pointer to the name of the file containing the function.
lineno | Line number on which the error is reported.
info | Pointer to additional information about the error.
logerror | Boolean to determine whether error should be logged to Natural Access trace log.

#### Return values

errcode

#### Details

If logerror is TRUE (non-zero), dispError logs an error to the trace log. The error code is then returned as the result of this function.

dispError is typically called using one of the following macros: CTAERROR, CTALOGERROR, or CTALOGERRORINFO. These macros return the error value passed in. They can also be used directly to return the error value from a command function.

#define CTAERROR (crhd, err) \
dispError((crhd),(err),CTA_SYS_SVCID,\
funcname,__FILE__, __LINE__,NULL,0)
#define CTALOGERROR (crhd, err, svcid) \
dispError((crhd),(err),(svcid),\
funcname, __FILE__, __LINE__,NULL, 1)
#define CTALOGERRORINFO (crhd, err, svcid, info) \
dispError((crhd),(err),(svcid),funcname,\
__FILE__, __LINE__, info, 1)

The following table describes each of these macros:

Macro | Description
--- | ---
CTAERROR | CTAERROR (ctahd, errorcode) is used to return an error without logging information to ctdaemon. The dispatcher passes the error back to the caller and does nothing with it. Use this macro when minimum reporting is required and the error will be returned and logged by the caller. If no reporting is desired (for internal service functions), return the error code directly to the calling function.
CTALOGERROR | CTALOGERROR (ctahd, errcode, svcid) is used when logging a trace message associated with the service ID, error code, function name, file, and line number. This macro expands to a call to dispError with the arguments as informational elements. If tracing is enabled, an error is logged to ctdaemon and an error appears in the trace log. This method allows services to report errors. Developers can diagnose exactly which service and function caused the error even if the error is reported by multiple services.
CTALOGERRORINFO | CTALOGERRORINFO (ctahd, errcode, svcid, info) does the same thing as CTALOGERROR except it allows an extra character string argument to be passed. This string gets logged in the trace buffer as additional information associated with the error. If used, this string should contain a clear explanation why the error occurred so that diagnosis of error conditions is easy and efficient. This is important when generic errors are returned from multiple functions in the same service. CTALOGERROR and CTALOGERRORINFO can be used to report error conditions without returning an error or they can be used in a return statement. Both macros return the error code argument as a result.

These macros expand to pass the function name (func), file name (file), and line number (lineno) as arguments to dispError. Use the macro CTABEGIN (func) at the beginning of the function calling these macros to establish the function name as a local variable to be referenced in the macro expansion.

Call dispError through the appropriate macros whenever an error condition is encountered. It should be done unconditionally since all errors should be logged if logging is enabled. Services wanting to filter certain internal errors can check the CTA_TRACEMASK_SVC_ERRORS bit in the service or global trace mask before calling dispError. The CTA_TRACEMASK_SVC_ERRORS bit is not checked by dispError.

#### See also

dispApiError, dispLogTrace