1 /***********************************************************************/ 2 /* Open Visualization Data Explorer */ 3 /* (C) Copyright IBM Corp. 1989,1999 */ 4 /* ALL RIGHTS RESERVED */ 5 /* This code licensed under the */ 6 /* "IBM PUBLIC LICENSE - Open Visualization Data Explorer" */ 7 /***********************************************************************/ 8 9 10 #if defined(__cplusplus) || defined(c_plusplus) 11 extern "C" { 12 #endif 13 14 #ifndef _DXI_ERROR_H_ 15 #define _DXI_ERROR_H_ 16 17 /* TeX starts here. Do not remove this comment. */ 18 19 /* 20 \section{Error handling} 21 \label{errorsec} 22 23 In general, the routines in the Data Explorer library return either a 24 pointer, such as an object reference, or an integer error indication. 25 Success is indicated by returning a non-null pointer or by returning 26 the non-zero integer constant {\tt OK}. Failure is indicated by 27 returning {\tt NULL}, or by returning {\tt ERROR} (which is defined to 28 be zero). 29 30 In case of failure, the library routine may have set the error code by 31 calling {\tt DXSetError()}, in which case the calling routine generally 32 should just return {\tt NULL} or {\tt ERROR} to propagate the error 33 up. On the other hand, the library routine may not have set the error 34 code. In this case it is up to the calling routine to decide whether 35 the null return indicates an error, in which case the calling routine 36 should set the error code by calling {\tt DXSetError()}, and then return 37 {\tt NULL} or {\tt ERROR}; or whether the null return was not an 38 error, in which case the calling routine should proceed. This manual 39 documents for each routine whether it sets the error code when it 40 returns null. 41 42 The error codes are defined as follows: \index{errorcodes} 43 */ 44 45 typedef enum errorcode { 46 ERROR_NONE, 47 ERROR_INTERNAL, 48 ERROR_UNEXPECTED, 49 ERROR_ASSERTION, 50 ERROR_NOT_IMPLEMENTED, 51 ERROR_NO_MEMORY, 52 ERROR_BAD_CLASS, 53 ERROR_BAD_TYPE, 54 ERROR_NO_CAMERA, 55 ERROR_MISSING_DATA, 56 ERROR_DATA_INVALID, 57 ERROR_BAD_PARAMETER, 58 ERROR_NO_HARDWARE_RENDERING, 59 ERROR_MAX 60 } ErrorCode; 61 62 typedef int Error; 63 #ifndef ERROR 64 #define ERROR 0 65 #endif 66 #ifndef OK 67 #define OK 1 68 #endif 69 70 typedef void *Pointer; 71 72 #ifndef NULL 73 #define NULL 0 74 #endif 75 76 Error DXSetError(ErrorCode e, char *message, ...); 77 #define DXErrorReturn(e,s) {DXSetError(e,s); return ERROR;} 78 #define DXErrorGoto(e,s) {DXSetError(e,s); goto error;} 79 #define DXErrorGoto2(e,s1,s2) {DXSetError(e,s1,s2); goto error;} 80 #define DXErrorGoto3(e,s1,s2,s3) {DXSetError(e,s1,s2,s3); goto error;} 81 82 83 #define ASSERT _dxdAssert 84 #define DXASSERT _dxdAssert 85 #define DXASSERTGOTO _dxdAssert 86 #define DXDATAASSERTGOTO _dxdAssert 87 88 #define _dxdAssert(expression) \ 89 { if (!(expression)) { \ 90 DXMessage("Internal error detected at \"%s\":%d.\n", \ 91 __FILE__, __LINE__); \ 92 abort(); } } 93 94 95 96 /** 97 \index{DXSetError}\index{DXErrorReturn}\index{DXErrorGoto}\index{ASSERT} 98 Sets the error code plus an explanatory {\tt message}. The {\tt 99 message} may be a {\tt printf()} format string, in which case 100 additional arguments as required by the format string must be 101 specified. This is used internally to the Data Explorer library, and 102 a breakpoint may be set on this routine to determine more specifically 103 the cause of the error. Always returns {\tt ERROR}. See the Usage 104 Notes below. 105 **/ 106 107 Error DXAddMessage(char *message, ...); 108 #define DXMessageReturn(s) {DXAddMessage(s); return ERROR;} 109 #define DXMessageGoto(s) {DXAddMessage(s); goto error;} 110 /** 111 \index{DXAddMessage}\index{DXMessageReturn}\index{DXMessageGoto} 112 Concatenates {\tt message} onto the error message already recorded. 113 This is used to provide more information about an error detected in a 114 low level routine. The {\tt message} may be a {\tt printf()} format 115 string, in which case additional arguments as required by the format 116 string must be specified. Always returns {\tt ERROR}. See the Usage 117 Notes below. 118 **/ 119 120 ErrorCode DXGetError(void); 121 /** 122 \index{DXGetError} 123 Returns the error code for the last error that occurred, or {\tt ERROR\_NONE} 124 if no error code has been set. 125 **/ 126 127 char *DXGetErrorMessage(void); 128 /** 129 \index{DXGetErrorMessage} 130 Returns the current error message. This is a pointer to a static buffer 131 in local memory, so it must be copied if it is to be used outside the 132 scope of the calling routine. 133 **/ 134 135 void DXResetError(void); 136 /** 137 \index{DXResetError} 138 Resets the error state. This should be used after correcting an error so 139 that subsequent queries of the error state do not return an incorrect 140 indication. 141 **/ 142 143 void DXWarning(char *message, ...); 144 /** 145 \index{DXWarning} 146 Presents a warning message to the user. The message string should not 147 contain newline characters, because the {\tt DXWarning()} routine formats 148 the message in a manner appropriate to the output medium. For terminal 149 output, this includes prefixing the message with the processor identifier 150 and appending a newline. The {\tt message} may be a {\tt printf()} format 151 string, in which case additional arguments may be needed. 152 **/ 153 154 void DXMessage(char *message, ...); 155 void DXUIMessage(char *who, char *message, ...); 156 /** 157 \index{DXMessage}\index{DXUIMessage} 158 Presents an informative message to the user. The message string should not 159 contain newline characters, because the {\tt DXMessage()} routine formats 160 the message in a manner appropriate to the output medium. For terminal 161 output, this includes prefixing the message with the processor identifier 162 and appending a newline. The {\tt message} may be a {\tt printf()} format 163 string, in which case additional arguments may need to be specified. 164 **/ 165 166 void DXBeginLongMessage(void); 167 void DXEndLongMessage(void); 168 /** 169 \index{DXBeginLongMessage}\index{DXEndLongMessage} 170 The {\tt DXMessage()} routine as documented above is suitable for 171 relatively short, unformatted messages. For long, multiple line 172 messages, you may enclose a series of calls to {\tt DXMessage()} between 173 {\tt DXBeginLongMessage()} and {\tt DXEndLongMessage()}. In this case, 174 newlines are not automatically appended to each message, and it is 175 your responsibility to indicate appropriate line breaks by including 176 newline characters in the various {\tt DXMessage()} calls. For example, 177 multiple calls to {\tt DXMessage()} may be printed on the same line, or 178 one call to {\tt DXMessage()} may contain multiple lines. 179 **/ 180 181 void DXExpandMessage(int enable); 182 /** 183 The DXExpandMessage routine enables and disables the substitution of 184 messages by number from the messages file. if the text of a message 185 starts with #xxx, the text corresponding to that number in the messages 186 file is substituted for the number. setting enable to 0 disables this 187 feature. it is on by default. 188 **/ 189 190 void DXDebug(char *classes, char *message, ...); 191 void DXEnableDebug(char *classes, int enable); 192 int DXQueryDebug(char *classes); 193 /** 194 \index{DXDebug}\index{DXEnableDebug}\index{DXQueryDebug} 195 The {\tt DXDebug()} routine generates a debugging message. The {\tt message} 196 may be a {\tt printf()} format string, in which case additional arguments 197 may need to be specified. The {\tt classes} argument is a pointer to 198 a string of characters; each character identifies a debugging class to 199 which this message belongs. Each message may belong to more than one 200 debugging class. The {\tt DXEnableDebug()} routine enables ({\tt enable=1}) 201 or disables ({\tt enable=0}) one or more classes of debugging messages 202 specified by the {\tt classes} string. Normally modules should not 203 directly use {\tt DXEnableDebug()}, but should allow the user to enable or 204 disable debugging messages at run time by using the {\tt Trace} module. 205 {\tt DXQueryDebug} returns 1 if any of the debug classes specified by 206 the {\tt classes} argument are enabled, 0 if none of them are enabled. 207 **/ 208 209 /* 210 \paragraph{Usage notes.} 211 Generally, functions signal an error by returning null, in which case 212 the function should set an error code and an error message. This may 213 be done in one of three ways: 214 \begin{program} 215 DXErrorReturn(errorcode, message); 216 DXMessageReturn(message); 217 return ERROR; 218 \end{program} 219 The first method sets the error code and the error message, then 220 returns null; this should be done by the lowest level routine that 221 detects the error. The second method appends its own message to the 222 message already recorded; this should be done by routines 1) that have 223 detected an error return from a lower level routine that has already 224 set the error code, and 2) that have useful information to add to the 225 message. The third method is used when an error return is detected 226 from a lower level routine, and when the current routine has nothing 227 useful to add to the message. 228 229 Alternatively, if cleanup is required before returning, you may use 230 {\tt DXErrorGoto} or {\tt DXMessageGoto} instead of {\tt DXErrorReturn} or 231 {\tt DXMessageReturn}. When using {\tt DXErrorGoto} or {\tt DXMessageGoto}, 232 you must have an {\tt error:} label, which does cleanup and then returns null. 233 \begin{program} 234 error: 235 ... cleanup goes here ... 236 return ERROR; 237 \end{program} 238 */ 239 240 241 void DXSetErrorExit(int t); 242 /** 243 \index{DXSetErrorExit} 244 Controls the behavior of the program when an error occurs. If {\tt 245 t=0}, the error code is set and execution continues. If {\tt t=1}, 246 which is the default, the error code is set, an error message is 247 printed, and execution continues. If {\tt t=2}, the program prints an 248 error message and exits. This should only be used by standalone 249 programs, not by modules that are included as part of the Data 250 Explorer application. 251 **/ 252 253 void DXErrorExit(char *s); 254 /** 255 \index{DXErrorExit} 256 Prints an error message describing the last error(s) that occurred, 257 and the calls {\tt exit()} with the error code. This should only be 258 used by standalone programs, not by modules that are included as part 259 of the Data Explorer application. 260 **/ 261 262 void DXPrintError(char *s); 263 /** 264 \index{NULL}\index{OK}\index{DXPrintError} 265 Prints an error message describing the last error(s) that occurred. 266 This should only be used by standalone programs, not by modules that 267 are included as part of the Data Explorer application. 268 **/ 269 270 #endif /* _DXI_ERROR_H_ */ 271 272 #if defined(__cplusplus) || defined(c_plusplus) 273 } 274 #endif 275