Oracle8i SQLJ Developer's Guide and Reference Release 8.1.5 A64684-01 |
|
This section documents the syntax and functionality of the basic flags and options you can specify in running SQLJ. These options allow you to run in a fairly standard mode of operation. For options that can also be specified in a properties file (such as sqlj.properties
), that syntax is noted as well (see "Properties Files for Option Settings").
More advanced command-line flags and options are discussed in "Advanced Translator Options" and "Translator Support and Options for Alternative Environments".
The following basic options can be specified only on the SQLJ command line or, equivalently, in the SQLJ_OPTIONS
environment variable. They cannot be specified in properties files.
The command-line-only flags (the -help
flags, -version
flags, and -n
) do not support =true
syntax. Enable them by typing only the flag name, as in the following example:
supported: sqlj -version-long ...
not supported: sqlj -version-long=true ...
Note:
There are also more advanced options, flags, and prefixes that can be set only on the command line or in |
The -props
option specifies a properties file from which SQLJ can read option settings (an alternative to specifying option settings on the command line).
See "Properties Files for Option Settings" for information about the format of these files, the details of how they are used in relation to command-line options, and where SQLJ looks for default properties files.
-props=filename
-props=myprops.properties
n/a
n/a
none
For compatibility with the syntax of most Java VMs and compilers, SQLJ recognizes the -classpath
option if it is specified on the command line. In setting this option, you can use either a space, as with most VMs or compilers, or "=", as with other SQLJ options. This is shown in the following examples (both on Solaris):
-classpath=.:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip
or:
-classpath .:./classes:/vobs/dbjava/classes/classes111.zip:/jdbc-1.2.zip
The -classpath
option sets the Java CLASSPATH
for both the Java VM and the Java compiler. If you do not want to use the same CLASSPATH
for both, set them separately using the SQLJ -J
and -C
prefixes, described in "Prefixes that Pass Option Settings to Other Executables".
sqlj -classpath=<class_path>
sqlj -classpath=/jdbc-1.2.zip:/classes/bin
n/a
n/a
none
The following three settings of the -help
flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ options:
You can enable this option by typing the desired setting on the command line as in the following examples:
sqlj -help
or:
sqlj -help-long
or:
sqlj -help-alias
No input-file translation is done when you use the -help
flag in any of these forms, even if you include file names and other options on the command line as well. It is assumed that you either want to run the translator or you want help, but not both.
You can also receive information about the profile customizer or Java compiler, requesting help through the -P
and -C
prefixes as in the following examples. These prefixes are discussed in "Prefixes that Pass Option Settings to Other Executables". As with the -help
flag, no translation is done if you request customizer or compiler help.
sqlj -P-help sqlj -C-help
Like other command-line-only flags, -help
(as well as -P-help
and -C-help
) does not support =true
syntax. Enable it by typing only the desired flag setting.
Notes:
|
The most basic level of help is achieved by specifying the -help
setting. This provides the following:
-help
flag settings available
This setting provides a complete list of SQLJ option information, including the following for each option:
boolean
, integer
, or String
)
This setting provides a synopsis of the command-line abbreviations that are supported for compatibility with the loadjava
utility.
sqlj help_flag_settings
sqlj -help sqlj -help -help-alias sqlj -help-long sqlj -warn=none,null -help-long sqlj -help-alias
n/a
n/a
none
The following settings of the -version
flag, specified on the command-line, instruct SQLJ to display varying levels of information about SQLJ and JDBC driver versions:
You can enable this option by typing the desired setting on the command line as in the following examples:
sqlj -version
or:
sqlj -version-long
No input-file translation is done when you use the -version
option, even if you include file names and other options on the command line. It is assumed that you either want to run the translator or you want version information, but not both. Properties files and anything else you type on the command line are ignored.
Like other command-line-only flags -version
does not support =true
syntax. Enable it by typing only the flag name.
The -version
setting displays the SQLJ release number, such as "Oracle SQLJ 8.1.5".
The -version-long
setting displays SQLJ release and build version information and the JDBC driver release number if one can be found. For example, if an Oracle JDBC driver is used, this option would display something like "Oracle JDBC version 8.1 (8.1.5.0.0)".
sqlj version_flag_settings
sqlj -version sqlj -version -version-long sqlj -version-long
n/a
n/a
none
The -n
flag, specified on the command line, instructs the sqlj
script to construct the full command line that would be passed to the SQLJ translator, including any SQLJ_OPTIONS
settings, and echo it to the user without having the SQLJ translator execute it. This includes capturing and echoing the name of the Java VM that would be launched to execute the SQLJ translator and echoing the full class name of the translator. This does not include settings from properties files.
This is useful in showing you the following:
-u
and other abbreviations supported for loadjava
compatibility)
SQLJ_OPTIONS
settings and command-line settings
The -n
option can appear anywhere on the command line or in the SQLJ_OPTIONS
variable.
Like other command-line-only flags -n
does not support =true
syntax. Enable it by typing only the flag name.
Consider the following sample scenario:
SQLJ_OPTIONS
:
-user=scott/tiger@jdbc:oracle:thin:@ -classpath=/myclasses/bin
% sqlj -n -e SJIS myapp.sqlj
You would see the following echo:
java -classpath /myclasses/bin sqlj.tools.Sqlj -user=scott/tiger@jdbc:oracle:thin:@ -C-classpath=/myclasses/bin -encoding=SJIS myapp.sqlj
(This is all one wrap-around line.)
Note:
|
-n
-n
n/a
n/a
false
The following option specifies encoding for SQLJ input and output source files:
These options specify where SQLJ output files are placed:
The -encoding
option specifies NLS encoding to be applied to .sqlj
and .java
input files and .java
generated files. For compatibility with javac
, you can use either a space or "=" in setting this option on the command line, as in the following examples:
-encoding=SJIS -encoding SJIS
If setting -encoding
in a properties file, however, use "=", not a space.
When this option is specified, it is also passed to the Java compiler (unless the -compiler-encoding-flag
is off), which uses it to specify encoding for .java
files processed by the compiler.
Notes:
|
-encoding=Java_character_encoding
-encoding=SJIS
sqlj.encoding=Java_character_encoding
sqlj.encoding=SJIS
setting in Java VM system property file.encoding
The -d
option specifies the root output directory for profiles generated by the SQLJ translator and is also passed to the Java compiler to specify the root output directory for .class
files generated by the compiler. Whether profiles are generated as .ser
files (default) or .class
files (if the -ser2class
option is enabled) is irrelevant in using the -d
option. (For information about -ser2class
, see "Conversion of .ser File to .class File (-ser2class)".)
Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in a package a.b.c
and specify directory /mydir
, output files will be placed in directory /mydir/a/b/c
.
If you specify a relative directory path, this will be from your current directory.
For compatibility with javac
, you can use either a space or "=" in setting this option on the command line, as in the following examples (both of which make /root
the root directory for generated profile files):
-d=/root -d /root
If setting -d
in a properties file, however, use "=", not a space (for example, sqlj.d=/root
).
If your current directory is /root/home/mydir
and you set the -d
option to the relative directory path mysubdir/myothersubdir
as follows, then /root/home/mydir/mysubdir/myothersubdir
will be the root directory for generated profile files:
-d=mysubdir/myothersubdir
You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir
):
-d=. -d=../paralleldir
If the -d
option is not specified, then files are generated under the directory where the associated .java
source file is generated, which is according to the -dir
option. If you specifically want the output directory to be the same as that used by -dir
(perhaps overriding other -d
settings, such as in properties files), then you can use the -d
option as follows:
-d=
-d=directory_path
-d=/topleveldir/mydir
sqlj.d=directory_path
sqlj.d=/topleveldir/mydir
none (use directory of generated .java
source file, per -dir
option)
The -dir
option specifies the root directory for .java
files generated by the SQLJ translator.
Whenever a directory is specified, the output files are generated under this directory according to the package name, if applicable. For example, if you have source files in a package a.b.c
and specify directory /mydir
, then output files will be placed in directory /mydir/a/b/c
.
If you specify a relative directory path it will be from your current directory.
A simple example is as follows, which will make /root
the root directory for generated .java
files:
-dir=/root
If your current directory is /root/home/mydir
and you set the -dir
option to the relative directory path mysubdir/myothersubdir
as follows, then /root/home/mydir/mysubdir/myothersubdir
will be the root directory for generated .java
files:
-dir=mysubdir/myothersubdir
You can also use standard syntax such as a period for the current directory or two periods to go up a level (the second example immediately below will go up a level, then back down to a parallel directory called paralleldir
):
-dir=. -dir=../paralleldir
If the -dir
option is not specified, then files are generated under the same directory as the original .sqlj
source file (not under the current directory).
If you specifically want the output directory to be the same as your .sqlj
source directory (perhaps overriding other -dir
settings, such as in properties files), then you can use the -dir
option as follows:
-dir=
-dir=directory_path
-dir=/topleveldir/mydir
sqlj.dir=directory_path
sqlj.dir=/topleveldir/mydir
none (use directory of .sqlj
source file)
The following options are used for the database connection for online semantics-checking:
There is no requirement that the SQLJ translator connect to the same database or schema as the application does at runtime. The connection information in application source code can be independent of the connection information in the SQLJ options.
A situation where you will probably want to use a different connection for translation than for runtime is if you are developing in a different environment than the one to which you will deploy.
Simple semantics-checking not involving a database connection is referred to as offline checking. The more thorough semantics-checking requiring a database connection is referred to as online checking. Online checking offers one of the prime advantages of the SQLJ strong-typing paradigm--type incompatibilities that would normally result in runtime SQL exceptions are caught during translation before users ever run the application.
The -user
option enables online semantics-checking and specifies the username (schema name) for the database schema used for the checking. You can also use the -user
option to specify the password and URL, as opposed to using the -password
and -url
options separately.
Note that there is no other flag to enable or disable online semantics-checking; SQLJ enables it or disables it according to the presence or absence of the -user
option.
Discussion of the -user
option is split into two categories--1) effect of -user
when you are using the default connection context class only; and 2) effect of -user
when you are using non-default or multiple connection context classes. Non-default connection context classes are discussed in "Connection Contexts".
General discussion of connection considerations, such as when to use multiple instances of the DefaultContext
class and when to declare additional connection context classes, is in "Connection Considerations".
Notes:
|
The most basic usage of the -user
option is as follows:
-user=scott
When you are using only the default connection or other instances of the DefaultContext
class, such a setting will apply to all of your SQLJ executable statements. This example results in online checking against the scott
schema.
You can also specify the password or URL or both along with the username, using syntax as in the following examples (with "/" preceding the password and "@" preceding the URL):
-user=scott/tiger
or:
-user=scott@jdbc:oracle:oci8:@
or:
-user=scott/tiger@jdbc:oracle:oci8:@
Otherwise the URL can be specified through the -url
option and the password can be specified interactively or through the -password
option.
You can disable online semantics-checking by setting the -user
option to an empty string:
-user=
Again, when you are using only the default connection or other instances of the DefaultContext
class, this will apply to all of your SQLJ executable statements.
Disabling online semantics-checking is useful, for example, if you have online checking enabled in a properties file but want to override that on the command line, or have it enabled in the default properties file but want to override that in a user-specified properties file (specified using the -props
option).
There is also a special username, URL.CONNECT
, which you can use when the URL specifies the user and password as well as the other details of the database connection. To see what the URL would look like in such a case, see "Connection URL for Online Semantics-Checking (-url)".
If you declare and use additional connection context classes in your application, then you can specify -user
settings for the testing of SQLJ executable statements that use instances of those classes. Specify a username for online checking against a particular connection context class as follows:
-user@CtxClass=scott
This results in online checking against the scott
schema for any of your SQLJ executable statements that specify a connection object that is an instance of CtxClass
.
As with the default connection context class, you can also specify the password or URL in your -user
setting for a particular connection context class, as in the following example:
-user@CtxClass=scott/tiger@jdbc:oracle:oci8:@
The CtxClass
connection context class must be declared in your source code or previously compiled into a .class
file. (See "Connection Contexts" for more information.)
Employ the -user
option separately for each connection context username you want to specify; these settings have no influence on each other:
-user@CtxClass1=user1 -user@CtxClass2=user2 -user@CtxClass3=user3
When you are using multiple connection context classes in your application, a -user
setting that does not specify a class will apply to the DefaultContext
class as well as to all classes for which you do not otherwise specify a -user
setting. Presumably, though, you will specify a -user
setting for each connection context class, given that different connection context classes are typically intended for use with different kinds of schemas.
Consider a situation where you have declared connection context classes CtxClass1
, CtxClass2
, and CtxClass3
and you set -user
as follows:
-user@CtxClass2=scott/tiger -user=bill/lion
Any statement in your application that uses an instance of CtxClass2
will be checked against the scott
schema. Any statement that uses an instance of DefaultContext
, CtxClass1
, or CtxClass3
will be checked against the bill
schema.
In addition, once you enable online checking by setting the -user
option, you can disable online checking for a particular connection context by setting the -user
option again with an empty username for that connection context. For example, after semantics checking is enabled, the following setting disables it for connection context CtxClass2
:
-user@CtxClass2=
This disables online semantics-checking for any SQLJ executable statements that specify a connection object that is an instance of CtxClass2
.
To disable online semantics-checking for the default connection context class and any other connection context classes for which you do not specify a username:
-user=
-user<@conn_context_class>=username</password><@url>
-user=scott -user=scott/tiger -user=scott@jdbc:oracle:oci8:@ -user=scott/tiger@jdbc:oracle:oci8:@ -user= -user=URL.CONNECT -user@Context=scott/tiger -user@Context=
sqlj.user<@conn _ocntext_class>=username</password><@url>
sqlj.user=scott sqlj.user=scott/tiger sqlj.user=scott@jdbc:oracle:oci8:@ sqlj.user=scott/tiger@jdbc:oracle:oci8:@ sqlj.user= sqlj.user=URL.CONNECT sqlj.user@CtxClass=scott/tiger sqlj.user@CtxClass=
none (no online semantics-checking)
The -password
option specifies the user password to use for the database connection for online semantics-checking. For the -password
setting to be meaningful, the -user
option must also be set .
You can also specify the password as part of the -user
option setting. (See "Online Semantics-Checking and Username (-user)".) Do not use the -password
option for a connection context class if you have already set its password in the -user
option, which takes precedence.
For the most part, functionality of the -password
option parallels that of the -user
option. That is, if your application uses only the default connection or other instances of DefaultContext
, the following will set the password for the schema to be used in checking all of your SQLJ statements:
-password=tiger
If you declare and use additional connection context classes, CtxClass1
for example, then you will presumably employ the -user
option to specify additional schemas to use in testing statements that use those connection context classes. Similarly, use the -password
option to specify passwords for those schemas, as in the following example:
-password@CtxClass1=tiger
A connection context class without a password setting, either through the -password
setting or the -user
setting, uses the password that was set for the default connection context class. If you set no password for the default connection context class, then SQLJ prompts you interactively for that password. If you also set no password for a user-defined connection context class, then SQLJ prompts you interactively for that password as well. An exception to this discussion is where username URL.CONNECT
is used, as discussed in "Online Semantics-Checking and Username (-user)". In this case, username and password are determined from the string specified in the -url
setting, and any setting of the -password
option is ignored.
You can specifically set an empty password to override other settings of the -password
option, such as in a properties file, and be prompted interactively. You can do this for the DefaultContext
class or any particular connection context class, as in the following examples:
-password=
or:
-password@CtxClass1=
If you actually want to use an empty password to log in, specify EMPTY.PASSWORD
as in the following examples:
-password=EMPTY.PASSWORD
or:
-password@CtxClass2=EMPTY.PASSWORD
Oracle, however, does not permit an empty password.
-password<@conn_context_class>=user_password
-password=tiger -password= -password=EMPTY.PASSWORD -password@CtxClass=tiger
sqlj.password<@conn_context_class>=user_password
sqlj.password=tiger sqlj.password= sqlj.password=EMPTY.PASSWORD sqlj.password@CtxClass=tiger
none
The -url
option specifies a URL for establishing a database connection for online semantics-checking. As necessary, the URL can include a host name, port number, and Oracle database SID.
You can also specify the URL as part of the -user
option setting. (See "Online Semantics-Checking and Username (-user)".) Do not use the -url
option for a connection context class if you have already set its URL in the -user
option, which takes precedence.
For the most part, functionality of the -url
option parallels that of the -user
option. That is, if your application uses only the default connection or other instances of DefaultContext
, the following example would set the URL to use for the database connection for checking all of your SQLJ statements:
-url=jdbc:oracle:oci8:@
Or, to include host name, port number, and SID:
-url=jdbc:oracle:thin:@hostname:1521:orcl
If you do not begin a URL setting with jdbc:
then the setting is assumed to be of the form host
:
port
:
sid
and by default is automatically prefixed with the following:
jdbc:oracle:thin:@
For a -url
setting of localhost:1521:orcl
, for example, this results in a URL of jdbc:oracle:thin:@localhost:1521:orcl
.
You can remove or alter this default prefix with the -default-url-prefix
option. See "Default URL Prefix (-default-url-prefix)" for more information.
You can specify the user and password in the -url
setting instead of in the -user
and -password
settings. In such a case, set -user
to URL.CONNECT
, as follows:
-url=jdbc:oracle:oci8:scott/tiger@ -user=URL.CONNECT
If you declare and use additional connection context classes, CtxClass1
for example, you will presumably specify additional schemas to use in testing statements that use those connection context classes. You can use the -url
option to specify URLs for those schemas, as in the following example:
-url@CtxClass1=jdbc:oracle:oci8:@
Any connection context class without a URL setting, either through the -url
setting or the -user
setting, uses the URL that was set for the default connection context class, presuming a URL has been set for the default context class.
-url<@conn_context_class>=URL
-url=jdbc:oracle:oci8:@ -url=jdbc:oracle:thin:@hostname:1521:orcl -url=jdbc:oracle:oci8:scott/tiger@ -url=hostname:1521:orcl -url@CtxClass=jdbc:oracle:oci8:@
sqlj.url<@conn_context_class>=URL
sqlj.url=jdbc:oracle:oci8:@ sqlj.url=jdbc:oracle:thin:@hostname:1521:orcl sqlj.url=jdbc:oracle:oci8:scott/tiger@ sqlj.url=hostname:1521:orcl sqlj.url@CtxClass=jdbc:oracle:oci8:@
jdbc:oracle:oci8:@
The following is the default prefix for any URL setting you specify that does not already start with jdbc:
jdbc:oracle:thin:@
This allows you to use a shorthand in specifying a URL setting, either in the -user
option or the -url
option--you can specify only the host, port, and SID of the database. As an example, presume you set a URL as follows:
-url=myhost:1521:orcl
or:
-user=scott/tiger@myhost:1521:orcl
By default, the URL will be interpreted to be the following:
jdbc:oracle:thin:@myhost:1521:orcl
If you specify a full URL that starts with jdbc:
then the default prefix will not be used, such as in the following example:
-url=jdbc:oracle:oci8:@orcl
Use the -default-url-prefix
option to alter or remove the default prefix. For example, if you want your URL settings to default to the OCI 8 driver instead of the Thin driver, then set the default prefix as follows:
-default-url-prefix=jdbc:oracle:oci8:@
With this prefix, a setting of -url=orcl
is equivalent to the -url=jdbc:oracle:oci8:@orcl
setting above.
If you do not want any prefix, then set the -default-url-prefix
option to an empty string, as follows:
-default-url-prefix=
-default-url-prefix=url_prefix
-default-url-prefix=jdbc:oracle:oci8:@ -default-url-prefix=
sqlj.default-url-prefix=url_prefix
sqlj.default-url-prefix=jdbc:oracle:oci8:@ sqlj.default-url-prefix=
jdbc:oracle:thin:@
The -driver
option specifies the JDBC driver class to register for interpreting JDBC connection URLs for online semantics-checking. Specify a driver class or comma-separated list of classes.
The default, OracleDriver
, supports the Oracle OCI 8, Thin, and server-side JDBC drivers for use with Oracle databases.
-driver=driver1<,driver2,driver3,...>
-driver=oracle.jdbc.driver.OracleDriver -driver=oracle.jdbc.driver.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
sqlj.driver=driver1<,driver2,driver3,...>
sqlj.driver=oracle.jdbc.driver.OracleDriver sqlj.driver=oracle.jdbc.driver.OracleDriver,sun.jdbc.odbc.JdbcOdbcDriver
oracle.jdbc.driver.OracleDriver
The following options specify what kinds of conditions SQLJ should monitor, whether to generate real-time error and status messages, and whether to include "cause" and "action" information with translator error messages:
The following option enables line-mapping from the .java
output file back to the .sqlj
source file, so that you can trace compilation and execution errors back to the appropriate location in your original source code.
There are various warnings and informational messages that the SQLJ translator can display as dictated by conditions it encounters during the translation. The -warn
option consists of a set of flags that specify which of those warnings and messages should be displayed (in other words, which conditions should be monitored and which should be ignored).
All of the flags for this option must be combined into a single, comma-separated string.
Table 8-2 documents the conditions that can be tested, what a true
flag value means, what the true
and false
flag values are for each condition, and which value is the default.
The verbose/noverbose
flag works differently than the others. It does not enable a particular test but enables output of general informational messages about the semantics-checking.
The global all
/none
flag takes priority over default settings. You can use it to enable or disable all flags, or to serve as an initialization to make sure all flags are off before you turn selected flags on, or vice versa. Essentially, all
is equivalent to precision,
nulls,
portable,
strict,
verbose
and none
is equivalent to noprecision,
nonulls,
noportable,
nostrict,
noverbose
. There is no default for all
/none
; there are only defaults for individual flags.
For example, use the following sequence to make sure only the nulls
flag is on:
-warn=none,nulls
And the following sequence will have the same result, because the verbose
setting will be overridden:
-warn=verbose,none,nulls
Or use the following to make sure everything except the portability flag is on:
-warn=all,noportable
And the following sequence will have the same result, because the nonulls
setting will be overridden:
-warn=nonulls,all,noportable
Other than placement of the all
/none
flag, the order in which flags appear in a -warn
setting is unimportant except in the case of conflicting settings. If there are conflicts, such as in -warn=portable,noportable
, then the last setting is used.
Separate settings of the -warn
option in properties files and on the command line are not cumulative. Only the last setting is processed. In the following example, the -warn=portable
setting is ignored; that flag and all other flags besides nulls/nonulls
are set according to their defaults:
-warn=portable -warn=nonulls
-warn=comma-separated_list_of_flags
-warn=none,nulls,precision
sqlj.warn=comma-separated_list_of_flags
sqlj.warn=none,nulls,precision
precision,nulls,noportable,strict,noverbose
The -status
flag instructs SQLJ to output additional status messages throughout all aspects of the SQLJ process--translation, semantics-checking, compilation, and customization. Messages are output as each file is processed and at each stage of SQLJ operation.
Notes:
|
-status=true/false
-status=true
sqlj.status=true/false
sqlj.status=false
false
The -explain
flag instructs the SQLJ translator to include "cause" and "action" information (as available) with translator error message output (for the first occurrence of each error).
This is the same information that is provided in "Translation Time Messages".
-explain=true/false
-explain=true
sqlj.explain=true/false
sqlj.explain=false
false
The -linemap
flag instructs SQLJ to map line numbers from a SQLJ source code file to locations in the corresponding .class
file. (This will be the .class
file created during compilation of the .java
file generated by the SQLJ translator.) As a result of this, when Java runtime errors occur, the line number reported by the Java VM is the line number in the SQLJ source code, making it much easier to debug.
Normally, the instructions in a .class
file map to source code lines in the corresponding .java
file. This would be of limited use to SQLJ developers, though, as they would still need to map line numbers in the generated .java
file to line numbers in their original .sqlj
file.
The SQLJ translator modifies the .class
file to implement the -linemap
option, replacing line numbers and the file name from the generated .java
file with corresponding line numbers and the file name from the original .sqlj
file. This process is known as instrumenting the class file.
In doing this, SQLJ takes the following into account:
-d
option setting, which determines the root directory for .class
files
-dir
option setting, which determines the root directory for generated .java
files
-linemap=true/false
-
linemap=true
sqlj.linemap=true/false
sqlj.linemap=false
false