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

## Customization Options and Choosing a Customizer

This section discusses options for profile customization, which fall into three categories:

- options you specify to the customizer harness, which apply to whatever customizer you use

  This includes general options, connection options, and options that invoke specialized customizers.

- customizer-specific options you specify to your customizer through the customizer harness

- SQLJ options, which determine basic aspects of customization, such as whether to customize at all and which customizer to use

All categories of options are specified through the SQLJ command line or properties files.

The following topics are included in this section:

- Overview of Customizer Harness Options

- General Customizer Harness Options

- Customizer Harness Options for Connections

- Customizer Harness Options that Invoke Specialized Customizers

- Overview of Customizer-Specific Options

- Oracle Customizer Options

- SQLJ Options for Profile Customization

To choose a customizer other than the default Oracle customizer, you can use either the customizer harness `customizer` option (discussed in "Overview of Customizer Harness Options") or the SQLJ `-default-customizer` option (discussed in "SQLJ Options for Profile Customization").

### Overview of Customizer Harness Options

The customizer harness provided with Oracle SQLJ offers a number of options that are not specific to a particular customizer. The harness uses these options in its front-end coordination of the customization process.

#### Syntax for Customizer Harness Options

Customizer harness option settings on the SQLJ command line have the following syntax:

    -P-option=value

Or, in a SQLJ properties file:

    profile.option=value

Enable boolean options (flags) either with:

    -P-option

or:

    -P-option=true

Boolean options are disabled by default, but you can explicitly disable them with:

    -P-option=false

This option syntax is also discussed in "Options to Pass to the Profile Customizer (-P)" and "Properties File Syntax".

#### Options Supported by the Customizer Harness

The customizer harness supports the following general options:

- `backup`--Save a backup copy of the profile before customizing it.

- `context`--Limit customizations to profiles associated with the listed connection context classes.

- `customizer`--Specify the customizer to use.

- `digests`--Specify digests for `.jar` file manifests (relevant only if specifying `.jar` files to customize).

- `help`--Display customizer options (specified in SQLJ command-line only).

- `verbose`--Display status messages during customization.

The customizer harness supports the following options for customizer database connections. As of release 8.1.6, these are used by the Oracle customizer only if you enable its `optcols` option for column definitions (for performance optimization). In addition, they used by the `SQLCheckerCustomizer` if you use this specialized customizer to perform online semantics-checking on profiles.

- `user`--Specify the user name for the connection used in this customization.

- `password`--Specify the password for the connection used in this customization.

- `url`--Specify the URL for the connection used in this customization.

- `driver`--Specify the JDBC driver for the connection used in this customization.

For information about the Oracle customizer `optcols` flag, see "Oracle Customizer Column Definition Option (optcols)". For information about the `SQLCheckerCustomizer`, see "SQLCheckerCustomizer for Profile Semantics-Checking".

The following commands function as customizer harness options, but are implemented through specialized customizers provided with Oracle SQLJ.

- `debug`--Insert debugging information into the specified profiles, to be output at runtime.

- `print`--Output the contents of the specified profiles, in text format.

- `verify`--Perform semantics-checking on a profile that was produced during a previous execution of the SQLJ translator (equivalent to semantics-checking performed on source code during translation).

### General Customizer Harness Options

This section describes general options supported by the customizer harness.

#### Profile Backup Option (backup)

Use the `backup` flag to instruct the harness to save a backup copy of each `.jar` file and standalone `.ser` file before replacing the original. (Separate backups of `.ser` files that are within `.jar` files are not necessary.)

Backup file names are given the extension `.bak` `n`, where `n` indicates digits used as necessary where there are similarly named files. For each backup file created, an informational message is issued.

If an error occurs during customization of a standalone `.ser` file, then the original `.ser` file is not replaced, and no backup is created. Similarly, if an error occurs during customization of any `.ser` file within a `.jar` file, then the original `.jar` file is not replaced, and no backup is created.

##### Command-line syntax

    -P-backup<=true/false>

##### Command-line example

    -P-backup

##### Properties file syntax

    profile.backup<=true/false>

##### Properties file example

    profile.backup

##### Default value

    false

#### Customization Connection Context Option (context)

