NCBI C Toolkit Cross Reference

C/corelib/ncbierr.h


  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 

source navigation ]   [ diff markup ]   [ identifier search ]   [ freetext search ]   [ file search ]  

This page was automatically generated by the LXR engine.
Visit the LXR main site for more information.