A Customization and Specialized Customizers

SQLJ Executable Statement

Presume the following declaration:

#sql iterator Iter (double sal, String ename);

And presume the following executable statements:

String empname = 'Smith';
Iter it;
...
#sql it = { SELECT ename, sal FROM emp WHERE ename = :empname };

Corresponding SQLJ Profile Entry

=================================================================
...
#sql { SELECT ename, sal FROM emp WHERE ename = ? };
...
PREPARED_STATEMENT executed through EXECUTE_QUERY 
role is QUERY
descriptor is null
contains one parameter
1. mode: IN, java type: java.lang.String (java.lang.String),
   sql type: VARCHAR, name: ename, ...
result set type is NAMED_RESULT
result set name is Iter
contains 2 result columns
1. mode: OUT, java type: double (double),
   sql type: DOUBLE, name: sal, ...
2. mode: OUT, java type: java.lang.String (java.lang.String),
   sql type: VARCHAR, name: ename, ...
=================================================================

Syntax for Customizer Harness Options

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

-P-option=value

Alternatively, 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 only in SQLJ command line).

• verbose: Display status messages during customization.

The customizer harness supports the following options for customizer database connections. Currently, these are used by Oracle customizer if you enable its optcols option for column definitions (for performance optimization). In addition, they are 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 the Oracle SQLJ implementation.

• debug: Insert debugging information into the specified profiles, to be output at run time. This is a shortcut to invoke the Oracle SQLJ AuditorInstaller, which is described in "AuditorInstaller Customizer for Debugging".

• 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). This is a shortcut to invoke Oracle SQLJ SQLCheckerCustomizer, which is described in "SQLCheckerCustomizer for Profile Semantics-Checking".

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 .bakn, 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.

The command-line syntax for this option is:

-P-backup<=true|false>

Command-line example is:

-P-backup

Properties file syntax is:

profile.backup<=true|false>

Default value is:

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-delimited 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 is:

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

Command-line example is:

-P-context=foo.bar.MyCtxtClass

Properties file syntax is:

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

Properties file example is:

profile.context=foo.bar.MyCtxtClass

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 is:

-P-customizer=customizer_class

Command-line example is:

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

Properties file syntax is:

profile.customizer=customizer_class

Properties file example is:

profile.customizer=a.b.c.MyCustomizer

Default value is:

None

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, use the digests option to specify a comma-delimited list of one or more algorithms. These are the algorithms that the JAR utility 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.

Command-line syntax is:

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

Command-line example is:

-P-digests=SHA,MD5

Properties file syntax is:

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

Properties file example is:

profile.digests=SHA,MD5

Default value is:

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

Command-line syntax is:

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

Command-line example is:

-P-help

Properties file syntax is:

NA

Properties file example is:

NA

Default value is:

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 is:

-P-verbose<=true|false>

Command-line example is:

-P-verbose

Properties file syntax is:

profile.verbose<=true|false>

Properties file example is:

profile.verbose

Default value is:

false

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:oci:@
-P-user=scott/tiger@jdbc:oracle:oci:@

Command-line syntax is:

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

Command-line examples is:

-P-user=scott
-P-user=scott/password
-P-user=scott/password@jdbc:oracle:oci:@

Properties file syntax is:

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

Properties file examples is:

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

Default value is:

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 is:

-P-password=password

Command-line example is:

-P-password=password

Properties file syntax is:

profile.password=password

Properties file example is:

profile.password=password

Default value is:

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 is:

-P-url=url

Command-line example is:

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

Properties file syntax is:

profile.url=url

Properties file example is:

profile.url=jdbc:oracle:oci:@

Default value is:

jdbc:oracle:oci:@

Customization JDBC Driver Option (driver)

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

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

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

Command-line syntax is:

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

Command-line example is:

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

Properties file syntax is:

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

Properties file example is:

profile.driver=sun.jdbc.odbc.JdbcOdbcDriver

Default value is:

oracle.jdbc.OracleDriver

