Product Documentation
Abstract
Important note: This document is being retained for those who may have already migrated WDI to CICS TS 5.1 via PTF UK95742. If you have not yet migrated WDI to CICS TS 5.1, then instead apply superseding PTF UI28316 and follow the revised implementation instructions at: http://www.ibm.com/support/docview.wss?uid=swg27046093
The implementation of PTF UI28316 provides updated artifacts, including a revised OSGi Bundle, which accommodates both CICS TS 5.1 and 5.2 implementations, whereas PTF UK95742 only accommodates CICS TS 5.1.
The WebSphere Data Interchange implementation of Java technology components is changing with support for CICS Transaction Server V5.1. As previously implemented for prior releases of CICS, WDI Java features will not run under CICS TS 5.1. This new implementation will utilize CICS TS 5.1 with Java 7 and jar files packaged as OSGi bundles, which requires corresponding configuration changes, such as to the CICS JVM Profile and to various RDO definitions in support of a new CICS Bundle definition.
This document identifies PTF maintenace, related configuration changes, and various tools and resources you can use to make WDI available in a CICS 5.1 environment. Furthermore, since most WDI functionality is not Java based, this is applicable to only a subset of WDI for CICS users. Java based components include the following from the WDI 3.3.0 Installation Guide for z/OS. This document is applicable to, and supplements, these sections:
3.2.12 Step 34. Setting Up XML Support for WebSphere Data Interchange
3.2.13 Step 35. Setting Up Error Notification Support for WebSphere Data Interchange
Only those who utilize these specific Java WDI functions need to follow these instructions. That is, WDI is otherwise compatible with CICS TS 5.1.
Lastly, at the end of this document, you will find the latest information regarding any known issues or limitations, for which there are none at this time.
Content
The WDI implementation for CICS TS 5.1 requires that Java jar files be packaged into OSGi Bundles and CICS Bundles for usage. In support of the new bundles, the JVM Profile parameters used in CICS TS 4.2 are somewhat different in CICS TS 5.1 and will need to be changed along with various RDO definitions. An example of changes to the objects used to implement Java in CICS TS 5.1 follows.
Note that CICS Explorer for TS 5.1 was used during our implementation and provides a way to view the OSGi Bundles. There are also CEMT / CECI Inquiries that allow viewing of OSGi Bundles and Services to insure that the implementation was successful. Work with your CICS Systems Programmer to install and set up CICS Explorer, if you feel it necessary.
Apply WebSphere Data Interchange for z/OS PTF UK95742
The application of this PTF will install the necessary objects in the product distribution SMP/E datasets. WDI PTFs are available via normal z/OS PTF ordering processes, such as ShopzSeries.
Important note: This document is being retained for those who may have already migrated WDI to CICS TS 5.1 via PTF UK95742. If you have not yet migrated WDI to CICS TS 5.1, then instead apply superseding PTF UI28316 and follow the revised implementation instructions at: http://www.ibm.com/support/docview.wss?uid=swg27046093
The implementation of PTF UI28316 provides updated artifacts, including a revised OSGi Bundle, which accommodates both CICS TS 5.1 and 5.2 implementations, whereas PTF UK95742 only accommodates CICS TS 5.1.
Authorizing the hlq.SDFJAUTH Library
This library is the partitioned data set extended (PDSE) version of SDFHAUTH, and it contains some of the components of the SJ domain. The SDFJAUTH library is required for Java support. It must be APF-authorized and included in the STEPLIB DD in your startup job stream.
SIT Parameter Requirements
The SIT provides a way of identifying the home directory of the JVM Profile. The following is an example of the necessary parameter:
- JVMPROFILEDIR=/u/edi/cicshome33
In prior versions of CICS, WDI specified that the Java pieces be included in a home directory named /u/edi/cicshome33. If this was changed during your original WDI 3.3 installation under a prior CICS release, then change subsequent instructions to accommodate the name used. WDI Java objects for prior versions of CICS can coexist in the cicshome33 directory and some objects can be shared, that is, assuming you do not run both regions concurrently. Alternatively, if you wish to leave your prior implementation undisturbed (recommended), you can define a new home directory and change subsequent instructions accordingly. If the directory chosen does not exist, then create it by beginning on the ISPF Command screen, then enter:
- omvs
mkdir /u/edi/cicshome33
exit
Note that this directory should have at least read, write, and execute permissions that allow access by the CICS region user id (UID) / group id (GID).
Also note that the USSHOME system initialization parameter must match the directory that you specified for CICS Transaction Server files on z/OS UNIX when you installed CICS. For example,
- USSHOME=/usr/lpp/cicsts/cics680
WDI Bundle Objects
WDI bundle objects such as the OSGi Bundles and jars are delivered in the WDI PTF (UK95742). The grouping of these files is compressed. To install these objects, first use OPUT to place the OSGiBundles and definitions in the /u/edi/cicshome33 directory. From the ISPF Command screen, enter:
- OPUT 'edi.v3r3m0.sedihfs2(fxxbundl)' '/u/edi/cicshome33/fxxbundl.pax' binary
Then, use OMVS to invoke the z/OS UNIX shell, position yourself in the cicshome33 directory, set umask, and expand the compressed file as follows:
- omvs
cd /u/edi/cicshome33
umask 022
pax -rv -f fxxbundl.pax
This expansion creates the directory structure needed for the CICS manifest, jars and OSGiBundle definitions.
There are two bundles included with the expansion:
- com.ibm.datainterchange.cics.bundle_1.0.0 - bundle to enable XML support as would have been done previously as per Installation guide section 3.2.12, Step 34.
com.ibm.edi.vendor.bundle_1.0.0 - bundle to enable error notification with email support as per Installation Guide section 3.2.13, Step 35. Enablement of this optional functionality will be continued as a separate section below.
Note that the CICS region user id (UID) / group id (GID) requires read permission. The permissions assigned via the umask 022 and subsequent pax expansion will accommodate the needed permissions at runtime.
Also, samples of the wdi.properties file and the EDIParser.properties file are part of the expansion within subdirectory: com.ibm.datainterchange.cics.bundle_1.0.0. These new properties files either need to be copied to cicshome33 directory and modified to suit installation desires or, if multiple CICS versions are to be executed concurrently, such as for those migrating WDI to CICS TS 5.1, ensure that the previously existing wdi.properties and EDIParser.properties files are present or copied to the cicshome33 directory. In other words, the same properties files as before CICS TS 5.1 can be used for this new deployment.
Next, as part of the base WDI 3.3 release install, there would already be a dtds and traces folder within the cicshome33 directory. If you do not already have these, create these subdirectories and provide the needed permissions as such for the CICS region user id (UID) / group id (GID) to be allowed to read, write, and execute. For example:
- mkdir /u/edi/cicshome33/dtds
chmod -R 775 /u/edi/cicshome33/dtds
- mkdir /u/edi/cicshome33/traces
chmod -R 775 /u/edi/cicshome33/traces
Special note: When the region's JVM is started for the first time, CICS TS creates and installs region specific runtime objects within a directory named: /u/edi/cicshome33/<region_applid> where "u/edi/cicshome33" would be the directory as specified on the CICS region SIT JVMPROFILEDIR and "<region_applid> is your CICS region APPLID. If multiple different User IDs will be starting the same CICS region, the original owner will need to grant permission to this directory, for example:
- chmod -R 775 /u/edi/cicshome33/<region_applid>
Changes to the JVM Profile
In CICS TS 5.1 WDI assumes the name EDIJVMPR as the JVM Profile name. In CICS TS 4.2, installation steps suggest using DFHJVMPR. The CLASSPATH_SUFFIX used to identify the jars for CICS to use is no longer valid in CICS TS 5.1. Instead the jars are grouped into OSGi Bundles. With this suggested implementation of including the OSGi Bundles inside a CICS Bundle, the OSGI_BUNDLES parameter and the CLASSPATH_SUFFIX parameter are not used, hence a new profile should be defined.
Create a JVM Profile from the WDI supplied sample as follows. The sample JVM Profile definition is located in the EDI.V3R3M0.SEDIHFS2 library as member FXXPROF2. To place the sample in the proper directory, beginning on the ISPF Command screen, enter:
- oput 'edi.v3r3m0.sedihfs2(fxxprof2)' '/u/edi/cicshome33/EDIJVMPR' text
Make sure that permission is granted for the profile such that the CICS region user id (UID) / group id (GID) would be allowed at least read access. For example:
- cd /u/edi/cicshome33
chmod 775 EDIJVMPR
oedit /u/edi/cicshome33/EDIJVMPR
See comments therein for any installation specific changes that may be required. And make sure that permissions on the file names specified for STDOUT and STDERR allow for read/write capability for the CICS region user id (UID) / group id (GID). These two files will be created at runtime.
Note: when in edit mode, be aware that some lines extend beyond column 72, hence make sure the data in columns thereafter are shifted appropriately so that the line is contiguous.
CICS RDO Resource Definition Changes
Some changes to the WDI CICS program table definitions are required for CICS TS 5.1. A new JVMSERVER and Bundle need to be defined. Additionally, any old PPT definitions for the following WDI java programs will be intentionally deleted or omitted:
- EDIJSTRT
EDIJSTOP
EDIJPXML
EDIJMNTR
EDIEVBRK
Use DFHCSDUP to DEFINE a JVMSERVER named EDIJVM and CICS Bundle named EDIJAVA. Updated sample JCL is available in EDI.V3R3M0.SEDISAM2 as member FXXOC51 or FXXOP51. Which sample member to run depends on whether WDI was already installed in a version of CICS TS prior to 5.1. FXXOC51 contains incremental updates for those only upgrading to CICS TS 5.1. FXXOP51 is for those newly installing WDI in a CICS TS 5.1 region, i.e. FXXOP51 is a replacement for FXXOPPT, as called for in WDI 3.3.0 for z/OS Installation Guide, Section 3.2.8 Step 30. Setting Up the PPT for WebSphere Data Interchange.
Execute XML Related Test Cases in CICS
To verify that WDI is installed correctly, execute EDIV. If that completes successfully, then non-Java components of WDI are installed successfully. To check the WDI Java installation for XML support, run test transactions which execute data transformation to and from XML, e.g. XML to ADF, XML to EDI, or EDI to XML, etc.
(Optional) Enabling Error Notification Support for email
The sample email notification event handler with java source (edicevhsample.jar) was designed to use the pooled JVM setup with the CLASSPATH class loader. This setup is no longer available for Java implementation. In the past, the sample required the following files:
- activation.jar
mail.jar
WebSphere Data Interchange does not supply these jar files. These jars are part of the Oracle JavaMail API and the JavaBeans Activation Framework.
JavaMail and the Java Activation Framework are currently released as separate jar archives. The Java Activation Framework (javax.activation) is included with Java 7 that is required to use CICS TS 5.1.
- javax.activation - is the Java Beans API that allows communication between the local code and the remote server.
javax.mail - is the interface with various mail services.
These files are downloadable from a number of sources.
WebSphere Data Interchange supplies a CICS bundle template (com.ibm.edi.vendor.bundle_1.0.0) for mail services. You will need to install the JavaMail jar into this bundle or create your own bundle using CICS Explorer. The instructions below are additional modifications for using the WDI supplied vendor bundle for mail services.
- 1. Define the CICS Bundle definition that will be associated with the com.ibm.edi.vendor.bundle_1.0.0 directory created during the pax expansion above. Use either RDO CEDA transaction to create the bundle as below or copy the sample JCL as provided previously (FXXOC51 or FXXOP51) and change dd SYSIN as follows:
- //STEP01.SYSIN DD *
DEFINE BUNDLE(EDIVEND) GROUP(EDIGROUP)
BUNDLEDIR(/u/edi/cicshome33/com.ibm.edi.vendor.bundle_1.0.0)
DESCRIPTION(WDI Common Event Handler mail support)
/*
Unix System Services will be required for the following steps. New installs must download the JavaMail implementation jar file from a reliable source.
2. Ensure the JavaMail implementation jar file is located in the HFS directory /u/edi/cicshome33/com.ibm.edi.vendor.bundle_1.0.0. Either mail.jar or javax.mail.jar may be used within the OSGi bundle, however, the name must be javax.mail.jar in order for it to match the bundle template class path in the OSGi manifest. Using a different name would require modification to the manifest. Hence, if you are not already using javax.mail.jar, you will need to copy or rename mail.jar to name javax.mail.jar and place it in /u/edi/cicshome33/com.ibm.edi.vendor.bundle_1.0.0.
3. Update the bundle with the javax.mail.jar file. Navigate to the vendor bundle HFS directory /u/edi/cicshome33/com.ibm.edi.vendor.bundle_1.0.0. Use a "jar" command similar to the following to update this bundle.
- jar -uv0f javax.mail_1.0.0.jar javax.mail.jar
Note: The option flag (-uv0f) contains the number zero not a letter.
4. New Installs may update the wdi.properties file following the instructions in the WebSphere Data Interchange Install Guide for z/OS. Existing installations can use the existing wdi.properties as already discussed above.
Outstanding issues:
As of October 4, 2013, there are no outstanding issues.
Related Information
WDI 3.3.0: Installation Guide for z/OS
CICS TS 5.1: Knowledge Center - Java Checklist
CICS TS 5.1: Java Applications in CICS
CICS TS 5.1: Updating OSGi bundles in a JVM server
CICS TS 5.1: Upgrading from CICS TS Version 4.2
CICS TS 5.1: Getting started with the CICS Explorer
Was this topic helpful?
Document Information
Modified date:
01 August 2018
UID
swg27039040