Specifies the pureQuery client optimization behavior if
errors occur during retrieving or writing pureQuery data. If the pureQuery
runtime properties and pureQueryXML data cannot be retrieved from
the location specified by the finalRepositoryProperties property,
or if the repository that stores captured SQL is not accessible.
For Java™ application
with pureQuery client optimization, this property is recognized only
if the finalRepositoryProperties property is also
specified, otherwise it is ignored. The finalRepositoryProperties property
is not supported for CLI applications enabled with pureQuery client
optimization.
This property can take these values:
- atStartup
- Specifies that the location specified by finalRepositoryProperties property
is required at application startup. If the pureQuery properties are
not available or read errors are detected an exception is thrown.
- forOutput
- Specifies that writing the first captured SQL data to the repository
must be successful. If the repository is not available or write errors
are detected an exception is thrown. If the repository becomes unavailable
after application startup, an error is logged if logging is enabled.
The application continues and writing the captured SQL is tried at
the next scheduled time.
The value is not supported for CLI applications
enabled with pureQuery client optimization.
- atStartupAndForOutput
- Specifies that both the atStartup and forOutput values
are enabled.
The value is not supported for CLI applications enabled
with pureQuery client optimization.
- no
- Specifies the default behavior if the location specified by the finalRepositoryProperties property
is not available at application startup. The following list describes
the default behavior:
- The application runs with the default pureQuery client optimization
and pureQuery runtime configuration. The application runs dynamic
SQL.
- If logging is enabled, a message is logged indicating the problem
with the repository.
- If a timer thread can be created, an attempt is made to retrieve
the pureQuery runtime properties and pureQueryXML data every 10 minutes.
If the information is retrieved, pureQuery client optimization uses
the retrieved pureQuery runtime properties and pureQueryXML data.
- If pureQuery client optimization is configured to store captured
SQL data in a repository, and the repository is not available, or
a write error is detected, a message is logged indicating the problem
with the repository. Writing of the captured SQL data to the repository
is attempted at the next scheduled time.
Usage notes
The following list contains
information about using the repositoryRequired property:
- To override the default pureQuery client optimization behavior,
specify the repositoryRequired property as part of
the application startup pureQuery properties.
- If the repositoryRequired property is specified
as a property that is retrieved from a repository, the property value
replaces the current property value.
- If the application is required to run static SQL or with SQL replacement,
specify either the atStartup or the atStartupAndForOutput property
value.
- Assuming the following environment:
- The repository that contains the pureQuery runtime properties
and pureQueryXML, and, if required, the repository that stores captured
SQL data, are available at application startup.
- The pureQuery properties and pureQueryXML data are retrieved and
processed successfully.
- The propertiesRefreshInterval property is enabled,
and is set with value greater than zero.
The following list describes the interaction between the propertiesRefreshInterval property
and the repositoryRequired property:
- If during a refresh, the location storing the pureQuery properties
and pureQueryXML data is not available, an error is logged, and the
application runs with the pureQuery properties and pureQueryXML that
were successfully retrieved at startup. At each refresh interval,
pureQuery client optimization attempts to retrieve the pureQuery data.
- If during a refresh, updates are detected to the pureQuery properties
or the pureQueryXML data in the storage location, the updated data
is retrieved. If an errors occur during retrieval, an error is logged
and the data is ignored. An attempt is made to retrieve the pureQuery
data during the next refresh.
- If during a refresh, updated pureQuery data was retrieved but
the properties are invalid or the pureQueryXML is malformed, an error
is logged, and the retrieved data is ignored. An attempt is made to
retrieve the pureQuery data during the next refresh.
- If the value of the cmx.controllerDiscoveryInterval property
is set to -2 in the following environments, timer thread creation
is prohibited and the propertiesRefreshInterval property
is ignored:
- DB2® z/OS® Java Stored
procedure
- CICS®
The value of the property is set to -2 to disable automatic
discovery for Performance Expert Extended Insight.
In these
environments, the application runs using dynamic SQL. If client optimization
is configured to capture SQL data and the captured SQL data cannot
be written, an error is logged and an attempt to write the captured
SQL is made later.
DB2 CLI and IBM Data Server Driver usage notes
When using DB2 Call Level Interface (CLI) or
the IBM® Data Server Driver with
pureQuery Runtime, you can use the pureQuery Runtime property as a
configuration keyword.
- IBM CLI keyword syntax
- repositoryRequired = atStartup | no
- IBM Data Server Driver configuration
syntax
- <parameter name="repositoryRequired" value="atStartup | no"
/>
- Equivalent IBM Data Server
Provider for .NET connection string keyword
- repositoryRequired=atStartup | no
DB2 CLI and
.NET usage notes
The following usage information applies
when the
pureQueryXmlRepository keyword is specified
with CLI or .NET applications enabled with pureQuery client optimization:
- For applications, only the pureQueryXML file data is retrieved
from the repository. The pureQuery Runtime settings are not retrieved
from the repository. The pureQuery Runtime settings specified in the
configuration file are used.
- repositoryRequired supports only the values atStartup and no.
- When you specify the repositoryRequired keyword,
the keywords pureQueryXmlRepository and propertiesGroupId must
also be specified.
- When the value of repositoryRequired is set to no and
the repository location specified by the pureQueryXmlRepository keyword
is not available at startup, the SQL statements are run dynamically
with default pureQuery Runtime settings. All the pureQuery Runtime
keyword values except for the sqlLiteralSubstitution keyword
are set to their default values. The value of sqlLiteralSubstitution set
in the configuration file is retained.
- The SQL error CLI00202E is returned when retrieving the pureQueryXml
capture file from the repository fails.