Document revision date: 5 July 2000

In general, to create an event log, you must follow these four basic steps:

1. Specify the -trace option in your idl command line to enable event logging.
2. Compile and link the application.
3. Assign the event log to a filename or to the screen.
4. Run the application.

The next sections describe how to use the -trace option.

12.2.1 Enabling Event Logging

To enable event logging, you use a command line interface to the IDL compiler. The IDL compiler supports two interfaces:

• A universal interface that can be used on any operating system
• A Digital Command Language (DCL) interface that can be used only on the OpenVMS operating system

Your system manager determines which interface is available on your system. The following sections describe each interface. The examples use the universal interface to demonstrate event logging capabilities.

12.2.1.1 Universal IDL Compiler Interface

To enable event logging with the universal interface, specify the -trace option when you use the idl command to compile an interface. The syntax of the idl command with the -trace option is as follows:

$ idl filename -trace value

Event types are specified as a value of -trace . Valid values and the event types they denote are listed in Table 12-2.

Table 12-2 Event Values and Types

Value	Event Type
all	Log all events.
none	Disable all previously specified trace options.
calls	Log events relating to start and end of all RPC calls.
context	Log events relating to context handle creation, deletion, and rundown.
errors	Log errors.
misc	Log all miscellaneous events.
log_manager	Enable command interface support which allows modification at runtime of event logging options.

For more information about the -trace option, see Section 12.2.2.

12.2.1.2 Digital Command Language Interface for the Event Logger

This section defines the Digital Command Language (DCL) for the Event Logger.

NAME

IDL /TRACE --- Invokes the Interface Definition Language (IDL) Compiler with event logging enabled.

SYNOPSIS

IDL filename /TRACE

QUALIFIER

/TRACE=option[,...])

Controls whether event logging is enabled. If you do not specify this qualifier, the compiler does not enable event tracing. To disable event logging, specify /NOTRACE.

Specify one or more of the following options:

LOG_MANAGER	Controls whether the Log Manager command line interface is enabled. The command line interface to the Log Manager allows you to modify event logging options at runtime. If you do not specify the LOG_MANAGER option, the command line interface will not be enabled. To disable the Log Manager, specify NOLOG_MANAGER.
EVENTS= value,...	Specifies the values for which event logging will be enabled. Specify one or more of the values shown in the following table, except for the value log_manager . (This function is provided by the DCL LOG_MANAGER qualifier.) If you specify only one option, you can omit the parentheses.

Table 12-3 lists some commonly used event logging options in the universal interface with DCL equivalents.

Table 12-3 Universal Interface with DCL Equivalents

Universal Interface	DCL Command
-trace all	/TRACE=EVENTS=ALL
-trace log_manager	/TRACE=LOG_MANAGER
-trace all -trace log_manager	/TRACE=(LOG_MANAGER,EVENTS=ALL)
-trace errors -trace calls	/TRACE=EVENTS=(ERRORS,CALLS)

12.2.2 Using the -trace Option

Once you have used the Event Logger, you will find that it generates a large volume of information to be analyzed. Discard any unneeded log files, since the Event Logger will continue to record information in the files, enlarging them until the disk is full.

To help reduce the generation of unwanted information, you can use the -trace options to enable event logging on only a subset of events. That is, rather than specifying the all option, specify only calls or only context_handles . The subset you specify will depend on the part of your application you are debugging. Because the -trace option provides logging control on a per-compilation basis, the interface must be rebuilt to enable or disable logging of different event types. The -trace options offer the ability to select different event types for the various IDL interfaces that may make up a single application.

You can use the -trace option to request logging of a single type of event, such as errors , with a command similar to the following:

$ idl binopwk.idl -trace errors

You can also use the -trace option to request logging of multiple event types, such as errors and calls as shown below:

$ idl binopwk.idl -trace errors -trace calls

This command enables the Event Logger, specifying error and call event logging.

To enable event logging to trace the execution of RPC calls within a process, perform the following steps:

1. Enable event logging by specifying the -trace option in the idl command you use to compile each interface definition. This example specifies the -trace all option:

   $ idl binopwk.idl -trace all

