The Trace Facility Design
Trace Information
Calling the Trace Facility
A Tracing Example
The Trace Facility Interface
The NonStop DOM Trace Facility consists of an object API that writes trace message to an ASCII file. You use the Trace Facility to implement instrumentation in your NonStop DOM applications. You can add trace statements to specific portions of your NonStop DOM applications or components to help you troubleshoot your program code.
The Trace Facility consists of a single object called NSDOM_Trace. This object provides several methods that write trace messages out to a specified trace file. To simplify the use of the Trace Facility, NonStop DOM provides several trace macros.
The trace macros (and the NSDOM_Trace methods themselves) shield the user from the details of writing trace messages; the user need not be concerned with the details of the trace file format, opening and closing the trace file, or any platform-specific issues.
When called, the Trace Facility composes a message based on both user-supplied data and data that the system obtains during the call. The Trace Facility then writes the message out to a specified ASCII trace file.
The Trace Facility is designed so that more than a single process can write trace information to a single trace file; the Trace Facility supports multiple processes writing to a single trace file.
The configuration file specifies the file to which the Trace Facility writes. By default, the Trace Facility writes to <stdout>. If a trace message is generated before ORB_init( ) gets called, the Trace Facility also writes to <stdout>.
Each time a trace message is generated, the Trace Facility writes the following information to the trace file:
Although most of this information is provided by the system, the user must supply a specific trace message. This message should aid the user in determining where in the code the trace message was generated.
To generate a trace message, the user calls the predefined trace macro, or the log_trace( ) method defined in the NSDOM_Trace object. The call must be complete with the required, user-supplied parameter values. The Trace Facility then creates a trace message and performs the appropriate operations to write the message to an ASCII trace file.
The trace file information and other configuration data used by the Trace Facility must be specified in the NonStop DOM configuration file. The NonStop DOM 2.0 Configuration Data Facility (CDF) is used to retrieve the configuration data. Trace information is written to a file specified for the ORB entity in the configuration database.
The following macros are provided to simplify the task of adding trace statements to your application code.
/* log trace message */
NSDOM_trace ( const char *pp_data,
short pp_data_len,
CORBA::Enfironment &pr_env );
/* printf style trace output */
NSDOM_tracef ( const char *pp_format, ...);
|
This macro opens the trace file and writes the trace message. By using this macro, you do need to make direct calls to the NSDOM_Trace object.
Note:
To specifically close the trace file, you must call NSDOM_Trace::close_trace_file( ). If you do not call this method, the Trace Facility will close the trace file when the current process exits.
The following example shows how to add a trace message to your code using the predefined trace macro. When your application processing encounters the call to NSDOM_TRACE( ), the Trace Facility will write a message to the default ASCII trace file.
#include "nsdorb/trace.h"
main( )
{
CORBA::Environment lv_env;
char lv_trace_buf[100];
...
/*perform trace operation */
strcpy(lv_trace_buf, "User-routine while loop");
NSDOM_trace ( lv_trace_buf, strlen(lv_trace_buf ), lv_env);
...
/* using the printf-style trace macro */
NSDOM_tracef ("%s %d", S1, 25);
...
}
|
As a user of the Trace Facility, you need not know the actual API calls NSDOM_Trace. You should use the Trace macros provided, and let them do the work of calling the API methods. However, you might find it useful to know how the Tracing Facility works.
The public section of NSDOM_Trace contains four methods. Three of these methods are used to actually create a trace message, while the fourth method can be used to create a specific, user-defined trace file (by default, the Trace Facility writes trace messages to the file specified during system configuration).
//C++ NSDOM_Trace Class
class NSDOM_Trace
{
public:
static void set_trace_file_name(char *pp_trace_fname,
CORBA::Environment &pr_env);
static void open_trace_file (CORBA::Environment &pr_env);
static void close_trace_file (CORBA::Environment &pr_env);
static void log_trace (char *pp_trace_data,
short pv_trace_data_len,
CORBA::Environment &pr_env);
};
|
The NSDOM_Trace::log_trace( ) method writes a trace message to the trace file. This method will also create and open the trace file if this operation has not already been performed by a specific call to the open_trace_file( ) method (it is not necessary to call open_trace_file( ) before calling this method).
The NSDOM_Trace::open_trace_file( ) method provides a means to create and open the trace file before calling the log_trace( ) method.
NSDOM_Trace::close_trace_file( ) provides a way to specifically close the opened trace file. NSDOM_Trace does not automatically close the trace file until the current process exits.
NSDOM_Trace::set_trace_file_name( ) provides an option to specify a user-defined trace file name. This method allows the user to override the default trace file specified in the configuration database. To create a user-specified trace file, this method must be called before you make any calls to open_trace_file( ) or log_trace( ).