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:
In addition to being able to specify the level of diagnostic logging, you also specify whether the DPCL communication daemon should:
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:
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
|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.