#!F-adobe-helvetica-medium-r-normal--18*
#!N
#!CNavyBlue
#!N #!Rerrsec Error Handling and Messages #!N #!EC #!N #!N Most
Data Explorer library routines return either a pointer or an integer
error code. A non- #!F-adobe-times-bold-r-normal--18* NULL #!EF pointer or the nonzero
integer constant #!F-adobe-times-bold-r-normal--18* OK #!EF indicates success. #!F-adobe-times-bold-r-normal--18* NULL #!EF or
#!F-adobe-times-bold-r-normal--18* ERROR #!EF (defined as zero) indicates failure. #!N #!N If
a library routine fails, it may use #!F-adobe-times-bold-r-normal--18* DXSetError() #!EF to
set an error code. If it does, the (user-written) calling routine
should return #!F-adobe-times-bold-r-normal--18* NULL #!EF or #!F-adobe-times-bold-r-normal--18* ERROR #!EF to propagate
the error back to the user. #!N #!N However, if the
library routine does not set an error code, the calling routine
should determine whether the #!F-adobe-times-bold-r-normal--18* NULL #!EF return indicates an error:
#!N #!I0 #!N #!F-adobe-times-medium-r-normal--18* #!N #!N #!I30 #!N o If an
error is indicated, the calling routine should set an error code
(by calling #!F-adobe-times-bold-r-normal--18* DXSetError() #!EF ) and return #!F-adobe-times-bold-r-normal--18* NULL #!EF
or #!F-adobe-times-bold-r-normal--18* ERROR #!EF . #!N #!I30 #!N o If no
error is indicated, the calling routine should proceed. #!N #!I0 #!N
#!EF #!N #!N #!N For example, #!F-adobe-times-bold-r-normal--18* DXGetComponentValue() #!EF returns #!F-adobe-times-bold-r-normal--18*
NULL #!EF if the specified component does not exist, but it
does not set an error code: the calling routine must determine
whether the absence of that component is an error. #!N #!N
How any one Data Explorer routine handles error codes is described
in the relevant entry in #!Lallr,dxall1162 h Data Explorer Library Routines #!EL . #!N #!N The error
codes are defined as follows: #!CForestGreen #!N #!N #!F-adobe-courier-bold-r-normal--18* #!N typedef
enum errorcode { #!N ERROR_MIN, #!N ERROR_NONE, #!N ERROR_INTERNAL, #!N ERROR_UNEXPECTED,
#!N ERROR_ASSERTION, #!N ERROR_NOT_IMPLEMENTED, #!N ERROR_NO_MEMORY, #!N ERROR_BAD_CLASS, #!N ERROR_BAD_TYPE, #!N
ERROR_NO_CAMERA, #!N ERROR_MISSING_DATA, #!N ERROR_INVALID_DATA, #!N ERROR_BAD_PARAMETER, #!N ERROR_MAX #!N }
ErrorCode; #!EF #!N #!N #!EC #!CForestGreen #!N #!N #!F-adobe-courier-bold-r-normal--18* #!N typedef
int Error; #!N #define ERROR 0 #!N #define OK 1 #!N
typedef void *Pointer; #!N #undef NULL #!N #define NULL 0 #!EF
#!N #!N #!EC #!N #!I0 #!N #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18*
Error DXSetError() #!EF #!N #define DXErrorReturn() #!N #define DXErrorGoto() #!N #define
DXASSERT() #!EF #!I50 #!N Set an error code and an explanatory
message. See #!Lun,dxall1094 s Note on Use #!EL and #!Ldxse,dxall1377 h DXSetError, DXErrorReturn, DXErrorGoto #!EL . #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18*
Error DXAddMessage() #!EF #!N #define DXMessageReturn() #!N #define DXMessageGoto() #!EF #!I50
#!N Append a message to the current error message. See #!Lun,dxall1094 s Note on Use #!EL
and #!Ldxam,dxall1168 h DXAddMessage, DXMessageReturn, DXMessageGoto #!EL . #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* void DXWarning() #!EF
#!EF #!I50 #!N Presents a warning message to the user. See
#!Ldxw,dxall1407 h DXWarning #!EL . #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* void DXMessage() #!EF #!EF
#!I50 #!N Presents an informational message to the user. See #!Ldxmess,dxall1307 h DXMessage #!EL
. #!I0 #!N #!N #!CIndianRed #!N #!N #!N #!F-adobe-times-bold-r-normal--18* Note on
Use #!Run #!N #!N When a function signals an error by
returning #!F-adobe-times-bold-r-normal--18* NULL #!EF , it should also set an error
code and an error message, using one of the following error
routines: #!N #!I0 #!N #!F-adobe-times-medium-r-normal--18* #!N #!N #!I30 #!N 1. #!F-adobe-times-bold-r-normal--18*
DXErrorReturn(errorcode, message); #!EF Sets an error code and an error message,
then returns #!F-adobe-times-bold-r-normal--18* NULL #!EF ; this function should be invoked
by the lowest-level routine that detects the error. #!N #!I30 #!N
2. #!F-adobe-times-bold-r-normal--18* DXMessageReturn(message); #!EF Appends its own message to the message
already recorded; this should be done by routines that: #!N #!I0
#!N #!F-adobe-times-medium-r-normal--18* #!N #!N #!I30 #!N o Detect an error returned
by a lower-level routine that has already set an error code.
#!N #!I30 #!N o Contain useful information to add to the
message. #!N #!I0 #!N #!EF #!N #!N #!I30 #!N 3. #!F-adobe-times-bold-r-normal--18*
return ERROR; #!EF Is used when an error return is detected
from a lower-level routine and the current routine has nothing useful
to add to the message. #!N #!I0 #!N #!EF #!N If
cleanup is required before return, #!F-adobe-times-bold-r-normal--18* DXErrorGoto() #!EF or #!F-adobe-times-bold-r-normal--18* DXMessageGoto()
#!EF may be used instead. Both routines require an #!F-adobe-times-bold-r-normal--18* error:
#!EF label, after which cleanup is performed and either #!F-adobe-times-bold-r-normal--18* NULL
#!EF (as shown here) or #!F-adobe-times-bold-r-normal--18* ERROR #!EF is returned. #!CForestGreen
#!N #!N #!F-adobe-courier-bold-r-normal--18* #!N error: #!N #!N ... cleanup goes here
... #!N return NULL; #!N #!EF #!N #!N #!EC #!N #!N
#!EC #!N #!N #!F-adobe-times-bold-r-normal--18* LESS COMMONLY USED ROUTINES #!EF __________________________________ #!N
#!I0 #!N #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* ErrorCode DXGetError() #!EF #!EF
#!I50 #!N Returns an error code for the last error that
occurred. See #!Ldxge,dxall1235 h DXGetError #!EL . #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* char *DXGetErrorMessage()
#!EF #!EF #!I50 #!N Returns the current error message. See #!Ldxgerm,dxall1237 h DXGetErrorMessage #!EL
. #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* void DXResetError() #!EF #!EF #!I50
#!N Resets the error state. See #!Ldxre,dxall1359 h DXResetError #!EL . #!N #!I0 #!N
#!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18* void DXBeginLongMessage() #!EF #!N void DXEndLongMessage(); #!EF #!I50 #!N
Together create a single "long" message from multiple calls to #!F-adobe-times-bold-r-normal--18*
DXMessage() #!EF . See #!Ldxblm,dxall1175 h DXBeginLongMessage, DXEndLongMessage #!EL . #!N #!I0 #!N #!F-adobe-times-bold-r-normal--18* #!F-adobe-times-bold-r-normal--18*
void DXDebug() #!EF #!N void DXEnableDebug(); #!N int DXQueryDebug(); #!EF #!I50
#!N Operate on global debug keys. See #!Ldxdb,dxall1194 h DXDebug, DXEnableDebug, DXQueryDebug #!EL . #!N #!N
#!F-adobe-times-bold-r-normal--18* DXDebug() #!EF compares an Array of keys to the global
debug keys and calls #!N #!F-adobe-times-bold-r-normal--18* DXMessage() #!EF if any are
common to both. #!N #!F-adobe-times-bold-r-normal--18* DXEnableDebug() #!EF enables or disables one
or more global debug keys. #!N #!F-adobe-times-bold-r-normal--18* DXQueryDebug() #!EF compares an
Array of keys to the global debug keys and #!N returns
"1" if any are common to both. #!I0 #!N #!N #!N
#!N #!N #!F-adobe-times-medium-i-normal--18* Next Topic #!EF #!N #!N #!Ltimg,dxall1095 h Timing #!EL #!N #!F-adobe-times-medium-i-normal--18*
#!N