#!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
Generated by dwww version 1.15 on Sat Jun 22 12:47:25 CEST 2024.