To understand the conventions that are used in the diagrams, see How to read syntax diagrams.
Applications that use embedded SQL that is statically bound into DB2 packages have inherent advantages in the areas of performance, reliability, security, monitoring, and administration.
Before running the StaticBinder utility, run the pureQuery Generator utility to generate the implementation classes for the interfaces that contain the SQL statements that you want to bind. When the pureQuery Generator utility is run, all of the information that is necessary to create a static DB2 package is collected and stored in the generated implementation class. This information includes the SQL statements and all applicable data type information from both the Java™ class definitions and any column or parameter metadata from the target database. The information also includes the root package names and, optionally, the collection IDs and versions for the DB2 packages.
The StaticBinder utility reads this information from the implementation classes when it creates and binds DB2 packages. When you run the StaticBinder utility, on the command line, you can specify either the implementation classes to read from or the interfaces that correspond to those classes. If you use an options file, you can specify one or more interfaces; the StaticBinder utility reads the information from the corresponding implementation classes.
If you use the -forceSingleBindIsolation option when you run the Generator utility, however, the number for the isolation level is not appended to the name of the created package.
If you use the -isolationLevel option when you perform a bind or specify the isolation level in the bind options string, only the package or DBRM file for the isolation level that you specify is created. The name follows the convention that the StaticBinder uses when creating packages or DBRM files for all four isolation levels.
An options file lists the interface or interfaces that you want the pureQuery StaticBinder utility to process, and the options that tell the StaticBinder utility 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 StaticBinder utility, you can specify the file to use with the -optionsFile option.
defaultOptions = -bindOptions "QUALIFIER qual1" -traceFile C:\logs\staticbinder.txt -traceLevel ALL -url jdbc:db2://SRVR01:50000/DB01 -username user01 -password pass01 com.myCompany.MyInterfaceA = -bindOptions "QUALIFIER qual2" com.myCompany.MyInterfaceB com.myCompany.MyInterfaceC = -url jdbc:db2://SRVR01:50001/DB02 -username user02 -password pass02In this example, the line that begins with defaultOptions specifies the qualifier for the DB2 packages and sets the default connection URL. The line also specifies the file in which to log messages. The next line specifies an interface with a qualifier that overrides the default qualifier. The next line specifies an interface for which all of the default options apply. The last line specifies an interface to bind against a different database.
-pkgVersion "ver#1"
DB2 Database for Linux, UNIX, and Windows: If the user has SYSADM authority, but no explicit privileges to complete the bind, the DB2 database manager grants explicit DBADM authority automatically.
You can use this command to run the StaticBinder utility on an archive that contains your application. The archive must contain the interfaces and implementation classes to supply to the StaticBinder utility. Use an options file with the extension .bindProps that lists the interfaces and implementation classes.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--server--+---------+--/--database--> '-:--port-' >-- -username--user-ID-- -password--password--------------------> >-- -archive-- -filename--+-.ear-+------------------------------> +-.jar-+ +-.war-+ '-.zip-' >--+------------------------------------------------------------------------+--> | (3) | +-| DBRM options |-------------------------------------------------------+ +- -bindOptions-- -"--bind-options--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--+--------------------------+--+-----------------------+----->< '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Trace options |-----' +-RS-+ '-UR-'
You can use this command to specify the name of the interfaces or implementation classes and to specify the options for creating a DB2 package or DBRM file.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> (2) >-------- -url--jdbc--:--db2--:--//--server--+---------+--/--database--> '-:--port-' >-- -username--user-ID-- -password--password--------------------> >--+------------------------------------------------------------------------+--> | (3) | +-| DBRM options |-------------------------------------------------------+ +- -bindOptions-- -"--bind-options--"--+-------------------------------+-+ | '- -verifyPackages--+-DETAIL--+-' | | '-SUMMARY-' | '- -verifyPackages--+-DETAIL--+------------------------------------------' '-SUMMARY-' >--+-----------------------------+--+----------------+----------> | .-FALSE-. | | (4) | '- -differenceOnly--+-TRUE--+-' '-| -grant |-----' >--+--------------------------+--+-----------------------+------> '- -isolationLevel--+-CS-+-' | (5) | +-RR-+ '-| Trace options |-----' +-RS-+ '-UR-' .------------------------. V | >-- -interface----Java-package.interface-+---------------------><
You can use the command and an options file to specify the names of interfaces and to specify the options for creating DB2 packages or DBRM files that are based on each of those interfaces.
(1) >>-java--com.ibm.pdq.tools.StaticBinder-------------------------> >--+---------------------------------------------------------------------------------------------------------+--> '- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+-----------------------------------------------+------------> | .------------------------------. | | V | | '- -interface----Java-package.interface.class-+-' >-- -optionsFile--file-name--+-----------------------+----------> | (2) | '-| Trace options |-----' >--+-------------------------------+--------------------------->< '- -verifyPackages--+-DETAIL--+-' '-SUMMARY-'
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--=--------------------------------------------> >--+---------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+---------------------------------------------+--------------> '-+-----------------------------------------+-' '-+- -bindOptions-- -"--bind-options--"-+-' | (3) | '-| DBRM options |--------------------' >--+----------------+--+--------------------------+-------------> | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-' >--+-----------------------+----------------------------------->< | (5) | '-| Trace options |-----'
This syntax diagram shows the options that you can set for each interface that you list in an options file.
(1) >>-Java-package.interface--=------------------------------------> >--+---------------------------------------------------------------------------------------------------------------+--> | (2) | '------- -url--jdbc--:--db2--:--//--server--+---------+--/--database-- -username--user-ID-- -password--password-' '-:--port-' >--+---------------------------------------------+--------------> '-+-----------------------------------------+-' '-+- -bindOptions-- -"--bind-options--"-+-' | (3) | '-| DBRM options |--------------------' >--+----------------+--+--------------------------+------------>< | (4) | '- -isolationLevel--+-CS-+-' '-| -grant |-----' +-RR-+ +-RS-+ '-UR-'
Use the bind() method of the com.ibm.pdq.tools.StaticBinder class to bind your application's SQL statements into DB2 packages at run time. The method returns a value of FALSE if the bind operation fails, and a value of TRUE if the bind operation runs successfully.
The method takes two parameters. The first is a String array for passing arguments to the StaticBinder utility. The second is a PrintWriter object that the StaticBinder utility can print messages and exceptions to.
Here is an example of a call to the bind() method:
StaticBinder binder = new StaticBinder (); PrintWriter out = new PrintWriter( new FileWriter("BinderOutput.txt")); String[] argsArray = {"-user","username","-password","password", "-url","JDBC-URL","-interface","interface-class"}; Boolean check=binder.bind(argsArray, out);
The syntax of the string is "option_1 value_1 option_2 value_2".
After the StaticBinder utility generates the DBRM files, you must copy the files to a data set. The default DBRM data set name is prefix.DBRMLIB.DATA, where prefix is the high-level qualifier that is specified in the TSO profile for the user. prefix is usually your user ID in TSO.
If the DBRM data set does not already exist, you must create it. The DBRM data set requires space to hold all the SQL statements, with additional space for each host variable name and some header information. The header information requires approximately two records for each DBRM, 20 bytes for each SQL record, and 6 bytes for each host variable. For an exact format of the DBRM, see the DBRM mapping macro, DSNXDBRM in library prefix.SDSNMACS.
The following syntax diagram describes the options for generating DBRM files.
>>- -generateDBRM--+-TRUE--+-- -outputDBRMPath--path----------->< '-FALSE-'
The root name of the generated DBRM files is the root package name that you specify when you run the Generator utility. If this name is longer than seven characters, the StaticBinder utility throws an exception.
For example, suppose that you run the StaticBinder utility on a pureQueryXML file named capture.pdqxml. The utility creates the packages MYPKGA, MYPKGB, and MYPKGC. You then modify the statement set MYPKGA in capture.pdqxml and run the Configure utility on this file, with the -cleanConfigure option at its default value of FALSE. The Configure utility assigns a new consistency token to the statement set because the set has changed. When you run the StaticBinder utility on capture.pdqxml again to bind the new version of MYPKGA, you specify -differenceOnly TRUE. The utility rebinds only MYPKGA and does not rebind the other two packages.
.-,--------------------. V | >>- -grant-- "--grantees--(----+-authorization-ID-+-+--) - "--->< '-PUBLIC-----------'
For DB2 Database for Linux, UNIX, and Windows: You can use the USER, GROUP, and ROLE keywords. For information about these keywords, see GRANT (Package Privileges) statement.
For DB2 for z/OS: You can use the ROLE keyword. For information about this keyword, see GRANT (package privileges).
Restrictions:
If the options file does not contain entries for the interfaces, the StaticBinder utility uses the bind options that are on the command line and in the defaultOptions entry in the options file.
The isolation level applies to all of the SQL statements that are in the package. If you set an isolation level through the Connection.setTransactionIsolation() method of the IBM® Data Server Driver for JDBC and SQLJ, pureQuery ignores that isolation level for statements executed statically.
>>-+------------------------+--+---------------------------+--->< '- -traceFile--file-name-' | .-OFF-----. | '- -traceLevel--+-ALL-----+-' +-SEVERE--+ +-WARNING-+ +-INFO----+ +-CONFIG--+ +-FINE----+ +-FINER---+ '-FINEST--'
For example, suppose that you ran the Generator utility on an interface named OrdersData that declares methods for querying and updating the table ORDERS. The Generator utility creates the implementation class OrdersDataImpl.
When you ran the utility, you supplied values for the -collection, -pkgVersion, and -rootPkgName options, and the utility stored these values in the implementation class. You run the StaticBinder utility, specifying the name of this class, and the utility creates DB2 packages.
At a later time, you want to see a list of the packages that the StaticBinder utility created from the implementation class. When you run the utility, you can use the -verifyPackages option, specifying the value DETAIL, and again supply the name of the class.
If the values for the -collection, -pkgVersion, and -rootPkgName options are the same as when you ran the StaticBinder utility the previous time, the utility finds the packages and lists them.
However, if you ran the Generator utility on the OrdersData interface after you first ran the StaticBinder utility and you changed any of the values for -collection, -pkgName, and -rootPkgName, the StaticBinder utility would not find any packages that matched the new values of these options. In its report, the StaticBinder utility would say that the packages that you were looking for do not exist.
The -verifyPackages option works on the premise that, after you generated the implementation class and ran the StaticBinder utility on that class or its associated interface, you did not run the Generator utility again on the interface and supply different values for -collection, -pkgVersion, and -rootPkgName.
You can specify this option together with the -bindOptions option. However, the StaticBinder utility will not bind packages. Use -bindOptions only to specify the collection for the packages that you want to verify if you used this option to specify the collection when you created the packages.