1 /* ncbierr.h 2 * =========================================================================== 3 * 4 * PUBLIC DOMAIN NOTICE 5 * National Center for Biotechnology Information 6 * 7 * This software/database is a "United States Government Work" under the 8 * terms of the United States Copyright Act. It was written as part of 9 * the author's official duties as a United States Government employee and 10 * thus cannot be copyrighted. This software/database is freely available 11 * to the public for use. The National Library of Medicine and the U.S. 12 * Government have not placed any restriction on its use or reproduction. 13 * 14 * Although all reasonable efforts have been taken to ensure the accuracy 15 * and reliability of the software and data, the NLM and the U.S. 16 * Government do not and cannot warrant the performance or results that 17 * may be obtained by using this software or data. The NLM and the U.S. 18 * Government disclaim all warranties, express or implied, including 19 * warranties of performance, merchantability or fitness for any particular 20 * purpose. 21 * 22 * Please cite the author in any work or product based on this material. 23 * 24 * =========================================================================== 25 * 26 * $Id: ncbierr.h,v 6.8 2006/07/13 17:10:36 bollin Exp $ 27 * 28 * $Revision: 6.8 $ 29 * 30 * Authors: Schuler, Sirotkin (UserErr stuff) 31 * 32 * Version Creation Date: 9-19-91 33 * 34 * File Description: Error handling functions 35 * 36 * Modifications: 37 * -------------------------------------------------------------------------- 38 * Date Name Description of modification 39 * -------- ----------- ----------------------------------------------------- 40 * 12-10-93 Schuler Major Revision. New APIs include: ErrPostEx, 41 * ErrSetMessageLevel, ErrSetFatalLevel, 42 * 10-20-94 Schuler Rearranged some things to make CodeCenter happy 43 * 11-18-94 Schuler Changed return type of Get/SetXXXLevel() family 44 * of functions from int to ErrSev to eliminate warnings 45 * 46 * $Log: ncbierr.h,v $ 47 * Revision 6.8 2006/07/13 17:10:36 bollin 48 * use Uint4 instead of Uint2 for itemID values 49 * 50 * Revision 6.7 2001/07/12 21:58:03 vakatov 51 * Introduced #NLM_NO_TRACE (define it if you need to prohibit macro #TRACE) 52 * 53 * Revision 6.6 2001/02/08 22:27:04 vakatov 54 * + Nlm_CallErrHandlerOnly() -- to allow processing of posted 55 * err.messages by the hook only. 56 * 57 * Revision 6.5 1999/10/01 14:41:39 kans 58 * added SEV_REJECT between SEV_ERROR and SEV_FATAL 59 * 60 * Revision 6.4 1999/05/20 20:07:03 sirotkin 61 * ErrPostItem bullet proofed as per vakatov 62 * 63 * Revision 6.3 1998/10/22 16:52:41 shavirin 64 * Added function *Nlm_GetErrLongText able to retrieve long error messages 65 * 66 * Revision 6.2 1997/11/04 19:08:36 ostell 67 * added ErrGetUserStrings() to eliminate direct access to ErrDesc.userstr 68 * so this could become a thread specific chain 69 * 70 * Revision 6.1 1997/08/27 20:40:27 kans 71 * added ErrPathReset 72 * 73 * Revision 6.0 1997/08/25 18:15:27 madden 74 * Revision changed to 6.0 75 * 76 * Revision 5.2 1996/12/03 21:48:33 vakatov 77 * Adopted for 32-bit MS-Windows DLLs 78 * 79 * Revision 5.1 1996/11/25 19:03:33 vakatov 80 * Moved 'busy' flag to the one-per-thread ErrMsgRoot() structure 81 * (it was static before and caused a lot of MT-mess). 82 * Added Nlm_ErrGetLogfile() and Nlm_AbnormalExitPure() f-protos. 83 * Added ASSERT_HARD() and VERIFY_HARD() macros calling 84 * Nlm_AbnormalExitPure() instead of Nlm_AbnormalExit(). 85 * 86 * Revision 5.0 1996/05/28 13:18:57 ostell 87 * Set to revision 5.0 88 * 89 * Revision 4.0 1995/07/26 13:46:50 ostell 90 * force revision to 4.0 91 * 92 * Revision 2.30 1995/05/15 18:45:58 ostell 93 * added Log line 94 * 95 * 96 * 97 * ========================================================================== 98 */ 99 100 #ifndef _NCBIERR_ 101 #define _NCBIERR_ 102 103 #include <ncbilcl.h> 104 #include <ncbistd.h> 105 #include <ncbimisc.h> 106 107 #undef NLM_EXTERN 108 #ifdef NLM_IMPORT 109 #define NLM_EXTERN NLM_IMPORT 110 #else 111 #define NLM_EXTERN extern 112 #endif 113 114 115 #ifdef __cplusplus 116 extern "C" { 117 #endif 118 119 #ifndef THIS_FILE 120 #define THIS_FILE __FILE__ 121 #endif 122 #ifndef THIS_MODULE 123 #define THIS_MODULE "" 124 #endif 125 126 #ifdef OS_UNIX 127 #define ERRTEXT_MAX 1024 128 #else 129 #define ERRTEXT_MAX 512 130 #endif 131 #define CODESTR_MAX 64 132 #define MODSTR_MAX 32 133 #define SRCFILE_MAX 92 134 135 #ifdef _DEBUG 136 #define DBFLAG 1 137 #else 138 #define DBFLAG 0 139 #endif 140 141 142 #define E_NoMemory 1 143 #define E_File 2 144 #define E_FOpen 3 145 #define E_FRead 4 146 #define E_FWrite 5 147 #define E_CdEject 9 148 #define E_Math 4 149 #define E_SGML 3 150 #define E_Programmer 999 151 152 153 typedef struct ErrMsgNode 154 { 155 struct ErrMsgNode *next; 156 struct ErrMsgNode *list; 157 const char *name; 158 int code; 159 int sev; 160 long cofs, clen; 161 long tofs, tlen; 162 const char *cstr; 163 const char *tstr; 164 } ErrMsgNode; 165 typedef const ErrMsgNode *ErrMsgNodePtr; 166 167 typedef struct ErrMsgRoot 168 { 169 struct ErrMsgRoot *next; 170 struct ErrMsgNode *list; 171 const char *name; 172 int busy; 173 } ErrMsgRoot; 174 typedef const ErrMsgRoot *ErrMsgRootPtr; 175 176 typedef struct ErrDesc 177 { 178 short severity; 179 short context; /* OBSOLETE */ 180 char module[MODSTR_MAX]; 181 int errcode; 182 int subcode; 183 char codestr[CODESTR_MAX]; 184 char srcfile[SRCFILE_MAX]; 185 int srcline; 186 char errtext[ERRTEXT_MAX]; 187 const ValNode *userstr; 188 const ErrMsgRoot *root; 189 const ErrMsgNode *node; 190 Nlm_Uint2 entityID, itemtype; /* for gather.c messages */ 191 Nlm_Uint4 itemID; 192 } ErrDesc; 193 typedef const ErrDesc *ErrDescPtr; 194 195 typedef struct ErrOpts 196 { 197 unsigned long flags; 198 short log_level; 199 short msg_level; 200 short die_level; 201 short actopt; 202 short logopt; 203 } ErrOpts; 204 typedef const ErrOpts *ErrOptsPtr; 205 206 207 /* prototype for user-supplied error handler */ 208 typedef int (LIBCALLBACK *ErrHookProc)(const ErrDesc *err); 209 210 /***************************************************************************\ 211 | POSTING AN ERROR | 212 \***************************************************************************/ 213 214 enum _ErrSev { SEV_NONE=0, SEV_INFO, SEV_WARNING, SEV_ERROR, SEV_REJECT, SEV_FATAL, SEV_MAX }; 215 typedef enum _ErrSev ErrSev; 216 217 #define SEV_MIN SEV_INFO 218 219 220 NLM_EXTERN void CDECL Nlm_ErrPost VPROTO((int ctx, int code, const char *fmt, ...)); 221 NLM_EXTERN int CDECL Nlm_ErrPostEx VPROTO((ErrSev sev, int lev1, int lev2, const char *fmt, ...)); 222 NLM_EXTERN int LIBCALL Nlm_ErrPostStr PROTO((ErrSev sev, int lev1, int lev2, const char *str)); 223 NLM_EXTERN void CDECL Nlm_ErrLogPrintf VPROTO((const char *fmt, ...)); 224 NLM_EXTERN void LIBCALL Nlm_ErrLogPrintStr PROTO((const char *str)); 225 NLM_EXTERN int LIBCALL Nlm_ErrSetContext PROTO((const char *ctx, const char *fn, int ln, int db, Nlm_Uint2 entityID, Nlm_Uint4 itemID, Nlm_Uint2 itemtype)); 226 227 #define ErrPost \ 228 (Nlm_ErrSetContext(THIS_MODULE,THIS_FILE,__LINE__,DBFLAG,0,0,0)) ? (void)0 : \ 229 Nlm_ErrPost 230 231 #define ErrPostEx \ 232 (Nlm_ErrSetContext(THIS_MODULE,THIS_FILE,__LINE__,DBFLAG,0,0,0)) ? 0 : \ 233 Nlm_ErrPostEx 234 235 #define ErrPostStr \ 236 (Nlm_ErrSetContext(THIS_MODULE,THIS_FILE,__LINE__,DBFLAG,0,0,0)) ? 0 : \ 237 Nlm_ErrPostStr 238 239 #define ErrPostItem \ 240 ( Nlm_ErrSetContext(THIS_MODULE,THIS_FILE,__LINE__,DBFLAG, \ 241 gcp ? gcp->entityID : 0, \ 242 gcp ? gcp->itemID : 0, \ 243 gcp ? gcp->thistype : 0)) ? 0 : \ 244 Nlm_ErrPostEx 245 246 #define ErrLogPrintf Nlm_ErrLogPrintf 247 #define ErrLogPrintStr Nlm_ErrLogPrintStr 248 249 /***************************************************************************\ 250 | FETCHING AND REPORTING ERRORS | 251 \***************************************************************************/ 252 NLM_EXTERN int LIBCALL Nlm_ErrFetch PROTO((ErrDesc FAR *err)); 253 NLM_EXTERN int LIBCALL Nlm_ErrCopy PROTO((ErrDesc FAR *err)); 254 NLM_EXTERN void LIBCALL Nlm_ErrClear PROTO((void)); 255 NLM_EXTERN int LIBCALL Nlm_ErrShow PROTO((void)); 256 /************************************************************************** 257 * 258 * ErrGetUserStrings(ErrDescPtr err) 259 * returns ValNodePtr to chain of user strings for this thread 260 * 261 ***************************************************************************/ 262 NLM_EXTERN ValNodePtr LIBCALL Nlm_ErrGetUserStrings PROTO((ErrDescPtr err)); 263 264 #define ErrShow Nlm_ErrShow 265 #define ErrFetch Nlm_ErrFetch 266 #define ErrClear Nlm_ErrClear 267 #define ErrCopy Nlm_ErrCopy 268 #define ErrPeek() Nlm_ErrCopy(NULL) 269 #define ErrGetUserStrings Nlm_ErrGetUserStrings 270 271 272 /***************************************************************************\ 273 | MESSAGE FILE SUPPORT | 274 \***************************************************************************/ 275 276 /** Don't use these functions **/ 277 NLM_EXTERN ErrMsgRootPtr LIBCALL ErrGetMsgRoot PROTO((const char *context)); 278 NLM_EXTERN const char* LIBCALL ErrGetExplanation PROTO((ErrMsgRootPtr idx, ErrMsgNodePtr item)); 279 280 /***************************************************************************\ 281 | CUSTOMIZATION | 282 \***************************************************************************/ 283 284 typedef Nlm_Uint1 ErrStrId; 285 286 NLM_EXTERN int LIBCALL Nlm_ErrSetLogfile PROTO((const char *filename, unsigned long flags)); 287 NLM_EXTERN const char* LIBCALL Nlm_ErrGetLogfile PROTO(( void )); 288 NLM_EXTERN ErrHookProc LIBCALL Nlm_ErrSetHandler PROTO((ErrHookProc)); 289 NLM_EXTERN Nlm_Boolean LIBCALL Nlm_CallErrHandlerOnly(Nlm_Boolean hook_only); 290 NLM_EXTERN ErrStrId LIBCALL Nlm_ErrUserInstall PROTO((const char *msg, ErrStrId magic_cookie)); 291 NLM_EXTERN Nlm_Boolean LIBCALL Nlm_ErrUserDelete PROTO((ErrStrId magic_cookie)); 292 NLM_EXTERN void LIBCALL Nlm_ErrUserClear PROTO((void)); 293 NLM_EXTERN ErrSev LIBCALL ErrSetLogLevel PROTO((ErrSev level)); 294 NLM_EXTERN ErrSev LIBCALL ErrGetLogLevel PROTO((void)); 295 NLM_EXTERN ErrSev LIBCALL ErrSetMessageLevel PROTO((ErrSev level)); 296 NLM_EXTERN ErrSev LIBCALL ErrGetMessageLevel PROTO((void)); 297 NLM_EXTERN ErrSev LIBCALL ErrSetFatalLevel PROTO((ErrSev level)); 298 NLM_EXTERN ErrSev LIBCALL ErrGetFatalLevel PROTO((void)); 299 NLM_EXTERN unsigned long LIBCALL ErrSetOptFlags PROTO((unsigned long flags)); 300 NLM_EXTERN unsigned long LIBCALL ErrClearOptFlags PROTO((unsigned long flags)); 301 NLM_EXTERN unsigned long LIBCALL ErrTestOptFlags PROTO((unsigned long flags)); 302 NLM_EXTERN void LIBCALL ErrSaveOptions PROTO((ErrOpts *opts)); 303 NLM_EXTERN void LIBCALL ErrRestoreOptions PROTO((const ErrOpts *opts)); 304 NLM_EXTERN void LIBCALL Nlm_ErrPathReset PROTO((void)); 305 NLM_EXTERN char *Nlm_GetErrLongText (char *module, 306 int errcode, int subcode); 307 /* Error Option (EO) flags */ 308 #define EO_LOG_SEVERITY 0x00000001L 309 #define EO_LOG_CODES 0x00000002L 310 #define EO_LOG_FILELINE 0x00000004L 311 #define EO_LOG_USERSTR 0x00000008L 312 #define EO_LOG_ERRTEXT 0x00000010L 313 #define EO_LOG_MSGTEXT 0x00000020L 314 #define EO_MSG_SEVERITY 0x00000100L 315 #define EO_MSG_CODES 0x00000200L 316 #define EO_MSG_FILELINE 0x00000400L 317 #define EO_MSG_USERSTR 0x00000800L 318 #define EO_MSG_ERRTEXT 0x00001000L 319 #define EO_MSG_MSGTEXT 0x00002000L 320 #define EO_LOGTO_STDOUT 0x00010000L 321 #define EO_LOGTO_STDERR 0x00020000L 322 #define EO_LOGTO_TRACE 0x00040000L 323 #define EO_LOGTO_USRFILE 0x00080000L 324 #define EO_XLATE_CODES 0x01000000L 325 #define EO_WAIT_KEY 0x02000000L 326 #define EO_PROMPT_ABORT 0x04000000L 327 #define EO_BEEP 0x08000000L 328 329 #define EO_ALL_FLAGS 0x0F0F3F3FL 330 331 #define EO_SHOW_SEVERITY (EO_LOG_SEVERITY | EO_MSG_SEVERITY) 332 #define EO_SHOW_CODES (EO_LOG_CODES | EO_MSG_CODES) 333 #define EO_SHOW_FILELINE (EO_LOG_FILELINE | EO_MSG_FILELINE) 334 #define EO_SHOW_USERSTR (EO_LOG_USERSTR | EO_MSG_USERSTR) 335 #define EO_SHOW_ERRTEXT (EO_LOG_ERRTEXT | EO_MSG_ERRTEXT) 336 #define EO_SHOW_MSGTEXT (EO_LOG_MSGTEXT | EO_MSG_MSGTEXT) 337 338 #define EO_DEFAULTS (EO_SHOW_SEVERITY | EO_LOG_CODES | EO_XLATE_CODES | \ 339 EO_SHOW_USERSTR | EO_SHOW_ERRTEXT) 340 341 /* flags for ErrSetLogfile */ 342 #define ELOG_APPEND 0x00000001 343 #define ELOG_BANNER 0x00000002 344 #define ELOG_NOCREATE 0x00000004 345 346 #define ErrSetHandler Nlm_ErrSetHandler 347 #define ErrUserInstall Nlm_ErrUserInstall 348 #define ErrUserDelete Nlm_ErrUserDelete 349 #define ErrUserClear Nlm_ErrUserClear 350 #define ErrSetLogfile Nlm_ErrSetLogfile 351 #define ErrSetLog(x) Nlm_ErrSetLogfile((x),ELOG_BANNER|ELOG_APPEND) 352 #define ErrPathReset Nlm_ErrPathReset 353 354 /***************************************************************************\ 355 | DEBUGGING | 356 \***************************************************************************/ 357 NLM_EXTERN void LIBCALL Nlm_AssertionFailed PROTO((const char*, const char*,const char*,int)); 358 NLM_EXTERN void LIBCALL Nlm_TraceStr PROTO((const char*)); 359 NLM_EXTERN void CDECL Nlm_Trace VPROTO((const char*, ...)); 360 NLM_EXTERN void LIBCALL Nlm_AbnormalExit PROTO((int)); 361 NLM_EXTERN void LIBCALL Nlm_AbnormalExitPure PROTO((int)); 362 363 #define AbnormalExit Nlm_AbnormalExit 364 365 #ifdef _DEBUG 366 367 #if !defined(TRACE) && !defined(NLM_NO_TRACE) 368 #define TRACE Nlm_Trace 369 #endif 370 #ifndef ASSERT 371 #define ASSERT(expr) ((expr) ? \ 372 (void)0 : Nlm_AssertionFailed(#expr,THIS_MODULE,THIS_FILE,__LINE__)) 373 #endif 374 #ifndef ASSERT_HARD 375 #define ASSERT_HARD(expr) ((expr) ? (void)0 : Nlm_AbnormalExitPure(-111)) 376 #endif 377 #ifndef VERIFY 378 #define VERIFY(expr) ASSERT(expr) 379 #endif 380 #ifndef VERIFY_HARD 381 #define VERIFY_HARD(expr) ASSERT_HARD(expr) 382 #endif 383 384 #else /* ! _DEBUG */ 385 386 #if !defined(TRACE) && !defined(NLM_NO_TRACE) 387 #define TRACE 1 ? (void)0 : Nlm_Trace 388 #endif 389 #ifndef ASSERT 390 #define ASSERT(expr) ((void)0) 391 #endif 392 #ifndef ASSERT_HARD 393 #define ASSERT_HARD(expr) ((void)0) 394 #endif 395 #ifndef VERIFY 396 #define VERIFY(expr) ((void)(expr)) 397 #endif 398 #ifndef VERIFY_HARD 399 #define VERIFY_HARD(expr) ((void)(expr)) 400 #endif 401 402 #endif /* ! _DEBUG */ 403 404 /********************* OBSOLETE STUFF BELOW THIS LINE **********************/ 405 406 /* actopt codes */ 407 #define ERR_CONTINUE 1 408 #define ERR_IGNORE 2 409 #define ERR_ADVISE 3 410 #define ERR_ABORT 4 411 #define ERR_PROMPT 5 412 #define ERR_TEE 6 413 414 /* logopt codes */ 415 #define ERR_LOG_ON 1 416 #define ERR_LOG_OFF 2 417 418 NLM_EXTERN void LIBCALL Nlm_ErrGetOpts PROTO((short * actopt, short * logopt)); 419 NLM_EXTERN void LIBCALL Nlm_ErrSetOpts PROTO((short actopt, short logopt)); 420 #define ErrGetOpts Nlm_ErrGetOpts 421 #define ErrSetOpts Nlm_ErrSetOpts 422 423 /* error context codes */ 424 #define CTX_DEBUG 0 425 #define CTX_UNKNOWN 1 426 #define CTX_ERRNO 2 427 #define CTX_NCBICORE 64 428 #define CTX_NCBIASN1 65 429 #define CTX_NCBICD 66 430 #define CTX_NCBIOBJ 67 431 #define CTX_NCBILMA 68 432 #define CTX_NCBIGBPARSE 69 433 #define CTX_NCBIPIRPARSE 70 434 #define CTX_NCBI2GB 71 435 #define CTX_NCBIBB2ASN 72 436 #define CTX_NCBIMATH 73 437 #define CTX_NCBIMED2ASN 74 438 #define CTX_NCBISEQENTRY 75 439 #define CTX_NCBISEQPORT 200 440 #define CTX_NCBIIDLOAD 300 441 #define CTX_NCBIIDPROCESS 301 442 #define CTX_NCBIIDRETRIEVE 302 443 #define CTX_NCBIAUTHINPARSE 303 444 #define CTX_KB2ASN 304 445 446 #define CTX_RESERVED 10000 447 /* context codes > 10000 are available for application use */ 448 #define CTX_USER 32767 /* default user application context */ 449 450 /* error codes for CTX_NCBICORE */ 451 #define CORE_UNKNOWN 1 452 #define CORE_NULLPTR 2 /* NULL pointer passed as an argument */ 453 #define CORE_NULLHND 3 /* NULL handle passed as an argument */ 454 #define CORE_MEMORY 4 /* Memory allocation failure */ 455 #define CORE_BAD_COOKIE 5 /* ErrPost User install misused */ 456 #define CORE_BAD_SGML 6 /* SGML entity or range error */ 457 458 #define CORE_FILE_ACCESS 10 /* Error accessing file */ 459 #define CORE_FILE_CREATE 11 /* Error creating file */ 460 #define CORE_FILE_OPEN 12 /* Error opening file */ 461 #define CORE_FILE_READ 13 /* Error reading file */ 462 #define CORE_FILE_WRITE 14 /* Error writing file */ 463 #define CORE_FILE_ERROR 15 /* any other file I/O error */ 464 465 #define ERRPOST(x) \ 466 Nlm_ErrSetContext(THIS_MODULE,THIS_FILE,__LINE__,DBFLAG,0,0,0), \ 467 Nlm_ErrPost x 468 469 #define Nlm_ErrSetLog(x) Nlm_ErrSetLogfile((x),ELOG_BANNER|ELOG_APPEND) 470 471 #define EO_LOG_STDOUT EO_LOGTO_STDOUT 472 #define EO_LOG_STDERR EO_LOGTO_STDERR 473 #define EO_LOG_TRACE EO_LOGTO_TRACE 474 #define EO_LOG_USRFILE EO_LOGTO_USRFILE 475 476 #ifdef __cplusplus 477 } 478 #endif 479 480 481 #undef NLM_EXTERN 482 #ifdef NLM_EXPORT 483 #define NLM_EXTERN NLM_EXPORT 484 #else 485 #define NLM_EXTERN 486 #endif 487 488 #endif 489 490