home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
ITRACE.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
16KB
|
281 lines
#ifndef _ITRACE_
#define _ITRACE_
/*******************************************************************************
* FILE NAME: itrace.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* ITrace - Trace Logging Facility *
* *
* COPYRIGHT: *
* (C) Copyright IBM Corporation 1992 *
* All Rights Reserved *
* Licensed Materials * Property of IBM *
* *
* HISTORY: *
*******************************************************************************/
#ifndef _IVBASE_
#include <ivbase.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
// Forward declarations for other classes:
class IString;
class ITrace : public IVBase {
typedef IVBase
Inherited;
/*******************************************************************************
* The ITrace class provides the capability for module tracing within the *
* library. Tracing occurs based on the setting of the environment variables *
* ICLUI TRACE and ICLUI TRACETO. *
* *
* The default state of tracing is: *
* - Tracing is disabled. *
* - The output location is the OS/2 queue \\QUEUES\\PRINTF32. *
* - A prefix is attached to the trace entry that contains a sequence *
* number followed by the process and thread where the trace call *
* occurred. *
* *
* Tracing can be set on by entering ICLUI TRACE=ON in the environment. *
* *
* The output location of tracing can be changed to stderr or stdout by *
* entering ICLUI TRACETO=STDERR or ICLUI TRACETO=STDOUT in the environment. *
* This has the side affect of turning tracing on. *
* *
* Prefix area tracing can be removed by entering ICLUI TRACE=NOPREFIX. This *
* also has the side affect of turning tracing on. *
* *
* Static functions also exist to accomplish these same things under program *
* control. *
* *
* Trace input is supported as IStrings or character arrays, and a line feed *
* is automatically added on all trace calls. *
* *
* To enable the trace calls to be compiled in and out of the code, the *
* following sets of macros are provided for tracing modules and data: *
* *
* - If IC_TRACE_RUNTIME is defined, the following macros are expanded: *
* *
* IMODTRACE_RUNTIME() IFUNCTRACE_RUNTIME() ITRACE_RUNTIME() *
* *
* - If IC_TRACE_DEVELOP is defined, the following macros, in addition to *
* the RUNTIME macros, are defined: *
* *
* IMODTRACE_DEVELOP() IFUNCTRACE_DEVELOP() ITRACE_DEVELOP() *
* *
* - If IC_TRACE_ALL is defined, the following macros, in addition to the *
* RUNTIME and DEVELOP macros, are defined: *
* *
* IMODTRACE_ALL() IFUNCTRACE_ALL() ITRACE_ALL() *
* *
* The IMODTRACE version of the macros takes as input a module name that will *
* be used for construction and destruction tracing. *
* *
* The IFUNCTRACE version of the macros takes no input and uses the *
* predefined identifier __FUNCTION__ for construction and destruction *
* tracing. *
* *
* The ITRACE version of the macros takes a text string to be traced. *
* *
* The following example traces the entry and exit of a function, as well as *
* writing a text string in the module. *
* *
* EXAMPLE: *
* *
* AnyClass :: anyFunction() *
* { *
* ITrace trc("AnyClass :: anyFunction"); *
* . *
* trc.write(IString("The answer is: ")+IString(10)); *
* } *
* Output produced is: *
* *
* +AnyClass :: anyFunction *
* >The answer is 10 *
* -AnyClass :: anyFunction *
* *
* *
* Using macros to accomplish the same thing: *
* *
* EXAMPLE: *
* *
* AnyClass :: anyFunction() *
* { *
* IMODTRACE_DEVELOP("AnyClass :: anyFunction"); *
* . *
* ITRACE_DEVELOP(IString("The answer is: ")+IString(10)); *
* } *
* *
*******************************************************************************/
friend class ITraceSetup;
friend static void debug( const char *fmt, ... );
public:
/*------------------------ Constructors/Destructor -----------------------------
| You can construct instances of this class in the following ways: |
| - By using the default constructor. An ITrace object is created, but no |
| logging occurs on construction or destruction. |
| - By passing an optional name and line number. If a name is passed, the |
| name is written on construction and again on destruction. |
| NOTE: If an IString is passed to the trace object, it is the caller's |
| responsibility to ensure that the lifetime of the IString |
| exceeds the lifetime of the ITrace object. The use of temporary |
| IStrings is not supported. |
------------------------------------------------------------------------------*/
ITrace ( const char* traceName=0,
long lineNumber=0);
~ITrace ( );
/*-------------------------- Trace Output Functions ----------------------------
| These functions cause trace data to be written to the current trace |
| location: |
| write - Writes the passed character string or IString. |
| Destination - Enumeration that provides values for specifying the |
| destination of the trace data. Valid values are queue, |
| standardError, and standardOutput. |
------------------------------------------------------------------------------*/
static void
write ( const IString& text),
write ( const char* text);
enum Destination { queue, standardError, standardOutput };
/*------------------------ Static Accessors ------------------------------------
| These functions provide a means of getting and setting the accessible |
| attributes of instances of this class: |
| traceDestination - Returns an enumeration specifying the trace |
| output destination. |
| enableTrace - Allows trace entries to be written. |
| disableTrace - Stops trace entries from being written. |
| writeToQueue - Sets the location for output to |
| \\QUEUES\\PRINTF32. This is the default. |
| writeToStandardError - Sets the location for output to Standard Error |
| Stream. |
| writeToStandardOutput - Sets the location for output to Standard |
| Output Stream. |
| enableWriteLineNumber - Enables the tracing of line number information. |
| disableWriteLineNumber - Disables the tracing of line number |
| information. |
| enableWritePrefix - Enables the writing of process ID, thread ID, |
| and output line number to trace. |
| disableWritePrefix - Disables the writing of process ID, thread ID, |
| and output line number to trace. |
| isTraceEnabled - Determines whether tracing is currently |
| enabled. |
| isWriteLineNumberEnabled - Determines whether line numbers are currently |
| being written. |
| isWritePrefixEnabled - Determines whether the line count prefix is |
| being written. |
------------------------------------------------------------------------------*/
static ITrace::Destination
traceDestination ( );
static void
enableTrace ( ),
disableTrace ( ),
writeToQueue ( ), /* Default */
writeToStandardError ( ),
writeToStandardOutput ( ),
enableWriteLineNumber ( ),
disableWriteLineNumber( ),
enableWritePrefix ( ),
disableWritePrefix ( );
static Boolean
isTraceEnabled ( ),
isWriteLineNumberEnabled ( ),
isWritePrefixEnabled ( );
protected:
/*----------------------------- Implementation ---------------------------------
| The following functions are used in the implementation: |
| threadId - Used to to determine the current thread identifier. |
| writeString - Used to write to the outout device without |
| formatting. |
| writeFormattedString - Used to write trace data after formatting. The |
| prefix is added, if necessary, and any newlines |
| embedded in the string are updated to include the |
| prefix. |
------------------------------------------------------------------------------*/
static unsigned long
threadId ( );
static void
writeString (char* text),
writeFormattedString (const IString& string,
char* marker);
private:
/*--------------------------------- Private ----------------------------------*/
enum State { uninitialized=1, on=2, writeLineNumber=4, writePrefix=8 };
char
*pszClTraceName;
static int
iClState;
static ITrace::Destination
iClTraceLocation;
static unsigned long
remainingStack ( );
};
/*--------------------------------------------------------------*/
/* Selective inclusion of tracing accomplished based on prior */
/* definition of Trace "level" macros. */
/*--------------------------------------------------------------*/
#ifdef IC_TRACE_ALL
#define IMODTRACE_ALL(modname) ITrace trc(modname, __LINE__ )
#define IFUNCTRACE_ALL() ITrace trc(__FUNCTION__, __LINE__ )
#define ITRACE_ALL(p1) ITrace::write(p1)
#ifndef IC_TRACE_DEVELOP
#define IC_TRACE_DEVELOP
#endif
#else
#define IMODTRACE_ALL(modname)
#define IFUNCTRACE_ALL()
#define ITRACE_ALL(p1)
#endif
#ifdef IC_TRACE_DEVELOP
#define IMODTRACE_DEVELOP(modname) ITrace trc(modname, __LINE__ )
#define IFUNCTRACE_DEVELOP() ITrace trc(__FUNCTION__, __LINE__ )
#define ITRACE_DEVELOP(p1) ITrace::write(p1)
#ifndef IC_TRACE_RUNTIME
#define IC_TRACE_RUNTIME
#endif
#else
#define IMODTRACE_DEVELOP(modname)
#define IFUNCTRACE_DEVELOP()
#define ITRACE_DEVELOP(p1)
#endif
#ifdef IC_TRACE_RUNTIME
#define IMODTRACE_RUNTIME(modname) ITrace trc(modname, __LINE__ )
#define IFUNCTRACE_RUNTIME() ITrace trc(__FUNCTION__, __LINE__ )
#define ITRACE_RUNTIME(p1) ITrace::write(p1)
#else
#define IMODTRACE_RUNTIME(modname)
#define IFUNCTRACE_RUNTIME()
#define ITRACE_RUNTIME(p1)
#endif
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
/*--------------------------------- INLINES ----------------------------------*/
#ifndef I_NO_INLINES
#include <itrace.inl>
#endif
#endif /* _ITRACE_ */