VisualAge(R) for Java(TM)

Version 3.5

SQLJ

RELEASE NOTES

Table of Contents

1.0 Introduction
2.0 Menu Items
      2.1 Workspace / Tools / SQLJ / Properties
      2.2 Workspace / Tools / SQLJ / Import
      2.3 Tools / SQLJ / Edit
      2.4 Tools / SQLJ / Translate
      2.5 Tools / SQLJ / Create SQLJ Debug Class File
3.0 Support Libraries
      3.1 Version
      3.2 Build-Time
      3.3 Run-Time
4.0 Customization
      4.1 Additional Classpath
      4.2 Translator Class Name
     4.3 Translator Method Name
5.0 Known Problems and Limitations
      5.1 Premature Process Termination
      5.2 Missing Dynamic Link Libraries
      5.3 Debug Class File Generation Limitation
      5.4 End of File Character
6.0 Hints and Tips
      6.1 Customization
      6.2 Refreshing a Project Resources View
      6.3 Importing To An Existing Package
7.0 Error Messages
      7.1 Import
8.0 JDBC(TM) Drivers

1.0 Introduction

Files with an extension of ".sqlj" are java source files that contain java source code with imbedded SQL statements. The SQLJ Tool provides the means to perform the following process:

  1. An ".sqlj" file is converted to a ".java" file, and one or more profile files with file extension '.ser', through a process called "translation". The imbedded SQL statements in the ".sqlj" file are converted to JDBC (TM) calls in the generated ".java" file.
  2. The resulting ".java" file is imported into a VisualAge for Java IDE project.
  3. The original ".sqlj" file, and resulting ".ser" files are copied to the project_resources directory of the project, and can be seen in a "Project Resources" window.
  4. During translation, an optional semantic check can be performed against the referenced database.

2.0 Menu Items

2.1 Workspace / Tools / SQLJ / Properties

This menu item displays a properties dialog. The following can be specified:

  1. The encoding to be used.
  2. Whether online semantics checking is to be performed against the database.
  3. The JDBC driver to be used for online semantics checking.
  4. The URL of the database for online semantics checking.
  5. The userid for database access for online semantics checking.
  6. The password for database access for online semantics checking.

2.2 Workspace / Tools / SQLJ / Import

This menu item displays an SQLJ file import dialog. The following can be specified:

  1. The project name to import the ".sqlj", ".java", and ".ser" files to.
  2. The name of the ".sqlj" file to import.
  3. Whether to perform a translation process.

If the translation process is disabled, then only the ".sqlj" file is imported.

2.3 Tools / SQLJ / Edit

This menu item and the following two menu items are actions you can perform against a previously imported ".sqlj" file. The menu items can be accessed by right-clicking on a ".sqlj" file in the Resources page of the Project browser.

This menu item displays an editor window for a ".sqlj" file. The file can be edited and saved.

Note that the editor menu item "Save as" will save the contents of the editor window in the specified file. However, after the save as operation has completed, the editor window continues to edit the old file, as reflected by the file name in the title bar.

2.4 Tools / SQLJ / Translate

This menu item performs a translation of the specified ".sqlj" file, with optional online semantics checking within the current project.

2.5 Tools / SQLJ / Create SQLJ Debug Class File

This menu item creates a class file and places it in the project_resources directory of the project that contains the ".sqlj" file. You can view this file in the Resources page of the Project browser.

The generated class file will contain debug line numbers that correspond to line numbers within the ".sqlj" file, and will reference the ".sqlj" file as its source file.

The class file and the original ".sqlj" file can be used with the distributed debugger.

3.0 Support Libraries

3.1 Version

The SQLJ support libraries packaged with VisualAge for Java support version 1.0.1.1 of the SQLJ specification.

3.2 Build-Time

A translator is packaged with VisualAge for Java and is contained in the file "sqlj-translator.zip" within the directory "x:\vajava\ide\tools\com-ibm-ivj-sqlj\lib", where vajava is your VisualAge for Java installation directory.

3.3 Run-Time

The generated ".java" files contain calls to a SQLJ Runtime Library. This library is packaged with VisualAge for Java in three forms within directory "x:\vajava\eab\runtime30":

  1. sqlj-runtime.jar is a compressed version of the runtime library for use with applets
  2. sqlj-runtime.zip is an uncompressed version of the runtime library

4.0 Customization

An SQLJ Tool customization file is provided so that a specific translator can be used with the SQLJ tool..This file is called "SQLJSupportToolTranslator.properties" and is located in the following directory "x:\vajava\ide\tools\com-ibm-ivj-sqlj". The content of this file is:

additionalclasspath = lib\\sqljtranslator.zip;x:\\sqllib\\java\\db2java.zip;
translatorclassname = sqlj.tools.Sqlj
translatormethodname = statusMain

4.1 Additional Classpath

The SQLJ Tool appends the specified classpath to the existing classpath before the tool attempts to search for the translator class.

4.2 Translator Class Name

The SQLJ Tool assumes the specified class name is the class that performs the translation process of converting ".sqlj" files to ".java" files and ".ser" files. The default class name is the name of a class that resides in the sqlj-translator.zip file packaged with VisualAge for Java.

4.3 Translator Method Name

The SQLJ Tool dynamically calls the specified method of the class specified by the translator classname specification in order to perform the translation.

5.0 Known Problems and Limitations

5.1 Premature Process Termination

Some translators and customizers may handle error conditions by sending a message to stdout and then exiting the translation process. If this occurs, the process terminates prematurely, and a completion message will not be displayed.

5.2 Missing Dynamic Link Libraries

If a dynamic link library of a translator is missing, then, a message such as "java.lang.UnsatisfiedLinkError: no db2sqlj in shared library path" may be generated. The process may terminate prematurely. Also, if the database driver cannot find the libraries associated with accessing the database, the translator will report that it cannot load the driver.

5.3 Debug Class File Generation Limitation

The creation of a debug class file is limited to the following assumptions:

  1. The size of the ".sqlj" file is smaller than that of the generated ".java" file.
  2. SQLJ statements are expanded at the location of the SQLJ statement and there is no code location optimization done by the translator.

5.4 End of File Character

If an SQLJ file has an end of file character such as hex 1a at the end of the file, the translation will fail. SQLJ files are treated in the same manner as Java files, where a javac compile of a Java file that contains an end of file character will fail.

6.0 Hints and Tips

6.1 Customization

Before using the SQLJ Tool translation facility, follow these steps:

  1. From the workbench, select Workspace > Tools > SQLJ > Properties and specify the translator and database options.

6.2 Refreshing a Project Resources View

From the Project Resources view, select Window > Refresh to refresh the view. You must refresh the window to view class files that are generated when you import or translate an SQLJ file or when you create a SQLJ debug class file.

6.3 Importing To An Existing Package

If the package name in an SQLJ file you are importing is the same as a package name that exists in a project other than the one you have selected, then all files will be imported
into the different project. A warning message will be displayed with the name of the project the SQLJ is imported into. 

The import may also fail if there is insufficient authority to import into the specified project.

7.0 Import Error Messages

When importing an SQLJ file to a project, or translating files that are imported into a project as resources, a failure may occur. This may occur because the project is a shared project, and is not owned by the current workspace user.

8.0 JDBC Drivers

Default: sun.jdbc.odbc.JdbcOdbcDriver
IBM DB2: COM.ibm.db2.jdbc.app.DB2Driver
Oracle : oracle.jdbc.driver.OracleDriver