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

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.
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

Qp0zDumpStack()--Dump Formatted Stack Trace Data
Qp0zDumpTargetStack()--Dump Formatted Stack Trace Data of the Target Thread
Qp0zLprintf()--Print Formatted Job Log Data
Qp0zUprintf()--Print Formatted User Trace Data

Example

See Code disclaimer information for information pertaining to code examples.

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

#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:

Each trace record is indented by several spaces to aid in readability. Trace records from different threads have different indentation levels.
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.

User Trace Dump for job 100464/USER/TPZDUMP0. Size: 300K, Wrapped 0
times. --- 01/05/1998 14:08:28 ---
    00000013:870960 Tracing Testcase Entry
    00000013:871720 Tracing creation of two threads
     00000014:879904 Tracing in the 50% Cotton, 50% Polyester thread
     00000014:880256 C66E80F4DF:001F60 L:0080 The Data
     00000014:880968  C66E80F4DF:001F60  F5F06C40 C396A3A3 96956B40 F5F06C40     *50% Cotton, 50% *
     00000014:881680  C66E80F4DF:001F70  D79693A8 85A2A385 9900E9E9 E9E9E9E9     *Polyester.ZZZZZZ*
     00000014:882392  C66E80F4DF:001F80  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
     00000014:883096  C66E80F4DF:001F90  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
     00000014:883808  C66E80F4DF:001FA0  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
     00000014:884512  C66E80F4DF:001FB0  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
     00000014:885224  C66E80F4DF:001FC0  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
      00000015:887872 Tracing in the Lacquered Camel Hair thread
      00000015:888216 C66E80F4DF:002000 L:0080 The Data
      00000015:888952  C66E80F4DF:002000  D3818398 A4859985 8440C381 94859340     *Lacquered Camel *
      00000015:889680  C66E80F4DF:002010  C8818999 00D8D8D8 D8D8D8D8 D8D8D8D8     *Hair.QQQQQQQQQQQ*
      00000015:890416  C66E80F4DF:002020  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
      00000015:891152  C66E80F4DF:002030  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
      00000015:891888  C66E80F4DF:002040  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
      00000015:892624  C66E80F4DF:002050  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
      00000015:893352  C66E80F4DF:002060  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
      00000015:894088  C66E80F4DF:002070  D8D8D8D8 D8D8D8D8 D8D8D8D8 D8D8D8D8     *QQQQQQQQQQQQQQQQ*
     00000014:896168  C66E80F4DF:001FD0  E9E9E9E9 E9E9E9E9 E9E9E9E9 E9E9E9E9     *ZZZZZZZZZZZZZZZZ*
    00000013:898832 Tracing completion of the testcase rc=0
Press ENTER to end terminal session.

API introduced: V4R3

Top | UNIX-Type APIs | APIs by category