You set pureQuery Runtime properties
to control the operation of pureQuery Runtime. You can control the
scope of pureQuery Runtime properties by setting the property in a
specific WebSphere® location.
If
you set a property in multiple locations, pureQuery Runtime determines
which value to use by an order of precedence that is based on the
location.
WebSphere uses
the location to determine the scope of the property and to determine
the order of precedence if a property is specified in multiple locations.
The levels of scope for WebSphere are
in the following the order of precedence:
- Application level: The pureQuery properties apply to the WebSphere application. The
pureQuery Runtime property settings at the application level override
both the global level and the data-source level settings for the same
property. Otherwise, the pureQuery Runtime properties are merged with
the global pureQuery properties and data-source level pureQuery properties.
- Data source level: The pureQuery properties apply to all
connections that are created from the data source. The data-source
level property settings override the global level property settings
if the same property is defined at both levels. Otherwise, the pureQuery
Runtime properties are merged with the global-level pureQuery properties.
- Global level: The pureQuery properties apply to all applications
in the WebSphere Application
Server.
You can use the pureQuery Runtime property finalRepositoryProperties to
retrieve runtime properties from a file system or a repository in
a database. Retrieving properties from a file system or a repository
affects the order of precedence.
- Specifying a file system or a repository
Before pureQuery Runtime properties retrieves and sets from
the location that is specified by the finalRepositoryProperties property,
pureQuery client optimization and existing pureQuery Runtime properties
are reset to default values. Any property that is set at the data
source level is not saved. Properties that are retrieved and set as
global pureQuery properties are not affected.
The following examples show how pureQuery Runtime
property settings are determined:
- If a property is set at multiple levels, the level determines
which value is used. For example, if the value of captureMode is
set to OFF in the pdq.properties global properties file, the value
is set to ON, NEW_STMTS, or LITE in the data source-level pdqProperties
for the data source that are used by the application, and set to OFF
in application level pdq.appwide.properties, then the application
level setting prevails and value of the captureMode property
is set to OFF .
- If pureQuery Runtime properties are retrieved from a file system
or a repository with the finalRepositoryProperties property,
the value of the captureMode property that is specified
in the location prevails irrespective of the property setting at the
global, data source, or application levels. For example, if captureMode is
set to ON, NEW_STMTS, or LITE in data-source level pdqProperties for
the data source that is used by the application and the finalRepositoryProperties
property is also set, pureQuery Runtime retrieves the properties from
the location that is specified by the finalRepositoryProperties property.
If the captureMode property is not set in the retrieved
properties, the captureMode property is set to the
default, OFF. If the value of the captureMode property
is set as a retrieved property, that value is used.
Control the scope of pureQuery Runtime properties
in a WebSphere environment
In
a WebSphere environment,
you set the pureQuery Runtime properties in different locations to
control the level of scope of the properties. The location also affects
the order of precedence when a property is set in multiple locations.
- Location for global scope
- Specify the pureQuery Runtime properties in a properties file
pdq.properties and include the file in the WebSphere JDBC provider class path.
When
using the pdq.properties file to set global properties, place the
directory containing the file pdq.properties in the JDBC provider class
path that contains the pureQuery JAR files. The properties that are
set in the JDBC provider class path apply to all the applications
that use the driver. Do not specify properties that apply to a specific
application or data source here.
The pureQuery Runtime property traceFile can
be specified only in a global pdq.properties file.
Set global
pureQuery Runtime properties from the WebSphere Application Server
Admin Console:
- Select the link JDBC Providers.
- For JDBC Provider, select either DB2 Universal JDBC
Driver Provider or DB2 Universal JDBC Driver
Provider (XA).
- If necessary, add the directory that contains the pureQuery JAR
files to the field Class path.
Note: Do not
include the file name pdq.properties.
- Apply the changes to the selected JDBC Provider and save the changes.
- It might be necessary to change the field Class path for
both JDBC providersDB2 Universal JDBC Driver Provider and DB2
Universal JDBC Driver Provider (XA)
- Place your pdq.properties file in the directory that you specified
in the field Class path.
When the pdq.properties
is in the directory, both the WebSphere Application
Server and pureQuery Runtime find the properties file.
- Depending on your application environment, you must restart either
the application server or the WebSphere Application
Server, or both servers for the changes to take effect.
Note: While you modify the pdq.properties file to move from
executing SQL statements from dynamic to static mode, an application
server restart is needed to reflect the changes. Because the properties
are applied to all the data sources that uses the particular JDBC
provider, all applications run with the same execution mode, and all
captured SQL statements go to the same pureQueryXML file during capture.
- Location for data-source-level scope
Specify the JDBC Driver custom property pdqProperties on
the WebSphere data source.
Users
can set the pureQuery Runtime properties for each data source. The
data source level is appropriate when the setting for each data source
needs to be independent from each other. For example, if the application
uses multiple distinct data sources, each data source captures the
SQL that is targeted for it in its own pureQueryXML file.
When
the properties are set on the data source, they are applied to all
the applications that are using that data source. So when applications
share a data source, the captured SQL statements are captured in a
common file for all applications.
Each time changes are made
to the value of the a data source's pdqProperties property, the application
server needs to be restarted so that the application server can use
the new values.
- Location for application-level scope
Enable pureQuery
Runtime properties at the application-level scope by using one or
both of the following property files in the application CLASSPATH:
The pdq.appwide.properties file specifies the application-specific
pureQuery properties. All property values that are specified in this
file will be applied to all the data sources that the application
uses.
The pdq.DSName.properties file specifies
the data-source-specific properties for an application. The properties
specified in this file will be applied only to the specific data source
that the application uses. The DSName is the string
value of WebSphere custom
property dataSourceName for the data source.
This custom property is set using steps similar to the steps used
to set the WebSphere custom
property pdqProperties.
For applications
that use the data source name DSName, the properties
specified in pdq.DSName.properties have precedence
over those specified by pdq.appwide.properties.
You can create
a JAR file containing the pureQuery Runtime properties files and place
the JAR file directly under the installed application directory in
a WebSphere installation.
Then you update the MANIFEST.MF file of all modules that use the pureQuery
Runtime properties.
If an application
uses application-specific properties files, such as pdq.appwide.properties
or pdq.dsName.properties files, to make the new
properties take affect when properties are changed, you must purge
the WebSphere connection
pool and restart the application instead of restarting the application
server to make new property values to take effect.
In the following
example the pureQuery Runtime properties are in pdq.appwide.properties
and the dynamic web project (.war file) is part of an .ear file. After
deploying the application in a WebSphere environment,
the installedApps directory contains the MyAppEAR.ear directory. The
following steps describe how how enable pureQuery Runtime properties
at the application level:
- Create a JAR file that contains pdq.appwide.properties. In this
example, the file is pdq_props.jar.
- Place pdq_props.jar in the following folder:
WAS_ROOT/profiles/AppSrv01/installedApps/version1/MyAppEAR.ear
- Edit the MANIFEST.MF file of all modules that use the pureQuery
Runtime properties. In this example, the war file MyApp.war uses the
properties and the MANIFEST.MF is in the following directory:
WAS_ROOT/profiles/AppSrv01/installedApps/version1/MyAppEAR.ear/MyAppEAR.war/META-INF/MANIFEST.MF
Add
the following Class-Path entry for the pdq_props.jar
file:
Class-Path: pdq_props.jar
The entry
is on a single line in the MANIFEST.MF file and there is a space between
the property and file name.
If modules in a application use different data sources,
you can specify pureQuery Runtime properties for each data source.
This example assumes that a custom JCC property dataSourceName is
set on the DataSource. Also in this example, two different data sources
with data source names DS1 and DS2 exist in the WebSphere Application Server environment.
In the example, an application consists of two modules:
- Web module Web1 that uses data source DS1
- EJB module EJB1 that uses data source DS2
You create two pureQuery Runtime property files for each data
source.
- pdq.DS1.properties
- pdq.DS2.properties
You create a JAR file that contains the two files pureQuery
Runtime files and place it under the installed application directory
as describe previously.
- Location is a file system or a repository
You specify a file system or a repository in a database with
the pureQuery Runtime property finalRepositoryProperties.
The property can be specified in the global level, data source level,
or at the application level.
pureQuery Runtime applies the
following rules when it retrieves properties from a location that
is specified by the
finalRepositoryProperties property:
The pureQuery Runtime repositoryRequired property
controls the behavior of pureQuery Runtime when using file system
or a repository. You specify the property in a WebSphere location pureQuery to control
the pureQuery Runtime behavior. The value of the repositoryRequired property
can be overridden by setting the repositoryRequired property
as one of the retrieved properties.