Problem Determination APIs

The problem determination APIs are:

• Qp0zDump() (Dump Formatted Storage Trace Data) dumps the user storage specified by area to the user trace.
• Qp0zDumpStack() (Dump Formatted Stack Trace Data) dumps a formatted representation of the call stack of the calling thread to the user trace.
• Qp0zDumpTargetStack() (Dump Formatted Stack Trace Data of the Target Thread) dumps a formatted representation of the call stack of the target thread to the user trace.
• Qp0zLprintf() (Print Formatted Job Log Data) prints user data specified by format-string as an information message type to the job log.
• Qp0zUprintf() (Print Formatted User Trace Data) prints user data specified by the format-string parameter to the user trace.
• QSCJOINT (Join Trace) sets and clears the trace characteristics of the current job.

Note: Some of these functions unconditionally write the specified application data. The use of these functions should be limited to unexpected failure, exception or other error conditions. The preferred method for writing application trace data is through the use of the QTRC Trace APIs.

Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. Make sure QSYSINC is installed on your system before using any of the functions. See Header Files for UNIX^®-Type Functions for the file and member name of each header file.

The problem determination APIs are intended to be used as an aid in debugging exception or error conditions in application programs. These functions should not be used in performance critical code.

These functions can be used during application development, as well as after the application is made available, as debug mechanisms. For example, a compile option could be used to activate the problem determination functions during application development. When the application is ready to be made available, recompile to deactivate the functions.

Some of the problem determination functions dump or print to the user trace. 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 user trace output. 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 user trace records to a file or to standard output.
  
  
• Delete User Trace (DLTUSRTRC) can be used to delete the user trace objects.

For those problem determination functions that use the user trace, the following should be considered:

• The functions require no authority to the user trace object. See CL commands CHGUSRTRC, DMPUSRTRC, and DLTUSRTRC for the authority required to administer, display, or modify tracing information using the CL commands.
  
  
• 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 user trace output will create the user trace again.
  
  
• If another job on the system has the same job number as an existing user trace, the existing user trace data is cleared, and the data from the new job replaces it.

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