Use the `context` option to limit customizations to profiles that correspond to the specified connection context classes. Fully qualify the class names and use a comma-separated list to specify multiple classes. For example:

    -P-context=sqlj.runtime.ref.DefaultContext,foo.bar.MyCtxtClass

There must be no space on either side of the comma.

If this option is not specified, then all profiles are customized, regardless of their associated connection context classes.

##### Command-line syntax

    -P-context=ctx_class1<,ctx_class2,...>

##### Command-line example

    -P-context=foo.bar.MyCtxtClass

##### Properties file syntax

    profile.context=ctx_class1<,ctx_class2,...>

##### Properties file example

    profile.context=foo.bar.MyCtxtClass

##### Default value

none (customize all profiles)

#### Customizer Option (customizer)

Use the `customizer` option to specify which customizer to use. Fully qualify the class name, such as in the following example:

    -P-customizer=oracle.sqlj.runtime.util.OraCustomizer

If you do not set this option, then SQLJ will use the customizer specified in the SQLJ `-default-customizer` option. Unless set otherwise, this is the following:

    oracle.sqlj.runtime.util.OraCustomizer

##### Command-line syntax

    -P-customizer=customizer_class

##### Command-line example

    -P-customizer=a.b.c.MyCustomizer

##### Properties file syntax

    profile.customizer=customizer_class

##### Properties file example

    profile.customizer=a.b.c.MyCustomizer

##### Default value

none (use default, set in SQLJ `-default-customizer` option)

#### Customization JAR File Digests Option (digests)

When a `.jar` file is produced, the `jar` utility can optionally include one or more digests for each entry, based on one or more specified algorithms, so that the integrity of the `.jar` file entries can later be verified. Digests are similar conceptually to checksums, for readers familiar with those.

If you are customizing profiles in a `.jar` file and want the `jar` utility to add new digests (or update existing digests) when the `.jar` file is updated, then use the `digests` option to specify a comma-separated list of one or more algorithms. These are the algorithms that `jar` will use in creating the digests for each entry. The `jar` utility produces one digest for each algorithm for each `.jar` file entry in the `jar` manifest file. Specify algorithms as follows:

    -P-digests=SHA,MD5

There must be no space on either side of the comma.

In this example, there will be two digests for each entry in the `.jar` manifest file--an `SHA` digest and an `MD5` digest.

For information about `.jar` files and the `jar` utility, see the following Web site:

    http://www.javasoft.com/products/jdk/1.1/docs/guide/jar/index.html

##### Command-line syntax

    -P-digests=algo1<,algo2,...>

##### Command-line example

    -P-digests=SHA,MD5

##### Properties file syntax

    profile.digests=algo1<,algo2,...>

##### Properties file example

    profile.digests=SHA,MD5

##### Default value

    SHA,MD5

#### Customization Help Option (help)

Use the `help` option to display the option lists of the customizer harness and the default customizer or a specified customizer. For the harness and Oracle customizer, this includes a brief description and the current setting of each option.

Display the option lists for the harness and default customizer as follows (where the default customizer is the Oracle customizer or whatever you have specified in the SQLJ `-default-customizer` option):

    -P-help

Use the `help` option in conjunction with the `customizer` option to display the option list of a particular customizer, as follows:

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

Notes: You can use the `-P-help` option on the SQLJ command line only, not in a SQLJ properties file. No customizations are performed if the `-P-help` flag is enabled, even if you specify profiles to customize on the command line.

##### Command-line syntax

    -P-help <-P-customizer=customizer_class>

##### Command-line example

    -P-help

##### Properties file syntax

n/a

##### Properties file example

n/a

##### Default value

none

#### Customization Verbose Option (verbose)

Use the `verbose` flag to instruct the harness to display status messages during customizations. These messages are written to the standard output device--wherever SQLJ writes its other messages.

##### Command-line syntax

    -P-verbose<=true/false>

##### Command-line example

    -P-verbose

##### Properties file syntax

    profile.verbose<=true/false>

##### Properties file example

    profile.verbose

##### Default value

none

### Customizer Harness Options for Connections

This section describes connection options supported by the customizer harness. As of release, these are used only in the following circumstances:

- The Oracle customizer uses database connections only for column definitions. If you do not enable the Oracle customizer `optcols` option, then there is no need to set the customizer harness `user`, `password`, `url`, and `driver` options.