2. Build and link the client and server portions of the application.
3. Use the symbol RPC_LOG_FILE to direct the log output for both the server and client processes. To store Event Logger output in a file, assign the symbol to a filename. To direct Event Logger output to the standard terminal output for the process (stdout), assign the symbol to double quotation marks (" "). This guide refers to standard terminal output as the screen.
   In the window from which the server portion of the application will be executed, direct logging for the server to a file with the following syntax:

   $ RPC_LOG_FILE == "server.log"

   
   Or, to direct logging for the server to the screen, use the following syntax:

   $ RPC_LOG_FILE == ""

4. In the window from which the client portion of the application will be executed, direct logging for the client to a file with the following syntax:

   $ RPC_LOG_FILE == "client.log"

   
   Or, to direct logging for the client to the screen, use the following syntax:

   $ RPC_LOG_FILE == ""

Now you can invoke the client and server processes. The event log will be recorded in the specified file or displayed on your screen when you execute the application.

12.2.3 Combining Event Logs

Although event logs are generated locally for each process, you can combine event log files to provide a broader view of application execution.

Note that this section does not give examples of each step in the application development process.

The syntax of a merge command is as follows:

$ merge server-filename.log, client-filename. log client_and_server-filename.log

If two events have the same timestamp, you receive a warning message after the merge is completed.

The following example illustrates how to merge logs from two different systems:

1. The server process command sequence is as follows:

   $ idl fpe_server.idl -trace calls -trace errors $ RPC_LOG_FILE == "server.log" $ server

2. The client process command sequence is as follows:

   $ idl fpe_client.idl -trace calls -trace errors $ RPC_LOG_FILE == "client.log" $ client

   
   These command sequences result in two log files: server.log and client.log , shown below. (Note that, in the following example log files, the Event Data field is replaced by the word <DATA> to improve readability of the log.)
   This is file server.log :

   1999-03-03:20:37.170-5:00I0.121 murp:17924/15 fpe.setup log_start <DATA> 1999-03-03:20:37.170-5:00I0.121 murp:17924/15 RPC LogMgrlistening <DATA> 1999-03-03:20:37.180-5:00I0.121 murp:17924/15 fpe.setup activate <DATA> 1999-03-03:20:37.180-5:00I0.121 murp:17924/15 fpe.setup terminate <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 fpe.float <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 transmit_fault <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 fpe.float terminate <DATA>

   
   This is file client.log :

   1999-03-03:20:37.850-5:00I0.121 ifdef:28168/1 fpe.stup log_start <DATA> 1999-03-03:20:37.880-5:00I0.121 ifdef:28168/1 fpe.stup call_start <DATA> 1999-03-03:20:37.190-5:00I0.121 ifdef:28168/1 fpe.stup call_end <DATA> 1999-03-03:20:37.190-5:00I0.121 ifdef:28168/1 fpe.flt call_start <DATA> 1999-03-03:20:37.210-5:00I0.121 ifdef:28168/1 receive_fault <DATA> 1999-03-03:20:37.210-5:00I0.121 ifdef:28168/1 call_failure <DATA>

3. Next, the two log files are merged with the merge command:

   $ merge server.log,client.log client_and_server.log

   
   The resulting file client_and_server.log is as follows:

   1999-03-03:20:37.850-5:00I0.121 ifdef:28168/1 fpe.setup log_start <DATA> 1999-03-03:20:37.880-5:00I0.121 ifdef:28168/1 fpe.setup call_start<DATA> 1999-03-03:20:37.170-5:00I0.121 murp:17924/15 fpe.setup log_start <DATA> 1999-03-03:20:37.170-5:00I0.121 murp:17924/15 RPC LogMgrlistening <DATA> 1999-03-03:20:37.180-5:00I0.121 murp:17924/15 fpe.setup terminate <DATA> 1999-03-03:20:37.190-5:00I0.121 ifdef:28168/1 fpe.setup call_end <DATA> 1999-03-03:20:37.190-5:00I0.121 ifdef:28168/1 fpe.float call_start<DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 fpe.float activate <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 fpe.float exception <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 transmit_fault <DATA> 1999-03-03:20:37.200-5:00I0.121 murp:17924/15 fpe.float terminate <DATA> 1999-03-03:20:37.210-5:00I0.121 ifdef:28168/1 receive_fault <DATA> 1999-03-03:20:37.210-5:00I0.121 ifdef:28168/1 call_failure <DATA>

