Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

## AuditorInstaller Customizer for Debugging

Oracle SQLJ provides a special customizer--`AuditorInstaller`--that will insert sets of debugging statements, known as auditors, into profiles specified on the SQLJ command line. These profiles must already exist from previous customization.

The debugging statements will execute during SQLJ runtime (when someone runs your application), displaying a trace of method calls and values returned.

Use the customizer harness `debug` option, preceded by `-P-` as with any general customization option, to insert the debugging statements. (Syntax for this option is also discussed in "Invoking AuditorInstaller with the Customizer Harness debug Option".)

### Overview of Auditors and Code Layers

When an application is customized, the Oracle customizer implements profiles in layers of code (typically less than five) for different levels of runtime functionality. The deepest layer uses straight Oracle JDBC calls and implements any of your SQLJ statements that can be executed through JDBC functionality. Each higher layer is a specialized layer for some category of SQLJ functionality that is not supported by JDBC and so must be handled specially by the SQLJ runtime. For example, a layer for iterator conversion statements (`CAST`) is used to convert JDBC result sets to SQLJ iterators. Another layer is used for assignment statements (`SET`).

At runtime, each SQLJ executable statement is first passed to the shallowest layer and then passed, layer-by-layer, until it reaches the layer that can process it (usually the deepest layer, which executes all JDBC calls).

You can install debugging statements at only one layer during a single execution of `AuditorInstaller`. Each set of debugging statements installed at a particular layer of code is referred to as an individual auditor. During runtime, an auditor is activated whenever a call is passed to the layer at which the auditor is installed.

Any one of the specialized code layers above the JDBC layer is usually of no particular interest during debugging, so it is typical to install an auditor at either the deepest layer or the shallowest layer. If you install an auditor at the shallowest layer, its runtime debugging output will be a trace of method calls resulting from all your SQLJ executable statements. If you install an auditor at the deepest layer, its runtime output will be a trace of method calls from all your SQLJ executable statements that result in JDBC calls.

Use multiple executions of `AuditorInstaller` to install auditors at different levels. You might want to do that to install auditors at both the deepest layer and the shallowest layer, for example.

See "AuditorInstaller Depth Option (depth)" for information about how to specify the layer at which to install an auditor.

### Invoking AuditorInstaller with the Customizer Harness debug Option

Following are examples of how to specify the Oracle customizer harness `debug` option to run `AuditorInstaller` in its default mode:

    sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser

    sqlj -P-debug *.ser

    sqlj -P-debug myappjar.jar

The `debug` option results in the customizer harness instantiating and invoking the following class:

    sqlj.runtime.profile.util.AuditorInstaller

This class performs the work of inserting the debugging statements.

The `-P-debug` option is equivalent to the following:

    -P-customizer=sqlj.runtime.profile.util.AuditorInstaller

This overrides the customizer specified in the SQLJ `-default-customizer` option.

Note: To run an application with auditors installed, the Oracle SQLJ file `translator.zip` must be in your `CLASSPATH` (normally, running a SQLJ application requires only `runtime.zip`, which is a subset of `translator.zip`). As with any Oracle customizer, help output and an option list will be provided if you specify `-P-debug` together with `-P-help` on the SQLJ command line. It is important to realize that because the `debug` option invokes a customizer, and only one customizer can run in any single running of SQLJ, you cannot perform any other customization when you use this option. You also cannot use more than one of `-P-print`, `-P-debug`, and `-P-verify` simultaneously, because each of these invokes a specialized customizer.

##### Command-line syntax

    sqlj -P-debug profile_list

##### Command-line example

    sqlj -P-debug Foo_SJProfile*.ser

##### Properties file syntax

`profile.debug` (must also specify profiles in file list)

##### Properties file example

`profile.debug` (must also specify profiles in file list)

##### Default value

n/a

### AuditorInstaller Runtime Output

During runtime, debugging statements placed by `AuditorInstaller` result in a trace of methods called and values returned. This happens for all profile layers that had debugging statements installed. (There is no means of selective debug output at runtime.)

`AuditorInstaller` output relates to profiles only; there is currently no mapping to lines in your original `.sqlj` source file.

