# Controlling Diagnostic Messages

Business Component diagnostics can be controlled by setting various `jbo.`xxx system properties. By default, the system property definitions reside in the file `Diagnostic.properties` in the `.\oracle\jbo\common` path on the `CLASSPATH`.

A default version of this file is supplied in the `.\lib\jbomt.zip` library. You can permanently change the default settings by extracting this file from the `.zip` archive, changing the values of the properties in the file, and making it available earlier in your project's library path. The file must appear before the library named "JBO Runtime" in the appropriate `.\oracle\jbo\common` subdirectory.

For a description of the properties in the `Diagnostic.properties` file, see Diagnostic Message Properties. For an example of the `Diagnostic.properties` file, see Sample Diagnostic Properties File.

## Performing One-time Overrides

You can perform a "one-time" override of any diagnostic property by entering the appropriate value in JDeveloper's Project's Properties dialog.

1. Select Project | Project Properties on the JDeveloper menu bar to open the project's Property dialog. Select the Run/Debug tab.

2. Enter a new value for the system property you want to change as a command-line switch in the Java VM Parameters field, following the Java VM's `-D` flag.

   For example, to suppress the reporting of diagnostics, enter the value
   `-Djbo.debugoutput=silent` in the Java VM Parameters field.

3. Click OK to close the dialog and enable your change.

## Diagnostic Message Properties

The following sections describe the properties you can set in the `Diagnostic.properties` file. For an example of the `Diagnostic.properties` file, see Sample Diagnostic Properties File.

### Determining Message Routing

Syntax: `jbo.debugoutput={silent|console|`routing_classname`}`

This property determines how you want to route diagnostic messages. The routing is determined by an implementation of the `oracle.jbo.common.IDiagnostic` interface. The value you give to the `jbo.debugoutput` property determines which implementation of the interface to use.

- `silent` - suppresses diagnostic messages; implemented by `oracle.jbo.common.SilentDiagnosticImpl`.

- `console` (default) - directs messages to the console; implemented by `oracle.jbo.common.ConsoleDiagnosticImpl`.

The `debugoutput` property also supports a pluggable diagnostic implementation. For example, you can write a class, `anyCorp.ACDiagnosticImpl`, that implements `oracle.jbo.common.IDiagnostic` to provide special instructions for routing the output. You can then pass the fully qualified class name of `anyCorp.ACDiagnosticImpl` to `debugoutput` instead of `console` or `silent`.

### Displaying the Calling Function

Syntax: `jbo.logging.show.function={true|false}`

The value of this property determines whether the name of the function which calls the diagnostic is displayed. Note that displaying the function name is expensive in terms or performance. The default value is `false`.

For an example of how the calling function is displayed in a diagnostic message, see Sample Diagnostic Message.

### Displaying Line Numbers

Syntax: `jbo.logging.show.linecount={true|false}`

The value of this property determines whether diagnostic message lines are numbered. The default value is `true`.

For an example of how line numbers are displayed in a diagnostic message, see Sample Diagnostic Message.

### Setting the Logging Threshold

Syntax:`jbo.logging.trace.threshold={[0-9]}`

Trace messages have an integer threshold number associated with them. The range is 0-9 inclusive. All messages currently in the system have level 3. If you have a debug build, there will be additional messages at level 6. The default value is 3.

The value of the trace threshold property determines which trace messages will print. If the level of the message is less than or equal to the value given to the parameter, then the message will print. If the level of the message is greater than the parameter, then the message will not print. For example, if the threshold value is set to 3, then messages at level 0, 1, 2, and 3 will print. Messages at levels 4, 5, or higher will not print.

### Setting the Prefix for Diagnostic Messages

Syntax:`jbo.debug.prefix={`prefix`}`

This property determines the prefix added to level 6 messages executed through debug diagnostics. Note that debug diagnostics are available only with a debug build of the Business Components product. The default value is `DBG`.

### Displaying the Time Between Debug Calls

