Qp0zUprintf()--Print Formatted User Trace Data

 #include <qp0ztrc.h>

 int Qp0zUprintf(char *format-string, ...);

The Qp0zUprintf() function prints user data specified by the format-string parameter to the user trace.

If a second parameter, argument-list, is provided, Qp0zUprintf() converts each entry in the argument-list and writes the entry to the user trace according to the corresponding format specification in format-string. If there are more entries in argument-list than format specifications in format-string, the extra argument-list entries are evaluated and then ignored. If there are less entries in argument-list than format specifications in format-string, the user trace output for those entries is undefined, and the Qp0zUprintf() function may return an error.

An application should not use the tracing function in performance critical code. These functions are intended for debugging exception or error conditions. The user trace is a permanent user space object named QP0Z<jobnumber> in the QUSRSYS library. The user trace is created the first time any thread in a job writes trace output. See the Change User Trace (CHGUSRTRC), Dump User Trace (DMPUSRTRC) and Delete User Trace (DLTUSRTRC) CL commands for information about manipulating the user trace properties and objects.

Parameters

format-string

(Input) The format string representing the format of the data to be printed. See the printf() function in the ILE C/C++ Programmer's Guide for a description of valid format strings.

... (argument-list)

(Input) An optional list of arguments that contain entries to be formatted and printed to the user trace.

Authorities

None.

Return Value

Error Conditions

If Qp0zUprintf() is not successful, errno indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL. An invalid format-string or argument-list was specified.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

Usage Notes

1. No locks are held on the user trace between calls to the tracing functions. The user trace can be deleted while in use. The next function that produces trace output will create the user trace again.
   
   
2. If another job on the system has the same job number as an existing user trace, the existing trace data is cleared, and the trace data from the new job replaces it.
   
   
3. As the format of the user trace records can change, only the following CL commands can be used to manipulate the user trace properties and objects:
   
   
   • Change User Trace (CHGUSRTRC) can be used to change the characteristics of the user trace.
     
     
   • Dump User Trace (DMPUSRTRC) can be used to dump trace records to a file or to standard output.
     
     
   • Delete User Trace (DLTUSRTRC) can be used to delete the user trace objects.

Related Information

• Qp0zDump()--Dump Formatted Storage Trace Data
  
  
• Qp0zDumpStack()--Dump Formatted Stack Trace Data
  
  
• Qp0zDumpTargetStack()--Dump Formatted Stack Trace Data of the Target Thread
  
  
• Qp0zLprintf()--Print Formatted Job Log Data

Example

See Code disclaimer information for information pertaining to code examples.

See Qp0zDump()--Dump Formatted Storage Trace Data.