Qp0zDump()--Dump Formatted Storage Trace Data


  Syntax
 #include <qp0ztrc.h>

 void Qp0zDump(const char *label,
               void       *area,
               int        len);

  Service Program Name: QP0ZCPA

  Default Public Authority: *USE

  Threadsafe: Yes

The Qp0zDump() function dumps the user storage specified by area to the user trace. The user-provided storage is formatted for viewing in hexadecimal representation for up to len number of bytes. The formatted storage is labeled with the text string specified by label.

If any input parameters are not valid, or an incorrect or error condition is detected, the Qp0zDump() function returns immediately and no error is indicated.

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

label
(Input) A pointer to a string that is used to label the storage dump.

area
(Input) A pointer to storage area that is to be formatted and dumped to the user trace.

len
(Input) The number of bytes of storage to be formatted in the user trace.

Authorities

None.


Return Value

None.


Error Conditions

If Qp0zDump() is not successful, the function returns immediately and no error is indicated.


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


Example

The following example uses Qp0zDump() and Qp0zUprintf() functions to produce trace output.

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

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <qp0ztrc.h>

#define  THREADDATAMAX    128

void *theThread(void *parm)
{
   char                    *myData = parm;

   printf("Entered the %s thread\n", myData);
   Qp0zUprintf("Tracing in the %s thread\n", myData);
   Qp0zDump("The Data", myData, THREADDATAMAX);
   free(myData);
   return NULL;
}


int main(int argc, char **argv)
{
   pthread_t             thread, thread2;
   int                   rc=0;
   char                 *threadData;


   printf("Enter Testcase - %s\n", argv[0]);
   Qp0zUprintf("Tracing Testcase Entry\n");

   printf("Create two threads\n");
   Qp0zUprintf("Tracing creation of two threads\n");

   threadData = (char *)malloc(THREADDATAMAX);
   memset(threadData, 'Z', THREADDATAMAX);
   sprintf(threadData, "50%% Cotton, 50%% Polyester");
   rc = pthread_create(&thread, NULL, theThread, threadData);
   if (rc) {
     printf("Failed to create a %s thread\n", threadData);
     exit(EXIT_FAILURE);
   }

   threadData = (char *)malloc(THREADDATAMAX);
   memset(threadData, 'Q', THREADDATAMAX);
   sprintf(threadData, "Lacquered Camel Hair");
   rc = pthread_create(&thread2, NULL, theThread, threadData);
   if (rc) {
     printf("Failed to create a %s thread\n", threadData);
     exit(EXIT_FAILURE);
   }

   printf("Wait for threads to complete\n");
   rc = pthread_join(thread, NULL);
   if (rc) { printf("Failed pthread_join() 1\n"); exit(EXIT_FAILURE); }

   rc = pthread_join(thread2, NULL);
   if (rc) { printf("Failed pthread_join() 2\n"); exit(EXIT_FAILURE); }

   printf("Testcase complete\n");
   Qp0zUprintf("Tracing completion of the testcase rc=%d\n", rc);
   return 0;
}

Trace Output:

This trace output was generated after the test case was run by using the CL command DMPUSRTRC JOB(100464/USER/TPZDUMP0) OUTPUT(*STDOUT). The above example program ran as job 100464/USER/TPZDUMP0.

Note the following in the trace output:

  1. Each trace record is indented by several spaces to aid in readability. Trace records from different threads have different indentation levels.

  2. Each trace record is identified by the hexadecimal thread ID, a colon, and a timestamp. The timestamp can be used to aid in debugging of waiting or looping threads. For example, the third trace record shown below (the Tracing Testcase Entry trace point) was created by thread 0x13, and occurred 0.870960 seconds after the last full date and time label. This means that the trace record was created on 5 January 1998 at 14:08:28.870960. A full date and time label is placed between those trace points that occur during different whole seconds.


API introduced: V4R3

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