IBM Support

Implementation of WebSphere Data Interchange 3.3 in CICS TS 5.1, 5.2, 5.3, and 5.4

Product Documentation


Abstract

The WebSphere Data Interchange implementation of Java technology components is changing with support for CICS Transaction Server V5.1, V5.2, V5.3 and V5.4. The jar files contained in the OSGI bundle for CICS are also used for Batch Event Notification Support (mail) and have been included with this PTF.

Note: As of September, 2017, WDI has also been tested with CICS TS 5.4 using the implementation herein as per the CICS TS 5.2 instructions that follow. No issues were found, and no changes to the implementation are required specifically for CICS TS 5.3 or 5.4.

WDI PTF UI75372 for APAR PH27835 provides the most current bundle definition, com.ibm.datainterchange.cics.parser_1.0.3.jar, to correct a WDI CICS XML JAVA parser issue found with the previous bundle definition, com.ibm.datainterchange.cics.parser_1.0.2.jar, that was provided with UI28316 below. This document has been modified to reflect the new bundle version.

WDI PTF UI28316 provides bundle definition com.ibm.datainterchange.cics.parser_1.0.2.jar with details described herein. This PTF is required with support for CICS TS 5.2, 5.3 and 5.4, or CICS TS 5.1 and Java 8. If you have applied WDI PTF UK95742 for CICS TS 5.1, and wish to apply this PTF, there are additional instructions to remove the vendor bundle used for mail services.

This document identifies PTF maintenance, related configuration changes, and various tools and resources you can use to make WDI available in a CICS 5.1, 5.2, 5.3 and 5.4 environments. Furthermore, since most WDI functionality is not Java based, this is applicable to only a subset of WDI 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, 5.2, 5.3 and 5.4.

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 and higher versions 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 5.2 and will need to be changed along with various RDO definitions.

Original implementations utilized Java 7 with CICS TS 5.1 and 5.2 and modified jar files packaged as OSGi bundles and batch. Most recent WDI JAVA implementations are replacing recordio.jar with ibmjzos.jar. The ibmjzos.jar is required for use with JAVA 8. The WDI Common Event Handler has been changed to respect this new requirement.


Additional code changes were needed for the XML Parser classes to locate EDIParser.properties in the HOME folder (which is the current location of this file), in addition to the bundle subdirectory (which is now the default location of this file).

The Common Event Handler core Java classes now correctly gather and carry the elements and values specified in the Event Destination profile.

WDI Mail Notification using attachment incorrectly used a code page conversion to ASCII. This conversion has been removed. The WDI Mail Notification is a sample and should be using the native EBCDIC code page for z/OS systems. Sample Mail attachments are transported in binary (encoded for mail in BASE64). This change to the WDI sample demonstrates using the mail notification for binary data, a feature important in some situations and critical for WMQ operating on data with different encoding.

As previously implemented for prior releases of CICS, WDI Java features and OSGI implementation must be modified under CICS TS 5.2. WebSphere Data Interchange for z/OS PTF UK95742 supplied OSGI and CICS bundle implementations for CICS TS 5.1. PTF UK95742 supplied a CICS bundle template (com.ibm.edi.vendor.bundle_1.0.0) to be used for mail services. The CICS bundle template was supplied to enable Mail Services for CICS TS 5.1 prior to CICS APAR PI27792. NOTE: Ensure the latest PTF maintenance has been applied to your CICS regions and confirm PTFs for APAR PI27792. The PTFs are UI23602 (TS 5.1) and UI23603 (TS 5.2)

Customers who are migrating from CICS V5.1 to CICS V5.2 and installed the CICS bundle for mail services for CICS V5.1 (PTF UK95742), must remove the WebSphere Data Interchange supplied CICS bundle template (com.ibm.edi.vendor.bundle_1.0.0) used for mail services.


The JVM Profile naming for CICS TS 5.1 is unchanged. The JVM profile file name for CICS TS 5.2 requires an explicit .jvmprofile extension.

Removal of the WDI supplied com.ibm.edi.vendor.bundle used for CICS TS 5.1 implementation and enabling the CICS mail.jar bundle in the JVM profile.

An example of changes to the objects used to implement Java in CICS TS 5.1 and 5.2 follows.

Note that CICS Explorer for TS 5.2 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 UI75372

This PTF is optional and provides the most current CICS bundle definition.  The bundle corrects an issue with WDI CICS XML JAVA parser failing with OUTOFMEMORY (OOM) error when XML input contains specific invalid syntax such as two double-quotes where there should be one double-quote.  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.

Apply WebSphere Data Interchange for z/OS PTF UI28316

This PTF is required with support for CICS TS 5.2, 5.3 and 5.4, or CICS TS 5.1 and Java 8.  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.  

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.


The hlq.LIC.SDFHLIC Library CICS TS 5.2

The LIC.SDFHLIC library is required for CICS TS 5.2. It must be 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 are located in z/os data set, edi.v3r3m0.sedihfs2.  The most current bundles in this data set are listed below:
  • fxxbund3 -  most current version 3 included with UI75372, com.ibm.datainterchange.cics.parser_1.0.3.jar
  • fxxbundl -  version 2 included with UI28316, com.ibm.datainterchange.cics.parser_1.0.2.jar
  • fxxbundo -  original and old bundle, com.ibm.edi.vendor.bundle_1.0.0.jar 