- The `SQLCheckerCustomizer`, a specialized customizer that performs semantics-checking on profiles, uses the customizer harness `user`, `password`, `url`, and `driver` settings for online checking.

  Note: Do not confuse the customizer harness `user`, `password`, `url`, and `driver` options with the translator options of the same names, which are for semantics-checking during the translation step and are unrelated.

#### Customization User Option (user)

Set the `user` option to specify a database schema if your customizer uses database connections.

In addition to specifying the schema, you can optionally specify the password, URL, or both in your `user` option setting. The password is preceded by a forward-slash (/), and the URL is preceded by an "at" sign (@), as in the following examples:

    -P-user=scott/tiger
    -P-user=scott@jdbc:oracle:oci8:@
    -P-user=scott/tiger@jdbc:oracle:oci8:@

##### Command-line syntax

    -P-user=username</password><@url>

##### Command-line examples

    -P-user=scott
    -P-user=scott/tiger
    -P-user=scott/tiger@jdbc:oracle:oci8:@

##### Properties file syntax

    profile.user=username</password><@url>

##### Properties file examples

    profile.user=scott
    profile.user=scott/tiger
    profile.user=scott/tiger@jdbc:oracle:oci8:@

##### Default value

    null

#### Customization Password Option (password)

Use the `password` option if your customizer uses database connections.

The password can also be set with the `user` option, as described in "Customization User Option (user)".

##### Command-line syntax

    -P-password=password

##### Command-line example

    -P-password=tiger

##### Properties file syntax

    profile.password=password

##### Properties file example

    profile.password=tiger

##### Default value

    null

#### Customization URL Option (url)

Use the `url` option if your customizer uses database connections.

The URL can also be set with the `user` option, as described in "Customization User Option (user)".

##### Command-line syntax

    -P-url=url

##### Command-line example

    -P-url=jdbc:oracle:oci8:@

##### Properties file syntax

    profile.url=url

##### Properties file example

    profile.url=jdbc:oracle:oci8:@

##### Default value

    jdbc:oracle:oci8:@

#### Customization JDBC Driver Option (driver)

Use the `driver` option to register a comma-separated list of JDBC drivers if your customizer uses database connections. For example:

    -P-driver=sun.jdbc.odbc.JdbcOdbcDriver,oracle.jdbc.driver.OracleDriver

There must be no space on either side of the comma.

##### Command-line syntax

    -P-driver=dvr_class1<,dvr_class2,...>

##### Command-line example

    -P-driver=sun.jdbc.odbc.JdbcOdbcDriver

##### Properties file syntax

    profile.driver=dvr_class1<,dvr_class2,...>

##### Properties file example

    profile.driver=sun.jdbc.odbc.JdbcOdbcDriver

##### Default value

    oracle.jdbc.driver.OracleDriver

### Customizer Harness Options that Invoke Specialized Customizers

The customizer harness supports the following options that invoke specialized customizers:

- `debug`--This invokes the `AuditorInstaller` customizer, used in debugging.

- `print`--This invokes a customizer that prints a text version of a profile.

- `verify`--This invokes the `SQLCheckerCustomizer` customizer, which performs semantics-checking on a profile.

  Important: Because each of these options invokes a customizer, and only one customizer can run in a single execution of SQLJ, you cannot perform any other customization when you use any of these options. You also cannot use more than one of `print`, `debug`, or `verify` simultaneously.

#### Profile Debug Option (specialized customizer) (debug)

The `debug` option runs a specialized customizer, called the `AuditorInstaller`, that inserts debugging statements into profiles. Use this option in conjunction with a SQLJ command line file list to insert debugging statements into the specified profiles. These profiles must already be customized from a previous SQLJ run.

For detailed information about this customizer, including additional options that it supports, see "AuditorInstaller Customizer for Debugging".

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

Following are examples of how to specify the `debug` option:

    sqlj -P-debug Foo_SJProfile0.ser Bar_SJProfile0.ser

    sqlj -P-debug *.ser

##### Command-line syntax

    sqlj -P-debug profile_list

##### Command-line example

    sqlj -P-debug Foo_SJProfile*.ser

##### Properties file syntax

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

##### Properties file example

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

##### Default value