For the merged output to be accurate, the system clocks on all hosts on which event logs are generated must be closely synchronized. The Distributed Time Service (DTS) component of Compaq's DCE provides such a service. Once the clocks are synchronized, the ordering of events in a merged log file is valid only if the difference between timestamps made on different machines is greater than the inaccuracy field in those timestamps. (See the DTS documentation for more information about timestamps.)

In the preceding client_and_server.log file example, consider the event with the timestamp 1999-03-03:20:37:03.180-5:00I0.121 and the event that follows it (these two event lines are separated from the rest of the log by a blank line before and after). Note that the timestamps indicate that the terminate event precedes the call_end event.

However, you cannot determine this sequence of events by comparing timestamps because the inaccuracy value at the end of the timestamp is greater than the difference between the timestamps. That is, the difference in time between these events is only 10 milliseconds (the difference between 180 and 190 milliseconds). However, the inaccuracy in the timestamps is 121 milliseconds (I0.121). Therefore, the log is not a definitive indicator of which event occurred first. Because of the simplicity of the example and the single thread of control, you can assume that the terminate event preceded the call_end event.

12.2.4 Disabling Event Logging

To disable event logging, compile your interface without specifying the -trace option. For example:

$ idl binopwk.idl

12.3 Using Symbols and the Log Manager to Control Logging Information

In addition to the -trace options, the Event Logger offers two other methods for controlling information in the event log. Each facility is advantageous in different circumstances, depending on the type of processes with which you are working and the type of events you need to log. The two methods are as follows:

• Controlling Logged Events with a Symbol: Select a subset of event types specified previously with the -trace option by creating the symbol RPC_EVENTS. You assign the symbol to the required event types before executing the process. This method allows you to use event logging without rebuilding the interface; however, you must first stop the process or assign the symbol before starting it. This method is also useful in cases where you specified all-inclusive event logging (such as with the -trace all option) but you determine that you need only a subset of events while the application is executing.
• Controlling Logged Events with the RPC Log Manager: Select a subset of event types specified previously with the -trace option by using the RPC Log Manager command interface. This method allows you to modify event logging parameters for an executing image; there is no need to rebuild the interface or to stop and restart the process. In addition, you can use the Log Manager to modify event types specified with the symbol RPC_EVENTS.

The following sections provide detailed descriptions of how to use each of these methods to control the type of events logged.

12.3.1 Controlling Logged Events with a Symbol

One way to control the type of events logged is by assigning the symbol RPC_EVENTS. This method is ideal for an application that contains a single RPC interface because a symbol provides control at the process level, rather than at the interface-by-interface level. However, to enable the symbol, you must first stop the client or server process.

To use symbols to control event logging, first use the IDL -trace option in your idl compile command and then assign the log file with RPC_LOG_FILE. You can then use the symbol RPC_EVENTS to reduce the number of events currently being logged. That is, if you used the -trace errors option to request error event logging, you can subsequently use only the symbol to request logging of errors or none . You cannot use the symbol to increase the number of event types to be logged. To do this, you must recompile the interface with the required -trace options.

The value of RPC_EVENTS is a list of event types separated by commas. The list identifies the event types to be monitored. Valid values are the same as those for -trace (except log_manager ). These values are all , none , calls , context , errors , and misc .

An example command line follows:

$ RPC_EVENTS == "calls,errors"

If the symbol RPC_EVENTS was not assigned, then by default all of the events specified with the -trace option are written into the event log.

12.3.2 Controlling Logged Events with the RPC Log Manager

During application development, certain problems occur only after a server has executed some number of calls. Other problems may require more information than anticipated to debug. These problems can be addressed by enabling the RPC Log Manager in your application image. The Log Manager offers a command line interface ( rpclm ) for manipulating logging operations during application execution. When you use the rpclm command line interface, you need not rebuild your interface or stop and restart your server or client process to manipulate logging operations.

