Setting up logging and tracing

As part of the configuration of the ODA, you must set up the logging and tracing. You specify the logging and tracing information for an ODA in the Configure Agent dialog box of Business Object Wizard. Business Object Wizard always provides the standard configuration properties (shown in Table 11) for an ODA.

Table 11. Standard ODA configuration properties.
Property name Property type Description
TraceFileName
 
String Specifies the file into which the ODA writes trace information. For more information, see "Specifying the trace file and trace level".
TraceLevel
 
 
 
Integer Trace level enabled for the ODA. For more information, see "Specifying the trace file and trace level"..
MessageFile
 
String Name of the ODA's error and message file. Use this property to verify or specify an existing file. For more information, see "Specifying the ODA message file".

This section provides the following information:

Specifying the trace file and trace level

Figure 44 shows the Configure Agent dialog box in Business Object Wizard, in which you specify the name of the trace file and the trace level.

Figure 44. Specifying tracing information


Specifying a trace file

The TraceFileName configuration property specifies the name of the ODA's

trace file. This file is the destination for all trace and error messages that the ODA logs. By default, the ODA run time names the trace file according to the following naming convention:

ODAnametrace.txt
 

In the preceding line, ODAname is the name that uniquely identifies the ODA. For example, if the ODA is named HTMLODA, it generates a trace file named HTMLODAtrace.txt.

Note:
An ODA uses only one file to hold both trace and error messages. Therefore, although this file is called a trace file, it also contains any error messages that the ODA generates.

If the specified trace file does not exist, the ODA creates it in the ODA's run-time directory, which is the ODA\srcDataName subdirectory of the product directory. If the specified trace file already exists, the ODA appends to it. When configuring the ODA, you can specify a different name for the trace file by resetting the TraceFileName property.

Setting the trace level

The TraceLevel configuration property specifies the ODA's system trace level. The ODA's trace method sends the specified message to the trace file when the message's trace level is less than or equal to this system trace level. Therefore, the system trace level determines the level of detail that the trace messages provide. Table 12 lists trace levels and their associated behavior.

Table 12.
Trace levels
Level Behavior
0 Writes error messages to the specified trace file.
1 Traces whenever a method is entered--useful for status messages and key information for each business object definition.
2 Traces the agent properties and the values received.
3
  • Traces the names of the business object.
  • Traces the business object properties and the values received.

4
  • Traces the spawning of all threads.
  • Traces a message whenever a method is entered and exited.

5
  • Indicates the initialization of the Object Discovery Agent and logs the values retrieved for all the Object Discovery Agent properties.
  • Traces detailed status of each thread spawned by the Object Discovery Agent.
  • Traces the business object definition dump.

Specifying the ODA message file

The MessageFile configuration property specifies the name of the ODA's message file. An ODA can store its error and trace messages in this ODA message file. It can then retrieve these messages by message number, instead of creating the message text itself.

By default, the ODA run time names this message file according to the following naming convention:

ODAnameAgent.txt
 

In the preceding line, ODAname is the name that uniquely identifies the ODA. For example, if the ODA is named HTMLODA, the value of the MessageFile property defaults to HTMLODAAgent.txt. The message file must reside in the following message-file directory:

ProductDir\ODA\messages
 
Important

If the specified message file does not exist or does not exist in the message-file directory, the ODA generates a runtime exception. You must ensure that the message file (which MessageFile specifies) exists before you continue with the execution of the ODA.

If the ODA uses a different message file, set the MessageFile property to specify a different name for the trace file.

If you create multiple instances of the ODA script or batch file and provide a unique name for each represented ODA, you can have a message file for each ODA instance. For more information, see Using multiple ODAs simultaneously .

Copyright IBM Corp. 2003, 2004