n/a

#### Profile Print Option (specialized customizer) (print)

The `print` option runs a specialized customizer that prints profiles in text format. Use this option in conjunction with a SQLJ command line file list to output the contents of one or more specified profiles. The output goes to the standard SQLJ output device, typically the user screen.

Following are examples of how to specify the `print` option:

    sqlj -P-print Foo_SJProfile0.ser Bar_SJProfile0.ser

    sqlj -P-print *.ser

For sample output, see "Sample Profile Entry".

##### Command-line syntax

    sqlj -P-print profile_list

##### Command-line example

    sqlj -P-print Foo_SJProfile*.ser

##### Properties file syntax

`profile.print` (also specify profiles in SQLJ file list)

##### Properties file example

`profile.print` (also specify profiles in SQLJ file list)

##### Default value

n/a

#### Profile Semantics-Checking Option (specialized customizer) (verify)

The `verify` option runs a specialized customizer, called the `SQLCheckerCustomizer`, that performs semantics-checking on a profile. This is equivalent to the semantics-checking that is performed on source code during translation. The profile will have been created during a previous execution of the SQLJ translator.

This option is useful for checking semantics against the runtime database, after deployment, and after the source code may no longer be available.

For detailed information about this customizer, including additional options that it supports, see "SQLCheckerCustomizer for Profile Semantics-Checking".

Note: For online semantics-checking of the profile, you must also use the customizer harness `user`, `password`, and `url` options.

Following are examples of how to specify the `verify` option. Both of these examples use the `SQLCheckerCustomizer` default semantics-checker, which employs online checking through the specified database connection.

    sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci8:@
    Foo_SJProfile0.ser Bar_SJProfile0.ser

(The preceding is a single wrap-around command line.)

    sqlj -P-verify -P-user=scott -P-password=tiger -P-url=jdbc:oracle:oci8:@ *.ser

##### Command-line syntax

    sqlj -P-verify <conn params> profile_list

##### Command-line example

    sqlj -P-verify <conn params> Foo_SJProfile*.ser

##### Properties file syntax

`profile.verify`

(You must also specify profiles, and typically customizer harness connection options, in the SQLJ command line.)

##### Properties file example

`profile.verify`

(You must also specify profiles, and typically customizer harness connection options, in the SQLJ command line.)

##### Default value

n/a

### Overview of Customizer-Specific Options

You can set customizer-specific options, such as options for the Oracle customizer, on the SQLJ command line or in a SQLJ properties file. The syntax is similar to that for setting customizer harness options.

Set a customizer option on the SQLJ command line by preceding it with:

    -P-C

Or set it in a SQLJ properties file by preceding it with:

    profile.C

This option syntax is also discussed in "Options to Pass to the Profile Customizer (-P)" and "Properties File Syntax".

The remainder of this section discusses features of the Oracle customizer, which supports several options. Most of these options are boolean and are enabled as follows:

    -P-Coption

or:

    -P-Coption=true

Boolean options are disabled by default, but you can explicitly disable them with:

    -P-Coption=false

Numeric or string options are set similarly:

    -P-Coption=value

### Oracle Customizer Options

This section describes options that are specific to the Oracle customizer, beginning with an overview of the options supported.

#### Options Supported by the Oracle Customizer

The Oracle customizer implements the following options:

- `compat`--Display version compatibility information.

- `force`--Instruct the customizer to customize even if a valid customization already exists.

- `optcols`--Enable iterator column type and size definitions to optimize performance.

- `optparams`--Enable parameter size definitions to optimize JDBC resource allocation (used in conjunction with `optparamdefaults`).

- `optparamdefaults`--Set parameter size defaults for particular datatypes (used in conjunction with `optparams`).

- `showSQL`--Display SQL statement transformations.

- `stmtcache`--Set the statement cache size (the number of statements that can be cached for each connection during runtime) for performance optimization, or set it to zero to disable statement caching.

- `summary`--Display a summary of Oracle features used in your application.

Any output displayed by these options is written to the standard output device, wherever SQLJ writes its other messages.

#### Oracle Customizer Version Compatibility Option (compat)

Use the `compat` flag to instruct the Oracle customizer to display information about compatibility of your application with different versions of the Oracle database and Oracle JDBC drivers. This can be accomplished either during a full SQLJ translation run or on profiles previously created.