The rpclm command interface commands are shown in Table 12-4.

Table 12-4 Command Interface to rpclm

Command	Description
inquire	Inquire about the currently logged events and determine the name of the active log file.
log	Specify additional events to log. Valid values are all , none , calls , context , errors , and misc .
unlog	Disable logging of the specified event types. Valid values are all , none , calls , context , errors , and misc .
file	Change the output device or file to which events are logged.
quit	Terminate the rpclm session.
help	Display a description of rpclm commands.

Follow these steps to enable the RPC Log Manager to control event logging:

1. Use the -trace log_manager option in your idl compile command.
2. Create the RPC_LOG_FILE symbol and assign it to a filename or to screen output.
3. Execute the client or server process, or both.
4. When the first call is made to an interface compiled with the -trace option, a listening event will be generated into the event log. Invoke the rpclm command interface (as described in step 4 which follows) by specifying the string binding from the listening event.

The rpclm command interface allows you to control event logging parameters from your keyboard. You can use the command interface to reduce the events currently being logged as well as to manipulate logging operations. You can enable or disable logging of different event types (within the set selected with the -trace option), store event logging in a file or display it on the screen, inquire about the current event types being logged, and display the name of the current log file.

The following procedure illustrates how to use the Log Manager:

1. When you compile your interface with the idl compile option, include the -trace log_manager option. For example:

   $ idl binopwk.idl -trace all -trace log_manager

2. Assign the RPC_LOG_FILE symbol to a filename. For example:

   $ RPC_LOG_FILE == "client.log"

3. Execute the client or server process, or both.
4. Upon the first remote procedure call to an interface compiled with the -trace log_manager option, a listening event will be generated into the log. Examine the Event Data field of the listening event in the log to determine the Log Manager string binding. (The RPC Event Logger is itself a client/server application: the Log Manager is a server process, and rpclm is its client. The rpclm client uses the string binding of the listening event to communicate with the Log Manager server.) Invoke rpclm and specify the Log Manager string binding. For example, consider the following event:

   <TIME> murp:17868/15 RPC LogMgr listening ncacn_ip_tcp:16.31.48[3820]

   
   The listening event indicates that the RPC Log Manager is waiting for commands from rpclm . (Note that, in the example, the Time field is replaced by the word <TIME> to improve readability of the log.) To invoke rpclm , enter the listening event string binding for this server process from the Event Data field as follows:

   $ rpclm "ncacn_ip_tcp:16.31.48.144[3820]"

   
   Note that you must enclose the string binding in double quotation marks (" ").

5. As you execute rpclm commands, the Log Manager displays current logging parameters that indicate the changes made to event logging for this process. For example:

   rpclm> unlog all Event types: Events logged to terminal rpclm> log calls Event types: call Events logged to terminal

   
   The log for this server process will have corresponding events logged as follows:

   <TIME> murp:17868/15 RPC Log Mgr log_events none <TIME> murp:17868/15 RPC Log Mgr log_events calls

The following example illustrates a command dialog between the user and rpclm . The dialog begins when the user specifies a string binding from a listening event to rpclm .

$ rpclm "ncacn_ip_tcp:cltdce[1821]" rpclm> help rpclm Commands: inquire - Display logged events and log filename log - Specify additional events to log unlog - Specify events that should no longer be logged file - Change file into which events are logged quit - Exit log manager rpclm> inquire Event Types: calls Events logged to terminal rpclm> log errors Event Types: calls errors Events logged to terminal rpclm> file server.log Event Types: calls errors Events logged to file 'server.log' rpclm> quit

In this dialog, the user enters the help command to display the rpclm commands and command descriptions.

The user then enters the inquire command to display the types of events being logged and the log filename. In this example, errors are being logged to the screen.

The user enters the log calls command to specify that the Log Manager should start logging all events relating to calls, in addition to error events.

The user then enters the file command and specifies a filename. This command requests that rpclm change its output device from the terminal screen to a file named server.log .

	privacy and legal statement
6532_DCE_PG_PRO_007.HTML