The process of capturing SQL statements
involves two steps: setting the values of certain properties and then
running your application.
In the capture process, you run your
application after first setting the property captureMode to
ON. pureQuery creates a file that lists the SQL statements, as well
as stack traces. The file is called a pureQueryXML file and you can
specify its extension as either .pdqxml or .xml.
When
you run your non-pureQuery API application with captureMode set
to ON, you must run successfully all logic paths that contain the
SQL statements that you want to run statically. pureQuery captures
SQL statements only when they are run successfully.
General
considerations
- The Connection.prepareStatement() method does not cause SQL statements
to be captured.
- It might be the case that your application does not function correctly
when it works with pureQuery to run SQL statically. Use the pureQuery
Log utility when you are capturing SQL. The messages that this utility
logs can help you determine the level of your application's compatibility
with static SQL. For a description of some of the situations that
might render your application incompatible with static SQL, see Situations or coding practices that might cause problems when your non-pureQuery API application runs SQL statements statically.
- Capturing the SQL statements that pureQuery annotated methods
call so that your application can run those statements statically
is not recommended. Doing so can result in suboptimal performance,
and certain features, such as heterogeneous batching, can result in
SQL errors.
- pureQuery Runtime does not support running compound statements
statically, except compound statements that start BEGIN ATOMIC.
When you capture compound statements, pureQuery sets the isBindable attribute
for each of these statements to false in the pureQueryXML
file. This attribute tells the StaticBinder utility whether to bind
a statement.
You can set isBindable to true for BEGIN
ATOMIC compound statements. If the StaticBinder utility
cannot bind the statement, it logs an error.
- pureQuery Runtime does not support capturing SQL statements that
contain hexadecimal characters that might map to certain XML control
characters. These characters are in the range of 0x32 (hexadecimal)
and below.
The occurrence of these characters is rare in SQL. The
characters might occur when using string literal values generated
from a non-traditional source. While these characters can be captured,
you might encounter errors during subsequent processing of the capture
file. If the use of such literal values in the SQL is unavoidable,
you can use the sqlLiteralSubstitution property to
avoid errors that might occur during processing of the capture file.
The sqlLiteralSubstitution property directs pureQuery
Runtime to replace all literals with parameters in the captured SQL.
- When capturing SQL statements running against DB2® databases, the capture process logs changes
to DB2 special registers. Changes
to special registers that are commonly used and that might affect
data returned by the SQL statement are also captured in the pureQueryXML
files.