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.

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, one of the following methods could be used:

• Use a compile option that activates the problem determination functions during application development. When the application is ready to be made available, recompile to deactivate the functions.
  
  
• Design a method to (quickly) check and see whether application problem determination is desired, as well as an external method to activate application problem determination. Then, use the problem determination functions in such a manner as to check (at run time) whether or not the functions should be called.

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 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 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 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 trace data is cleared, and the trace data from the new job replaces it.