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.

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.

dispError

Prototype

Return values

Details

See also