#include <qtrc.h> int QtrcWriteTextPPrintF (unsigned int Coded_Level, const char *Component, const char *Subcomponent, const char *Function, const char *Format, ...);Service Program Name: QTRCMGR
The QtrcWriteTextPPrintF() function writes a component trace record as text string data, using a pointer-based print formatted layout, to an active trace collection if certain trace conditions are met. Note: The QtrcWriteTextPPrintF() function is intended to be used only by prototyped call languages, such as RPG. Other languages, such as C and C++, should instead use the QtrcWriteTextPrintF() function.
The QtrcWriteTextPPrintF() uses the Format parameter to process any additional parameters (Argument_List) that are specified following the Format parameter. The QtrcWriteTextPPrintF() function works just like the QtrcWriteTextPrintF() function, except that the additional parameters (Argument_List) are all expected to be pointers (references) to the entries to be formatted. Format specifications, which begin with a percent sign (%), are used to convert each corresponding argument list entry referenced by the pointer, and include the resulting text string in the trace record. If there are more argument list referenced entries than there are format specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not enough argument list referenced entries for all the format specifications.
Each call to the QtrcWriteTextPPrintF() 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:
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:
QTRC_LEVEL_ERROR (1) | ERROR-level trace point. A component trace record is written if the Component has an active trace level of either *ERROR, *INFO, or *VERBOSE. |
QTRC_LEVEL_INFO (2) | INFO-level trace point. A component trace record is written if the Component has an active trace level of either *INFO or *VERBOSE. |
QTRC_LEVEL_VERBOSE (3) | VERBOSE-level trace point. A component trace record is written if the Component has an active trace level of *VERBOSE. |
The trace level of the trace point.
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.
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.
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.
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 function for a description of valid format strings and how the format specifications are used along with an argument list.
An optional list of arguments that contain pointers (references) to entries that are to be formatted and written as part of the text string trace record.
None.
If QtrcWriteTextPPrintF() 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 condition | Additional information |
---|---|
[EINVAL] |
The specified Coded_Level is not one of the supported trace levels. The specified Component is not a valid component name. |
[EFAULT] | |
[EUNKNOWN] |
None.
The following example uses an INFO-level trace point to write formatted text trace data for a component named MYCOMP. The component trace record will be written to the active trace collection if the program is called with at least one parameter and the STRTRC CL command was used before calling the example, specifying either TRCTYPE((MYCOMP *INFO)) or 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> int main(int argc, char *argv[]) { const char *myComp = "MYCOMP"; const int ParmNum = 1; int rc; if (argc > 1) { rc = QtrcWriteTextPPrintF(QTRC_LEVEL_INFO, myComp, "SUBCOMP", argv[0], "Parameter %d is %s", &ParmNum, argv[ParmNum] ); if (rc != 0) { printf("QtrcWriteTextPPrintF() 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; }Example Output:
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 ]