MQSeries Workflow 3.2.1 - Service Pack #2 ----------------------------------------- INDEX ------------------------------------------ 1. Installation of Service Pack #2 1.1 Installation on IBM OS/2 1.2 Installation on Microsoft Windows 1.3 Installation on IBM AIX 1.4 Installation on Sun Solaris 1.5 Installation on HP-Unix 2. Important Notices 2.1 General 2.2 Java 3. Changes 3.1 Changes in Service Pack #1 3.2 Changes in Service Pack #2 ------------------------------------------ 1. Installation of Service Pack #2 =========================================== 1.1 Installation on IBM OS/2 ------------------------------------------- 1.1.1 Which files must be downloaded? The Service Pack consists of several self-extracting executables. One for each National Language version of IBM MQSeries Workflow. If you need to update a language other than U.S. English ("ENU"), both the U.S. English language version and the language version of choice must be downloaded. Following is the list of the self-extracting executables: O321ENU2.EXE - U.S. English language version including the common files of MQSeries Workflow O321CHS2.EXE - Simplified Chinese language version O321CHT2.EXE - Traditional Chinese language version O321DAN2.EXE - Danish language version O321DEU2.EXE - German language version O321ESP2.EXE - Spanish language version O321FIN2.EXE - Finnish language version O321FRA2.EXE - French language version O321HEB2.EXE - Hebrew language version O321HUN2.EXE - Hungarian language version O321ITA2.EXE - Italian language version O321JPN2.EXE - Japanese language version O321KOR2.EXE - Korean language version O321NLD2.EXE - Dutch language version O321NOR2.EXE - Norwegian language version O321PLK2.EXE - Polish language version O321PTB2.EXE - Brazilian Portuguese language version O321PTG2.EXE - Portuguese language version O321SVE2.EXE - Swedish language version O321TRK2.EXE - Turkish language version 1.1.2 Unpack the files Copy the O321ENU2.EXE to a temporary directory and invoke it using the command: O321ENU2 /D This command unpacks all common files and the U.S. English files. If you need to update a language other than U.S. English ("ENU"), you must copy the file you additionally downloaded to the temporary directory and invoke it using the command: O321xxx2 /D where 'xxx' is the language abbreviation. 1.1.3 Update your existing MQSeries Workflow installation To install this Service Pack, use the Install & Maintain icon in your MQSeries Workflow folder. Note: First stop any running MQSeries Workflow programs. 1. Double-click on the MQSeries Workflow Install & Maintain icon 2. Select FILE from the menu bar. 3. From FILE select OPEN CATALOG. 4. Select DRIVE. 5. From the Drive list box, select the drive that contains the Service Pack. 6. Use the SEARCH button to search for the catalog file FMCZIxxx.ICF of the Service Pack. It is located in the subdirectory 'xxx' of the directory into which you unpacked the downloaded executable. Note: 'xxx' is the language used also with the downloaded executable. 7. Press OPEN. 8. Select ACTION from the menu bar. 9. From ACTION, select UPDATE. 10. Select the UPDATE button. 11. Select if YES for Rollback or NO for No-Rollback Reboot the system to activate the changes done of the Service Pack installation. 1.1.4 Upgrading your existing MQSeries Workflow Configuration Note: If you have already installed Service Pack #1, step 1 is not required! 1. To be able to use the product after upgrading the files, certain new queue definitions have to be made to MQSeries. To do this, run fmczq321.EXE. This executable will read your configuration profiles and identify the configurations that need to be updated. For these configurations the definitions in the MQSeries definition files will be recreated from the new templates shipped and will be executed to make the data available to the queue manager. Existing queue definitions will be overwritten and additional queues and aliases will be defined. 2. Because updates of DB2 bind files are included in this package, you must bind the new files to your MQSeries Workflow Runtime databases. For each configuration on your system, invoke fmczrdb -y -o:b to create the bindings. This may take several minutes. 1.2 Installing the Service Pack on Windows NT, Windows 95 and Windows 98 ------------------------------------------------------------------------ 1.2.1 Which files must be downloaded? The Service Pack consists of several self-extracting executables. One for each National Language version of IBM MQSeries Workflow. If you need to update a language other than U.S. English ("ENU"), both the U.S. English language version and the language dependent version must be downloaded. Following is the list of the self-extracting executables: W321ENU2.EXE - U.S. English language version including the common files of MQSeries Workflow W321CHS2.EXE - Simplified Chinese language version W321CHT2.EXE - Traditional Chinese language version W321DAN2.EXE - Danish language version W321DEU2.EXE - German language version W321ESP2.EXE - Spanish language version W321FIN2.EXE - Finnish language version W321FRA2.EXE - French language version W321HEB2.EXE - Hebrew language version W321HUN2.EXE - Hungarian language version W321ITA2.EXE - Italian language version W321JPN2.EXE - Japanese language version W321KOR2.EXE - Korean language version W321NLD2.EXE - Dutch language version W321NOR2.EXE - Norwegian language version W321PLK2.EXE - Polish language version W321PTB2.EXE - Brazilian Portuguese language version W321PTG2.EXE - Portuguese language version W321SVE2.EXE - Swedish language version W321TRK2.EXE - Turkish language version 1.2.2 Unpack the files Copy the W321ENU2.EXE to a temporary directory and execute it using the command: W321ENU2 /D x:\path ( where x: is the drive letter This command unpacks the common files and the U.S. English files. If you need to update a language other than U.S. English ("ENU"), you must copy the file you downloaded additionally to the temporary directory and invoke it using the command: W321xxx2 /D y:\path ( where y: is the drive letter where 'xxx' is the language abbreviation. 1.2.3 Update your existing MQSeries Workflow installation To install this Service Pack, switch to the subdirectory xxx which is located in the directory into which you unpacked the downloaded file. Note: First stop any running MQSeries Workflow programs and services. To start the installation of the Service Pack, run SETUP.EXE. After having run the installation, start the MQSeries Workflow services as described in the Installation Guide. Note: If you install Service Pack #2 immediately after running the installation of MQSeries Workflow version 3.2 (General Availability version), make sure you reboot your machine between these two installation processes, whenever the system requires you to do so. Otherwise the registration of ocx and dll files will not work properly and you might experience errors in Buildtime and the Runtime client. 1.2.4 Upgrading your existing MQSeries Workflow Configuration Note: If you have already installed Service Pack #1, step 1 is not required! 1. To be able to use the product after upgrading the files, certain new queue definitions have to be made to MQSeries. To do this, run fmczq321.EXE. This executable will read your configuration profiles and identify the configurations that need to be updated. For these configurations, the definitions in the MQSeries definition files will be recreated from the new templates shipped and will be executed to make the data available to the queue manager. Existing queue definitions will be overwritten and additional queues and aliases will be defined. 2. Because updates of DB2 bind files are included in this package, you must bind the new files to your MQSeries Workflow Runtime databases. For each configuration on your system, invoke fmczrdb -y -o:b to create all bindings.This may take several minutes. 1.3 Installation on IBM AIX --------------------------- 1) First, stop all running MQSeries Workflow processes, for example by shutting down the MQSeries Workflow System using the admin utility "fmcautil". 2) As root, perform the command 'slibclean'. 3) Update your MQSeries Workflow 3.2.1.0 or 3.2.1.10 installation (with or without having hotfixes applied) using smit - "update to latest level" to level 3.2.1.20. Note: Your configuration (profiles, /home/fmc/..., /var/fmc/...) will not be modified by the installation update. 4) To be able to use the product after having upgraded the files, certain new queue definitions have to be made to MQSeries. To do this, run fmczq321 as user "fmc". This executable will read your configuration profiles and identify the configurations that need to be updated. For those configurations the definitions in the MQSeries definition files will be recreated from the new templates shipped and will be executed to make the data available to the queue manager. Existing queue definitions will be overwritten and additional queues and aliases will be defined. Note: If you have already installed Service Pack #1, this step is not required! 5) Because updates of DB2 bind files are included in this package, you must bind the new files to your MQSeries Workflow Runtime databases. As user "fmc" invoke fmczutil and choose the configuration identifier of the configuration you want to update. Then choose the 'r'untime database menu and select 'b'ind to create all bindings.This may take several minutes. After completion of these 5 steps, your system is ready to run. You can restart your queue manager, the trigger monitor, and the administration server as usual by invoking the following programs: strmqm FMCQM & runmqtrm -q FMCTRIGGER -m FMCQM & fmcamain & 1.4 Installation on SUN Solaris ------------------------------- 1) First, stop all running MQSeries Workflow processes, for example by shutting down the MQSeries Workflow System using the admin utility "fmcautil". Make sure that all MQSeries Workflow processes are stopped and no file of the product is in use. Stopping your MQSeries queue manager is described in step 3, DB2 need not be shut down. 2) This is how to update your MQSeries Workflow 3.2.1.0 or 3.2.1.10 files (with or without having hotfixes applied) to level 3.2.1.20: Issue the following command line as user "root", replace the path "/tmp/fmc-3.2.1-service_pack_2.pkg" from this example with the fully qualified path and filename of your ".pkg" file: pkgadd -d /tmp/fmc-3.2.1-service_pack_2.pkg accept the installation of this package and overwriting files of the previous package 3.2.1.0 or 3.2.1.1 Note: Your configuration(s) (profiles, /home/fmc/..., /var/fmc/...) will NOT be modified by the update. 3) To be able to use the product after upgrading the files, certain new queue definitions have to be made to MQSeries. To do this, run fmczq321 as user "fmc". This executable will read your configuration profiles and identify the configurations that need to be updated. For those configurations the definitions in the MQSeries definition files will be recreated from the new templates shipped and will be executed to make the data available to the queue manager. Existing queue definitions will be overwritten and additional queues and aliases will be defined. Note: If you have already installed Service Pack #1, this step is not required! 4) Because updated DB2 bind files are included in this package, you must bind the new files to your MQSeries Workflow Runtime databases. As user "fmc" invoke fmczutil and choose the configuration identifier of the configuration you want to update. Then choose the 'r'untime database menu and select 'b'ind to create all bindings. This may take several minutes. After completion of these 4 steps your system is ready to run. You can restart your queue manager, the trigger monitor, and the administration server as usual by invoking the following programs: strmqm FMCQM & runmqtrm -q FMCTRIGGER -m FMCQM & fmcamain & 1.5 Installation on HP-Unix --------------------------- 1) First, stop all running MQSeries Workflow processes, for example by shutting down the MQSeries Workflow System using the admin utility "fmcautil". Make sure that all MQSeries Workflow processes are stopped and no file of the product is in use. Stopping your MQSeries queue manager will be described in step 3, DB2 need not be shut down. 2) This is how to update your MQSeries Workflow 3.2.1.0 or 3.2.1.1 files (with or without having hotfixes applied) to level 3.2.1.20: use "sam" to install the new package. Use the "software" icon, and select "add software to local host". Then choose the installation from the CD and enter the fully-qualified path to the file "fmc321u2.pkg" and the file name itself. Choose "Install" from the "Actions" pulldown menu and confirm twice. After completing the installation, continue with step 3. If you do not want to use sam, you can use "swinstall" with the appropriate command line parameters that suit your needs. Note: Your configuration(s) (profiles, /home/fmc/..., /var/fmc/...) will NOT be modified by the update. 3) To be able to use the product after upgrading the files, certain new queue definitions have to be made to MQSeries. To do this, run fmczq321 as user "fmc". This executable will read your configuration profiles and identify the configurations that need to be updated. For those configurations the definitions in the MQSeries definition files will be recreated from the new templates shipped and will be executed to make the data available to the queue manager. Existing queue definitions will be overwritten and additional queues and aliases will be defined. Note: If you have already installed Service Pack #1, this step is not required! 4) Because updated DB2 bind files are included in this package, you must bind the new files to your MQSeries Workflow Runtime databases. As user "fmc" invoke fmczutil and choose the configuration identifier of the configuration you want to update. Then choose the 'r'untime database menu and select 'b'ind to create all bindings. This may take several minutes. After completion of these 4 steps, your system is ready to run. You can restart your queue manager, the trigger monitor, and the administration server as usual by invoking the following programs: strmqm FMCQM & runmqtrm -q FMCTRIGGER -m FMCQM & fmcamain & 2. Important Notices =========================================== This ServicePack applies to these APAR numbers: PQ34776, PQ34802, PQ34803,PQ34805, and PQ34806 for MQSeries Workflow 3.2.1 for OS/390 2.1 General ----------- o If the system fails to start by invoking fmcemain, shut down MQSeries Workflow. Then, run the following commands as user fmc: - endmqm -i , e.g. endmqm -i FMCQM - dltmqm , e.g. dltmqm FMCQM - fmczqqm -o:i Now you can start your MQSeries Workflow system as user fmc: strmqm , e.g. strmqm FMCQM runmqtrm -m FMCQM -q FMCTRIGGER &, assuming FMC is the qualifier being used fmcamain & o For Microsoft Windows NT, install the MQSeries 5.1 Hotfix. This fix is needed on top of the MQSeries Service Pack,which is part of this CD. The Hotfix is located on the MQSeries Workflow Service Webpage http://www6.software.ibm.com/MQSWF/Workflow.htm o Wrong description in Programming Guide WfMessageHeader instead of WfMessage In chapter 28. "The MQ Workflow message: The application data", page 186, the sample contains the following mistake. The Element WfHeader is wrong. The name of the element is WfMessageHeader as described in chapter 31, "The MQ Workflow XML message format". Format instead of MsgId In chapter 28. "The MQ Workflow message: Relevant MQSeries Message Descriptor fields", page 183, the reference to MsgId is wrong. The reference name should be: Format. o Configuring on a Windows NT server, which is not the primary domain controller During the configuration of an MQSeries Workflow 3.2.1 server, the 'fmc' user is created automatically. This user is required for MQSeries 5.1 communication. You can change the password of the user ID 'fmc' to any value you want. MQSeries and MQSeries Workflow do not use this password. The user ID 'fmc' is automatically added to the MQSeries Administration group 'mqm'. On a Windows NT server, which is not the primary domain controller, you cannot create users. If you try to create userss, an error occurs during the creation of the MQSeries Queue Manager. To avoid the error, create the user ID 'fmc' on the primary domain controller before configuring an MQSeries Workflow server. o Configurations on UNIX using different user IDs If you choose to run the server for configuration 'A' using a different user than the one you selected when setting up your MQSeries Workflow installation, you have to define that user ID as the WorkflowAdmin BEFORE configuring 'A'. You can do this using the command fmczchk -c inst:i,WorkflowAdmin, where is the user to start fmcamain. o Changing the DB2 user's password on Microsoft Windows or OS/2 If you need to change the password for the DB2 user, do the following: 1. Start 'MQSeries Workflow Configuration Utility' 2. Select the configuration 3. Select notebook page 'Runtime Database' 4. Select 'DB2 Connect parameters ...' 5. Enter User ID and Password 6. Select 'OK' 7. Select 'Done' The configuration profile is changed and the queue manager is updated to use the new password. An incorrect password results in return code 2122 from MQSeries - Participant not available and subsequently with errors in the startup phase of the administration server. o Changing the DB2 user's password on UNIX If you need to change the password for the DB2 user, do the following: 1. As user "fmc" invoke fmczutil and choose the configuration identifier of the configuration you want to update. Then, choose the 'r'untime database menu and select 'p' to change the password, enter the new password and end the fmczutil utilty. This will change the configuration profile. 2.2 Java -------- o Java Troubleshooting As a general rule of thumb: Whenever you experience problems with the Java API, turn off the JIT (Just in Time) compiler. Consult your JDK- / JRE- / Application Server- documentation for details on how to do this. o Applying Service to the Java API Beans and Java CORBA Agent component Locator policy LOC_LOCATOR -------------------------- Using the LOC_LOCATOR policy means that the Java Agent runs in the process of the application, a call level interface instead of a communication interface is used. For service updates,the new Java Agent code is installed into the directory \bin\java321x, where x is the number of the Service Pack. The directory name javaVRMS denotes Version, Release, Modification, and Service Pack Level of the code. Make sure that the CLASSPATH uses the path to the most recent level of code. Note: Whenever you use the LOC_LOCATOR policy in conjunction with servlets, for example, the MQ Workflow HTML client, you may need to update your servlet registration for the servlet engine. Locator policies COS_LOCATOR, IOR_LOCATOR, OSA_LOCATOR AND RMI_LOCATOR ---------------------------------------------------------------------- The Java API Beans and the Java CORBA Agent are based on RMI (Remote Method Invocation) and CORBA (Common Object Request Broker) technology. These technologies allow to develop distributed applications. This requires that the code on the server and on the client must match. If they do not match, the clients are NOT able to work with the server's objects. For example, if the code version on the server and on the client for the RMI protocol do NOT match, the following exception is thrown on the client: error unmarshalling return; nested exception is: java.io.InvalidClassException: ....Stub; Local class not compatible: stream classdesc serialVersionUID=5710528428249292109 local class serialVersionUID=9080421622065857355 This exception is caught by the Java API Beans code and wrapped into an FmcException with the message text "Could not locate Agent for Domain ..". Starting with MQSeries Workflow V3.2.1, a solution for this problem is available. Scenario for Windows NT: If you have a machine with the Java CORBA Agent installed, the java code (fmcojagt.jar), which represents the Java CORBA Agent, is installed in the \bin\java3210. It is assumed that various configurations exist, exploiting either RMI, OSA, IOR or COS locator policy. For each of the Agent configurations, there's a batch file to start the agent. Note that there are naming rules that apply, that is, if you have multiple agents exploiting the same locator policy, each one must have a unique name. The OSA locator policy is an exception to that rule, which means you can have two or more agents with the same name. This allows you to do an automatic workload balancing between these agents (Consult the Inprise Visibroker for Java documention for more details on that feature.) Now a Service Pack (CSD) for MQSeries workflow is made available. The Java component code of the service pack is installed into the directory \bin\java321x, where x is the number of the Service Pack. The directory name javaVRMS denotes the Version, Release, Modification and Service Pack Level of the code. To activate the new level of code, new Java CORBA Agent configurations have to be created. During the configuration, the level of code to be used must be specified. Select the most recent level. You can then migrate, which means you apply the service to one client after another. Having migrated the last one of the clients, the 'old' Agent, which is now obsolete, can be stopped and its configuration deleted. When applying service to the Java API Beans on the client, the CLASSPATH has to be adapted manually. The CLASSPATH is NOT updated automatically, because this allows you to apply the new Java API Beans code first and use it later. Note: - When you create an Agent with the new level of code, a unique name must be used. This requires your clients with the new level of code to use this new name too. This applies especially to OSA_LOCATOR, because the Visibroker Smart Agent technology selects the ORB to which the request is directed, and if there are two Agents running with different levels of code, one request will be handled successfully whereas another request may fail. - Service Packs are cumulative, which means that the latest Service Pack contains all the fixes of all previous Service Packs. Therefore, it is not necessary that you install all Service Packs in consecutive order. 3. Changes =========================================== 3.1 Problems addressed in Service Pack #1 ----------------------------------------- 1. Execution Server: Improved Memory Management Platform: independent 2. Administration Server: Improved Memory Management Platform: independent 3. Runtime Client: Improved Memory Management Platform: WinNT, Win95, Win98 4. Buildtime: Whenever you specify square brackets [] in condition strings, the Buildtime export function now converts square brackets to left and right brackets (). This improves flexibility to use FDL files in the OS/390 environment, which does not support square brackets. Platform: WinNT, Win95, Win98 5. Buildtime: In the BT dialog 'User-defined Program execution server properties', the UPES Queue Name (page 'Message Queuing') is no longer restricted to 32 characters. Now, 48 characters are allowed as well as lower case. Platform: WinNT, Win95, Win98 6. Buildtime: When creating a new system, the name of the system group is now preset, using the system group name, from which the dialog was invoked. Platform: WinNT, Win95, Win98 7. API: SetAnotherPersonAbsent() This method can now be called from the Execution Service object. Platform: WinNT, Win95, Win98 8. Standard Client for Runtime: Performance The default setup for the Standard Client is to display all available lists whenever you log on. The windows that are displayed for Process Template Lists, Process Instance Lists, and Worklists can contain a large number of list items. This can slow you down considerably, for example, if you have to deal with many worklists. Up to now, you could not close any of the List windows. You could only minimize these windows. To improve performance, new settings in the Windows Registry for the Client allow you to specify the following: If you set the following: "OpenWorklists"="N" "OpenProcessInstanceLists"="N" "OpenProcessTemplateLists"="N" the Tree View is displayed only, without opening all lists and displaying their contents. When you double-click on a list in the Tree View, the selected list and its contents are displayed. If you set the following: "Close"="Y" you can now close any of the List windows, using the standard Windows closing function (X in the upper right-hand corner of the window), instead of only minimizing them. To apply these the new settings, create the following entries in the Windows Registry: [HKEY_CURRENT_USER\Software\VB and VBA Program Settings\fmcn6rtc] [HKEY_CURRENT_USER\Software\VB and VBA Program Settings\fmcn6rtc\Lists] "Close"="Y" [HKEY_CURRENT_USER\Software\VB and VBA Program Settings\fmcn6rtc\Logon] "OpenWorklists"="N" "OpenProcessInstanceLists"="N" "OpenProcessTemplateLists"="N" Note: You must restart the Standard Client to activate the changes in the Windows Registry. Platform: WinNT, Win95, Win98 9.Database: Overall Performance Improve overall performance by introducing special database calls for immediate deletion of processes and work items. Platform: WinNT, IBM AIX, SUN Solaris, HP Unix 10.API: Memory Management To reduce the message size for container values, the message stream is now optimized and compacted. Platform: all 3.2 Problems addressed in Service Pack #2 ----------------------------------------- 1. Administration Server: Optional system shutdown without forced client logoff including shutdown of PEA. When an MQSeries Workflow system is shut down, all clients (including API programs) are logged off by deleting their session records from the MQSeries Workflow database, and all program execution agents (PEAs) are shut down. You can change this behavior by setting the variable "RTSystemShutdownMode" to: "KeepSessions" in the MQSeries Workflow profile. If the variable is set, clients are not logged off and running PEAs are not shut down. You can set this variable as follows: fmczchk -y -c inst:m,RTSystemShutdownMode,KeepSessions where is the ID of the configuration. For information on how to set and change profile variables, see the chapter about "MQ Workflow profiles" in the "MQSeries Workflow Installation Guide". Because session records are not removed from the database when the system is shut down with this option, make make sure that the regular cleanup of sessions is done by the administration server by setting a session expiration time and a session expiration check interval in the system settings. 2. Timestamps in filters are now assumed to be in local time So far, timestamps in filter strings were interpreted as specifying a time in UTC. They are now interpreted as timestamps in local time. If you have written applications to support local timestamps for your users, then any adaptions made must be removed. 3. Standard Client for Runtime The syntax for entering filter values has changed as follows: Strings for DESCRIPTION, NAME, PROCESS_CATEGORY, and PROCESS_NAME have to be enclosed in single quotation marks ('). If the IN operator is used to specify more than one string, enclose the strings in brackets (). The following example shows the syntax to be used in the value1 field: ('string1, 'string2'). Patterns must also be enclosed in single quotation marks (').