Fix (APAR): PQ70655 Status: Fix Release: 5.0.0 Operating System: All Supersedes Fixes: None CMVC Defect: PQ70655 Byte size of APAR: 1186623 Date: 2003-02-24 Abstract: Mandatory Compensation Fix to correct limitation when using Workflow with Compensation Description/symptom of problem: There is currently a limitation when you use workflow and compensation in a run-time environment that has one of the following symptoms: * If you are using Oracle 8i, or Oracle 9i with the thin driver, compensation does not work. The following exception message is shown: com.ibm.ws.ejbpersistence.utilpm.PersistenceManagerException: PMGR6022E: Error using adapter to create or execute an Interaction. com.ibm.ws.rsadapter.cci.WSInteractionImpl@6052cabd This is caused by an SQL exception as indicated in a message similar to the following: java.sql.SQLException: Data size bigger than max size for this type: 6601 * If you use any other database, or Oracle 9i with the OCI driver, there is a limit to the number of compensatable steps that you can execute in a workflow. This limitation is dependent upon configuration settings and the amount of information associated with the compensation steps in the workflow. Due to space limitations, a database or Java Virtual Machine (JVM) exception is thrown when 300 to 700 compensation steps are executed. The exception message is similar to the following: com.ibm.ws.ejbpersistence.utilpm.PersistenceManagerException: PMGR6022E: Error using adapter to create or execute an Interaction.com.ibm.ws.rsadapter.cci.WSInteractionImpl@221e1719 This is caused by a database exception as indicated in a message similar to the following using DB2 in this example): COM.ibm.db2.jdbc.DB2Exception: [IBM][CLI Driver][DB2/NT] SQL0973N Not enough storage is available in the "QUERY_HEAP" heap to process the statement. SQLSTATE=57011 This limitation also applies to workflows that contain compensation steps within loops. An exception is thrown once the loop has iterated 300 to 700 times. Directions to apply fix: The following instructions install two mandatory APAR fixes, PQ70655 and PQ71037. These fixes correct a limitation in Process Choreographer associated with workflows using compensation. THESE APAR FIXES ARE MANDATORY AND MUST BE INSTALLED IMMEDIATELY FOLLOWING THE INSTALLATION OF WEBSPHERE APPLICATION SERVER VERSION 5 ENTERPRISE EDITION. NOTE: YOU MUST FIRST DOWNLOAD THE FIX INSTALLER TOOL IN ORDER TO INSTALL A FIX. This is available at ftp://ftp.software.ibm.com/software/websphere/appserv/support/tools/eFixInstaller/WAS5.0/ Unzip the downloaded file "efixInstaller.zip" and follow the README instructions to configure the Fix Installer. 1) Create a temporary "fix" directory to store JAR files associated with the fixes. For example: UNIX: /tmp/WebSphere/fix Windows: c:\temp\WebSphere\fix 2) Download the APAR fix for PQ70655 and copy the JAR file into the temporary "fix" directory created in step 1. 3) Download the APAR fix for PQ71037 and copy the JAR file into the temporary "fix" directory created in step 1. 4) Shut down the application server or cluster where you want to apply these fixes. 5) Run the Fix Installer Tool to install the fix for APAR PQ70655. 5.1) On the Menu Panel select "Install Fixes". 5.2) On the Fix Selection Panel: - specify the "fix" directory created in step 1 in the "Fix Directory" input area, - select the fix named "WAS_Compensation_02-24-2003_5.0.x_cumulative". 6) Run the Fix Installer Tool again to install the fix for APAR PQ71037. 6.1) On the Menu Panel select "Install Fixes". 6.2) On the Fix Selection Panel: - specify the "fix" directory created in step 1 in the "Fix Directory" input area, - select the fix named "WAS_Workflow_02-24-2003_5.0.x_cumulative". 7) If the Process Choreographer has not been configured yet then run the following command from the $WAS_HOME\ProcessChoreographer directory: Windows: $WAS_HOME\bin\wsadmin -conntype NONE -f bpeupgrade.jacl -user -password UNIX: $WAS_HOME/bin/wsadmin.sh -conntype NONE -f bpeupgrade.jacl -user -password Note 1: The and parameters are only required if WAS security is switched on. 8) If the Process Choreographer is configured on a stand- alone application server then: 8.1) Run the following command from the $WAS_HOME\ProcessChoreographer directory: Windows: $WAS_HOME\bin\wsadmin -conntype NONE -f bpeupgrade.jacl -server -node -user -password UNIX: $WAS_HOME/bin/wsadmin.sh -conntype NONE -f bpeupgrade.jacl -server -node -user -password Note 1: The parameter may be omitted if the server runs on the local node. The and parameters are only required if WAS security is switched on. Note 2: A standalone server may have also been created when selecting "Create sample configuration" during WebSphere Application Server V5 Enterprise Edition. Note 3: If the Process Choreographer is configured using the sample configuration, or the database configured is Cloudscape then execution of the command in this step will also perform the necessary database updates for you and step 8.2 can be skipped. If not, a message will be produced during the execution of this step indicating the name of the DDL file to use in the step 8.2. 8.2) Create the new tables used by Compensation by executing the DDL file specified in the previous step: Windows: $WAS_HOME\ProcessChoregrapher\PQ71037- UNIX: $WAS_HOME/ProcessChoregrapher/PQ71037- where dbType is the database (e.g. DB2) associated with this Process Choreographer. Note 1: This DDL file contains instructions describing how to set parameters for different database configurations. Use these instructions to update the DDL file before executing it. Note 2: This step can be skipped if Either the Process Choreographer is configured using the sample configuration, Or the Process Choreographer is configured using the Cloudscape database. 9) If the Process Choreographer is configured in a cluster then: 9.1) Run the following command from the $WAS_HOME\ProcessChoreographer directory: Windows: $WAS_HOME\bin\wsadmin -conntype NONE -f bpeupgrade.jacl -cluster -user -password UNIX: $WAS_HOME/bin/wsadmin.sh -conntype NONE -f bpeupgrade.jacl -cluster -user -password Note 1: The and parameters are only required if WAS security is switched on. Note 2: A message will be produced during the execution of this step indicating the name of the DDL file to use in the next step. 9.2) Create the new tables used by Compensation by executing the following DDL file: Windows: $WAS_HOME\ProcessChoregrapher\PQ71037- UNIX: $WAS_HOME/ProcessChoregrapher/PQ71037- where dbType is the database (e.g. DB2) associated with this Process Choreographer. Note 1: This DDL file contains instructions describing how to set parameters for different database configurations. Use these instructions to update the DDL file before executing it. 10) Repeat steps 4 to 9 for all clusters and stand-alone application servers upon which the Process Choreographer is configured. 11) Remove the temporary directory created in step 1 but save the JAR files. Do not remove any files created and stored in the /WebSphere/AppServer/fix/ directories. These files are required if a fix is to be removed. 12) Start the WebSphere Application Server or cluster. Directions to remove fix: APAR fixes PQ70655 and PQ71037 are mandatory and must not be removed. However, if the fix has to be reapplied then the follow the instructions in the next section. Directions to re-apply fix: 1) Shut down the application server or cluster where you want to re-apply the fixes. 2) Run the Fix Installer Tool to uninstall the fix for APAR PQ71037. 2.1) On the Menu Panel select "Uninstall Fixes". 2.2) On the Fix Selection Panel: - select the fix named "WAS_Workflow_02-24-2003_5.0.x_cumulative". 3) Run the Fix Installer Tool to uninstall the fix for APAR PQ70655. 3.1) On the Menu Panel select "Uninstall Fixes". 3.2) On the Fix selection panel: - select the fix named "WAS_Compensation_02-24-2003_5.0.x_cumulative". 4) Start the application server or cluster where you have just uninstalled the fixes. 5) Follow the instructions in the section "Directions to apply fixes" to reinstall the APAR fixes. 6) Repeat steps 1 to 5 for all clusters and stand-alone application servers for which the fixes are to be re- applied. Additional Information: 1) The WebSphere Application Server V5 Enterprise Edition Release Notes include the section entitled: "Updating the compensation tables before configuring the WebSphere Process Choreographer on z/OS". These release notes are available at http://www-3.ibm.com/software/webservers/appserv/library/ APAR fixes PQ70655 and PQ71037 automate the steps described in this section of the release notes and these steps can therefore be ignored. 2) The WebSphere Application Server V5 Enterprise Edition Release Notes include the section entitled: "The workflow application does not start after a transaction timeout". These release notes are available at http://www-3.ibm.com/software/webservers/appserv/library/ APAR fixes PQ70655 and PQ71037 create new compensation tables. Therefore replace step 3 in this section of the release notes with the following steps: 3a. Manually update the STANDARDEXECUTOR table in the BPEDB database. Change any rows in the database whose EXECUTORSTATEFLD column is set to 4 to a value of 3. The following is an example of an SQL command used to update the STANDARDEXECUTOR table: UPDATE SCHEMA.STANDARDEXECUTOR SET EXECUTORSTATEFLD = 3 WHERE EXECUTORSTATEFLD = 4 3b. Manually update the CONTEXTUALPROCLET table in the BPEDB database. Change any rows in the database whose PROCLETSTATE column is set to 4 to a value of 2. The following is an example of an SQL command used to update the CONTEXTUALPROCLET table: UPDATE SCHEMA.CONTEXTUALPROCLET SET PROCLETSTATE = 2 WHERE PROCLETSTATE = 4 3) A new parameter has been added to patchDatabaseBackendId.jacl. When configuring for Oracle V9 only, you must specify the JDBC driver type, as follows: Windows: $WAS_HOME\wsadmin -f patchDatabaseBackendId.jacl Oracle 9 UNIX: $WAS_HOME/wsadmin.sh -f patchDatabaseBackendId.jacl Oracle 9 where has one of the following values: thin if configuring Oracle V9 to use the thin JDBC driver, oci8 if configuring Oracle V9 to use the OCI JDBC driver.