TraceCreateEntry

TraceCreateEntry creates an event entry in the system event buffer. It is the static trace-point creation mechanism.

Syntax

TraceCreateEntry(pTraceCreateEntry);

Parameters

pTraceCreateEntry (PTCEREQUEST) - input

Pointer to the TraceCreateEntry parameter packet.

Returns

rc (APIRET) - returns

TraceCreateEntry returns the following values:

• 1702 INVALID_LF_PACKET_REVISION_NUMBER
• 1703 INVALID_DATA_POINTER
• 1802 INVALID_TRACE_MAJOR_CODE
• 1803 INVALID_TRACE_MINOR_CODE
• 1806 INVALID_PACKET_SIZE

Remarks

Event trace records contain information that describes the occurrence of software events. They can be used both as service aids and in performance monitoring.

The library TRACE.LIB must be linked with object files that use TraceCreateEntry.

Example Code

#define INCL_TRACE
#include <os2.h>

PTCEREQUEST    pTraceCreateEntry;
APIRET         rc;

rc = TraceCreateEntry(pTraceCreateEntry);

The following example adds an event trace entry to the system trace buffer. For this example, the trace entry will contain the contents of two internal program variables.

  #define INCL_DOSPROCESS

  #include <stdio.h>                     /* C library for standard I/O        */
  #include <stdlib.h>                    /* C library of standard routines    */
  #include <string.h>                    /* C library for string operations   */
  #include <os2.h>                       /* OS/2 Dos api calls                */
  #include <trace.h>                     /* Trace public API data structures  */

  #define HKWD_TEST 43
  #define hkwd_test_entry 0001

  struct {
    ULONG  var1;
    USHORT var2;
  } trace_data;

  TCEREQUEST trace_create_entry_packet;

  VOID main(VOID)
  {
    APIRET rc = NO_ERROR;

    /**************************************************************************/
    /* Set up the TraceCreateEntry parameter packet                           */
    /**************************************************************************/
    trace_create_entry_packet.packet_size            = sizeof(TCEREQUEST);
    trace_create_entry_packet.packet_revision_number = TRACE_RELEASE;
    trace_create_entry_packet.major_event_code       = HKWD_TEST;
    trace_create_entry_packet.minor_event_code       = hkwd_test_entry;
    trace_create_entry_packet.event_data_length      = sizeof(trace_data);
    trace_create_entry_packet.event_data             = (PVOID)&trace_data;

    /**************************************************************************/
    /* Place tracepoint data in the tracepoint data buffer                    */
    /**************************************************************************/
    trace_data.var1 = UINT_MAX;
    trace_data.var2 = 1;

    rc = TraceCreateEntry(&trace_create_entry_packet);
    if (rc |= NO_ERROR) {
      printf("TraceCreateEntry RC(%d)\n", rc);
    }
  }