To see compatibility output when translating and customizing the application `MyApp`:

    sqlj <...SQLJ options...> -P-Ccompat MyApp.sqlj

In this example, the `MyApp` profiles will be created, customized, and checked for compatibility in a single running of SQLJ.

To see compatibility output for `MyApp` profiles previously created:

    sqlj <...SQLJ options...> -P-Ccompat MyApp_SJProfile*.ser

In this example, the `MyApp` profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and checked for compatibility in the above running of SQLJ.

Following are two output samples from a `-P-Ccompat` setting when using the default Oracle customizer. The first example indicates that the application can be used with all Oracle JDBC driver versions:

    MyApp_SJProfile0.ser: Info: compatible with all Oracle JDBC drivers

This second example indicates that the application can be used only with 8.1 or later Oracle JDBC driver versions:

    MyApp_SJProfile0.ser: Info: compatible with Oracle 8.1 or later JDBC driver

Note: If customization does not take place because a valid previous customization is detected, the `compat` option reports compatibility regardless.

##### Command-line syntax

    -P-Ccompat<=true/false>

##### Command-line example

    -P-Ccompat

##### Properties file syntax

    profile.Ccompat<=true/false>

##### Properties file example

    profile.Ccompat

##### Default value

    false

#### Oracle Customizer Force Option (force)

Use the `force` flag to instruct the Oracle customizer to force the customization of a given profile (specified on the command line) even if a valid customization already exists in that profile. For example:

    sqlj -P-Cforce MyApp_SJProfile*.ser

This will customize all the `MyApp` profiles, regardless of whether they have already been customized. Otherwise, by default, the Oracle customizer will not reinstall over a previously existing customization unless the previous one had been installed with an older version of the customizer.

##### Command-line syntax

    -P-Cforce<=true/false>

##### Command-line example

    -P-Cforce

##### Properties file syntax

    profile.Cforce<=true/false>

##### Properties file example

    profile.Cforce

##### Default value

    false

#### Oracle Customizer Column Definition Option (optcols)

Use the `optcols` flag to instruct the Oracle customizer to determine types and sizes of iterator or result set columns, and add this information to the profile. This enables the SQLJ runtime to automatically register the columns with the Oracle JDBC driver when your application runs, saving round trips to the database depending on the particular driver implementation. Specifically, this is effective for the Thin driver.

For an overview of column definitions, see "Column Definitions".

You can enable or disable this flag on the SQLJ command line or in a properties file.

Enable it on the command line as follows:

    -P-Coptcols

or:

    -P-Coptcols=true

This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:

    -P-Coptcols=false

Column definitions require the customizer to make a database connection to examine columns of tables being queried, so the customizer harness `user`, `password`, and `url` options must be set appropriately (as well as the customizer harness `driver` option if you are not using the default `OracleDriver` class). For example:

    sqlj <...SQLJ options...> -P-user=scott/tiger@jdbc:oracle:oci8:@ -P-Coptcols MyApp.sqlj

(Note that as with the SQLJ translator, you can optionally set password and URL in the `user` option instead of in the `password` and `url` options.)

Or you can insert column definitions into a previously existing profile (in this case you must also use the Oracle customizer `force` option to force a recustomization):

    sqlj -P-user=scott/tiger@jdbc:oracle:oci8:@ -P-Cforce -P-Coptcols MyApp_SJProfile*.ser

Or you can insert column definitions into previously existing profiles in a `.jar` file:

    sqlj -P-user=scott/tiger@jdbc:oracle:oci8:@ -P-Cforce -P-Coptcols MyAppProfiles.jar

    Notes:

    Because definitions are done for all columns that you select, it is advisable in your SQL operations to explicitly select the columns you will use, rather than using a SELECT * where you might not actually use all the columns selected. A situation where you select more than you need exposes you to a greater risk of runtime errors if any changes were made to the table between customization and runtime, especially when you have customized with column definitions. You might want to translate with the SQLJ -warn=strict flag set, which will warn you if additional (unwanted) columns will be selected by your query.

    Column definitions are not possible for any iterator or result set that includes one or more object or collection columns.