Specialized Customizer: Profile Debug Option (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 run time (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 is:

sqlj -P-debug profile_list

Command-line example is:

sqlj -P-debug Foo_SJProfile*.ser

Properties file syntax is:

profile.debug 

(Also specify profiles in the SQLJ file list.)

Properties file example is:

profile.debug

Default value is:

NA

Specialized Customizer: Profile Print Option (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. For example:

% sqlj -P-print Foo_SJProfile0.ser Bar_SJProfile0.ser

Use the following command, if you want to see all the customizer options:

% sqlj -P-print *.ser

The output of the preceding command is like the following:

printing contents of profile Sample_SJProfile0
created 1154609279331 (8/3/06 5:47 AM)
associated context is Mycontext1
profile loader is sqlj.runtime.profile.DefaultLoader@12a3793
contains one customization
OracleCustomization Options  :
Version is :2300
Cstmtcache :5
Ccompat    :false
Cforce     :false
Coptcols   :false
Coptparams :false
Coptparamdefaults:null
CshowSQL   :false
Csummary   :false
CuserSQL   :true

#sql { SELECT a    FROM test WHERE name= ?  }
setFixedchar is enabled
Ncharconv  is disabled

#sql { commit }
setFixedchar is disabled
Ncharconv  is disabled
………

Command-line syntax is:

sqlj -P-print profile_list

Command-line example is:

sqlj -P-print Foo_SJProfile*.ser

Properties file syntax is:

profile.print

(Also specify profiles in SQLJ file list.)

Properties file example is:

profile.print

Default value is:

NA

Specialized Customizer: Profile Semantics-Checking Option (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 run-time 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".

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. (The first is a single wraparound command.)

% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ Foo_SJProfile0.ser Bar_SJProfile0.ser
Password: password

% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ *.ser
Password: password

Command-line syntax is:

sqlj -P-verify <conn params> profile_list

Command-line example is:

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

Properties file syntax is:

profile.verify

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

Properties file example is:

profile.verify

Default value is:

NA

Options Supported by Oracle Customizer

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 data types (used in conjunction with optparams).

• fixedchar: Enable CHAR comparisons with blank padding for WHERE clauses.

• showSQL: Display SQL statement transformations.

• stmtcache: Set the statement cache size (the number of statements that can be cached for each connection during run time) 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 Oracle customizer to display information about compatibility of your application with different versions of Oracle Database and Oracle JDBC drivers. This can be accomplished either during a full SQLJ translation run or on profiles previously created.

For example, 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 the JDBC implementation from an Oracle 8.1.x or later release:

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

Command-line syntax is:

-P-Ccompat<=true|false>

Command-line example is:

-P-Ccompat

Properties file syntax is:

profile.Ccompat<=true|false>

Properties file example is:

profile.Ccompat

Default value is:

false

Oracle Customizer Force Option (force)

Use the force flag to instruct 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, 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 is:

-P-Cforce<=true|false>

Command-line example is:

-P-Cforce

Properties file syntax is:

profile.Cforce<=true|false>

Properties file example is:

profile.Cforce

Default value is:

false

Oracle Customizer Column Definition Option (optcols)

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

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

An error will be generated if you enable Oracle customizer optcols option without setting the user name, password, and URL for a database connection. You can accomplish this through the translator -user, -password, and -url options, which are forwarded to the customizer during ISO standard code generation, or directly through the customizer user, password, and url options.

The customizer does not have to connect to the same schema or even the same database that your application will connect to at run time, but the relevant columns will have to be in the same order and of identical types and sizes to avoid run-time errors.

For information about the customizer harness connection options, see the user, password, url, and driver sections under "Overview of Customizer Harness Options".

You can enable or disable the customizer optcols 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@jdbc:oracle:oci:@ -P-Coptcols MyApp.sqlj
Password: password

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

Alternatively, 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@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Password: password

You also can insert column definitions into previously existing profiles in a JAR file:

% sqlj -P-user=scott@jdbc:oracle:oci:@ -P-Cforce -P-Coptcols MyAppProfiles.jar
Password: password

When you run 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 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@jdbc:oracle:oci:@ -P-verbose -P-Cforce -P-Coptcols MyApp_SJProfile*.ser
Password: password

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

You can execute 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".

Command-line syntax is:

-P-Coptcols<=true|false>

Command-line example is:

-P-Coptcols

Properties file syntax is:

profile.Coptcols<=true|false>

Properties file example is:

profile.Coptcols

Default value is:

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.

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

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

Alternatively, to enable parameter size definitions for a previously existing profile:

% sqlj -P-Coptparams -P-Coptparamdefaults=defaults_string MyApp_SJProfile*.ser

You can also use previously existing profiles in a JAR file:

% sqlj -P-Coptparams -P-Coptparamdefaults=defaults_string MyAppProfiles.jar

Command-line syntax is:

-P-Coptparams<=true|false>

Command-line example is:

-P-Coptparams

Properties file syntax is:

profile.Coptparams<=true|false>

Properties file example is:

profile.Coptparams

Default value is:

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 data types. If optparams is not enabled, then any optparamdefaults setting is ignored.

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),...

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

The syntax is explained in "Parameter Default Size (-optparamdefaults)".

Alternatively, 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

You also 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

Command-line syntax is:

-P-Coptparamdefaults=defaults_string

Command-line example is:

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

Properties file syntax is:

profile.Coptparamdefaults=defaults_string

Properties file example is:

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

Default value is:

null

Oracle Customizer CHAR Comparisons with Blank Padding (fixedchar)

Set this flag to true to account for blank padding in CHAR database columns when binding character strings for WHERE clause comparisons. This way, for example, "mystring" would compare positively against "mystring ".

Here is an example of Oracle customizer fixedchar usage:

% sqlj -P-Cfixedchar MyProgram.sqlj AnotherProg.java ...

Command-line syntax is:

-P-Cfixedchar<=true|false>

Command-line example is:

-P-Cfixedchar

Properties file syntax is:

profile.Cfixedchar<=true|false>

Properties file example is:

profile.Cfixedchar

Default value is:

false

Oracle Customizer Show-SQL Option (showSQL)

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

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) };

During customization, Oracle customizer replaces the SET statement with an equivalent PL/SQL block.

Command-line syntax is:

-P-CshowSQL<=true|false>

Command-line example is:

-P-CshowSQL

Properties file syntax is:

profile.CshowSQL<=true|false>

Properties file example is:

profile.CshowSQL

Default value is:

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 as your application runs—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 also can alter the statement cache size in an existing profile without retranslating the application, but you must also use the Oracle customizer force option to force a recustomization, as follows:

% 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 is:

-P-Cstmtcache=value

Command-line example is:

-P-Cstmtcache=10

Properties file syntax is:

profile.Cstmtcache=value

Properties file example is:

profile.Cstmtcache=10

Default value is:

5

Oracle Customizer Summary Option (summary)

Use the summary flag to instruct 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 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—several Oracle extended data types 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 

The following example prints out the number of usages of the Oracle setFixedCHAR() API (enabled through the Oracle customizer fixedchar option, to account for blank padding when binding a string into a WHERE clause for comparison against CHAR data):

% sqlj -P-Cfixedchar -P-Csummary -P-Cforce *.ser
FC_SJProfile0.ser: Info: re-installing Oracle customization
FC_SJProfile0.ser: Info: Oracle features used:
FC_SJProfile0.ser: Info: * setFixedCHAR(): 4

Command-line syntax is:

-P-Csummary<=true|false>

Command-line example is:

-P-Csummary

Properties file syntax is:

profile.Csummary<=true|false>

Properties file example is:

profile.Csummary

Default value is:

false

SQLCheckerCustomizer Semantics-Checker Option (checker)

The checker option enables you to specify the semantics-checker to use in checking the SQL operations in a profile.

This defaults to the Oracle semantics-checker front end, oracle.sqlj.checker.OracleChecker, which for SQLCheckerCustomizer chooses an appropriate online checker for your environment. For more information about OracleChecker, see "Semantics-Checkers and OracleChecker Front End (default checker)".

Following is a full command-line example, showing how to use the SQLCheckerCustomizer checker option, in conjunction with the customizer harness verify option and connection options.

% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ -P-Cchecker=abc.def.MyChecker *.ser
Password: password

(This is a single wraparound command line.)

Command-line syntax is:

-P-Cchecker=checker_class

Command-line example is:

-P-Cchecker=a.b.c.MyChecker

Properties file syntax is:

profile.Cchecker=checker_class

Properties file example is:

profile.Cchecker=a.b.c.MyChecker

Default value is:

oracle.sqlj.checker.OracleChecker

SQLCheckerCustomizer Warnings Option (warn)

The warn option is equivalent to the SQLJ translator -warn option, enabling you to choose the categories of warnings and messages to be displayed as semantics-checking is performed on a profile.

For a complete description of the functionality and possible settings of these options, see "Translator Warnings (-warn)".

This defaults to the all,noverbose,noportable settings, resulting in all warning categories except verbose and portable being enabled. You will receive any warnings regarding inheritance hierarchy requirements, data precision, conversion loss for nullable data, and strict matching for named iterators. These are the same defaults as for warnings during SQLJ translation.

Following is a full command-line example showing how to use the SQLCheckerCustomizer warn option, in conjunction with the customizer harness verify option and connection options. This would result in only portability warnings being displayed.

% sqlj -P-verify -P-user=scott -P-url=jdbc:oracle:oci:@ -P-Cwarn=none,portable *.ser
Password: password

(This is a single wraparound command line.)

Command-line syntax is:

-P-Cwarn=comma-delimited_list_of_flags

Command-line example is:

-P-Cwarn=none,verbose

Properties file syntax is:

profile.Cwarn=comma-delimited_list_of_flags

Properties file example is:

profile.Cwarn=none,verbose

Default value is:

all,noverbose,noportable

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 enables 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; 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 is:

-P-Cdepth=n

Command-line example is:

-P-Cdepth=0

Properties file syntax is:

profile.Cdepth=n

Properties file example is:

profile.Cdepth=0

Default value is:

-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, so that 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 is:

-P-Clog=log_file

Command-line example is:

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

Properties file syntax is:

profile.Clog=log_file

Properties file example is:

profile.Clog=foo/bar/mylog.txt

Default value is:

Empty (for 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 is:

-P-Cprefix="string"

Command-line example is:

-P-Cprefix="layer 2: "

Properties file syntax is:

profile.Cprefix="string"

Properties file example is:

profile.Cprefix="layer 2: "

Default value is:

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 is:

-P-CshowReturns<=true|false>

Command-line example is:

-P-CshowReturns=false

Properties file syntax is:

profile.CshowReturns<=true|false>

Properties file example is:

profile.CshowReturns=false

Default value is:

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 is:

-P-CshowThreads<=true|false>

Command-line example is:

-P-CshowThreads

Properties file syntax is:

profile.CshowThreads<=true|false>

Properties file example is:

profile.CshowThreads

Default value is:

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 is:

-P-Cuninstall

Command-line example is:

-P-Cuninstall

Properties file syntax is:

profile.Cuninstall

Properties file example is:

profile.Cuninstall

Default value is:

Disabled