Syntax: `jbo.logging.show.timing={true|false}`

The value of this property determines whether the time between debug calls is displayed. The amount of time is measured in milliseconds. The default value is `false`.

For an example of how the timing is displayed in a diagnostic message, see Sample Diagnostic Message.

### Displaying a Message's Trace Level

Syntax: `jbo.logging.show.level={true|false}`

The value of this property determines whether the trace level associated with a message is displayed. Note that this property is not normally used; in release mode, all debug messages are level 3. The default value is `false`.

For an example of how the trace level is displayed in a diagnostic message, see Sample Diagnostic Message.

## Viewing Diagnostic Messages While Executing in an Oracle8i Database

When Business Components are executing inside an Oracle8i database, its output is stored in the log file associated with the database instance. This log file can be found at:

    <ORACLE_HOME>ADMIN\<DB_SID\udump\<DB_SID>S000.TRC

To upload an updated version of the `Diagnostic.properties` file to the database while executing inside an Oracle8i database, you can use the `loadjava` utility:

1. Set the diagnostics `console` option in the `Diagnostic.properties` file:

> >     jbo.debugoutput=console

2. Use the `loadjava` utility to upload the file:

> >     loadjava -v -r -user jbo/jbo@testserver:1521:ORCL -thin oracle\jbo\common\Diagnostic.properties

## Sample Diagnostic Message

The following is a sample diagnostic message that is issued when the message routing is set to console mode (that is, `jbo.debugoutput=console`).

    <3>[11] (10) RowSetHelper.getListeners Getting listeners ready...

In this sample message:

- `<3>` - indicates that the message was issued at trace level 3

- `[11]` - indicates that this is trace line number 11

- `(10)` - indicates that 10 milliseconds have elapsed since the last trace message

- `RowSetHelper` - the name of the class from which the trace message was issued

- `getListeners` - the name of the function from which the trace message was issued

- `Getting Listeners ready ...` - the text of the trace message

## Sample Diagnostic Properties File

Here is a sample `Diagnostic.properties` file:

    # ------------------------------------------------------------------------
    # File: oracle.jbo.common.logging.Diagnostic.properties
    # Cont: Diagnostic.properties file for DEBUG build of Business Components for Java
    # Desc: This is the file used to determine the way that Diagnostic
    #       calls in the code are handled: all the properties below can be
    #       overridden by specifying then as -D switches to the java VM
    # ------------------------------------------------------------------------

    # Which implementation of IDiagnostic to use: console|silent|classname
    # classname is the fully qualified name of a user-defined class that
    # implements the IDiagnostic interface
    jbo.debugoutput=console

    # --------------------------------------------------
    # Sample DebugOutput Line
    # --------------------------------------------------
    # <3>[11] (10) RowSetHelper.getListeners Getting listeners ready...
    # In the above example:
    # <3>  - the message is issues at trace level 3
    # [11] - this is trace line number 11
    # (10) - 10 ms have elapsed since the last trace message
    # RowSetHelper - class from which the trace message was issued
    # getListeners - function from which the trace message was issued
    # Getting Listeners ready ... - test of the trace message
    # --------------------------------------------------

    # Show calling function: false|true
    jbo.logging.show.function=false

    # Show a linecount as each diagnostic line is output (true|false)
    jbo.logging.show.linecount=true

    # Logging cutoff threshold: any trace messages with a level
    # higher than this threshold will be suppressed.
    # For a release build, system Diagnostic messages are at level 3
    # Additionally, in a Debug build, DebugDiagnostic messages are at level 6
    jbo.logging.trace.threshold=3

    # Prefix string to display on DebugDiagnostic lines
    # Debug build only
    jbo.debug.prefix=DBG

    # Show elapsed time info every call (true|false)
    jbo.logging.show.timing=false

    # Show level of trace statement
    jbo.logging.show.level=false

    # ------------------------------------------------------------------------
    # end of file
    # ------------------------------------------------------------------------