When you run the Oracle customizer with its `optcols` flag enabled (either during translation and creation of a new profile or during customization of an existing profile), you can also enable the customizer harness `verbose` flag. This will instruct the Oracle customizer to display information about what iterators and result sets are being processed and what their column type and size definitions are. For example:

    sqlj -P-user=scott/tiger@jdbc:oracle:oci8:@ -P-verbose -P-Cforce -P-Coptcols MyApp_SJProfile*.ser

For general information about the `verbose` flag, see that section under "Overview of Customizer Harness Options".

You can execute the Oracle customizer with its `summary` flag enabled on an existing profile to determine if column definitions have been added to that profile:

    sqlj -P-Csummary MyApp_SJProfile*.ser

For general information about the `summary` flag, see that section under "Overview of Customizer-Specific Options".

Note: An error will be generated if you enable the Oracle customizer `optcols` option without setting the customizer harness user name, password, and URL for a database connection. Do not confuse this with setting the translator user name, password, and URL for semantics-checking--these are unrelated. The customizer does not have to connect to the same schema or even the same database that your application will connect to at runtime, but the relevant columns will have to be in the same order and of identical types and sizes to avoid runtime errors. For information about the customizer harness connection options, see the `user`, `password`, `url`, and `driver` sections under "Overview of Customizer Harness Options".

##### Command-line syntax

    -P-Coptcols<=true/false>

##### Command-line example

    -P-Coptcols

##### Properties file syntax

    profile.Coptcols<=true/false>

##### Properties file example

    profile.Coptcols

##### Default value

    false

#### Oracle Customizer Parameter Definition Option (optparams)

Use the `optparams` flag to enable parameter size definitions. If this flag is enabled, SQLJ will register your input and output parameters (host variables) to optimize JDBC resource allocations according to sizes you specify, with the following precedence:

1. size specified in a source code hint, if any

2. default size, if any, specified for the corresponding datatype in the `optparamdefaults` option setting

If there is no source code hint or default datatype size for a given host variable, then resource allocation is left to JDBC.

For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".

You can enable or disable the `optparams` flag on the command line or in a SQLJ properties file.

Enable it on the command line as follows:

    -P-Coptparams

or:

    -P-Coptparams=true

This flag is disabled by default, but you can also disable it explicitly. Disable it on the command line as follows:

    -P-Coptparams=false

Note: Unlike the `optcols` option, the `optparams` option does not require a database connection by the customizer, because you are providing the size specifications yourself.

Following is a command-line example (omitting a setting for the `optparamdefaults` option, which is discussed in the next section):

    sqlj <...SQLJ options...> -P-Coptparams -P-Coptparamdefaults=defaults-string MyApp.sqlj

Or you can enable parameter size definitions for a previously existing profile:

    sqlj -P-Coptparams -P-Coptparamdefaults=defaults-string MyApp_SJProfile*.ser

Or for previously existing profiles in a `.jar` file:

    sqlj -P-Coptparams -P-Coptparamdefaults=defaults-string MyAppProfiles.jar

##### Command-line syntax

    -P-Coptparams<=true/false>

##### Command-line example

    -P-Coptparams

##### Properties file syntax

    profile.Coptparams<=true/false>

##### Properties file example

    profile.Coptparams

##### Default value

    false

#### Oracle Customizer Parameter Default Size Option (optparamdefaults)

If you enable the `optparams` option to set parameter sizes, use the `optparamdefaults` option as desired to set default sizes for specified datatypes. If `optparams` is not enabled, then any `optparamdefaults` setting is ignored.

If a host variable has a source code hint to specify its size, that takes precedence over the corresponding datatype default size set with this option. If there is no source code hint or corresponding datatype default size for a particular host variable, then resource allocation for that variable is determined by the JDBC driver, just as it would be if `optparams` were not enabled.

There is no requirement to use the `optparamdefaults` option, although it is typically used whenever `optparams` is enabled. If `optparams` is enabled and there are no default size settings, then resources are allocated either according to source code hints (if any) or the JDBC driver.

For an overview of parameter size definitions and a discussion of source code hints, see "Parameter Size Definitions".

You can set the `optparamdefaults` flag on the command line or in a SQLJ properties file.

Set it on the command line as follows:

    -P-Coptparamdefaults=datatype1(size1),datatype2(size2),...

