[Previous Example] [Next Example] [Overview of Examples] [User's Guide]
Examples\Advanced\User_Formats

User-Defined Formats

Introduction

This example demonstrates how to define your own data formatting subprograms, for processing your data at format time (usually not while the program is running). Format subprograms give you finer control over the way the logged data is formatted, and give you more flexibility during post-runtime data reduction.

Here are some reasons why you may want to use user-defined log formats:

Here is how it works:
Each log statement inside your probe can specify not only which data to log, but also specify which subprogram to use for formatting these logged values (for later on). Then, when the logged data is formatted (with either the apformat tool or aprobe's immediate_formatting mechanism), it will be passed to your specified format subprogram rather than just printed out. At format time, the format subprograms will be called in the same order as their corresponding log statements were executed at run-time (during earlier data collection).

Your format subprogram's parameter profile must conform to the types of the logged data items. This means that, for each logged data item, the format subprogram must have a corresponding formal parameter declared as a pointer to the actual type of the object being logged. We'll discuss more on this later.

Target Program

For this example, we will use the same target program Examples\Target\Hello.c which was described in Example 1.

Writing the Probe

Suppose that we want to log all the parameters passed in all calls to SayHello(). The probe below accomplishes this task:

Examples\Advanced\User_Formats\Hello.apc 

void EnterSubprogramFormat(char *s, int *Year)
{
   static int Count = 0;
   printf("#%d Enter %s(%d)\n", ++Count, s, *Year);
}

probe thread
{
   probe "SayHello"
   {
      on_entry
         log("SayHello", $1) with EnterSubprogramFormat;
   }
}

Notice that the log statement has an extra "with EnterSubprogramFormat" part appended to it. This tells aprobe and apformat which subprogram to call when formatting the data that came from this (and only this) log statement. Any other log statements are unaffected by this. Every log statement can have its own format subprogram.

The format subprogram's parameters must conform to the data types being logged by the log statement itself, not to the subprogram being probed. And, if a log statement happens to log, say, 5 items of types A, B, C, D, and E, then the format subprogram must have 5 parameters of types *A, *B, *C, *D, and *E. Notice that these are all pointers to the actual logged data types, not exactly the same as the logged data types. The exception to this rule is arrays (incl. strings), because of the way the C language treats arrays, so a logged array is matched by a parameter of exactly that same array type, not by a pointer to the array.

The log statement in this probe always logs 2 items: a null-terminated string literal, and $1 which denotes the first parameter of SayHello(). In Hello.c, we see that SayHello's first parameter is named Year and is of type int.

Therefore, EnterSubprogramFormat must have 2 parameters of the appropriate types: first a string, secondly a pointer to an int. Recall that a string is a special case, and therefore we pass in a string, not a pointer to a string.

EnterSubprogramFormat may do anything it wants with that data, including printing it out, like this. The more typical scenario, though, is to combine it with data from other format subprograms, and build a large report at the end of formatting.

Running The Example

  1. Build the probe.

  2. Run the program with Aprobe.

  3. Format the collected data.

Exercises

  1. Modify the EnterSubprogramFormat format subprogram, and use the apc compiler to rebuild the Hello.dll User Action Library (UAL), but do not rerun the executable.
  2. Format the same old Hello.apd output with the modified Hello.dll

Summary

From this example you have learned:
[Previous Example] [Next Example] [Overview of Examples] [User's Guide]