VkTrace(3x)

NAME
     VkTrace - Utility routines for tracing ViewKit applications

HEADER FILE
     #include <Vk/VkTrace.h>

DESCRIPTION
          This package is a set of functions that can be used to generate
          time-stamped traces from within ViewKit applications.  Traces are
          normal ASCII files, intended for human perusal.  For normal VkApp
          applications, the user must insert all calls into the source,
          including initialization from within the application.  For VkMsgApp
          applications, initialization, and some calls are already present.

GLOBAL VARIABLE CONTROLS
          Tracing is controlled by global variables that should be set as
          early as possible within the application.  The variables are:

   vkTraceEnable
          If set, enables tracing.  All calls to VkTrace* will generate
          records.  If clear, no tracing will occur.

   vkTraceDetailEnable
          If set, enables detailed tracing.  All calls to VkTraceDetail* will
          generate records.  If clear, no output from the VkTraceDetail* calls
          will occur.

   vkTraceMessageEnable
          If set, trace records for all ToolTalk messages will be generated.

   vkTraceMessageArgsEnable
          If set, trace records for the arguments to ToolTalk messages will be
          generated.

CONTROLS FROM WITHIN VkMsgApp APPLICATIONS
          VkMsgApp tracing is controlled by application resources as follows:

   TraceEnable
          Enables tracing.  If set, a file name for the trace is constructed
          from the application class name, and the process pid.

   TraceDetailEnable
          Enables detailed tracing.  If set, it will force TraceEnable, too.

   TraceMessageEnable
          Enables tracing of all ToolTalk messages.  If set, it also sets
          TraceEnable.

   TraceMessageArgsEnable
          Enables tracing of the arguments to all ToolTalk messages.  If set,
          it also sets TraceEnable.
FUNCTION DESCRIPTIONS
          There are three sets of functions used to write traces.  All require
          the VkTraceOpen call, and they differ in the format of the trace
          messages.  VkTrace* records have a time stamp, VkTraceDetail records
          do not, and are normally used as supplemental records following a
          regular trace record, and VkTraceMark records have additional
          information giving the time delta since the last VkTraceMark record.

   VkTraceOpen(char *fname)
          void VkTraceOpen(char *fname);


          Opens a trace file with the given name.

   VkTrace(char *string)
          void VkTrace(char *string);


          If vkTraceEnable is set, write a time-stamped trace record with the
          given string.

   VkTrace2(char *string, char* param)
          void VkTrace2(char *string, char* param);


          If vkTraceEnable is set, write a time-stamped trace record with the
          two given strings.

   VkTracev(char *string, char *format, ...)
          void VkTracev(char *string, char *format, ...);


          If vkTraceEnable is set, write a time-stamped trace record with the
          given string, followed by additional text using the format string
          and additional arguments.

   VkTraceDetail(char *string)
          void VkTraceDetail(char *string);


          If vkTraceDetailEnable is set, write a trace record with the given
          string.

   VkTraceDetail2(char *string, char* param)
          void VkTraceDetail2(char *string, char* param);


          If vkTraceDetailEnable is set, write a trace record with the two
          given strings.

   VkTraceDetailv(char *string, char *format, ...)
          void VkTraceDetailv(char *string, char *format, ...);


          If vkTraceDetailEnable is set, write a trace record with the given
          string, followed by additional text using the format string and
          additional arguments.

   VkTraceMark(char *string)
           void VkTraceMark(char *string);


          If vkTraceEnable is set, writes a trace record with the given
          string.

   VkTraceMark2(char *string, char* param)
           void VkTraceMark2(char *string, char* param);


          If vkTraceEnable is set, write a trace record with the two given
          strings.

   VkTraceMarkv(char *string, char *format, ...)
           void VkTraceMarkv(char *string, char *format, ...);


          If vkTraceEnable is set, write a trace record with the given string,
          followed by additional text using the format string and additional
          arguments.

INHERITED MEMBER FUNCTIONS
     None.

CLASSES USED BY THIS CLASS
     None

SEE ALSO
     VkComponent, VkWidgetList,
     ViewKit Programmer's Guide
     The X Window System, DEC Press, Bob Sheifler and Jim Gettys
     The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
     The OSF/Motif Programmers Reference, Prentice Hall, OSF