home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / ITRACE.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  16KB  |  281 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. *******************************************************************************/
  17. #ifndef _IVBASE_
  18.   #include <ivbase.hpp>
  19. #endif
  20.  
  21. /*----------------------------------------------------------------------------*/
  22. /* Align classes on four byte boundary.                                       */
  23. /*----------------------------------------------------------------------------*/
  24. #pragma pack(4)
  25.  
  26. // Forward declarations for other classes:
  27. class IString;
  28.  
  29. class ITrace : public IVBase {
  30. typedef IVBase
  31.   Inherited;
  32. /*******************************************************************************
  33. *  The ITrace class provides the capability for module tracing within the      *
  34. *  library.  Tracing occurs based on the setting of the environment variables  *
  35. *  ICLUI TRACE and ICLUI TRACETO.                                              *
  36. *                                                                              *
  37. *  The default state of tracing is:                                            *
  38. *    - Tracing is disabled.                                                    *
  39. *    - The output location is the OS/2 queue \\QUEUES\\PRINTF32.               *
  40. *    - A prefix is attached to the trace entry that contains a sequence        *
  41. *      number followed by the process and thread where the trace call          *
  42. *      occurred.                                                               *
  43. *                                                                              *
  44. *  Tracing can be set on by entering ICLUI TRACE=ON in the environment.        *
  45. *                                                                              *
  46. *  The output location of tracing can be changed to stderr or stdout by        *
  47. *  entering ICLUI TRACETO=STDERR or ICLUI TRACETO=STDOUT in the environment.   *
  48. *  This has the side affect of turning tracing on.                             *
  49. *                                                                              *
  50. *  Prefix area tracing can be removed by entering ICLUI TRACE=NOPREFIX.  This  *
  51. *  also has the side affect of turning tracing on.                             *
  52. *                                                                              *
  53. *  Static functions also exist to accomplish these same things under program   *
  54. *  control.                                                                    *
  55. *                                                                              *
  56. *  Trace input is supported as IStrings or character arrays, and a line feed   *
  57. *  is automatically added on all trace calls.                                  *
  58. *                                                                              *
  59. *  To enable the trace calls to be compiled in and out of the code, the        *
  60. *  following sets of macros are provided for tracing modules and data:         *
  61. *                                                                              *
  62. *    - If IC_TRACE_RUNTIME is defined, the following macros are expanded:      *
  63. *                                                                              *
  64. *          IMODTRACE_RUNTIME()  IFUNCTRACE_RUNTIME()  ITRACE_RUNTIME()         *
  65. *                                                                              *
  66. *    - If IC_TRACE_DEVELOP is defined, the following macros, in addition to    *
  67. *      the RUNTIME macros, are defined:                                        *
  68. *                                                                              *
  69. *          IMODTRACE_DEVELOP()  IFUNCTRACE_DEVELOP()  ITRACE_DEVELOP()         *
  70. *                                                                              *
  71. *    - If IC_TRACE_ALL is defined, the following macros, in addition to the    *
  72. *      RUNTIME and DEVELOP macros, are defined:                                *
  73. *                                                                              *
  74. *          IMODTRACE_ALL()      IFUNCTRACE_ALL()      ITRACE_ALL()             *
  75. *                                                                              *
  76. *  The IMODTRACE version of the macros takes as input a module name that will  *
  77. *  be used for construction and destruction tracing.                           *
  78. *                                                                              *
  79. *  The IFUNCTRACE version of the macros takes no input and uses the            *
  80. *  predefined identifier __FUNCTION__  for construction and destruction        *
  81. *  tracing.                                                                    *
  82. *                                                                              *
  83. *  The ITRACE version of the macros takes a text string to be traced.          *
  84. *                                                                              *
  85. *  The following example traces the entry and exit of a function, as well as   *
  86. *  writing a text string in the module.                                        *
  87. *                                                                              *
  88. * EXAMPLE:                                                                     *
  89. *                                                                              *
  90. *    AnyClass :: anyFunction()                                                 *
  91. *    {                                                                         *
  92. *       ITrace trc("AnyClass :: anyFunction");                                 *
  93. *          .                                                                   *
  94. *       trc.write(IString("The answer is: ")+IString(10));                     *
  95. *    }                                                                         *
  96. *   Output produced is:                                                        *
  97. *                                                                              *
  98. *       +AnyClass :: anyFunction                                               *
  99. *         >The answer is 10                                                    *
  100. *       -AnyClass :: anyFunction                                               *
  101. *                                                                              *
  102. *                                                                              *
  103. *  Using macros to accomplish the same thing:                                  *
  104. *                                                                              *
  105. * EXAMPLE:                                                                     *
  106. *                                                                              *
  107. *    AnyClass :: anyFunction()                                                 *
  108. *    {                                                                         *
  109. *      IMODTRACE_DEVELOP("AnyClass :: anyFunction");                           *
  110. *          .                                                                   *
  111. *      ITRACE_DEVELOP(IString("The answer is: ")+IString(10));                 *
  112. *    }                                                                         *
  113. *                                                                              *
  114. *******************************************************************************/
  115. friend class ITraceSetup;
  116. friend static void debug( const char *fmt, ... );
  117.  
  118. public:
  119. /*------------------------ Constructors/Destructor -----------------------------
  120. | You can construct instances of this class in the following ways:             |
  121. |    - By using the default constructor.  An ITrace object is created, but no  |
  122. |      logging occurs on construction or destruction.                          |
  123. |    - By passing an optional name and line number.  If a name is passed, the  |
  124. |      name is written on construction and again on destruction.               |
  125. |      NOTE: If an IString is passed to the trace object, it is the caller's   |
  126. |            responsibility to ensure that the lifetime of the IString         |
  127. |            exceeds the lifetime of the ITrace object.  The use of temporary  |
  128. |            IStrings is not supported.                                        |
  129. ------------------------------------------------------------------------------*/
  130.   ITrace   ( const char* traceName=0,
  131.              long        lineNumber=0);
  132.  
  133. ~ITrace    ( );
  134.  
  135. /*-------------------------- Trace Output Functions ----------------------------
  136. | These functions cause trace data to be written to the current trace          |
  137. | location:                                                                    |
  138. |   write       - Writes the passed character string or IString.               |
  139. |   Destination - Enumeration that provides values for specifying the          |
  140. |                 destination of the trace data.  Valid values are queue,      |
  141. |                 standardError, and standardOutput.                           |
  142. ------------------------------------------------------------------------------*/
  143. static void
  144.   write       ( const IString& text),
  145.   write       ( const char*    text);
  146.  
  147. enum Destination { queue, standardError, standardOutput };
  148.  
  149. /*------------------------ Static Accessors ------------------------------------
  150. | These functions provide a means of getting and setting the accessible        |
  151. | attributes of instances of this class:                                       |
  152. |   traceDestination         - Returns an enumeration specifying the trace     |
  153. |                              output destination.                             |
  154. |   enableTrace              - Allows trace entries to be written.             |
  155. |   disableTrace             - Stops trace entries from being written.         |
  156. |   writeToQueue             - Sets the location for output to                 |
  157. |                              \\QUEUES\\PRINTF32.  This is the default.       |
  158. |   writeToStandardError     - Sets the location for output to Standard Error  |
  159. |                              Stream.                                         |
  160. |   writeToStandardOutput    - Sets the location for output to Standard        |
  161. |                              Output Stream.                                  |
  162. |   enableWriteLineNumber    - Enables the tracing of line number information. |
  163. |   disableWriteLineNumber   - Disables the tracing of line number             |
  164. |                              information.                                    |
  165. |   enableWritePrefix        - Enables the writing of process ID, thread ID,   |
  166. |                              and output line number to trace.                |
  167. |   disableWritePrefix       - Disables the writing of process ID, thread ID,  |
  168. |                              and output line number to trace.                |
  169. |   isTraceEnabled           - Determines whether tracing is currently         |
  170. |                              enabled.                                        |
  171. |   isWriteLineNumberEnabled - Determines whether line numbers are currently   |
  172. |                              being written.                                  |
  173. |   isWritePrefixEnabled     - Determines whether the line count prefix is     |
  174. |                              being written.                                  |
  175. ------------------------------------------------------------------------------*/
  176. static ITrace::Destination
  177.   traceDestination      ( );
  178.  
  179. static void
  180.   enableTrace           ( ),
  181.   disableTrace          ( ),
  182.   writeToQueue          ( ),     /* Default */
  183.   writeToStandardError  ( ),
  184.   writeToStandardOutput ( ),
  185.   enableWriteLineNumber ( ),
  186.   disableWriteLineNumber( ),
  187.   enableWritePrefix     ( ),
  188.   disableWritePrefix    ( );
  189.  
  190. static Boolean
  191.   isTraceEnabled            ( ),
  192.   isWriteLineNumberEnabled  ( ),
  193.   isWritePrefixEnabled      ( );
  194.  
  195.  
  196. protected:
  197. /*----------------------------- Implementation ---------------------------------
  198. | The following functions are used in the implementation:                      |
  199. |   threadId             - Used to to determine the current thread identifier. |
  200. |   writeString          - Used to write to the outout device without          |
  201. |                          formatting.                                         |
  202. |   writeFormattedString - Used to write trace data after formatting.  The     |
  203. |                          prefix is added, if necessary, and any newlines     |
  204. |                          embedded in the string are updated to include the   |
  205. |                          prefix.                                             |
  206. ------------------------------------------------------------------------------*/
  207. static unsigned long
  208.   threadId               ( );
  209.  
  210. static void
  211.   writeString            (char*          text),
  212.   writeFormattedString   (const IString& string,
  213.                           char*          marker);
  214.  
  215. private:
  216. /*--------------------------------- Private ----------------------------------*/
  217.  
  218. enum State       { uninitialized=1, on=2,  writeLineNumber=4, writePrefix=8 };
  219. char
  220.  *pszClTraceName;
  221. static int
  222.   iClState;
  223. static ITrace::Destination
  224.   iClTraceLocation;
  225. static unsigned long
  226.   remainingStack ( );
  227. };
  228.  
  229.  
  230. /*--------------------------------------------------------------*/
  231. /* Selective inclusion of tracing accomplished based on prior   */
  232. /* definition of Trace "level" macros.                          */
  233. /*--------------------------------------------------------------*/
  234. #ifdef IC_TRACE_ALL
  235.    #define IMODTRACE_ALL(modname)  ITrace trc(modname, __LINE__ )
  236.    #define IFUNCTRACE_ALL()        ITrace trc(__FUNCTION__, __LINE__ )
  237.    #define ITRACE_ALL(p1)          ITrace::write(p1)
  238.    #ifndef IC_TRACE_DEVELOP
  239.      #define IC_TRACE_DEVELOP
  240.    #endif
  241. #else
  242.    #define IMODTRACE_ALL(modname)
  243.    #define IFUNCTRACE_ALL()
  244.    #define ITRACE_ALL(p1)
  245. #endif
  246.  
  247. #ifdef IC_TRACE_DEVELOP
  248.    #define IMODTRACE_DEVELOP(modname) ITrace trc(modname,  __LINE__ )
  249.    #define IFUNCTRACE_DEVELOP()       ITrace trc(__FUNCTION__, __LINE__ )
  250.    #define ITRACE_DEVELOP(p1)         ITrace::write(p1)
  251.    #ifndef IC_TRACE_RUNTIME
  252.      #define IC_TRACE_RUNTIME
  253.    #endif
  254. #else
  255.    #define IMODTRACE_DEVELOP(modname)
  256.    #define IFUNCTRACE_DEVELOP()
  257.    #define ITRACE_DEVELOP(p1)
  258. #endif
  259.  
  260. #ifdef IC_TRACE_RUNTIME
  261.    #define IMODTRACE_RUNTIME(modname)  ITrace trc(modname, __LINE__ )
  262.    #define IFUNCTRACE_RUNTIME()        ITrace trc(__FUNCTION__, __LINE__ )
  263.    #define ITRACE_RUNTIME(p1)          ITrace::write(p1)
  264. #else
  265.    #define IMODTRACE_RUNTIME(modname)
  266.    #define IFUNCTRACE_RUNTIME()
  267.    #define ITRACE_RUNTIME(p1)
  268. #endif
  269.  
  270. /*----------------------------------------------------------------------------*/
  271. /* Resume compiler default packing.                                           */
  272. /*----------------------------------------------------------------------------*/
  273. #pragma pack()
  274.  
  275. /*--------------------------------- INLINES ----------------------------------*/
  276. #ifndef I_NO_INLINES
  277.   #include <itrace.inl>
  278. #endif
  279.  
  280. #endif /* _ITRACE_ */
  281.