QtrcWriteTextVPrintF()--Write Text Trace Data Using Variable Argument List Print Formatted

 #include <qtrc.h>

 int QtrcWriteTextVPrintF
         (unsigned int    Coded_Level,
          const char     *Component,
          const char     *Subcomponent,
          const char     *Function,
          const char     *Format,
          va_list         Argument_List);

The QtrcWriteTextVPrintF() function writes a component trace record as text string data, using a variable argument list print formatted layout, to an active trace collection if certain trace conditions are met. Note: Because of the variable argument list parameter, the QtrcWriteTextVPrintF() function is meant to be used only in C and C++ programs.

The QtrcWriteTextVPrintF() uses the Format parameter to process the variable argument list specified by the Argument_List parameter. The QtrcWriteTextVPrintF() function works just like the QtrcWriteTextPrintF() function, except that Argument_List points to a list of arguments whose number can vary from call to call in the program. These arguments should be initialized by va_start for each call. Format specifications, which begin with a percent sign (%), are used to convert each corresponding argument list entry, and include the resulting text string in the trace record. If there are more argument list entries than there are format specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not enough argument list entries for all the format specifications.

Each call to the QtrcWriteTextVPrintF() 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.

Format

(Input)

A pointer to the null-terminated format string. The format string provides the format specification of the text to be written as a trace record. See the printf()--Print Formatted Characters for a description of valid format strings and vprintf()--Print Argument Data for a description of how the format specifications are used along with a variable argument list.

Argument_List

(Input)

Pointer to a list of arguments whose number can vary from call to call in the program. These arguments should be initialized by va_start for each call. The variable argument list contains entries to be formatted and written as part of the text string trace record.

Authorities and Locks

None.

Return Value

0

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

value

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

Error Conditions

If QtrcWriteTextVPrintF() 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 QtrcWriteTextVPrintF() 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 QtrcWriteTextVPrintF() 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, and Function parameters.
3. The Format parameter and the corresponding Argument_List parameter are used to write a string of characters as trace data, in the same style as the vprintf() function. This provides a way to write a function that takes a variable argument list, and use those arguments to write out text trace data with replacement values. The Format string is assumed to be in the CCSID of the job.
4. The Format parameter should only contain characters in the invariant character set. This is also true for any strings that may be used in the Argument_List.
5. The total amount of text data that can be written as trace data is limited to 2048 characters. In order to trace more than 2048 characters of text data, the QtrcWriteHexDumpF function could be used to write the text data as hexadecimal trace data with a formatting option that includes the appropriate text representation. An alternative would be to split up the text data into multiple sections and call the QtrcWriteTextVPrintF() function for each section.

Related Information

• QtrcGetActiveLevel()--Get Active Trace Level
• QtrcWriteHexDump()--Write Hexadecimal Dump Trace Data
• QtrcWriteHexDumpF()--Write Hexadecimal Dump Formatted 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
• printf()--Print Formatted Characters
• vprintf()--Print Argument Data
• Start Trace (STRTRC) CL command
• For additional information about the QTRC Trace environment, see QTRC Trace APIs.

Example

The following example provides two internal functions that can be used to write formatted text trace data for a component named MYCOMP and a component named THATCOMP. This example shows how an application can provide their own trace point functions that reduce the amount of code needed to write similar trace records. The component trace records will be written to the active trace collection if the STRTRC CL command was used before calling the example, specifying either TRCTYPE((MYCOMP *INFO) (THATCOMP *VERBOSE)) or TRCTYPE((MYCOMP *VERBOSE) (THATCOMP *VERBOSE)).

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

#include <qtrc.h>
#include <stdarg.h>

void traceMYCOMP(unsigned int, char *, ...);
void traceV_THATCOMP(char *, ...);

int main(int argc, char *argv[])
{
  int val = 63;
  int val2 = 430;
  int val3 = 82;

  /* Trace val as INFO-level trace point for MYCOMP */
  traceMYCOMP(QTRC_LEVEL_INFO,"val=%d",val);

  /* Trace val2 and val3 for THATCOMP.  The function */
  /* always uses subcomponent SUBCOMP and a          */
  /* VERBOSE-level trace point.                      */
  traceV_THATCOMP("val2=%d val3=%d", val2, val3);

  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;
}

void traceMYCOMP(unsigned int tLvl, char *fmt, ...)
{
  va_list argPtr;
  const char *myComp = "MYCOMP";
  int rc;

  va_start(argPtr, fmt);
  rc = QtrcWriteTextVPrintF(tLvl,
           myComp,
           NULL,  /* No subcomponent defined */
           NULL,  /* No function defined */
           fmt,
           argPtr );
  if (rc != 0) {
    printf("QtrcWriteTextVPrintF() failed with error %d\n",
           rc);
  }
  va_end(argPtr);
  return;
}

void traceV_THATCOMP(char *fmt, ...)
{
  va_list argPtr;
  const char *thatComp = "THATCOMP";
  const char *thatSubcomp = "SUBCOMP";
  int rc;

  va_start(argPtr, fmt);
  rc = QtrcWriteTextVPrintF(QTRC_LEVEL_VERBOSE,
           thatComp,
           thatSubcomp,
           NULL,        /* No function defined */
           fmt,
           argPtr );
  if (rc != 0) {
    printf("QtrcWriteTextVPrintF() failed with error %d\n",
           rc);
  }
  va_end(argPtr);
  return;
}

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 ]