Dynamic Probe Class Library Programming Guide

Chapter 17. Generating diagnostic logs

Each DPCL communication daemon is capable of generating diagnostic messages that enable you or the IBM Support Center to identify problems that your analysis tool may encounter while interacting with the DPCL system. These messages can be turned on separately for each DPCL communication daemon that your analysis tool is interacting with. Since, on each host machine, there is one DPCL communication daemon running per DPCL user, this means that you can generate diagnostic messages that detail your analysis tool's interaction with the DPCL system on each host machine that is running target application processes to which your analysis tool is connected. Be aware, however, that you cannot have multiple analysis tools for the same user attempting to control logging at the same time.

To turn logging on for a particular host machine, your analysis tool code can call either the Ais_log_on function or its blocking equivalent -- Ais_blog_on. The prototypes for these functions (in addition to supporting data type and constant definitions) are contained in the header file LogSystem.h. There are five levels of diagnostic messages that may be generated. When calling either the Ais_log_on or Ais_blog_on function, your analysis tool can specify the logging level using one of the enumeration constants of the LoggingLevel enumeration type. The LoggingLevel enumeration constants are:

LGL_fatal

Diagnostic messages will be generated by the DPCL communication daemon only if the next DPCL system action is to crash.

LGL_severe

In addition to messages indicating fatal conditions, the DPCL communication daemon will generate messages for other serious errors.

LGL_warning

In addition to messages indicating fatal and severe error conditions, the DPCL communication daemon will also generate warning messages.

LGL_trace

In addition to fatal, severe and warning messages, the DPCL communication daemon will also generate function entry/exit trace information.

LGL_detail

The most detailed level of diagnostic messages will be generated by the DPCL communication daemon. In addition to the severe, error, warning, and function entry/exit trace information, the DPCL communication daemon will generate other, more general, information. Be aware that this setting will result in a large number of generated messages.

In addition to being able to specify the level of diagnostic logging, you also specify whether the DPCL communication daemon should:

• Save messages to a file on the host machine.
• send each message back to the analysis tool to be handled by a callback, or
• save messages to a file on the host machine, and also send each message back to the analysis tool to be handled by a callback.

If you elect to have the DPCL communication daemon save the messages to a file, it will save the file to the directory /tmp, and will name it by concatenating the string "dpclsd" with the DPCL communication daemon's UNIX process ID. The string "dpclsd" and the UNIX process ID are separated by a period (.). For example, if the UNIX process ID of the DPCL communication daemon is 3231, the generated file would be /tmp/dpclsd.3231.

While it is easiest to simply have the DPCL communication daemon save the diagnostic information to a log file on the host machine, you might want to manipulate the messages using a callback in order to have more control over the log file your analysis tool then generates. For example, you could create a single log from the diagnostic messages generated by several host machines, or you could intersperse additional diagnostic messages specific to your tool along with the DPCL communication daemon messages.

When calling either the Ais_log_on or Ais_blog_on function, your analysis tool can specify this "logging destination" using one of the enumeration constants of the LoggingDest enumeration type. The LoggingDest enumeration constants are:

LGD_client

The DPCL communication daemon sends each message back to the analysis tool for processing within a specified callback routine. The messages sent to the logging callback are null-character ('\0') terminated ASCII strings.

LGD_daemon

The DPCL communication daemon saves the messages to a log file on the host machine.

LGD_both

The DPCL communication daemon sends each message back to the analysis tool for processing within a specified callback routine and also saves the messages to a log file on the host machine. If processing the messages in a callback, be aware that the messages sent to the logging callback are null-character ('\0') terminated ASCII strings.

LGD_neither

Turns logging off. Messages are not sent to the analysis tool, nor are they saved to a log file on the host.

The following table illustrates how to turn logging on using either the Ais_log_on or Ais_blog_on function. In this example, warning-level messages will be generated and saved to a log file on the host. The NULL values in the following examples represent where we could potentially specify a callback routine or a callback tag. If we had chosen to have the DPCL communication daemon send each message back to the analysis tool, we would have specified the callback routine that would process these messages.

To start the target application processes:	Do this:
Using the asynchronous function Ais_log_on	sts = Ais_log_on(host, LGL_warning, LGD_daemon, NULL, NULL, NULL, NULL);
Using the blocking function Ais_blog_on	sts = Ais_blog_on(host, LGL_warning, LGD_daemon, NULL, NULL);

Once your analysis tool code has turned logging on, it can modify the logging level or the logging destination by simply calling the Ais_log_on or Ais_blog_on functions again, specifying the new logging level or destination. You can turn logging off by specifying enumeration constant LGD_neither as the logging destination. You can also turn logging off by calling the Ais_log_off or Ais_blog_off functions.

For more information about the Ais_log_on, Ais_blog_on, Ais_log_off, or Ais_blog_off functions, refer to the UNIX man pages for these functions, or their entries in the DPCL Class Reference.