Following is a sample portion of `AuditorInstaller` runtime output. This is what the output might look like for a SQLJ `SELECT INTO` statement:

    oracle.sqlj.runtime.OraProfile@1 . getProfileData (  )
    oracle.sqlj.runtime.OraProfile@1 . getProfileData returned
    sqlj.runtime.profile.ref.ProfileDataImpl@2
    oracle.sqlj.runtime.OraProfile@1 . getStatement ( 0 )
    oracle.sqlj.runtime.OraProfile@1 . getStatement returned
    oracle.sqlj.runtime.OraRTStatement@3
    oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows ( 1000 )
    oracle.sqlj.runtime.OraRTStatement@3 . setMaxRows returned
    oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize ( 3000 )
    oracle.sqlj.runtime.OraRTStatement@3 . setMaxFieldSize returned
    oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout ( 1000 )
    oracle.sqlj.runtime.OraRTStatement@3 . setQueryTimeout returned
    oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal ( 1 , 5 )
    oracle.sqlj.runtime.OraRTStatement@3 . setBigDecimal returned
    oracle.sqlj.runtime.OraRTStatement@3 . setBoolean ( 2 , false )
    oracle.sqlj.runtime.OraRTStatement@3 . setBoolean returned
    oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery (  )
    oracle.sqlj.runtime.OraRTStatement@3 . executeRTQuery returned
    oracle.sqlj.runtime.OraRTResultSet@6
    oracle.sqlj.runtime.OraRTStatement@3 . getWarnings (  )
    oracle.sqlj.runtime.OraRTStatement@3 . getWarnings returned null
    oracle.sqlj.runtime.OraRTStatement@3 . executeComplete (  )
    oracle.sqlj.runtime.OraRTStatement@3 . executeComplete returned
    oracle.sqlj.runtime.OraRTResultSet@6 . next (  )
    oracle.sqlj.runtime.OraRTResultSet@6 . next returned true
    oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 )
    oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal returned 5
    oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 )
    oracle.sqlj.runtime.OraRTResultSet@6 . getDate returned 1998-03-28

There are two lines for each method call--the first showing the call and input parameters, and the second showing the return value.

Note: The classes you see in the `oracle.sqlj.runtime` package are SQLJ runtime classes with equivalent functionality to similarly named JDBC classes. For example, `OraRTResultSet` is the SQLJ runtime implementation of the JDBC `ResultSet` interface, containing equivalent attributes and methods.

### AuditorInstaller Options

As with any customizer, `AuditorInstaller` has its own options that can be set using the `-P-C` prefix on the SQLJ command line (or `profile.C` in a SQLJ properties file).

`AuditorInstaller` supports the following options:

- `depth`--Specify how deeply you want to go into the layers of runtime functionality in your profiles.

- `log`--Specify the target file for runtime output of the debugging statements of the installed auditor.

- `prefix`--Specify a prefix for each line of runtime output that will result from this installation of debugging statements.

- `showReturns`--Enable the installed auditor to include return arguments in its runtime call tracing.

- `showThreads`--Enable the installed auditor to include thread names in its runtime call tracing (relevant only for multithreaded applications).

- `uninstall`--Remove the debugging statements placed into the profiles during the most recent previous invocation of `AuditorInstaller` on those profiles.

#### AuditorInstaller Depth Option (depth)

As discussed in "Overview of Auditors and Code Layers", `AuditorInstaller` can install a set of debugging statements, known as an auditor, at only a single layer of code during any one execution. The `AuditorInstaller` `depth` option allows you to specify which layer. Use multiple executions of `AuditorInstaller` to install auditors at different levels.

Layers are numbered in integers. The shallowest depth is layer 0, and a maximum depth of 2 or 3 is typical. The only depth settings typically used are 0 for the shallowest layer or -1 for the deepest layer. In fact, it is difficult to install an auditor at any other particular layer, because the layer numbers used for the various kinds of SQLJ executable statements are not publicized.

The `depth` option is sometimes used in conjunction with the `prefix` option. By running `AuditorInstaller` more than once, with different prefixes for different layers, you can see at runtime what information is coming from which layers.

If you do not set the `depth` option, or the specification exceeds the number of layers in a given profile, then an auditor will be installed at the deepest layer.

##### Command-line syntax

    -P-Cdepth=n

##### Command-line example

    -P-Cdepth=0

##### Properties file syntax

    profile.Cdepth=n

##### Properties file example

    profile.Cdepth=0

##### Default value

`-1` (deepest layer)

#### AuditorInstaller Log File Option (log)

Use the `log` option to specify an output file for runtime output that will result from the auditor that you are currently installing. Otherwise, standard output will be used--debug output will go to wherever SQLJ messages go.

When auditors write messages to an output file, they append; they do not overwrite. Therefore, you can specify the same log file for multiple auditors without conflict (in fact, it is typical in this way to have debug information from all layers of your application go to the same log file).

##### Command-line syntax

    -P-Clog=log_file

##### Command-line example

    -P-Clog=foo/bar/mylog.txt

