home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / ibmcli / iexcbase.hp_ / IEXCBASE.HPP
Encoding:
C/C++ Source or Header  |  1992-10-26  |  15.1 KB  |  330 lines

  1. #ifndef _IEXCBASE_ 
  2.   #define _IEXCBASE_
  3. /****************************************************************/
  4. /* CLASS NAMES: IExceptionLocation                              */
  5. /*              IException                                      */
  6. /*              IAccessError                                    */
  7. /*              IAssertionFailure                               */
  8. /*              IDeviceError                                    */
  9. /*              IInvalidParameter                               */
  10. /*              IInvalidRequest                                 */
  11. /*              IResourceExhausted                              */
  12. /*              IOutOfMemory                                    */
  13. /*              IOutOfSystemResource                            */
  14. /*              IOutOfWindowResource                            */
  15. /*                                                              */
  16. /* DESCRIPTION:  Base exception class for exception handling    */
  17. /*               mechanism.  NOTE:  This header has no          */
  18. /*               dependencies on the "PM" class library.  It is */
  19. /*               capable of being used by other class librarys  */
  20. /*               and is used as the base exception class for    */
  21. /*               the Boeblingen Building Blocks. All of the     */
  22. /*               IBM Class Library: User Interface subclasses of IException are declared */
  23. /*               here.                                          */
  24. /*                 This file also contains all of the macros    */
  25. /*               macros required for implementing the exception */
  26. /*               handling mechanism, including IASSERT, ITHROW, */
  27. /*               IExceptionLocation, and IEXCLASSDECLARE.       */
  28. /*                                                              */
  29. /*               Hungarian notation is "exloc"                  */
  30. /*                                     "ex"                     */
  31. /*                                                              */
  32. /*                                                              */
  33. /* $Log:   R:/IBMCLASS/IBASE/VCS/IEXCBASE.HPV  $                                                        */
  34. //
  35. //   Rev 1.12   25 Oct 1992 16:46:10   nunn
  36. //changed library name to ICLUI
  37. //
  38. //   Rev 1.11   17 Oct 1992 14:54:16   BUILDER
  39. //added //'s to log entries
  40. //
  41. //    Rev 1.10   17 Oct 1992 14:13:02   BUILDER
  42. // removed */, will add CommentPrefix to PVCS master config file
  43. //
  44. //    Rev 1.9   17 Oct 1992 13:47:00   BUILDER
  45. // added missing */ at end of change description
  46. //
  47. //    Rev 1.8   16 Oct 1992 19:14:48   SWEDE
  48. // removed change log, added check for ifdef __FUNCTION__ to
  49. // support all compilers
  50. /****************************************************************/
  51. /* Copyright (c) IBM Corporation 1992                           */
  52. /****************************************************************/
  53.  
  54. #define IMAX_THROWS      5
  55.  
  56. typedef void (IEXCEPTIONTRACECALLBACK)(const char*);
  57.  
  58. /****************************************************************/
  59. /* Class: IExceptionLocation                                    */
  60. /****************************************************************/
  61. class IExceptionLocation {
  62. public:
  63.   /****************************************************************/
  64.   /* Constructor to encapsulate information on where an           */
  65.   /* exception has been thrown or re-thrown.  Usually used in     */
  66.   /* conjunction with the IEXCEPTION_LOCATION macro.              */
  67.   /****************************************************************/
  68.                 IExceptionLocation(const char* fileName=0,
  69.                                    const char* functionName=0,
  70.                                    unsigned long lineNo=0);
  71.  
  72.   /****************************************************************/
  73.   /* Function to return the path qualified file name where an     */
  74.   /* exception has been thrown or re-thrown.                      */
  75.   /****************************************************************/
  76.    const char*  file() const;
  77.  
  78.   /****************************************************************/
  79.   /* Function to return the name of the function which has        */
  80.   /* thrown or re-thrown an exception.                            */
  81.   /****************************************************************/
  82.    const char*  function() const;
  83.  
  84.   /****************************************************************/
  85.   /* Function to return the line number of the statement in the   */
  86.   /* source file from which an exception has been thrown or       */
  87.   /* re-thrown.                                                   */
  88.   /****************************************************************/
  89.  unsigned long  lineNo() const;
  90.  
  91. private:
  92.    const char*  pszClFile;
  93.    const char*  pszClFunction;
  94.  unsigned long  ulClLineNo;
  95. };
  96.  
  97.  
  98. enum IExceptionSeverity {recoverable, unrecoverable};
  99.  
  100. /****************************************************************/
  101. /* Class: IException                                            */
  102. /****************************************************************/
  103. class IException {
  104. public:
  105.   /****************************************************************/
  106.   /* Constructor to create an exception from a message string.    */
  107.   /****************************************************************/
  108.                 IException(const char* exMsgText,
  109.                            unsigned long errorId = 0,
  110.                            IExceptionSeverity exSev = unrecoverable);
  111.  
  112.   /****************************************************************/
  113.   /* Copy constructor                                             */
  114.   /****************************************************************/
  115.                 IException(const IException& exc);
  116.  
  117.        virtual ~IException();
  118.  
  119.   /****************************************************************/
  120.   /* Function to allow appending of text to the message string on */
  121.   /* the top of the "stack". e.g. Call help desk at 999-999-9999  */
  122.   /****************************************************************/
  123.     IException& appendText(const char* exMsgText);
  124.  
  125.   /****************************************************************/
  126.   /* Function to add an exception message string to the top of    */
  127.   /* the message "stack".                                         */
  128.   /****************************************************************/
  129.     IException& setText(const char* exMsgText);
  130.  
  131.   /****************************************************************/
  132.   /* Function to set the severity of the exception.               */
  133.   /****************************************************************/
  134.     IException& setSeverity(IExceptionSeverity exsev);
  135.  
  136.   /****************************************************************/
  137.   /* Function to set the error ID of the exception.               */
  138.   /****************************************************************/
  139.     IException& setErrorId(unsigned long errorId);
  140.  
  141.   /****************************************************************/
  142.   /* Function to return the name of the exception class.          */
  143.   /****************************************************************/
  144.  virtual const  char* name() const;
  145.  
  146.   /****************************************************************/
  147.   /* Function to return an exception message string from the      */
  148.   /* "stack".  Index 0, the top of the stack, is the default.     */
  149.   /****************************************************************/
  150.    const char*  text(unsigned long indexFromTop = 0) const;
  151.  
  152.   /****************************************************************/
  153.   /* Function to return the number of levels of message text in   */
  154.   /* the exception message "stack".                               */
  155.   /****************************************************************/
  156.  unsigned long  textCount() const;
  157.  
  158.   /****************************************************************/
  159.   /* Function to return the error ID of the exception.            */
  160.   /****************************************************************/
  161.  unsigned long  errorId() const;
  162.  
  163.   /****************************************************************/
  164.   /* Function to determine if the exception is deemed to be       */
  165.   /* recoverable, returns 1 if so, 0 if unrecoverable.            */
  166.   /****************************************************************/
  167.   unsigned int  isRecoverable() const;
  168.  
  169.   /****************************************************************/
  170.   /* Function to add location information regarding where an      */
  171.   /* exception is thrown or re-thrown. (Stored in an array)       */
  172.   /****************************************************************/
  173.    IException&  addLocation(const IExceptionLocation& exloc);
  174.  
  175.   /****************************************************************/
  176.   /* Function to return a pointer to the location information at  */
  177.   /* an index in the array of exception locations. The index is   */
  178.   /* 0 based.  If an out of bounds index is passed in, a zero     */
  179.   /* pointer is returned.                                         */
  180.   /****************************************************************/
  181.  const IExceptionLocation* locationAtIndex(unsigned long locIndex) const;
  182.  
  183.   /****************************************************************/
  184.   /* Function to return the number of IExceptionLocation          */
  185.   /* instances stored in the array.                               */
  186.   /****************************************************************/
  187.  unsigned long  locationCount() const;
  188.  
  189.   /****************************************************************/
  190.   /* Function to register a callback function for use by the      */
  191.   /* logExceptionData function.  This function is static and      */
  192.   /* should ONLY be invoked from one thread in a program.         */
  193.   /****************************************************************/
  194.    static void  setTraceCallback(IEXCEPTIONTRACECALLBACK* extrcCB);
  195.  
  196.   /****************************************************************/
  197.   /* Function to support logging of exception instance data.  If  */
  198.   /* a tracing function has been registered with the              */
  199.   /* setTraceCallback function, it is passed a buffer of data. If */
  200.   /* no function has been registered the data is written to       */
  201.   /* STDERR.                                                      */
  202.   /****************************************************************/
  203.    IException&  logExceptionData();
  204.  
  205.   /****************************************************************/
  206.   /* Function used to terminate the application.  This is part of */
  207.   /* the termination model temporarily in place since exception   */
  208.   /* handling is not fully supported.  When the compiler fully    */
  209.   /* supports exception handling this function may be removed.    */
  210.   /****************************************************************/
  211.           void  terminate();
  212.    
  213.  
  214. private:
  215.  
  216. class IMsgText {
  217. public:
  218.                 IMsgText(const char* errText,
  219.                          const IMsgText* msgtxtOld);
  220.                 IMsgText(const IMsgText& msg);
  221.                ~IMsgText();
  222.  
  223.    const char*  text();
  224.           void  appendText(const char* errText);
  225.  
  226.   char*                pszClMsg;
  227.   IMsgText*            msgtxtClNext;
  228.  
  229. };  // end of IMsgText
  230.    
  231.   IExceptionSeverity  exsevCl;
  232.   unsigned long       ulClErrorId;
  233.   IExceptionLocation  exlocClArray[IMAX_THROWS];
  234.   unsigned long       ulexlocClCount;
  235.  
  236.   unsigned long       ulClTxtLvlCount;
  237.   IMsgText*           msgtxtClTop;
  238.  
  239.                 void  logData(char * pbuf);
  240.          IException&  operator=(const IException& exc);
  241. };  // end of IException
  242.  
  243. #if !defined( INO_EXCEPTIONS_SUPPORT )
  244.   #define INO_EXCEPTIONS_SUPPORT 0
  245. #endif
  246.  
  247.   /****************************************************************/
  248.   /* Macro which creates an instance of IExceptionLocation using  */
  249.   /* the compiler defined symbols for the filename, line number,  */
  250.   /* and function name.  It is primarily used by the ITHROW       */
  251.   /* macro.                                                       */
  252.   /****************************************************************/
  253. #if defined ( __FUNCTION__ )
  254.   #define IEXCEPTION_LOCATION()  IExceptionLocation(__FILE__, __FUNCTION__, __LINE__)
  255. #else
  256.   #define IEXCEPTION_LOCATION()  IExceptionLocation(__FILE__, "Unknown", __LINE__)
  257. #endif
  258.  
  259.   /****************************************************************/
  260.   /* Macro used to throw or re-throw an exception instance.  It   */
  261.   /* uses the IEXCEPTION_LOCATION macro to capture location       */
  262.   /* information, logs the information out and then throw's the   */
  263.   /* exception.  Until the compiler fully supports exception      */
  264.   /* handling, the macro terminates the program instead of throw. */
  265.   /****************************************************************/
  266.  
  267. #if (INO_EXCEPTIONS_SUPPORT)
  268.   #define ITHROW(exc)\
  269.      exc.addLocation(IEXCEPTION_LOCATION());\
  270.      exc.logExceptionData();\
  271.      exc.terminate()
  272. #else
  273.   #define ITHROW(exc)\
  274.      exc.addLocation(IEXCEPTION_LOCATION());\
  275.      exc.logExceptionData();\
  276.      throw exc
  277. #endif
  278.  
  279. #define IRETHROW(exc)\
  280.      exc.addLocation(IEXCEPTION_LOCATION());\
  281.      exc.logExceptionData();\
  282.      throw
  283.  
  284.   /****************************************************************/
  285.   /* Macro to provide "assertion" support in the library.  User   */
  286.   /* simply asserts a test, if the test is false an exception of  */
  287.   /* type IAssertionFailure is thrown.  This macro will be        */
  288.   /* compiled out in the delivery version of the library for      */
  289.   /* performance reasons.                                         */
  290.   /****************************************************************/
  291. #if defined(IC_DEVELOP)
  292.   #define IASSERT(test)\
  293.       if(!(test))\
  294.        {\
  295.          IAssertionFailure assrtnfail("Failing Assertion Test Is: " #test);\
  296.          ITHROW(assrtnfail);\
  297.        }
  298. #else
  299.   #define IASSERT(test)
  300. #endif
  301.   
  302.  
  303.   /****************************************************************/
  304.   /* Macro used to generate all of the declarations of the        */
  305.   /* ICLUI subclasses of IException.                           */
  306.   /****************************************************************/
  307. #define IEXCLASSDECLARE(child,parent) class child : public parent {\
  308. public:\
  309.   child(const char* a, unsigned long b = 0,\
  310.         IExceptionSeverity c = unrecoverable);\
  311.   virtual ~child();\
  312.   virtual const char* name() const;\
  313. }
  314.  
  315.   /****************************************************************/
  316.   /* Invocations of the IEXCLASSDECLARE macro.                    */
  317.   /****************************************************************/
  318. IEXCLASSDECLARE(IAccessError,IException);
  319. IEXCLASSDECLARE(IAssertionFailure,IException);
  320. IEXCLASSDECLARE(IDeviceError,IException);
  321. IEXCLASSDECLARE(IInvalidParameter,IException);
  322. IEXCLASSDECLARE(IInvalidRequest,IException);
  323. IEXCLASSDECLARE(IResourceExhausted,IException);
  324.   IEXCLASSDECLARE(IOutOfMemory,IResourceExhausted);
  325.   IEXCLASSDECLARE(IOutOfSystemResource,IResourceExhausted);
  326.   IEXCLASSDECLARE(IOutOfWindowResource,IResourceExhausted);
  327.  
  328.  
  329. #endif /* _IEXCBASE_ */
  330.