WDI bundle objects such as the OSGi Bundles and jars are delivered in the WDI PTFs (UK95742, UI28316, and UI75372). 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(fxxbund3)' '/u/edi/cicshome33/fxxbund3.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 fxxbund3.pax

This expansion creates the directory structure needed for the CICS manifest, jars and OSGiBundle definitions.

There is one bundle included with the expansion:
 
  • com.ibm.datainterchange.cics.bundle_1.0.3 - bundle to enable XML support and to enable event notification with email support as would have been done previously as per Installation guide sections 3.2.12, Step 34 and 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.3. 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 or 5.2, 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 or 5.2 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
     
Place all XML DTDs to be used in the dtds directory. This would be for those who are migrating and already have a dtds directory elsewhere. You do not need to put anything in the traces directory. The EDI Java parsers will write any trace output to the trace directory.

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 and modified.

See comments within the EDIJVMPR 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 TS 5.1:


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

Edit the file, beginning on the ISPF Command screen, enter:

  • oedit /u/edi/cicshome33/EDIJVMPR


CICS TS 5.2:

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.jvmprofile' 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.jvmprofile

Edit the file, beginning on the ISPF Command screen, enter:

  • oedit /u/edi/cicshome33/EDIJVMPR.jvmprofile

CICS TS 5.1 to 5.2 Migration:

Rename or Copy an existing JVM Profile. Use OMVS to invoke the z/OS UNIX shell, to copy or rename an existing JVM profile.

To rename an existing profile, position to the home directory. For example:
 
  • cd /u/edi/cicshome33
  • mv EDIJVMPR EDIJVMPR.jvmprofile
To copy an existing profile, position to the directory where the JVM profile is located. For example:
 
  • cd /u/edi/cicshome33
  • cp EDIJVMPR /u/edi/cicshome33/EDIJVMPR.jvmprofile

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
  • mv EDIJVMPR EDIJVMPR.jvmprofile

Edit the file, beginning on the ISPF Command screen, enter: 

  • oedit /u/edi/cicshome33/EDIJVMPR.jvmprofile

CICS RDO Resource Definition Changes

Some changes to the WDI CICS program table definitions are required for CICS TS 5.1 and higher. A new JVMSERVER and Bundle needs to be defined. Additionally, any old PPT definitions for the following WDI java programs will be intentionally deleted or omitted.

If you have applied WDI PTF UK95742 for CICS TS 5.1, the old PPT definitions have already been removed but the JVM Server bundle needs to be altered (not defined) to enable the new OSGi bundle.
 
  • 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 or 5.2. FXXOC51 contains incremental updates for those only upgrading to CICS TS 5.1 or 5.2. FXXOP51 is for those newly installing WDI in a CICS TS 5.1 or 5.2 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.

To ALTER the CICS Bundle definition that will be associated with the com.ibm.edi.vendor.bundle_1.0.3 directory. Use either RDO CEDA transaction to create the bundle as below or copy the sample JCL as provided previously (FXXOC51) and change dd SYSIN as follows:


//STEP01.SYSIN DD *
ALTER BUNDLE(EDIJAVA) GROUP(EDIGROUP)
BUNDLEDIR(/u/edi/cicshome33/com.ibm.datainterchange.cics.bundle_1.0.3)
DESCRIPTION(WDI XML Parser and Event Handler)
/*



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 Event 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. The sample will now use to the cics mail.jar located in the folder CICS_install_dir/lib/pipeline. The sample mail notification for CICS no longer used the mail and activation jar file.

Modify the OSGI_BUNDLES property in the JVM profile to include the JavaMail file mail.jar supplied with CICS or the location of this file.

For example:
 
  • OSGI_BUNDLES=/usr/lpp/mqm/V7R0M1/java/lib/OSGi/com.ibm.mq.osgi.java_7.0.1.10.jar,\
    /CICS_install_dir/lib/pipeline/mail.jar

OR
 
  • OSGI_BUNDLES=/CICS_install_dir/lib/pipeline/mail.jar



Removing the VENDOR Bundle:

As previously implemented for prior releases of CICS, WDI Java features and OSGI implementation must be modified under CICS TS 5.2. WebSphere Data Interchange for z/OS PTF UK95742 supplied OSGI and CICS bundle implementations for CICS TS 5.1. PTF UK95742 supplied a CICS bundle template (com.ibm.edi.vendor.bundle_1.0.0) to be used for mail services. The CICS bundle template was supplied to enable Mail Services for CICS TS 5.1 prior to CICS APAR PI27792 and should be removed.

The instructions below are additional modifications for removing the WDI supplied vendor bundle for mail services.
  1.  Delete the CICS Bundle definition that will be associated with the com.ibm.edi.vendor.bundle_1.0.0 directory. 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 *
    DELETE BUNDLE(EDIVEND) GROUP(EDIGROUP)
    /*

    Unix System Services will be required for the following steps.
     
  2.  Delete the CICS Bundle is located in the HFS directory. Use OMVS to invoke the z/OS UNIX shell, position yourself in the cicshome33 directory.
  • cd /u/edi/cicshome33
  • rm -R com.ibm.edi.vendor.bundle_1.0.0
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 May 17, 2021, there are no outstanding issues.

[{"Product":{"code":"SSFKTZ","label":"WebSphere Data Interchange"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"WDI 3.3 z\/OS","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"3.3","Edition":"All Editions","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Document Information

Modified date:
17 May 2021

UID

swg27046093