This topic contains the following sections:
To understand the conventions that are used in the diagrams, see How to read syntax diagrams.
The pureQuery Generator utility requires parameters that specify the Eclipse environment to use, the database, JDBC driver, and interface to use when generating an implementation class.
The Generator analyzes the content of the input interface file and creates Java™ code that queries or updates the data object referenced in the @Select, @Update, and @Call annotations. It generates the code to populate the target bean on a query operation and uses the bean contents on update as input data.
Many pureQuery users build their applications using the workbench. In that environment, the pureQuery Generator is automatically invoked for all pureQuery annotated method interfaces that are contained in a Java project that has pureQuery support enabled. The generation of interface implementations happens as part of the normal build process for Java projects.
However, you can also invoke the pureQuery Generator from a command line. You must have IBM® Data Studio Developer or IBM Optim™ Development Studio installed. Depending on which of these two products you have installed, you must include the following .jar file in either the system classpath or JVM classpath when you run the Generator utility:
The Generator utility does not start Data Studio Developer or Optim Development Studio. It only makes use of the infrastructure and plugins that these products provide.
An options file lists the interface or interfaces that you want the pureQuery Generator utility to process, and the options that tell the Generator how to process the interfaces. You can set default options that apply to all of the interfaces that you list in an options file. You can also set options for interfaces so that you can override the default options and set other options that are specific to individual interfaces.
In the command to run the Generator, you can specify the file to use with the -optionsFile option.
defaultOptions = -driverName com.ibm.db2.jcc.DB2Driver -url jdbc:db2://SRVR01:50000/DB01 -username user01 -password passw0rd com.myCompany.MyInterfaceA = -collection NULLID com.myCompany.MyInterfaceB = -collection COLL01 -xmlFile C:\overrides\myInterfaceB_sql2.xml com.myCompany.MyInterfaceC = -url jdbc:db2://SRVR01:50001/DB02 -username user02 -password pass02In this example, the line that begins with defaultOptions specifies the driver to use when connecting to the database, the URL for connecting to the database, and the user name and password. These settings apply to all of the interfaces that are in the options file. The lines that are specific to the first two interfaces set options for those interfaces only.
-pkgVersion "ver#1"
You can choose to use only the command if you want to use the same options for all of the interfaces that you specify.
(1) >>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------> >-- -data--temporary-workspace-- -driverName--JDBC-driver-------> >-- -url--connection-URL-- -username--user-ID-- -password--password--> >--+------------------------+-- -rootPath--root_path------------> | .-FALSE-. | '- -noCleanup--+-TRUE--+-' >--+----------------------------+-------------------------------> '- -userClasspath--classpath-' >--+-----------------------------------+------------------------> | .-NULLID----------. | '- -collection--+-collection-name-+-' >--+--------------------------------+---------------------------> '- -pkgVersion-- -+-AUTO-------+-' '-version-ID-' >--+----------------------------------+-------------------------> '- -rootPkgName--package-name-stem-' >--+---------------------------------------+--------------------> | .-FALSE-. | '- -forceSingleBindIsolation--+-TRUE--+-' >--+---------------------+--+-----------------------+-----------> '- -xmlFile--XML-file-' | (2) | '-| Trace options |-----' .------------------------------. V | >-- -interface----Java-package.interface.class-+----------------> >--+---------------------------------------------+------------->< '- -baseDataOverride--Java-package.class-name-'
You can use an options file to specify the names of the interfaces and the options for creating the DB2® packages or DBRM files. With an options file, you can specify different options for the different interfaces.
If you are using the workbench, you can list in an options file (such as the Default.genProps file) only those interfaces that you want to specify options for individually. The defaultOptions line applies to all of the interfaces that are in a Java project.
(1) >>-java--org.eclipse.core.launcher.Main-- -application--com.ibm.pdq.tools.Generator------> >-- -data--temporary-workspace-- -driverName--JDBC-driver-------> >-- -url--connection-URL-- -username--user-ID-- -password--password--> >-- -optionsFile--file-name--+------------------------+---------> | .-FALSE-. | '- -noCleanup--+-TRUE--+-' >-- -rootPath--root_path--+----------------------------+--------> '- -userClasspath--classpath-' >--+-----------------------+----------------------------------->< | (2) | '-| Trace options |-----'
The remaining two syntax diagrams describe how to create entries in options files.
This syntax diagram shows the default options that you can set for all of the interfaces that you list in an options file.
(1) >>-defaultOptions--=------ -driverName--JDBC-driver-------------> >-- -url--connection-URL-- -username--user-ID-- -password--password--> >--+------------------------+-- -rootPath--root_path------------> | .-FALSE-. | '- -noCleanup--+-TRUE--+-' >--+----------------------------+--+-----------------------+----> '- -userClasspath--classpath-' | (2) | '-| Trace options |-----' >--+-----------------------------------+------------------------> | .-NULLID----------. | '- -collection--+-collection-name-+-' >--+--------------------------------+---------------------------> '- -pkgVersion-- -+-AUTO-------+-' '-version-ID-' >--+---------------------------------------+--------------------> | .-FALSE-. | '- -forceSingleBindIsolation--+-TRUE--+-' >--+---------------------+--------------------------------------> '- -xmlFile--XML-file-' >--+---------------------------------------------+------------->< '- -baseDataOverride--Java-package.class-name-'
This syntax diagram shows the options that you can set for each interface that you list in an options file.
(1) >>-Java-package.interface--=------ -driverName--JDBC-driver-----> >-- -url--connection-URL-- -username--user-ID-- -password--password--> >--+-----------------------------------+------------------------> | .-NULLID----------. | '- -collection--+-collection-name-+-' >--+--------------------------------+---------------------------> '- -pkgVersion-- -+-AUTO-------+-' '-version-ID-' >--+----------------------------------+-------------------------> '- -rootPkgName--package-name-stem-' >--+---------------------------------------+--------------------> | .-FALSE-. | '- -forceSingleBindIsolation--+-TRUE--+-' >--+---------------------+--------------------------------------> '- -xmlFile--XML-file-' >--+---------------------------------------------+------------->< '- -baseDataOverride--Java-package.class-name-'
If you want to use the -isolationLevel option to bind a single statement set into two or three different packages, with each package at a different isolation level, do not use the -forceSingleBindIsolation option when you run the Configure utility on the pureQueryXML file in which the statement set appears.
For example, in an options file for the StaticBinder utility, suppose that you included these two entries:
C:/dir/captureFile.pdqxml:MYPKGA = -isolationLevel UR C:/dir/captureFile.pdqxml:MYPKGA = -isolationLevel CS
If you used the -forceSingleBindIsolation option when you ran the Configure utility on the captureFile.pdqxml file, the StaticBinder utility performs these actions:
The result is a single MYPKGA package that is bound at the CS isolation level.
If you want the result to be two MYPKGA packages, one at the UR and the other at the CS isolation level, do not use the -forceSingleBindIsolation option when you run the Configure utility on captureFile.pdqxml.
DB2 allows multiple versions of a package to exist at the same time, so that you can bind new packages without replacing older versions of packages with the same names. If you encounter problems with a newer package, you can use an older version of that package.
If you do not specify this option, database packages that result from subsequent binds are created without a version.
Verification of the version at run time is based on the consistency token, not the version name.
If you plan to use the pureQuery StaticBinder utility to generate DBRM files rather than create DB2 packages, package-name-stem must be in uppercase and up to only 7 characters long. If you use the StaticBinder utility to generate a DBRM file and package-name-stem plus the added characters for the isolation level is longer than 7 characters, the StaticBinder utility throws an exception.
Package names must be unique within a single database, so you cannot specify one root package name for more than one interface. You can specify a root package name on the command line if you specify exactly one interface there. Also, you can specify a root package name for interfaces in an options file, but not as part of the defaultOptions line.
For example, the directory might be C:\user\app1\. Within that directory would be the directories that correspond to Java packages, such as C:\user\app1\com\myCompany\.
With the -interface option of the Generator utility, you specify the name of the interface that you want the utility to process, qualifying the name with the name of the package, as in this example: com.myCompany.MyInterface
The interface must be able to compile.
The Generator utility generates an implementation class in the same directory as the corresponding interface. Therefore, each implementation class is created in the same Java package as its interface.
If you run the pureQuery Generator utility with -rootPath set to C:\user\app1\ and -interface set to com.myCompany.MyInterface, the utility generates the class MyInterfaceImpl.java in the directory C:\user\app1\com\myCompany\. The fully-qualified name of the class is com.myCompany.MyInterfaceImpl.
If you do not use the -rootPath option, the pureQuery Generator utility uses the current working directory.
>>-+------------------------+--+---------------------------+--->< '- -traceFile--file-name-' | .-OFF-----. | '- -traceLevel--+-ALL-----+-' +-SEVERE--+ +-WARNING-+ +-INFO----+ +-CONFIG--+ +-FINE----+ +-FINER---+ '-FINEST--'