============================================================================== ============================================================================== Licensed materials - Property of IBM 5655-FIN (C) Copyright IBM Corp. 2002, 2014 All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. ============================================================================== ============================================================================== README for IBM(R) WebSphere(R) Business Integration for Financial Networks for z/OS V3.1.1 Messaging Services for SWIFTNet InterAct and FileAct PTF UI18301 for APAR PI12992 Driver level: 4203 Date 2014-05-30 ============================================================================== ============================================================================== Table of contents ----------------- A About this document B Summary of changes C Planning D Preparation E Activating F Cleaning up G Falling back to the previous PTF level H Re-migrating after a previous fallback I APAR details J Other changes K Known issues A. About this document ---------------------- Only the online version of this readme document is current. Before you install the corresponding PTF, download the latest version from: http://www.ibm.com/software/integration/wbifn/support Download the latest version of the WebSphere BI for FN product documentation from: http://www-01.ibm.com/support/docview.wss?uid=swg27041133 The structure of WebSphere BI for FN readme documents is identical for all PTFs. Sections that are not applicable are left blank. If you install more than one PTF at a time, combine the readme documents by merging the contents of each section. The installation of this PTF is done in two phases: 1. Preparation - During this phase your system can continue to process messages as usual. 2. Activation - During this phase your system cannot process messages. This readme document uses the following variables: The installation directory of WebSphere BI for FN. The directory /usr/lpp is used in examples. The customization directory. The directory /var/dni_03_01/cus is used in examples. The deployment directory. The directory /var/dni_03_01/cus/depdata is used in examples. The name of the WebSphere BI for FN instance. The name INST1 is used in examples. The name of the organizational unit. Depending on the context, this might be SYSOU, DNFSYSOU, or the name of a business OU. The names of users, groups, files, and directories are the same as those used in WebSphere BI for FN Planning, Installation, and Customization. If you use different names, use those names instead of the names shown here. B. Summary of changes --------------------- APARs addressed by this PTF: PI12992 MSIF FILE TRANSFER ENDED IN DELIVFILEINERROR, INDICATING A NETWORK TRANSMISSION ERROR PI11220 MSIF INERRORACTION APP IS NOT CONSIDERED FOR DNFO3654E PI13982 MSIF MSIF: ADAPTING WEBSPHERE BI FOR FN BASE APAR PI07234 AUTHORITIZATION CHANGES IN MSIF PI14467 MSIF DNFO1253E SHOULD SHOW THE SCENARIO STATE BY THE TIME WHEN AN ERROR OCCURED, NOT THE STATE WHICH IS SET DUE TO THE ERROR PI15440 MSIF FULL SUPPORT OF PAYLOAD ATTRIBUTES AND SIGNATURE REFERENCES IN MSIF PI15521 MSIF EXCEPTIONS IN BROKER JOBLOG, WHEN MSIF IS CUSTOMIZED BUT NOT CONFIGURED Additional functional changes: - MSIF removes service check for delivery notifications - MSIF adds the logical file name to the AckInfo SNL parameter Documentation updates: The following manuals have been changed: - Planning, Installation, and Customization - Messages and Codes - Application Programming - System Administration The following modules have been changed: /dnfv311/admin/data/DNFEFAS.xml /dnfv311/admin/data/dnfmzoco.def /dnfv311/run/jplugin/dnfco.jar /dnfv311/run/msg/dnfcomsg.cat /dnfv311/run/msg/DNFO_Msg.properties /dnfv311/run/res/dnfcomsg.xml The following are new modules: /dnfv311/admin/data/dnfmzo2o.def C. Planning ----------- C1. Checks to be done >>BEFORE<< installing a new PTF ----------------------------------------------------- 1. Check if you have any efixes (emergency fixes) applied in your WebSphere BI for FN installation. In case you have efixes installed after your previous WebSphere BI for FN PTF installation and migration contact your IBM support before installing and migrating this PTF. 2. Ensure that all previously prepared deployment instructions were carried out. 3. Ensure that all previous CDD changes were implemented using the CDP. To check this, log on to z/OS UNIX on the customization system as a customizer (UCUST1) and enter the following command on your customization system: /dniv311/admin/bin/dnicdpst -i -cdefs where The name of the WebSphere BI for FN instance The name of the customization definitions directory as specified in the CDP ini file, for example: /var/dni_03_01/cus/defs If the response to this command indicates that a customization operation is still pending and it was carried out in: - Customization mode (dnicdp), implement the pending operation before continuing. - Migration mode (dnicdpm): - Ensure that you have not yet shared the files contained in this or any other PTF as described in section D1 step 3. - Implement the pending operation before continuing. 4. Until the migration for this PTF has been completely finished, ensure that no changes are made to the currently implemented CDD. 5. Ensure that all configuration administration changes have been deployed. To check this, enter the following commands: dnicli -s DNI_SYSADM -ou SYSOU > list -ou % -qo amorz > list -cos % -qo amorz > list -ct % -qo amorz Each list command should result in 'No [OU/COS/CT] match search criteria'. 6. Ensure that all security administration changes have been approved. To check this, enter the following commands for each OU: dnicli -s DNI_SECADM -ou > list -ro % -qo mor [only for SYSOU] > list -rg % -qo mor [only for SYSOU] > list -user % -qo mor The list command should result in 'No roles/role groups/users found that match specified criteria'. C2. Prerequisite and supersede information ------------------------------------------ This PTF requires the following PTFs: - UK94581 for APAR PM82681 - UK98509 for APAR PM92661 - UI16369 for APAR PI07234 This PTF supersedes the following PTFs: - UI14394 for APAR PM99719 C3. Roles involved ------------------ The activities in this PTF involve the following roles: - Installer (USMPE1) - Customizer (UCUST1) - ESM administrator (UESM1) - WebSphere MB administrator (UWMBA1) D. Preparation -------------- D1. Installation ---------------- 1. Log on to z/OS as an installer (USMPE1). 2. Install this PTF using SMP/E. 3. Share the files in the /dnfv311/admin directory with your customization system. 4. Ensure that the group ownership of the /dnfv311/admin directory and all of its subdirectories and files, is set to group DNIADMIN. To do this, enter the following command in z/OS UNIX: chgrp -R DNIADMIN /dnfv311/admin D2. Steps on a customization system ----------------------------------- To update your current definition directory and the customized administrative scripts, and to create deployment instructions and vehicles: 1. Log on to z/OS UNIX on the customization system as a customizer (UCUST1). 2. Change to the customization directory: cd 3. Run your customization profile: . ./dnicus_ 4. Start the CDP in migration mode and use the following commands to migrate customization data: dnicdpm -i > export cdd/_PI12992.cdd > import cdd/_PI12992.cdd > prepare This step updates the customized administrative scripts in the directory '//admin' and generates deployment data for migration of the run-time system for the following resource classes: - MQAUT * update permission on queue DNIvINST.DNIvOU.DNF_O_CMD for group DNIvSGRP Deployment instructions are generated in the file '///instructions.txt'. You will need this later in the 'E. Activating' section. 5. Implement the customization definition data and quit the CDP session: > implement When the message "DNIZ9013I: If you continue, the current CDD will be overwritten by a new CDD." is displayed enter 'y' to continue. > quit D3. Copy DB2 modules to data sets --------------------------------- NOT APPLICABLE. D4. Generating configuration data migration scripts --------------------------------------------------- NOT APPLICABLE. D5. Prepare BAR file deployment ------------------------------- NOT APPLICABLE. D6. Prepare to migrate Java database routines --------------------------------------------- NOT APPLICABLE. *-----------------------------------------------------------------------------* * End of Preparation * *-----------------------------------------------------------------------------* E. Activating ------------- E1. Stopping all sessions and services you use ---------------------------------------------- Stop all sessions and services, for example: - Stop all applications that send requests to WebSphere BI for FN. - Log out SIPN FIN LTs. - Close MSIF SnF input and output channels. - Release SWIFTNet SnF queues. - Stop the MSIF Message Transfer service. - Close all dnicli sessions. For further information, see "Administering and operating components, sessions, and services" in WebSphere BI for FN System Administration. E2. Stopping all application servers ------------------------------------ NOT APPLICABLE. E3. Stopping all WebSphere BI for FN message brokers ---------------------------------------------------- Stop all WebSphere BI for FN message brokers. E4. Sharing the runtime directory structure ------------------------------------------- 1. Share the files in the /dnfv311/run directory with the runtime systems. 2. Set the group ownership of these directories and files to group DNILPP. To do this, enter the following command in z/OS UNIX: chgrp -R DNILPP /dnfv311/run E5. Backing up configuration and security data in image copies -------------------------------------------------------------- NOT APPLICABLE. E6. Following the deployment instructions created in step D2.4 -------------------------------------------------------------- Follow the deployment instructions that were created in step D2.4. E7. Additional activities ------------------------- NOT APPLICABLE. E8. Restarting all WebSphere BI for FN message brokers ------------------------------------------------------ Restart all WebSphere BI for FN message brokers. E9. Redeploy updated BAR files ------------------------------ NOT APPLICABLE. E10. Migrating configuration data --------------------------------- NOT APPLICABLE. E11. Updating the WebSphere BI for FN enterprise application ------------------------------------------------------------ NOT APPLICABLE. E12. Restarting all sessions and services ----------------------------------------- Restart all of the sessions and services that you use. How to do this depends on which WebSphere BI for FN features you use. For example: - Log in SIPN FIN LTs. - Subscribe MSIF to SAGs to enable file transfer and session monitoring. - Start the MSIF Message Transfer service. - Acquire SWIFTNet SnF queues. - Open MSIF SnF input and output channels. - Start the applications that send requests to WebSphere BI for FN. For further information, see "Administering and operating components, sessions, and services" in WebSphere BI for FN System Administration. E13. Updating the Toolkit development environment ------------------------------------------------- NOT APPLICABLE. E14. Verifying your Installation --------------------------------- NOT APPLICABLE. *------------------------------------------------------------------------------* * End of Activating * *------------------------------------------------------------------------------* F. Cleaning up -------------- NOT APPLICABLE. G. Falling back to the previous PTF level ----------------------------------------- G1. Stopping all sessions and services you use ---------------------------------------------- Stop all sessions and services you use as described in E1. G2. Stopping all application servers ------------------------------------ NOT APPLICABLE. G3. Stopping all WebSphere BI for FN message brokers ---------------------------------------------------- Stop all WebSphere BI for FN message brokers. G3.1 Stopping the WLM Java application environment - - - - - - - - - - - - - - - - - - - - - - - - - NOT APPLICABLE. G4. Uninstalling the PTF using SMP/E and sharing the files and directories -------------------------------------------------------------------------- Uninstall the PTF using SMP/E and share the files and directories with your customization and runtime systems. G5. Recovering the customization system --------------------------------------- NOT APPLICABLE. G6. Fallback activities ----------------------- G6.1. DB2 related activities - - - - - - - - - - - - - - NOT APPLICABLE. G6.2. WebSphere Message Broker related activities - - - - - - - - - - - - - - - - - - -- - - - - - NOT APPLICABLE. G6.3. External Security Manager (ESM) related activities - - - - - - - - - - - - - - - - - - -- - - - - - - - - - NOT APPLICABLE. G6.4. WebSphere MQ related activities - - - - - - - - - - - - - - - - - - - NOT APPLICABLE. G7. Restarting all WebSphere BI for FN message brokers ------------------------------------------------------ Restart all WebSphere BI for FN message brokers. G8. Restoring configuration and security data using dnfczmlc ------------------------------------------------------------ NOT APPLICABLE. G9. Redeploying previous BAR files ---------------------------------- NOT APPLICABLE. G10. Restoring the WebSphere Application Server configuration ------------------------------------------------------------- NOT APPLICABLE. G11. Restarting all application servers --------------------------------------- NOT APPLICABLE. G12. Restarting all sessions and services you use ------------------------------------------------- Restart all sessions and services you use as described in E12. G13. Restore your previous Toolkit development environment ---------------------------------------------------------- NOT APPLICABLE. *------------------------------------------------------------------------------* * End of Fallback * *------------------------------------------------------------------------------* H. Re-migrating after a previous fallback ----------------------------------------- After you fall back to an earlier level, plan for re-migration only after you have identified the reason for the fallback and have corrected the problem. To re-migrate, follow the steps described in this readme document. *------------------------------------------------------------------------------* * End of Re-migration * *------------------------------------------------------------------------------* I. APAR details --------------- Fixes for the following APARs are contained in this PTF: PI12992 MSIF FILE TRANSFER ENDED IN DELIVFILEINERROR, INDICATING A NETWORK TRANSMISSION ERROR If MSIF receives a file where a delivery notification is requested by the sender, then, as soon as the file is received, it sends back to SWIFT an acknowledgement request. Then SWIFT returns an acknowledgement response indicating whether the request was processed successfully. Beside this acknowledgement processing MSIF performs some file operation like copying or unzipping the file, before it finally sends a FileReceived notification message to the application. If there are multiple MSIF threads running, then the acknowledgment handling and the file operations are performed in parallel. In this case it is possible that either the acknowledgment processing completes before the file operations, or vice versa. Formerly, if the acknowledgment processing completed before the file operations, and the acknowledgement response contained errors, then the file was delivered to the application with completion code Failed, and the transfer ended in state DelivFileInError. If the file operations completed before the acknowledgment processing, that means the file was delivered to the application before the acknowledgement response was received, then the file was delivered to the application with completion code Ok, and the transfer ended in state DelivComplete. Now, the completion code and the transfer state is independent on the acknowledgment processing, that means that errors in the acknowledgment response are issued as events and are regarded for the notification state, but are not regarded anymore for the completion code and the transfer state. PI11220 MSIF INERRORACTION APP IS NOT CONSIDERED FOR DNFO3654E Formerly, when an application sent a SendFile request to MSIF that referred to a file that did not exist or could not be accessed, then MSIF did not use the option InErrorAction of CT DnfEfaBouParameters, but always issued an error event, for example DNFO3654E. Now, in such an error scenario, MSIF checks the option InErrorAction, and if it is set to App, then it notifies the application about the file access problem instead of raising an event. PI13982 MSIF MSIF: ADAPTING WEBSPHERE BI FOR FN BASE APAR PI07234 AUTHORITIZATION CHANGES IN MSIF With WebSphere BI for FN Base PTF UI16369 for APAR PI07234 the WAS security in WebSphere BI for FN web applications was changed. This WebSphere BI for FN MSIF PTF provides the necessary adaptions for MSIF. See also to WebSphere BI for FN Base APAR PI07234. PI14467 MSIF DNFO1253E SHOULD SHOW THE SCENARIO STATE BY THE TIME WHEN AN ERROR OCCURED, NOT THE STATE WHICH IS SET DUE TO THE ERROR The error events DNFO1249E and DNFO1253E contain the original state in which a transfer received an error. Formerly, the events did not contain the original state, but the state in which the transfer went after handling the error. Now, the events contain the original state before handling the error. PI15440 MSIF FULL SUPPORT OF PAYLOAD ATTRIBUTES AND SIGNATURE REFERENCES IN MSIF To support a solution for the CLS service, an extended support of payload attributes and signature references was required. Formerly MSIF provided a full support of the payload type attribute, but only a limited support of payload attributes in general. Now MSIF provides a full support of payload attributes. Payload attributes can now be specified by an application in a SendMsg request, and are forwarded in a MsgReceived notification to an application. For more information see the Application Programming manual. Formerly MSIF supports a maximum of 8 signature references. This restriction is derived from a limitation in the central system at SWIFT. SWIFT has announced a plan to increase this limit later this year. Please note that at the time this PTF is published, the limit is still 8 due to the limitation in the central system at SWIFT. Now MSIF provides a support of an unlimited number of signature references in SendMsg requests. For more information see the Application Programming manual. PI15521 MSIF EXCEPTIONS IN BROKER JOBLOG, WHEN MSIF IS CUSTOMIZED BUT NOT CONFIGURED Formerly if in the WBIFN configuration no configuration object DnfEfaParameters was configured, then MSIF failed to determine the batch size and initiate the internal timout processing due to a NullPointerException. Now this was corrected, and MSIF initiates the timeout processing without errors. Fixes for the following APARs from superseded PTFs are also contained in this PTF: PM99719 MSIF INTRODUCING BATCHING FOR DETECTION OF TIMED OUT AND EXPIRED TRANSFERS The MSIF DNF_O_CMD service periodically looks for transfers that, for example, timed out or expired from a business perspective. For each of these transfers the DNF_O_CMD service sends an internal MQ message to the DNF_O_FTx service to further process the transfer. The maximum number of transfers that the DNF_O_CMD service handles in a single broker transaction can be configured with parameter BatchSize of configuration object DnfEfaParameters. Formerly, this parameter specified the maximum number of transfers that the DNF_O_CMD service could handle in a period of three minutes. If this number was too large, this could end up in abends because the execution group ran out of resources. Now, when the DNF_O_CMD service determines that there are more transfers than configured as BatchSize, it immediately continues a new batch in another broker transaction. Batching is now used in the following situations: - cleanup - timed-out transfers - transfers that expired from a business perspective - monitoring the replication status of SnF transfers - transfers affected by SnF system recovery - monitoring the file transfer window for an SAG - stopped transfers that can be restarted when the service gets started The default value for BatchSize in all situations is 100. PM99522 MSIF ADAPT MSIF TO IMPLEMENT VL/122013 WHICH DEFINED CHANGES IN DIGITAL SIGNATURES FOR INTERACT AND FILEACT MESSAGING Formerly the usage of digest references in SNL primitives sent to an SAG have been unclear for some InterAct and FileAct scenarios. With vendor letter VL/122013 SWIFT provided a clarification for all InterAct and FileAct scenarios. Now, MSIF fully applies to this vendor letter and for all supported InterAct and FileAct scenarios MSIF adds the required digest references to the SNL primitives sent to an SAG. PI06232 MSIF ENHANCED MSIF TRACING IN CONTEXT OF THE DNFO9501E AND DNFO9505E Formerly, when running MSIF flows with additional flow instances, it was possible that in rare cases an event DNFO9501E was issued that indicated an internal error. The root cause of this internal error was, that two MSIF threads tried to initialize the same internal object at the same time. For a correct object initialization it was required that at most one thread executes the object initialization. Now, this problem is fixed and the MSIF code guarantees that only one thread executes the object initialization. PI07467 MSIF CHANGE CLEANUP TO USE "WITH UR" TO AVOID SQL -913 (TIMEOUT) MSIF processes business transfers and in parallel can issue a cleanup process to delete finished transfers. The processing of business transfers and the cleanup process, both access the DB2 table DNFO_FSM_STATE as part of their transaction. Formerly, this could cause DB2 timeouts in the cleanup processing, especially when long file operations were executed and the DB2 table DNFO_FSM_STATE was locked longer than the timeout specified in DB2. The reason for this scenario was that the cleanup processing tried to get a list of transfers that are eligible for cleanup in a transactional way. Now, this behavior has been changed, and the cleanup processing gets the list of transfers that are eligible for cleanup with uncommitted read DB2 access. PI08183 MSIF TRY AUTORECOVERY WHEN UNKNOWN SAG STATUS EVENTS ARE RECEIVED MSIF supports automatic recovery of failed transfers by specifying the attribute MaxAutoRecoverCount of CO DnfEfaSagCommOptionSet. In case of errors reported by an SAG, MSIF analyzes the error codes Sag:System.xxx.xxx and initiates the recovery of a transfer only for selected codes. Formerly, in case an SAG reported an error code that is undocumented in the SWIFT error guide manual, then MSIF treated such an unknown error as non-recoverable. Now, this behavior has been changed and the failed transfer is automatically recovered. PI09045 MSIF DNFO3463E DURING SENDMSG SCENARIO VIA INPUT CHANNEL An application passes an MSIF SendMsg transfer to MSIF that is to be transferred to SWIFT using an input channel. In case a severe error like a DB2 error occurs before the transfer is initially sent out on the input channel, it is possible the transfer remains in the state Requested and condition inError. Formerly, when issuing a recover command on such a transfer the recovery failed with an exception as no message partner was assigned to the transfer. Now, the recovery succeeds and the transfer is sent out on the input channel successfully. J. Other changes ---------------- - Message updates: * Event messages changed: DNFO0461E, DNFO3251E, DNFO3600E, DNFO9501E * Response messages changed: DNFO0557E, DNFO9500E - MSIF removes service check for delivery notifications MSIF can process InterAct and FileAct traffic in different MSIF services DNF_O_FTx. Formerly, MSIF verified that on the sending side a delivery notification is received in the same service than the corresponding send transfer was processed. In case the delivery notification was received in a different service, MSIF rejected the message. Now, this condition is not verified anymore, and delivery notification received in other MSIF services are accepted. This change can simplify the message routing conditions specified on an SAG. - MSIF adds the logical file name to the AckInfo SNL parameter Due to a SWIFT vendor letter MSIF adds now the logical file name to the AckInfo SNL parameter so SWIFT can forward this information in delivery notification messages to the sender of a file. K. Known issues --------------- NOT APPLICABLE. ++++ End +++ End +++ End +++ End +++ End +++ End +++ End +++ End +++ End ++++