QtrcWriteHexDumpF()--Write Hexadecimal Dump Formatted Trace Data

 #include <qtrc.h>

 int QtrcWriteHexDumpF
         (unsigned int    Coded_Level,
          const char     *Component,
          const char     *Subcomponent,
          const char     *Function,
          const char     *Label,
          const void     *Data,
          size_t          Data_Length,
          unsigned int    Format_Option,
          void           *Reserved);

The QtrcWriteHexDumpF() function writes a component trace record as hexadecimal dump data to an active trace collection if certain trace conditions are met. A format option can be used to indicate the desired formatting of the hexadecimal dump through the Format_Option parameter.

Each call to the QtrcWriteHexDumpF() function is considered a trace point. A component trace record is written to the trace collection when all the trace conditions are met for a given trace point. The trace conditions include:

• A trace collection must be active for the current thread.
• The specified Component must be part of the trace collection.
• The active trace level that was used for the specified Component when the trace collection was started must allow the Coded_Level of the trace point.

Each trace point must indicate the desired trace level using the Coded_Level parameter. This trace level is compared against the active trace level that was used for the specified Component when the trace collection was started. Components are defined to the trace collection using the Start Trace (STRTRC) CL command. The Coded_Level must be one of the following values:

Parameters

Coded_Level

(Input)

The trace level of the trace point.

Component

(Input)

A pointer to the null-terminated component name. The component name should be 10 characters in length or less. If more than 10 characters are specified, only the first 10 characters are used.

Subcomponent

(Input)

A pointer to the null-terminated subcomponent name. The subcomponent name should be 10 characters in length or less. If more than 10 characters are specified, only the first 10 characters are used. This parameter can be set to NULL if no subcomponent is to be defined.

Function

(Input)

A pointer to the null-terminated function name. The function name should be 512 characters in length or less. If more than 512 characters are specified, only the first 512 characters are used. This parameter can be set to NULL if no function is to be defined.

Label

(Input)

A pointer to the null-terminated label that will precede the hexadecimal dump data. The label should be 128 characters in length or less. If more than 128 characters are specified, only the first 128 characters are used. This parameter can be set to NULL if no label is to be defined.

Data

(Input)

A pointer to the data to be written as a hexadecimal dump.

Data_Length

(Input)

The length in bytes of the data to be written.

Format_Option

(Input)

The desired formatting option to be used for the hexadecimal dump. The formatting option must be set to one of the following:

QTRC_FORMAT_OPTION_NONE (0)	No format. Only the hexadecimal data will be shown in the trace record. This option is equivalent to using the QtrcWriteHexDump() API.
QTRC_FORMAT_OPTION_EBCDIC (1)	EBCDIC format. The hexadecimal data will be shown in the trace record along with the EBCDIC representation of that data.
QTRC_FORMAT_OPTION_ASCII (2)	ASCII format. The hexadecimal data will be shown in the trace record along with the ASCII representation of that data.
QTRC_FORMAT_OPTION_UTF8 (3)	UTF-8 format. The hexadecimal data will be shown in the trace record along with the UTF-8 representation of that data.
QTRC_FORMAT_OPTION_UTF16 (4)	UTF-16 format. The hexadecimal data will be shown in the trace record along with the UTF-16 representation of that data.

Reserved

(Input)

Reserved for future use. Must be set to NULL.

Authorities and Locks

None.

Return Value

0

QtrcWriteHexDumpF() was successful. However, the component trace record will only be written if the trace conditions are met.

value

QtrcWriteHexDumpF() was not successful. An error condition was detected which would prevent the component trace record from ever being written.

Error Conditions

If QtrcWriteHexDumpF() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

Error Messages

None.

Usage Notes

1. If the QtrcWriteHexDumpF() function is called multiple times, there may be a noticeable performance impact. The QtrcGetActiveLevel() API can be used, and the results saved into a variable for later, multiple uses. The variable can be used to quickly check if the specified Component is currently active at the appropriate trace level, prior to calling the QtrcWriteHexDumpF() function. The variable should be periodically updated, to ensure a current view of the component's active trace level. Refer to the QTRC Trace APIs for additional information concerning the use of trace levels.
2. Refer to the QTRC Trace APIs for additional information concerning the Coded_Level, Component, Subcomponent, Function, and Label parameters.
3. When the Format_Option indicates EBCDIC format, code page 37 is used for the EBCDIC representation. When the Format_Option indicates ASCII format, code page 819 is used for the ASCII representation.

Related Information

• QtrcGetActiveLevel()--Get Active Trace Level
• QtrcWriteHexDump()--Write Hexadecimal Dump Trace Data
• QtrcWriteStack()--Write Call Stack Trace Data
• QtrcWriteText()--Write Text Trace Data
• QtrcWriteTextPrintF()--Write Text Trace Data using Print Formatted
• QtrcWriteTextPPrintF()--Write Text Trace Data using Pointer-based Print Formatted
• QtrcWriteTextVPrintF()--Write Text Trace Data using Variable Argument List Print Formatted
• Start Trace (STRTRC) CL command
• For additional information about the QTRC Trace environment, see QTRC Trace APIs.

Example

The following example uses a VERBOSE-level trace point to write EBCDIC formatted hexadecimal dump trace data for a component named MYCOMP. The component trace record will only be written to the active trace collection if the STRTRC CL command was used before calling the example, specifying TRCTYPE((MYCOMP *VERBOSE)).

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <qtrc.h>
#include <stdio.h>
#include <errno.h>

int main(int argc, char *argv[])
{
  const char *myComp = "MYCOMP";
  char myBuffer[256];
  int i, rc;

  for (i=0; i<sizeof(myBuffer); ++i) {
    myBuffer[i] = i;
  }

  rc = QtrcWriteHexDumpF(QTRC_LEVEL_VERBOSE,
                         myComp,
                         "SUBCOMP",
                         argv[0],
                         "Contents of myBuffer after initialization",
                         (void *)myBuffer,
                         sizeof(myBuffer),
                         QTRC_FORMAT_OPTION_EBCDIC,
                         NULL );
  if (rc != 0) {
    printf("QtrcWriteHexDumpF() failed with error %d\n",
           rc);
    return -1;
  }

  printf("Use the ENDTRC CL command with PRTTRC(*YES) in order to\n");
  printf("see the component trace records that were written to the\n");
  printf("trace collection.\n");

  return 0;
}

Use the ENDTRC CL command with PRTTRC(*YES) in order to
see the component trace records that were written to the
trace collection.

[ Back to top | Problem Management APIs | APIs by category ]