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.
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
retrieves and sets properties 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.
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 is 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 properties that are specified in the location specified
by the finalRepositoryProperties propety 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. In general, the
same rules apply to all the non-global properties except for those
properties that define the location of the final repository.
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 directory
containing 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.
You can also
set global pureQuery Runtime
properties from the administrative console for WebSphere Application Server:
- Select the link JDBC Providers.
- For JDBC Provider, select either DB2 Universal JDBC
Driver Provider or DB2 Universal JDBC Driver
Provider (XA).
- If you need to add the pureQuery JAR
files to the class path, 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 use 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 described previously.
- Specifying JNDI variables in application-level scope properties
files
WebSphere Application
Server 8 supports JNDI variables. pureQuery Runtime
Version 3.2 and later supports JNDI variables for application wide
runtime properties file when using WebSphere Application
Server Version 8.
This makes it easier to deploy pdq.appwide.properties
files by having a single generic file for all applications to be deployed
without having to embed application specific values in each file.
When
using WebSphere Version
8 or later with pureQuery Runtime
Version 3.2 and later, you can specify the variables ${appName} and
${moduleName} in pureQuery runtime
property values. The variables are supported in the pureQuery runtime properties file. For
example, you can use the variables with the runtime property pureQueryXml
to specify a pureQueryXML file.
pdq.pureQueryXml=C:\\capturedFiles\\${appName}-${moduleName}.pdqxml
- 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:
- Properties that are loaded from finalRepositoryProperties affect
only the application that is loading them.
- Properties that are loaded from finalRepositoryProperties that
are not valid for pureQuery client
optimization or pureQuery Runtime
are ignored and logged if logging is enabled. This behavior is the
same as data-source level or application-level properties.
- The value for the property finalRepositoryProperties is
ignored if it is retrieved from the location specified by the initial finalRepositoryProperties property. pureQuery Runtime does not
support multiple levels of redirection with the finalRepositoryProperties property.
- In addition to specifying the finalRepositoryProperties property,
you specify the pureQuery Runtime
property propertiesGroupId to specify the runtime
group version in a repository created in a database that the application
uses to retrieve the pureQuery data.
The
value for the propertiesGroupId property is ignored
unless it is used with a repository created in a database. When a
repository is being used, you cannot change the value of the propertiesGroupId property
within the redirected properties.
- The pureQuery Runtime
properties that are retrieved from repository in a database specified
by the finalRepositoryProperties property will be
enabled for automatic property refresh depending on the values of
the runtimeGroupActivationCheckInterval property
and the propertiesRefreshInterval property:
- The property runtimeGroupActivationCheckInterval controls
when pureQuery Runtime
checks for activated runtime group versions. The property must be
set so that it applies to all pureQuery Runtime
instances that run in a JVM.
- The property propertiesRefreshInterval can
be used to specify a specific interval to check for updates to pureQuery information for a
runtime group version. The property can also be set to disable all
checking for updated pureQuery information
for the runtime group version, including the checking that occurs
when a runtime group version is activated.
For information about the properties, see runtimeGroupActivationCheckInterval property,
and propertiesRefreshInterval 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.