All sizes are in bytes. Do not include any white space. Use empty parentheses for a null setting.

For example, the following will set sizes of 30 bytes for `VARCHAR2` and 1000 bytes for `RAW`, and will specify a null size setting for `CHAR`. So for any host variable corresponding to the `CHAR` datatype, if there is no source code hint, then the JDBC driver is left to allocate the resources.

    -P-Coptparamdefaults=VARCHAR2(30),RAW(1000),CHAR()

The `optparamdefaults` option recognizes the following datatype names:

- `CHAR`

- `VARCHAR`, `VARCHAR2` (synonymous)

- `LONG`, `LONGVARCHAR` (synonymous)

- `BINARY`, `RAW` (synonymous)

- `VARBINARY`

- `LONGVARBINARY`, `LONGRAW` (synonymous)

The `optparamdefaults` option also recognizes group names and wildcards, as follows:

- `CHAR_TYPE` covers `CHAR`, `VARCHAR`/`VARCHAR2`, and `LONG`/`LONGVARCHAR`.

- `RAW_TYPE` covers `BINARY`/`RAW`, `VARBINARY`, and `LONGVARBINARY`/`LONGRAW`.

- `%` by itself covers all recognized datatypes, or, appended to a partial name, covers a subset of datatypes. For example, `VAR%` includes all datatypes that start with "VAR".

The `optparamdefaults` setting is processed from left to right. When using group names or wildcards, you can override a group setting for particular datatypes.

The following example sets a general default size of 50 bytes, overrides that with a setting of 500 bytes for raw types, then overrides the raw type group setting with a null setting for `VARBINARY` (leaving that to JDBC for corresponding host variables with no source code hints):

    -P-Coptparamdefaults=%(50),RAW_TYPE(500),VARBINARY()

Following is a command-line example, including the `optparams` setting as well:

    sqlj <...SQLJ options...> -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp.sqlj

Or you can specify parameter size defaults for a previously existing profile (in which case you must also use the Oracle customizer `force` option to force a recustomization):

    sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyApp_SJProfile*.ser

Or you can specify parameter size defaults for previously existing profiles in a `.jar` file:

    sqlj -P-Cforce -P-Coptparams -P-Coptparamdefaults=CHAR_TYPE(50),RAW_TYPE(500),CHAR(10) MyAppProfiles.jar

    Note:

    If at runtime the actual size exceeds the registered size of any parameter, runtime errors will occur.

##### Command-line syntax

    -P-Coptparamdefaults=defaults-string

##### Command-line example

    -P-Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()

##### Properties file syntax

    profile.Coptparamdefaults=defaults-string

##### Properties file example

    profile.Coptparamdefaults=VAR%(50),LONG%(500),RAW_TYPE()

##### Default value

null

#### Oracle Customizer Show-SQL Option (showSQL)

Use the `showSQL` flag to display any SQL statement transformations performed by the Oracle customizer. Such transformations are necessary in cases where SQLJ supports syntax that Oracle8i does not.

To show SQL transformations when translating and customizing the application `MyApp`:

    sqlj <...SQLJ options...> -P-CshowSQL MyApp.sqlj

In this example, the `MyApp` profiles will be created and customized and their SQL transformations displayed in a single running of SQLJ.

To show SQL transformations when customizing `MyApp` profiles previously created:

    sqlj <...SQLJ options...> -P-CshowSQL MyApp_SJProfile*.ser

In this example, the `MyApp` profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and have their SQL transformations displayed in the above running of SQLJ.

The `showSQL` output might include an entry such as this:

    MyApp.sqlj:14: Info: <<<NEW SQL>>> #sql {BEGIN  ? := VALUES(tkjsSET_f1); END};

    in file MyApp, line 14, we had:

    #sql {set :v1= VALUES(tkjsSET_f1) };

SQLJ supports the `SET` statement, but Oracle8i does not. During customization, the Oracle customizer replaces the `SET` statement with an equivalent PL/SQL block.

Note: If customization does not take place because a valid previous customization is detected, the `showSQL` option shows SQL transformations regardless.

##### Command-line syntax

    -P-CshowSQL<=true/false>

##### Command-line example

    -P-CshowSQL

##### Properties file syntax

    profile.CshowSQL<=true/false>

