home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional Developers Kit 1992 November / Disc01 / Disc01.mdf / cppbeta / ibmcli / itrace.hp_ / ITRACE.HPP
Encoding:
C/C++ Source or Header  |  1992-10-26  |  11.9 KB  |  220 lines
  1. #ifndef _ITRACE_
  2. #define _ITRACE_
  3. /*******************************************************************************
  4. * FILE NAME: itrace.hpp                                                        *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     ITrace   - Trace Logging Facility                                        *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   (C) Copyright IBM Corporation 1992                                         *
  12. *   All Rights Reserved                                                        *
  13. *   Licensed Materials * Property of IBM                                       *
  14. *                                                                              *
  15. * HISTORY:                                                                     *
  16. * $Log:   R:/IBMCLASS/IBASE/VCS/ITRACE.HPV  $
  17. //
  18. //   Rev 1.7   25 Oct 1992 16:46:44   nunn
  19. //changed library name to ICLUI
  20. //
  21. //   Rev 1.6   24 Oct 1992 15:36:12   BOBLOVE
  22. //Fixed problem with IVBase inheritance
  23. //
  24. //   Rev 1.5   24 Oct 1992 12:52:22   BOBLOVE
  25. //Updated documentation for External Beta
  26. *                                                                              *
  27. *******************************************************************************/
  28. #ifndef _IVBASE_
  29.   #include <ivbase.hpp>
  30. #endif
  31.  
  32. // Forward declarations for other classes:
  33. class IString;
  34.  
  35. class ITrace : public IVBase
  36. /*******************************************************************************
  37. *  Trace Logging Facility                                                      *
  38. *                                                                              *
  39. *  Provides the capability for module tracing within the library.  Tracing     *
  40. *  occurs based on the setting of the environment variables "ICLUI TRACE"      *
  41. *  "ICLUI TRACETO". Tracing is off by default but can be set on using          *
  42. *  "SET ICLUI TRACE=ON".  By default tracing occurs to the OS/2 queue name     *
  43. *  "\\QUEUES\\PRINTF32" but can be routed to standard error using              *
  44. *  "SET ICLUI TRACETO=STDERR" or standard out using "SET ICLUI TRACETO=STDOUT".*
  45. *  It can be be switched back to the queue by using "SET ICLUI TRACETO=QUEUE". *
  46. *  Static functions also exist to accomplish these same things under program   *
  47. *  control.                                                                    *
  48. *                                                                              *
  49. *  Trace input is supported as IString's or character arrays and a line feed   *
  50. *  is automatically added on all trace calls.                                  *
  51. *                                                                              *
  52. *  To enable the trace calls to be compiled in and out of the code, 3 sets     *
  53. *  of macros are provided for tracing modules and data.                        *
  54. *                                                                              *
  55. *  If IC_TRACE_RUNTIME is defined, the following macros                        *
  56. *  are expanded:                                                               *
  57. *      IMODTRACE_RUNTIME()  IFUNCTRACE_RUNTIME()  ITRACE_RUNTIME()             *
  58. *                                                                              *
  59. *  If IC_TRACE_DEVELOP is defined, the following macros, in                    *
  60. *  addition to the RUNTIME macros, are defined:                                *
  61. *      IMODTRACE_DEVELOP()  IFUNCTRACE_DEVELOP()  ITRACE_DEVELOP()             *
  62. *                                                                              *
  63. *  If IC_TRACE_ALL is defined, the following macros, in                        *
  64. *  addition to the RUNTIME & DEVELOP macros, are defined:                      *
  65. *      IMODTRACE_ALL()      IFUNCTRACE_ALL()      ITRACE_ALL()                 *
  66. *                                                                              *
  67. *  The IMODTRACE version of the macros takes as input a module name that will  *
  68. *  be used for construction and destruction tracing.                           *
  69. *                                                                              *
  70. *  The IFUNCTRACE version of the macros takes no input and uses the predefined *
  71. *  identifier __FUNCTION__  for construction and destruction tracing.          *
  72. *                                                                              *
  73. *  The ITRACE version of the macros takes a text string to be traced.          *
  74. *                                                                              *
  75. * EXAMPLE:                                                                     *
  76. *                                                                              *
  77. *  The following example traces the entry and exit of a function as well as    *
  78. *  writing a text string in the module.                                        *
  79. *                                                                              *
  80. *    AnyClass :: anyFunction()                                                 *
  81. *    {                                                                         *
  82. *       ITrace trc("AnyClass :: anyFunction");                                 *
  83. *          .                                                                   *
  84. *       trc.write(IString("The answer is: ")+IString(10));                     *
  85. *    }                                                                         *
  86. *   Output produced is:                                                        *
  87. *                                                                              *
  88. *       +AnyClass :: anyFunction                                               *
  89. *         >The answer is 10                                                    *
  90. *       -AnyClass :: anyFunction                                               *
  91. *                                                                              *
  92. *                                                                              *
  93. *    Using macros to accomplish the same thing:                                *
  94. *                                                                              *
  95. *    AnyClass :: anyFunction()                                                 *
  96. *    {                                                                         *
  97. *      IMODTRACE_DEVELOP("AnyClass :: anyFunction");                           *
  98. *          .                                                                   *
  99. *      ITRACE_DEVELOP(IString("The answer is: ")+IString(10));                 *
  100. *    }                                                                         *
  101. *                                                                              *
  102. *                                                                              *
  103. *******************************************************************************/
  104. {
  105. friend void writeString(const IString& str);
  106.  
  107. public:
  108. /*------------------------ CONSTRUCTORS/DESTRUCTORS ----------------------------
  109. | There are 2 ways to construct instances of this class:                       |
  110. |   1. default                                                                 |
  111. |     An ITrace object is created but no logging occurs on construction        |
  112. |     or destruction.                                                          |
  113. |   2. By passing an optional name and line number                             |
  114. |     If a name is passed then the name is written on construction and         |
  115. |     again on destruction.                                                    |
  116. ------------------------------------------------------------------------------*/
  117. ITrace(const char* pszTraceName=0,
  118.         long LineNumber=0);
  119.  
  120. ~ITrace();
  121.  
  122. /*---------------------------Trace Output Functions ----------------------------
  123. | These functions cause trace data to be written to the current trace location.|
  124. |   write -  Write the passed character string or IString                      |
  125. ------------------------------------------------------------------------------*/
  126. static void
  127.   write(const IString& str),
  128.   write(const char* psz);
  129.  
  130. /*-------------------------STATIC ACCESSORS ------------------------------------
  131. | These functions provide means of getting and setting the accessible          |
  132. | attributes of instances of this class:                                       |
  133. | traceLocation        - Return an enumeration specifying the trace output     |
  134. |                        location.                                             |
  135. | enableTrace          - Allow trace entries to be written.                    |
  136. | disableTrace         - Stop trace entries from being written.                |
  137. | sendTraceToQueue     - Set the location for output to "\\QUEUES\\PRINTF32".  |
  138. | sendTraceToStdError  - Set the location for output to Standard Error         |
  139. |                         Stream.                                              |
  140. | sendTraceToStdOut    - Set the location for output to Standard Output Stream.|
  141. | enableTraceLineNo    - Enable the tracing of line number information.        |
  142. | disableTraceLineNo   - Disable the tracing of line number information.       |
  143. | isTraceEnabled       - Determine if tracing is currently enabled.            |
  144. | isLineNoTraceEnabled - Determine if line numbers are currently being written.|
  145. ------------------------------------------------------------------------------*/
  146. enum traceLoc { toQueue, toStdError, toStdOut, readEnv };
  147.  
  148. static long
  149.   traceLocation();
  150.  
  151. static void
  152.   enableTrace(),
  153.   disableTrace(),
  154.   sendTraceToQueue(),     /* Default */
  155.   sendTraceToStdError(),
  156.   sendTraceToStdOut(),
  157.   enableTraceLineNo(),
  158.   disableTraceLineNo();
  159.  
  160. static Boolean
  161.   isTraceEnabled(),
  162.   isLineNoTraceEnabled();
  163.  
  164. static void
  165.   writeString(char* psz),
  166.   writeString(IString& str);
  167.  
  168. protected:
  169. /*----------------------------- IMPLEMENTATION ---------------------------------
  170. | Actual trace output functions after formating.                               |
  171. ------------------------------------------------------------------------------*/
  172. static long
  173.   threadId();
  174.  
  175. private:
  176. /*------------------------------ DATA MEMBERS ----------------------------------
  177. |  pszTraceName - Function name passed on construction.                        |
  178. ------------------------------------------------------------------------------*/
  179. char
  180.  *pszClTraceName;
  181. };
  182.  
  183.  
  184. /*--------------------------------------------------------------*/
  185. /* Selective inclusion of tracing accomplished based on prior   */
  186. /* definition of Trace "level" macros.                          */
  187. /*--------------------------------------------------------------*/
  188. #ifdef IC_TRACE_ALL
  189.    #define IMODTRACE_ALL(modname)  ITrace trc(modname, __LINE__ )
  190.    #define IFUNCTRACE_ALL()        ITrace trc(__FUNCTION__, __LINE__ )
  191.    #define ITRACE_ALL(p1)          ITrace::write(p1)
  192. #else
  193.    #define IMODTRACE_ALL(modname)
  194.    #define IFUNCTRACE_ALL()
  195.    #define ITRACE_ALL(p1)
  196. #endif
  197.  
  198. #ifdef IC_TRACE_DEVELOP
  199.    #define IMODTRACE_DEVELOP(modname) ITrace trc(modname,  __LINE__ )
  200.    #define IFUNCTRACE_DEVELOP()       ITrace trc(__FUNCTION__, __LINE__ )
  201.    #define ITRACE_DEVELOP(p1)         ITrace::write(p1)
  202. #else
  203.    #define IMODTRACE_DEVELOP(modname)
  204.    #define IFUNCTRACE_DEVELOP()
  205.    #define ITRACE_DEVELOP(p1)
  206. #endif
  207.  
  208. #ifdef IC_TRACE_RUNTIME
  209.    #define IMODTRACE_RUNTIME(modname)  ITrace trc(modname, __LINE__ )
  210.    #define IFUNCTRACE_RUNTIME()        ITrace trc(__FUNCTION__, __LINE__ )
  211.    #define ITRACE_RUNTIME(p1)          ITrace::write(p1)
  212. #else
  213.    #define IMODTRACE_RUNTIME(modname)
  214.    #define IFUNCTRACE_RUNTIME()   
  215.    #define ITRACE_RUNTIME(p1)
  216. #endif
  217.  
  218.  
  219. #endif /* _ITRACE_ */
  220.