Function
Set an error code and an explanatory message.
Syntax
#include <dx/dx.h>
Error DXSetError(ErrorCode e, char *message, ...)
#define DXErrorReturn(e,s) {DXSetError(e,s); return ERROR;}
#define DXErrorGoto(e,s) {DXSetError(e,s); goto error;}
Functional Details
Modules that return ERROR should in many cases also set the error code and error message. DXSetError provides the interface to do this, and needs to be called only once for each error.
If a Data Explorer function returns an error and sets an error code, the caller should usually return ERROR without using one of these routines, since the error message set by the Data Explorer function will usually be more informative. If the error code is set by the Data Explorer function and the calling program proceeds without returning ERROR, DXResetError should be called.
If the Data Explorer function does not set the error code, it is the calling function's responsibility to do so using one of these routines.
The message may be a printf format string, in which case additional arguments as required by the format string must be specified. Messages beginning with the pound sign, #, are reserved for system use.
Additional information can be added to an error message using the DXAddMessage function.
DXErrorReturn calls DXSetError and returns from the caller with return value ERROR.
DXErrorGoto calls DXSetError and goes to the label "error." This is useful when some clean-up activity is required (e.g., freeing allocated memory). It is the caller's responsibility to provide the "error" label in the code.
The error code e must be one of the following:
ERROR_ASSERTION ERROR_INTERNAL ERROR_NO_CAMERA ERROR_BAD_CLASS ERROR_INVALID_DATA ERROR_NO_MEMORY ERROR_BAD_PARAMETER ERROR_MISSING_DATA ERROR_NOT_IMPLEMENTED ERROR_BAD_TYPE ERROR_UNEXPECTED
Return Value
Always return ERROR.
See Also
DXAddMessage, DXMessageReturn, DXMessageGoto, DXMessage, DXResetError, DXWarning
13.1 , "Error Handling and Messages".