##### Properties file example

    profile.CshowSQL

##### Default value

    false

#### Oracle Customizer Statement Cache Size Option (stmtcache)

Use the Oracle customizer `stmtcache` option to set the statement cache size--the number of statements that can be cached for each database connection when your application is run--or to disable statement caching.

The default statement cache size is 5. For an overview of statement caching, see "Statement Caching".

You can set the statement cache size on the command line or in a properties file.

To use the command line to set the statement cache size to 15 (for example) for the application `MyApp`:

    sqlj <...SQLJ options...> -P-Cstmtcache=15 MyApp.sqlj

To disable statement caching, set the cache size to 0:

    sqlj <...SQLJ options...> -P-Cstmtcache=0 MyApp.sqlj

You can also alter the statement cache size in an existing profile, without re-translating the application (but you must also use the Oracle customizer `force` option to force a recustomization):

    sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile0.ser

If you have multiple profiles, you can set their statement cache sizes individually by running SQLJ separately for each profile, after you have translated your application:

    sqlj -P-Cforce -P-Cstmtcache=10 MyApp_SJProfile0.ser
    sqlj -P-Cforce -P-Cstmtcache=15 MyApp_SJProfile1.ser
    sqlj -P-Cforce -P-Cstmtcache=0 MyApp_SJProfile2.ser

Of course, you must determine which profile corresponds to each of your connection context classes. This is determined as follows: Profile 0 will correspond to the connection context class used for the first executable statement in your application; Profile 1 will correspond to the connection context class used for the first executable statement that does not use the first connection context class, and so on. You can verify the correlation by using the customizer harness `print` option to examine each profile.

##### Command-line syntax

    -P-Cstmtcache=value

##### Command-line example

    -P-Cstmtcache=10

##### Properties file syntax

    profile.Cstmtcache=value

##### Properties file example

    profile.Cstmtcache=10

##### Default value

    5

#### Oracle Customizer Summary Option (summary)

Use the `summary` flag to instruct the Oracle customizer to display a summary of Oracle features used in an application being translated, or in specified profile files. This is useful in identifying features that would prevent portability to other platforms and can be accomplished either during a full SQLJ translation run or on profiles previously created.

To see summary output when translating and customizing the application `MyApp`:

    sqlj <...SQLJ options...> -P-Csummary MyApp.sqlj

In this example, the `MyApp` profiles will be created, customized, and summarized in a single running of SQLJ.

To see summary output for `MyApp` profiles previously created:

    sqlj <...SQLJ options...> -P-Csummary MyApp_SJProfile*.ser

In this example, the `MyApp` profiles were created (and possibly customized) in a previous running of SQLJ and will be customized (if needed) and summarized in the above running of SQLJ.

Following are two samples resulting from a `-P-Csummary` setting when using the default Oracle customizer. The first example indicates that no Oracle features are used:

    MyApp_SJProfile0.ser: Info: Oracle features used:
    MyApp_SJProfile0.ser: Info: * none

This second example indicates that Oracle features are used--namely, several Oracle extended datatypes from the `oracle.sql` package--and lists them:

    MyApp_SJProfile0.ser: Info: Oracle features used:
    MyApp_SJProfile0.ser: Info: * oracle.sql.NUMBER: 2
    MyApp_SJProfile0.ser: Info: * oracle.sql.DATE: 2
    MyApp_SJProfile0.ser: Info: * oracle.sql.CHAR: 2
    MyApp_SJProfile0.ser: Info: * oracle.sql.RAW: 2

Note: If customization does not take place because a valid previous customization is detected, the `summary` option produces a summary regardless.

##### Command-line syntax

    -P-Csummary<=true/false>

##### Command-line example

    -P-Csummary

##### Properties file syntax

    profile.Csummary<=true/false>

##### Properties file example

    profile.Csummary

##### Default value

    false

### SQLJ Options for Profile Customization

The following SQLJ options relate to profile customization and are described elsewhere in this manual:

- `-default-customizer`--Specify the default profile customizer to use if none is specified in the customizer harness `-customizer` option.

  See "Default Profile Customizer (-default-customizer)".

- `-profile`--Specify whether to customize during this running of SQLJ.

  See "Profile Customization Flag (-profile)".

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