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 14) for an ODA.

Table 14. 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 43 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 43. 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 more information, see Naming the ODA. For example, if the ODA is named HTMLODA, it generates a trace file named HTMLODAtrace.txt.

Note:
Because the ODK API provides one method to log both trace and error messages, an ODA has only one file to hold both these kinds of 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 runtime 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 use 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 15 lists trace levels and their associated behavior.

Table 15.

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 log 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.

For information on how to generate trace messages within the ODA, see Handling trace and error messages.

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. Isolating messages into the message file provides an easy way for ODA messages to be translated into the languages of the different locales the ODA can run in.

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 more information, see Naming 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 are using a non-US English locale, Business Object Wizard automatically looks for an ODA message file that includes the name of the locale in the file name, as follows:

ODAnameAgent_locale.txt
 

where locale has the format "ll_TT", with ll as the two-character language name (in lowercase) and TT as the two-character country or territory name (in uppercase). For example, if the ODA named HTMLODA has its message file localized to the Japanese locale, its message file would have the name:

HTMLODAAgent_ja_JP.txt
 
Note:
When you are logged into a non-US English locale, you do not have to specify the non-US English name in the MessageFile property. For example, if you are using the HTML ODA, you set MessageFile to the US English file name (HTMLODAAgent.txt). If you are logged into a Japanese local, Business Object Wizard locates the correct message file for the Japanese locale: HTMLODAAgent_ja_JP.txt.

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. 1997, 2004