##### Properties file syntax

    profile.Clog=log_file

##### Properties file example

    profile.Clog=foo/bar/mylog.txt

##### Default value

empty (use standard output)

#### AuditorInstaller Prefix Option (prefix)

Use the `prefix` option to specify a prefix for each line of runtime output resulting from the debugging statements installed during this invocation of `AuditorInstaller`.

This option is often used in conjunction with the `depth` option. By running `AuditorInstaller` multiple times with different prefixes for different layers, you can easily see at runtime what information is coming from which layers.

##### Command-line syntax

    -P-Cprefix="string"

##### Command-line example

    -P-Cprefix="layer 2: "

##### Properties file syntax

    profile.Cprefix="string"

##### Properties file example

    profile.Cprefix="layer 2: "

##### Default value

empty

#### AuditorInstaller Return Arguments Option (showReturns)

Use the `showReturns` option to enable or disable the display of return arguments as part of the runtime call tracing. This is enabled by default.

The following few lines show sample output with `showReturns` enabled (default):

    oracle.sqlj.runtime.OraRTStatement@3 . executeComplete (  )
    oracle.sqlj.runtime.OraRTStatement@3 . executeComplete returned
    oracle.sqlj.runtime.OraRTResultSet@6 . next (  )
    oracle.sqlj.runtime.OraRTResultSet@6 . next returned true
    oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 )
    oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal returned 5
    oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 )
    oracle.sqlj.runtime.OraRTResultSet@6 . getDate returned 1998-03-28

With `showReturns` disabled, the output would appear as follows:

    oracle.sqlj.runtime.OraRTStatement@3 . executeComplete (  )
    oracle.sqlj.runtime.OraRTResultSet@6 . next (  )
    oracle.sqlj.runtime.OraRTResultSet@6 . getBigDecimal ( 1 )
    oracle.sqlj.runtime.OraRTResultSet@6 . getDate ( 7 )

Instead of both a call line and a return line for each method call, there is only a call line.

##### Command-line syntax

    -P-CshowReturns=true/false

##### Command-line example

    -P-CshowReturns=false

##### Properties file syntax

    profile.CshowReturns=true/false

##### Properties file example

    profile.CshowReturns=false

##### Default value

    true

#### AuditorInstaller Thread Names Option (showThreads)

Use the `showThreads` option to enable or disable the display of thread names as part of the runtime call tracing (relevant only for multithreaded applications). This is disabled by default.

When this option is enabled, thread names prefix the method names in the trace output.

##### Command-line syntax

    -P-CshowThreads=true/false

##### Command-line example

    -P-CshowThreads=true

##### Properties file syntax

    profile.CshowThreads=true/false

##### Properties file example

    profile.CshowThreads=false

##### Default value

    false

#### AuditorInstaller Uninstall Option (uninstall)

Use the `uninstall` option to remove debugging statements placed during previous invocations of `AuditorInstaller`. Each time you use the `uninstall` option, it will remove the auditor most recently installed.

To remove all auditors from a profile, run `AuditorInstaller` repeatedly until you get a message indicating that the profile was unchanged.

##### Command-line syntax

    -P-Cuninstall

##### Command-line example

    -P-Cuninstall

##### Properties file syntax

    profile.Cuninstall

##### Properties file example

    profile.Cuninstall

##### Default value

    false

### Full Command-Line Examples

Following are some full SQLJ command-line examples showing the specification of `AuditorInstaller` options.

Insert a set of debugging statements, or auditor, into the deepest layer (which is the default layer), with runtime output to standard output:

    sqlj -P-debug MyApp_SJProfile*.ser

Insert an auditor into the deepest layer, with runtime output to `log.txt`:

    sqlj -P-debug -P-Clog=foo/bar/log.txt MyApp_SJProfile*.ser

Insert an auditor into the deepest layer, with runtime output to standard output, showing thread names but not return arguments:

    sqlj -P-debug -P-CshowThreads=true -P-CshowReturns=false MyApp_SJProfile*.ser

Insert an auditor into layer 0 (the shallowest layer). Send runtime output to `log.txt`; prefix each line of runtime output with "`Layer 0:` " (the following command is a single wrap-around line):

    sqlj -P-debug -P-Clog=foo/bar/log.txt -P-Cdepth=0 -P-Cprefix="Layer 0: "
    MyApp_SJProfile*.ser

Uninstall an auditor (this uninstalls the auditor most recently installed; do it repeatedly to uninstall all auditors):

    sqlj -P-debug -P-Cuninstall MyApp_SJProfile*.ser

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index