PQ69991: SQLCODE -126 WHEN EXECUTING A CUSTOM FINDER METHOD FROM A CMP CMP BEAN.

APAR status
Closed as documentation error.

Error description
A SQLCODE -126 occurs in the server region for the application
server when executing a custom finder method from a cmp bean.
Some applications build custom finders that have SQL which
includes "FOR UPDATE","ORDER BY", and "DISTINCT".  The
environment entry (following property is one line):
com.ibm.websphere.persistence.bean.managed.custom.finder.access.
intent
set to Boolean=true in the beans standard deployment
descriptor (ejb-jar.xml).  This can be modified in WSAD or AAT.
Another option would be to set the environment variable
com.ibm.websphere.persistence.bean.managed.custom.finder.access.
intent=1 in jvm.properties for the appication server.  Setting
the environment variable in jvm.properties will take affect for
all beans in that server.
Local fix Problem summary
****************************************************************
* USERS AFFECTED: All users of WebSphere Application Server    *
*                 V4.0.1 for z/OS and OS/390                   *
****************************************************************
* PROBLEM DESCRIPTION: Text in the WebSphere for z/OS book     *
*                      Assembling J2EE Applications should be  *
*                      updated to correctly configure the      *
*                      access intent of beans that use         *
*                      container-managed persistence           *
*                      (CMP beans). Without correct            *
*                      configuration, CMP beans using custom   *
*                      finders will encounter SQLCODE -126     *
*                      errors.                                 *
****************************************************************
* RECOMMENDATION:                                              *
****************************************************************
A SQLCODE -126 occurs in the server region for the application
server when executing a custom finder method from a CMP bean.
This error occurs when the following conditions are true:
- The custom finder uses SQL SELECT with the "FOR UPDATE"
  clause or the "ORDER BY" or "DISTINCT" keywords, and
- The following environment entry or JVM property is not set
  correctly:
    com.ibm.websphere.persistence.bean.managed.custom.finder.
      access.intent
  (the property is one line)
Problem conclusion
APAR PQ69991 requires changes to documentation.

To access the latest online documentation, go to the product
library page at:

www.ibm.com/software/webservers/appserv/zos_os390/

WebSphere Application Server V4.0.1 for z/OS and OS/390
Assembling J2EE Applications (SA22-7836-05)
will be changed as follows:

"Chapter 4. A closer look at the J2EE server"
Topic "Controlling concurrent access to persistent data"
"Checklist for using pessimistic concurrency control"
  on page 57 will be updated with the following rule, at the
  end of the checklist item about verifying access intent:

  Rule: Some applications use custom finders that contain
  the FOR UPDATE clause, or keywords ORDER BY and DISTINCT,
  on the SELECT operation. In these cases, you must use one
  of the following settings to avoid encountering an SQL
  error (SQLCODE -126) when the J2EE server attempts to run
  the CMP bean:
  - Specify the ReadOnly setting on the method level;
  - Specify env-entry "com.ibm.websphere.persistence.bean.
    managed.custom.finder.access.intent" as true in the bean's
    standard deployment descriptor (ejb-jar.xml); or
  - Specify the property "com.ibm.websphere.persistence.
    bean.managed.custom.finder.access.intent=1" in the JVM
    properties file for the J2EE server. Using this property
    in the J2EE server's JVM property file sets the same access
    intent for all CMP beans that run in the server.
    For additional information about this JVM property, see
    "JVM properties and properties files".

"Chapter 6. Creating new application components to be
  installed in a J2EE server"
Topic "Developing Enterprise beans"
"Guidelines" on page 107 will be updated with the
  following additional item:

  If you supply a custom finder for a bean that uses
  container-managed persistence (CMP bean), check the
  SQL SELECT statement in the custom finder. If the
  SELECT statement contains the FOR UPDATE clause, or the
  keyword ORDER BY or DISTINCT, you must use one of the
  following settings to avoid encountering an SQL error
  (SQLCODE -126) when the J2EE server attempts to run the
  CMP bean:
  - Specify the ReadOnly setting on the method level, through
    the appropriate application development or assembly tool;
  - Specify env-entry "com.ibm.websphere.persistence.bean.
    managed.custom.finder.access.intent" as true in the bean's
    standard deployment descriptor (ejb-jar.xml); or
  - Specify the property "com.ibm.websphere.persistence.
    bean.managed.custom.finder.access.intent=1" in the JVM
    properties file for the J2EE server. Using this property
    in the J2EE server's JVM property file sets the same access
    intent for all CMP beans that run in the server.

  For additional information, see:
  - "Isolating transactions that access persistent data" and
    "Controlling concurrent access to persistent data" for IBM
    extensions related to access intent for CMP beans.
  - "JVM properties and properties files" for the "com.ibm.
    websphere.persistence.bean.managed.custom.finder.access.
    intent" property.

"Appendix A. Environment and JVM properties files"
Topic "JVM properties and properties files"
"Table 24. Where to use JVM properties" will be updated with
   the new entry for property "com.ibm.websphere.persistence.
   bean.managed.custom.finder.access.intent=0" which is
   optional for only J2EE servers.

"Appendix A. Environment and JVM properties files"
Topic "Properties descriptions" on page 303 will be updated
  with the following new property description:

  com.ibm.websphere.persistence.bean.managed.custom.
  finder.access.intent=value
    Specifies the access intent of custom-finder methods for
    a bean that uses container-managed persistence (CMP bean).
    The values you may specify are 0 (update access intent)
    or 1 (read-only access intent). Using this property in the
    J2EE server's JVM property file sets the access intent for
    all CMP beans that run in the server.

    Rule: Some applications use custom finders that contain
    the ORDER BY or DISTINCT keyword on the SELECT operation.
    In such cases, specify the value 1 to avoid encountering
    an SQL error when the J2EE server attempts to run the CMP
    bean. If you do not want this setting used for all CMP
    beans that run in the J2EE server, see the "Verify access
    intent" item in "Checklist for using pessimistic
    concurrency control" for alternative choices.

    Note: Using a setting of 1 (read-only access intent) does
    not prevent the custom finder from making updates, should
    any be necessary during the course of its processing.

    Default: 0 (update access intent)
Temporary fix Comments
APAR information
APAR number PQ69991
Reported component name WASKBASE
Reported component ID 5655A9801
Reported release 401
Status CLOSED DOC
PE NoPE
HIPER NoHIPER
Submitted date 2003-01-17
Closed date 2003-02-26
Last modified date 2003-02-26

APAR is sysrouted FROM one or more of the following:

APAR is sysrouted TO one or more of the following:

Modules/Macros

Fix information

Applicable component levels


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server for z/OS
Operating system(s):
Software version: 401
Software edition:
Reference #: PQ69991
IBM Group: Software Group
Modified date: Feb 26, 2003