IBM WebSphere® Transformation Extender for z/OS, Version 8.1 Release Notes (rev. 2) © Copyright IBM Corporation 2006. All Rights Reserved. ===================================================================== CONTENTS ===================================================================== 1. About this release 2. Known limitations, problems, and workarounds 3. IBM WebSphere Transformation Extender - Common Components 4. IBM WebSphere Transformation Extender with Command Server 5. IBM WebSphere Transformation Extender with Launcher 6. IBM WebSphere Transformation Extender for Message Broker 7. IBM WebSphere Transformation Extender 8. Information common to all the features 9. Contacting customer support 10. Notices and trademarks ===================================================================== 1. ABOUT THIS RELEASE ===================================================================== The new features for this release are listed in the What's new in IBM WebSphere Transformation Extender for z/OS section of this file. For additonal information about the new features for other IBM WebSphere Transformation Extender products, see the "What's New" documentation. For details on installing and configuring the IBM WebSphere Transformation Extender z/OS features, see the following program directory: Program Directory for IBM WebSphere Transformation Extender for Use with z/OS (order number: GI11-2870) The sections in this file provide release notes for the IBM WebSphere Transformation Extender z/OS features listed below. There are also sections for notes that apply to specific products, as well as across products. - IBM WebSphere Transformation Extender - Common Components - IBM WebSphere Transformation Extender with Command Server - IBM WebSphere Transformation Extender with Launcher - IBM WebSphere Transformation Extender for Message Broker - IBM WebSphere Transformation Extender These notes are applicable to the features that have already been installed. They provide additional configuration instructions for deploying the installed features to your runtime environment, setting environmental variables, running examples, as well as other post-installation information to assist you in using the installed features. What's new in IBM WebSphere Transformation Extender for z/OS ------------------------------------------------------------ SMP/E Installation ------------------ The installation process for the IBM WebSphere Transformation Extender for z/OS features is now done through System Modification Program Extended (SMP/E). For instructions about installing the WebSphere Transformation Extender for z/OS features, see the "Program Directory for IBM WebSphere Transformation Extender for Use with z/OS" (order number: GI11-2870). IMS map and MDQ file preloader exit ----------------------------------- The map and mdq preloader exit is a new IMS user exit routine that provides a way for you to preload IBM WebSphere Transformation Extender map and mdq files into memory. When you use this exit, all subsequent access to these files during map execution are from memory and don't require any file input and output (I/O) processing from these preloaded files. For prerequisites and instructions about using the exit, see the IMS/DC Execution Option (1103.pdf) documentation that is posted on the product Web site (www.ibm.com/software/integration/wtx). ===================================================================== 2. KNOWN LIMITATIONS, PROBLEMS, AND WORKAROUNDS ===================================================================== [EC105513] - Exit map call function ----------------------------------- When you run the DTXBMJCL example JCL that is included in the installation and used for the Installation Verification Process (IVP), a load failure occurs and an error message is returned. This is caused by a syntax error in the EXIT function call to the DTXTPBSP COBOL EXIT program in the reverse map. However, the IVP indicates that the product was successfully installed. If you want to run the DTXBMMVS reverse map to see how the Burst feature is used, a workaround solution is to modify the map source. Change the first parameter of the EXIT call in the DTXBMMMS map source that is in the DTX.SDTXMAPS PDS to a null value by removing the space between the quotation marks. It should be changed to: =EITHER (EXIT("","dtxtpbsp","LINE"), "Exit DTXTPBSP not found") Generate the DTXBMMMS map and re-submit the DTXBMJCL example JCL that is in the DTX.SDTXSAMP PDS. For information about how to modify the map source and run the map, see the DTXBMRME reverse example readme file in the DTX.SDTXSAMP PDS. [EC103974] - PACKAGE function change ------------------------------------ There has been a change to the PACKAGE function, where it will now return a valid code page for data contained within group objects, which previously had an unknown code page. This primarily affects the following three map rule functions on all platforms: - GET - PUT - RUN For example, if you are running a map on the UNIX System Services (USS) execution environment, that is set up to use the Java adapter, and has a rule that uses the PACKAGE function, change the rule to use, instead, the CPACKAGE function. Also, specify the character set as NATIVE for the second argument on the rule. Because of a change to the PACKAGE function, if you use it in this specific case, the map will convert the data to the NATIVE code page, which might be invalid for the Java adapter, and cause a Java exception error. If you are running maps on the USS execution environment, the character set for NATIVE is EBCDIC, which is invalid for the JAVA adapter. Change the rule from: GET("JAVA","-T",PACKAGE(GROUP:RECORD)) to: GET("JAVA","-T",CPACKAGE(GROUP:RECORD,"NATIVE")) In this example, when you specify NATIVE in the second argument of the CPACKAGE function, the function treats the data as if it already is in the appropriate code page and therefore, does not attempt to convert it to NATIVE. [ECM18993] - Possible delay in viewing GUI contents on USS ---------------------------------------------------------- Since z/OS operating systems do not have GUI hosting capabilities, the Launcher's Java-based GUIs need to be displayed on a remote X Windows server. This might cause a delay in viewing the contents of these GUIs on the remote machine when running the IBM Transformation Extender with Launcher on UNIX Systems Services (USS) platforms. Several factors can attribute to the time delay in displaying the GUI including, but not limited to: - Network traffic - CPU utilization on the z/OS system - TCP/IP communication delays - Capabilities of the X Windows server [ECM18996] - Possible USS Launcher failure ------------------------------------------ A large number of maps, triggers, or I/O requirements might cause the IBM Transformation Extender with Launcher on the UNIX System Services (USS) platforms to fail due to resource shortage. You might need to increase the region size or adjust 'SYS1.PARMLIB' parameters, which affect z/OS operating systems on USS platforms. Most of these parameters are described in the IBM z/OS Initialization and Tuning Guide section for member 'BPXPRMxx'. [ECM19065] - Adjust settings in the dtx.ini file ------------------------------------------------ Because every system environment is different, it is recommended that, when running the IBM Transformation Extender with Launcher on the UNIX Systems Services (USS) platform, you review the dtx.ini documentation and make the necessary adjustments to the settings to allow for appropriate resource allocation for your specific environment. See the IBM z/OS Initialization and Tuning Guide section for member 'BPXPRMxx' for recommendations on additional parameter settings. [ECM19077] - Using the DBLOOKUP, DBQUERY, GET and PUT map functions with the database adapter ---------------------------------------------------------- When using the DBLOOKUP, DBQUERY, GET and PUT map functions with the database adapter, the adapter will use and expect the default values for the Delimiter, Terminator and Release settings. This is because the data passed to and from the adapter is, in this case, not represented by a type tree generated in Database Interface Designer. The adapter will use the default values for the Delimiter, Terminator and Release settings since it cannot access this information from a type tree. [ECM19451] Preserving the encoding of XML files ----------------------------------------------- To preserve the encoding of XML files created on an ASCII platform, these files (including files such as the Resource Registry .mrc and .mrn files) should be transferred in BINARY mode (using FTP or IND$FILE) and not ASCII mode. Note, however, that these files, transferred in BINARY mode, will still be ASCII-encoded and therefore not readable on the mainframe platform. An XML instance document might contain an encoding attribute, which identifies the code page of its content. If you transfer these files to your mainframe in ASCII mode or convert the files to EBCDIC, you will need to manually change the encoding setting in the resulting XML instance document to identify the correct code page (normally "UTF-8" should be changed to "IBM-1047") to ensure that the XML parser correctly processes the file. ===================================================================== 3. IBM WEBSPHERE TRANSFORMATION EXTENDER - COMMON COMPONENTS ===================================================================== Configuration steps ------------------- The files that are installed with the IBM WebSphere Transformation Extender - Common Components base feature are programs and JCL that are used with the other IBM WebSphere Transformation Extender optional features that you have installed. This section describes the required configuration steps for the common components. Accessing DB2 databases in CICS and IMS environments ---------------------------------------------------- When you are running the IBM WebSphere Transformation Extender in your CICS and IMS environments and need to access and manipulate data in your DB2 database, you must use the DB2 (z/OS) Call Attachment Facility (CAF) adapter. To use the DB2 (z/OS) CAF adapter, follow the steps described in the Binding the Data Base Request Module (DBRM) section. Accessing DB2 databases in Batch and USS environments ----------------------------------------------------- When you are running the IBM WebSphere Transformation Extender with Command Server feature in your Batch environment or the IBM WebSphere Transformation Extender feature in your UNIX System Services (USS) execution environment and need to access and manipulate data in your DB2 databases, you can use either the DB2 (z/OS) CAF adapter or the DB2 (z/OS ODBC) adapter. To use the DB2 (z/OS) CAF adapter, follow the steps described in the Binding the Data Base Request Module (DBRM) section. The prerequisite for using the DB2 (z/OS ODBC) adapter is that the ODBC support is set up in the DB2 subsytem. For more information about installing and configuring ODBC, see the "DB2 UDB for z/OS ODBC Guide and Reference." There are no additional configuration steps required to use the DB2 (z/OS ODBC) adapter. Allocating an HFS on USS environments ------------------------------------- It is recommended that you define a unique mount point on your UNIX System Services (USS) environment for the deployed runtime environment for the IBM WebSphere Transformation Extender USS features that you have installed, run the DTXDHFS JCL that is installed in the DTX.SDTXSAMP PDS. The DTXDHFS JCL will allocate a Hierarchical File System (HFS) data set on your USS environment, mount it, and set the owner and file permissions. Defining programs to CICS region for CICS adapter server-side components ------------------------------------ Before using the CICS adapter, define the programs to the CICS region that will be running the CICS adapter server-side components. The programs can be defined to CICS by adding statements to the CICS CSD definitions. To update the CSD, use the definitions in the DTXCRDEF member of the DTX.SDTXSAMP PDS included in the installation. The DTXCRDEF file contains example RDO commands. Add the DTX.SDTXLOAD load library to the DFHRPL concatenation for the CICS region that will be running the CICS adapter server-side components. For additional information about using the CICS adapter, see the CICS adapter documentation (1105.pdf) that is posted on the product Web site (www.ibm.com/software/integration/wtx). ===================================================================== 4. IBM WEBSPHERE TRANSFORMATION EXTENDER WITH COMMAND SERVER ===================================================================== Configuration steps ------------------- Binding the DB2 plan -------------------- For configuration steps for the Data Base Request Module (DBRM) that is included with the installation files, see the Binding the Data Base Request Module (DBRM) section. Examples -------- There are several examples that are described in the following readme files installed in the DTX.SDTXSAMP PDS and are used to demonstrate the various feature components. For your Batch environment: DTXBMRME - Burst Map example DTXDMRME - DB2 Map example - run only if you will be using the DB2 adapter DTXMQRME - WebSphere MQ example - run only if you will be using the IBM WebSphere MQ adapter DTXMSRME - Resource Registry example - run only if you will be using the Resource Registry Names to make calls. ===================================================================== 5. IBM WEBSPHERE TRANSFORMATION EXTENDER WITH LAUNCHER ===================================================================== Configuration steps ------------------- The files that are installed with the IBM WebSphere Transformation Extender with Launcher require you to do some configuration steps. UNIX System Services (USS) -------------------------- For additional configuration steps that are common to other IBM WebSphere Transformation Extender features installed on UNIX System Services (USS), see the Additional configuration on USS section that is in the Information common to all the features section. z/OS native administration interface ------------------------------------ Before you use the z/OS native administration interface for the IBM WebSphere Transformation Extender with Launcher, make sure that the IBM XML Toolkit for z/OS v1.8 load library has been added to the system linklist or the TSO logon PROC STEPLIB. Adding the XML load library for the native administration interface ----------------------------------- If you are using the z/OS native administration interface for the IBM WebSphere Transformation Extender with Launcher, the IBM XML Toolkit for z/OS v1.8 load library (default name is IXM.SIXMLOD1) needs to be defined to the system linklist or in the TSO logon PROC STEPLIB. ===================================================================== 6. IBM WEBSPHERE TRANSFORMATION EXTENDER FOR MESSAGE BROKER ===================================================================== Configuration steps ------------------- For additional configuration steps that are common to other IBM WebSphere Transformation Extender features installed on UNIX System Services (USS), see the Additional configuration on USS section that is in the Information common to all the features section. Updating the WebSphere Message Broker for z/OS environment ---------------------------------------------------------- The Message Broker environment file (ENVFILE) needs to be updated with the exported environment variables required by the IBM WebSphere Transformation Extender for Message Broker z/OS UNIX System Services (USS) runtime environment. Updating WebSphere Message Broker V6 ENVFILE -------------------------------------------- As a result of running the DTXINST JCL, the process created the dtxmqsi.sh shell script in the IBM WebSphere Transformation Extender for Message Broker z/OS runtime environment that it defined: /wtx_dir/mqsi/dtxmqsi.sh The wtx_dir location refers to the z/OS runtime environment where the DTXINST JCL job deployed the installed IBM WebSphere Transformation Extender for Message Broker z/OS feature. This script contains the commands that will set the environment variables required by the IBM WebSphere Transformation Extender for Message Broker z/OS run time. To update the ENVFILE, do the following steps: 1. Add the following command line to the end of the profile member, BIPBPROF, located in the PDSE data set for the brokers: . /wtx_dir/wmqi/dtxwmqi.sh 2. Run the BIPGEN JCL that is located in the PDSE for the brokers to recreate the ENVFILE environment file. The BIPGEN JCL will invoke the shell script specified in the command line that you added to the BIPBPROF profile member, which will set the required environment variables. For information on editing the BIPBPROF member and running the BIPGEN JCL, see the WebSphere Message Broker Version 6.0 information center. Updating WebSphere Message Broker V5 ENVFILE -------------------------------------------- The IBM WebSphere Transformation Extender for Message Broker z/OS environment variables need to be added manually. Update the mqsicompcif file for the broker instance that will be interfacing with IBM WebSphere Transformation Extender for Message Broker on z/OS. To update the ENVFILE, do the following steps: 1. Update the following environment variables: PATH - add /wtx_dir/bin to the list LIBPATH - add /wtx_dir/libs to the list LILPATH - add /wtx_dir/wmqi to the list 2. Add the following variables to the Environment Variable Section of the mqsicompcif file: DTX_HOME_DIR=/wtx_dir DTX_TEMP_DIR=/wtx_dir/tmp 3. Run the mqsicustomize command to recreate the ENVFILE file. For information about editing the mqsicompcif file and customizing the broker, see the WebSphere Business Integration information center. ===================================================================== 7. IBM WEBSPHERE TRANSFORMATION EXTENDER ===================================================================== The IBM WebSphere Transformation Extender feature supports the following execution environments: - z/OS Software Development Kit - UNIX System Services Software Development Kit - IMS/TM - CICS CICS environment ---------------- The IBM WebSphere Transformation Extender includes the CICS Execution Option through which you can run maps in your CICS environments. Prior to this release, this functionality was provided in the CICS Command Server product. Configuration steps for the CICS environment -------------------------------------------- The files that are installed with the IBM WebSphere Transformation Extender require you to do some configuration steps. Loading maps ------------ To use the IBM WebSphere Transformation Extender feature on CICS execution environments, and to successfully complete the IVP, you must load the IBM WebSphere Transformation Extender executable maps into a VSAM keyed-sequential data set (KSDS) by doing the following steps: - Define the VSAM cluster used to store IBM WebSphere Transformation Extender executable maps. You can use the sample DTXCIJCL JCL to define the VSAM KSDS. - Extract, format, and load IBM WebSphere Transformation Extender maps into the VSAM map KSDS. You can use the sample DTXCMJCL JCL that will extract, format, and load the maps into the VSAM KSDS that was defined by the DTXCIJCL JCL. Language Environment (LE) Requirement ------------------------------------- The transformation server is ported to CICS using the IBM "C/C++" compiler and requires the z/OS Language Environment runtime libraries. The z/OS IBM WebSphere Transformation Extender for the CICS execution environment is compatible with all supported releases of Language Environment (LE). This will require that LE support be installed in CICS. (Optional) Setting up the DB/2 (z/OS) adapter to use the CICS CAF --------------------------------------------- To use the DB/2 (z/OS) adapter, you will need to set it up to use the CICS DB/2 Attachment Facility. You will be updating the CSD. For information about updating the CSD, see the IBM CICS System Definition Guide. To set up the adapter to use the CICS DB/2 Attachment Facility: 1. Bind the Data Base Request Module (DBRM). See the Binding the Data Base Request Module (DBRM) section. 2. Create a DB2ENTRY in the CICS CSD for the DBUTILE plan. 3. Create DB2TRAN entries in the CICS CSD for each CICS transaction that will call the z/OS IBM WebSphere Transformation Extender for the CICS execution environment and invoke a DB2 map. 4. Create a DB2TRAN entry in the CICS command line for the DTXI (used for backward compatibility to a previous release) and DTXT transactions. 5. If your site uses the RCT macro, DSNCRCT, to define the entries for the CICS DB/2 Attachment Facility, you will need to code and assemble the DSNCRCT TYPE=ENTRY macro instruction to add the entry for the DBUTILE plan. Multiple versions of the IBM WebSphere Transformation Extender for the CICS execution environment in a Single CICS region -------------------------------------------------------------- Description ----------- If you are installing this feature for the first time, continue with the Updating CICS CSD definitions section. This feature enables people who use the IBM WebSphere Transformation Extender for the CICS execution environment or the Mercator Integration Broker or Ascential DataStage TX to run multiple versions of these products concurrently in a single CICS region. The benefit of this feature is the ability to do a staged migration to IBM WebSphere Transformation Extender while being able to run your existing product release in the same CICS region. This feature is only available starting with Ascential DataStage TX version 7.5. As of Ascential DataStage TX 7.5, only one prior release of Ascential DataStage TX can be used at the same time as this version. For more information, see the topic on Multiple Command Server versions in the z/OS CICS section of the Command Server documentation (1010.pdf) that is posted on the product Web site (www.ibm.com/software/integration/wtx). If you are not installing multiple versions of the these products in the same CICS region, continue with the Updating CICS CSD definitions section. Installing multiple versions ---------------------------- - Complete the feature installation steps as defined in this document. - Install IBM WebSphere Transformation Extender for the CICS execution environment in a region that has an existing version of the Mercator Integration Broker or Ascential DataStage TX. - Both versions will be separate instances of the product for the CICS execution environment that can run concurrently. - The CICS RDO definitions supplied with this release contain resource definitions that provide backwards compatibility for existing users of the product for the CICS execution environment. These definitions will create conflicts and render the prior release unusable. Before installing the RDO definitions for this release, either comment out or delete the following items: - program entry: MERCCICS or DSTXCICS - transaction definitions: MERC or DSTX - for the start CICS transaction MERT, DSTT or DSTX - for the start the test sample transaction Note: If you do not comment out or delete the above items, these RDO definitions will create conflicts between an older release and the new release and as a result, you will not be able to use the prior release. There are multiple program entry and transaction definitions options depending on which release of the product for the CICS execution environment you currently have installed. - Do not delete the CICS RDO group, TSIMERC or ASCLDSTX. - Place the data set definition of the IBM WebSphere Transformation Extender load library for the CICS execution environment for this release after the load library of the existing release in the DFHRPL concatenation. Updating CICS CSD definitions ----------------------------- The IBM WebSphere Transformation Extender for the CICS execution environment installs the DTXCTBL file in the DTX.SDTXSAMP PDS, which contains the RDO definitions. Use the supplied RDO definitions to update the CICS CSD definitions, defining transactions, programs and data sets for the region or regions where you will be using the IBM WebSphere Transformation Extender for the CICS execution environment. If you plan to run multiple, concurrently executing IBM WebSphere Transformation Extender for the CICS execution environment tasks that share the map keyed-sequential data sets (KSDS), set the CSDSTRNO parameter for the map KSDS equal to the maximum number of concurrently executing tasks you want to allow in the z/OS CICS region. Note: If you are adding the IBM WebSphere Transformation Extender to an existing IBM WebSphere Transformation Extender installation (meaning, that this is not a new installation), you must update the CSD. Unless you are planning on running multiple versions of IBM WebSphere Transformation Extender in a single CICS region, remove the ASCLDSTX group from the CSD and add the new system definitions. Note: The use of CICS Temporary Storage Queues might increase if you upgrade from Mercator Integration Broker or Ascential Datastage TX. The VSAM-based work space manager has been replaced with a TSQ-based work space manager. The benefits of using a TSQ-based work space manager is that it simplifies the installation process and improves the performance of your map execution. The storage requirements for TSQ may be impacted. You must ensure that there enough TSQ available. For more information about how to size temporary storage, see the Sizing Temporary Storage section. Sizing temporary storage ------------------------ Temporary Storage Queue (TSQ) is used to back IBM WebSphere Transformation Extender work spaces required to run a map. Work space refers to a physical store that is used to shadow input and output data. Shadow data is usually created when the map uses an adapter or Transient Data Queues, or the map is expecting the data to contain record seperators. Work spaces are also used by the core transformation services to store information about the data that is being mapped. Because you can develop a map with no inputs and outputs, work spaces may not be used in some situations. The minimum number of possible work spaces for a map execution is 1. The maximum possible number is 1 + (2 * number of inputs) + (2 * number of outputs). TSQ will not be used by a map if the map's source and targets are passed as memory buffers and the workspace in memory option (-WM) is used. Each work space is keyed by a unique TSQ qname. The format of the qname is TXnnnnnNddddddd, where nnnnn is the CICS task id and ddddddd is a sequence number. In theory, the maximum size of a single work space is 1,073,545,221 bytes. To calculate the TSQ space requirements for a particular map you need to determine the maximum data size of each input and each output. The formula for a specific input is: TSQ size = (max data size * 5) The criteria for the multiplier of 5 is 1 for the shadow file and 4 for the work space used by the core transformation service. The amount of space required by the core transformation service may actually be less. It depends on a number of factors such as the number of objects being validated. Four (4) is typical for a complex type tree with lots of types defined. Sizing Temporary Storage Example: This section presents an example of how the temporary storage for a map is sized. Assume that your map has two inputs and one output. Input 1 is a Websphere MQ message. Input 2 is a lookup from a DB/2 table. The target destination for the output is to DB/2. The MQ message is 100,000 bytes. The DB/2 lookup is 1,200 bytes. The target destination for the output is to DB/2 and is 25,000 bytes. Work space estimates: Input 1 500,000 = 100,000 + (100,000 * 4) Input 2 6,000 = 1,200 + (1,200 * 4) Output 1 25,000 = 25,000 Map total size is: 531,000. In this example, the actual amount of TSQ used will be greater based on the fact that the size of the TSQ records used by the work space manager is 32,763. Also, the map's page size setting will determine the minimum amount of space used by the core. Assuming a 64K page size setting, the estimate would be: Input 1 622,497 = ((100,000 / 32,763) + 32,763) + ((((400,000 / 65,535) + 65,535) / 32,763) + 32,763) Input 2 131,052 = 32,763 + ((65,535 / 32,763) + 32,763) Output 1 32,763 New map total size is 786,312. The actual required amount will depend on how many 64K pages are necessary to validate the input. An additional factor for which you need to account when sizing temporary storage is the maximum number of concurrent transactions that will be running the map. Assuming there can be 3 concurrent tasks, the total temporary storage would be: 2,358,936 = 3 * 786,312 (Optional) Defining and loading the Resource Name file ------------------------------------------------------ Optionally define and load the VSAM entry-sequenced data set (ESDS) that stores the DTXCRMRN resource name file. The step should be done only if you want to use the IBM WebSphere Transformation Extender resource name file, and successfully complete the IVP for the Resource Registry example described in the DTXCRRME readme file. To use the resource name file on CICS, create the resource name file. For information about creating the resource name file (.mrn) on Windows, see the IBM WebSphere Transformation Extender Resource Registry documentation (1041.pdf). The DTXCRMRN example resource name file is provided in the IBM WebSphere Transformation Extender installation in the DTX.SDTXSAMP PDS. Examples for the CICS environment --------------------------------- There are several examples that are described in the following readme files installed in the DTX.SDTXSAMP PDS and are used to demonstrate the various feature components. See the Loading maps section for the required configuration steps. DTXRVRME - Burst Map example DTXCDRME - DB2 Map example - run only if you will be using the DB2 adapter and the DB2 plan DTXCMRME - WebSphere MQ example - run only if you will be using the IBM WebSphere MQ adapter DTXCRRME - Resource Registry example - run only if you will be using the Resource Registry - for configuration requirements, see the (Optional) Defining and loading the Resource Name file section IMS environment --------------- Configuration steps for the IMS environment ------------------------------------------- There might be configuration steps required for you to do before you can use the IBM WebSphere Transformation Extender feature, depending on your business needs and if specific system administration and set up prerequistites have not yet been done in your IMS environment. For more information, see the IMS/DC Execution Option (1103.pdf) documentation that is posted on the product Web site (www.ibm.com/software/integration/wtx). (Optional) Binding the DB2 plan ------------------------------- For configuration steps for the Data Base Request Module (DBRM) that is included with the installation files, see the Binding the Data Base Request Module (DBRM) section. UNIX System Services (USS) Software Development Kit --------------------------------------------------- For additional configuration steps that are common to other IBM WebSphere Transformation Extender features installed on UNIX System Services (USS), see the Additional configuration on USS section that is in the Information common to all the features section. Note: For information about using the API on USS, see the the Platform API documentation (1020.pdf) that is posted on the product Web site (www.ibm.com/software/integration/wtx). ===================================================================== 8. INFORMATION COMMON TO ALL THE FEATURES ===================================================================== Binding the Data Base Request Module (DBRM) ------------------------------------------- Upgrading from an earlier version --------------------------------- If you are using the DB2 (z/OS) adapter with your current release of the IBM WebSphere Transformation Extender and with a prior release or prior releases of the IBM WebSphere Transformation Extender concurrently, we suggest binding the application plans as a package. This will allow multiple releases of the IBM WebSphere Transformation Extender to be bound to the same application plan. Binding the DBUTILE application plan ------------------------------------ If you have not already bound the DBRM, you will need to do the configuration steps described in this section so that you can use the DB2 CAF adapter. There is only one Data Base Request Module (DBRM), named DBUTILE. It is contained in the DTXDBUTE member of the DTX.SDTXSAMP PDS included with the installation files. It can be bound as the DBUTILE plan by running the DTXBIND JCL that is included in the feature installation, or bound as a package and included in a plan of your choice. The DBUTILE plan name will be used when the DB2 adapter connects to the DB2 subsystem where its DB request module was bound. For more instructions on binding the application plan using the sample DTXBIND JCL, see the Command Server documentation (1010.pdf) that is posted on the product Web site (www.ibm.com/software/integration/wtx). Additional configuration on USS ------------------------------- DTXINST ------- The DTXINST JCL job is used create the IBM WebSphere Transformation Extender UNIX System Services (USS) runtime environment. Run this job if you have not yet run it to deploy the installed files on USS and only after you have installed one or more of the following features: JDTX812 Transformation Extender JDTX813 Transformation Extender for Message Broker JDTX814 Transformation Extender with Launcher Modify the SET INSTHOME statement in the JCL to define the location of your IBM WebSphere Transformation Extender - Common Components base feature installation if it is different than the default location settings. The default location is: /usr/lpp/dtx/V8R1M0/IBM/common Modify the SET CRTHOME statement in the JCL to define the location of the directory structure where you want the UNIX System Services (USS) runtime environment for the optional features you installed to be created if it is different than the default location settings. The default location is: /u/dtxuser/dtx When you run the DTXINST JCL, it will run the SET commands, and then run the following two steps: MAKEDIR and INSTALL. MAKEDIR step ------------ The MAKEDIR step runs the BPXBATCH MVS utility program, which uses a MKDIR command to create the IBM WebSphere Transformation Extender home directory. INSTALL step ------------ The INSTALL step runs the BPXBATCH MVS utility program, which runs the createuser shell script from the bin directory of the IBM WebSphere Transformation Extender - Common Components base feature. The script creates the following subdirectories in the IBM WebSphere Transformation Extender home directory (DTX_HOME_DIR) location, specified in the CRTHOME setting, and installs the files from the location specified in the INSTHOME setting into these subdirectories: config libs bin systems maps data logs tmp dump src wmqi Note: The wmqi subdirectory is created if you have installed the IBM WebSphere Transformation Extender for Message Broker optional feature. The createuser shell script creates symbolic links to the bin, libs and config directories of the installed IBM WebSphere Transformation Extender features. It also creates the setup shell script and optionally creates the deploy shell script for the IBM WebSphere Transformation Extender for Message Broker if you have installed this optional feature. The INSTALL step uses the INSTHOME symbolic parameter to identify the installed location of the common components directory and the CRTHOME symbolic parameter to identify the location of the user runtime directory. (Optional) Binding the DB2 plan ------------------------------- For configuration steps for the Data Base Request Module (DBRM) that is included with the installation files, see the Binding the Data Base Request Module (DBRM) section. Setting USS environment variables --------------------------------- - Set the export _CEE_RUNOPTS environment variable. If you are using Java 1.4.2 on a z/OS operating system and you want to use the IBM WebSphere Transformation Extender in your UNIX System Services (USS) execution environment, you must add XPLINK to the _CEE_RUNOPTS USS environment variable: export _CEE_RUNOPTS=$_CEE_RUNOPTS,"XPLINK(ON)" - Modify the setup script in the current directory to set the DISPLAY, JAVAHOME and _BPX_SHAREAS environment variables. The setup script defines the environment variables required to run the IBM WebSphere Transformation Extender. The DISPLAY, JAVAHOME and _BPX_SHAREAS environment variables are defined as the following: - DISPLAY is the address of the X Server. - JAVAHOME is the install directory of JAVA v1.4.2 on the mainframe. - _BPX_SHAREAS determines whether or not the z/OS shell will run foreground processes in the same address space in which the shell is running. These environment variables can either be uncommented in the setup script or included in your profile (.profile). Note: The DISPLAY and JAVAHOME variables are currently commented out in the script, while the _BPX_SHAREAS variable is not. Note: If you include these settings in your profile (.profile) in your UNIX System Services (USS) home directory, you can avoid having to reset these variables each time you install the IBM WebSphere Transformation Extender in your USS environment. - Set the environment variables for IBM WebSphere Transformation Extender. Enter ". ./setup" at the command prompt from the directory where you deployed the runtime environment under UNIX System Services (USS) for the IBM WebSphere Transformation Extender features that you have installed. Now you can begin to run the IBM WebSphere Transformation Extender that you installed on your UNIX System Services (USS) execution environment. (Optional) Defining DB2 system load library ------------------------------------------- To use either the DB2 (z/OS), and DB2 (z/OS(ODBC)) adapter in your UNIX System Services (USS) execution environment, the hlq.SDSNLOAD DB2 system load library needs to be defined to the system linklist. Otherwise, the STEPLIB variable will need to be exported with the location of the DB2 load library as follows: export STEPLIB=hlq.SDSNLOAD where hlq is the high-level qualifier for the DB2 installation Each time you run the IBM WebSphere Transformation Extender, you can use this export statement at the shell prompt or you can add the export statement to the /etc/profile or the .profile file of the specific user of the feature. (Optional) Defining IBM WebSphere MQ system load libraries ---------------------------------------------------------- To use the IBM WebSphere MQ adapter in your UNIX System Services (USS) execution environment, the IBM WebSphere MQ system load libraries need to be defined to the system linklist. Otherwise, the STEPLIB variable will need to be exported with the location of the IBM Websphere MQ load libraries as follows: export STEPLIB=hlq..SCSQANLE:hlq.SCSQAUTH where hlq is the high-level qualifier for the IBM Websphere MQ installation. Each time you run the IBM WebSphere Transformation Extender, you can use this export statement at the shell prompt or you can add the export statement to the /etc/profile or the .profile file of the specific user of the feature. (Optional) Accessing Oracle 9i database --------------------------------------- The Oracle 9i client adapter is available for you to use in maps on your UNIX System Services (USS) execution environment. This adapter allows access to data stored in Oracle 9i databases on remote systems. To be able to access data using the Oracle 9i client adapter: - Install and configure Oracle 9i. - Be sure that Oracle 9i is included in the PATH= environment variable and that other environment variables required by the Oracle 9i database are set appropriately. Note: Environment variables required by the Oracle 9i database that are involved with translation from ASCII to EBCDIC require particularly close attention. - Support is not currently provided for direct connection to an Oracle database on the same z/OS system on which the IBM WebSphere Transformation Extender is executing. (Optional) Using Language Environment parameters ------------------------------------------------ The IBM WebSphere Transformation Extender UNIX System Services (USS) execution environment is a 31-bit application. The Language Environment (LE) parameters at many sites are optimized for COBOL programs and 24-bit applications. To prevent the application from running out of memory because it lacked storage below the 16 megabyte (MB) line, and then terminating abnormally with an ABEND code such as 80A, the LE parameters listed below are recommended. Note: These LE parameters are documented in the "z/OS: Language Environment Programming Reference" publication. Put the following LE parameters in an export statement to be added to the .profile file of the specific user of the feature. Memory Management STACK(128K,64K,ANY,FREE) HEAP(256K,64K,ANY,FREE) HEAPPOOLS(ON) Error Management TER(UADUMP) or TER(UAIMM) Examples: (The following LE parameters must be placed all on one line, without any space between them.) _CEE_RUNOPTS="TER(UADUMP),STACK(128K,64K,ANY,FREE),HEAPPOOLS(ON), HEAP(256K,64K,ANY,FREE)" (Optional) Defining port numbers when using the E-mail adapter -------------------------------------------------------------- The e-mail adapter is available for use in maps run on your UNIX System Services (USS) execution environment. To ensure correct operation of the e-mail adapter, you need to define the port numbers for SMTP and pop3 in the "TCPIP.ETC.SERVICES" or /etc/services files. - The well-known port number for SMTP is 25. - The well-known port number for pop3 is 110. - For a complete list and discussion of well-known port numbers, see the Internet Assigned Numbers Authority (IANA) website at http://www.iana.org. Using Transformation Extender on USS ------------------------------------ The IBM WebSphere Transformation Extender contains JAVA interfaces, which include a number of components that are available for you to be able to run the UNIX System Services Software Development Kit on z/OS operating systems running on the mainframe in a UNIX environment. Note: To see all the components that have been included in this feature release, see the Web site (www.ibm.com/software/integration/wtx). There are some fundamental differences between how the Java Virtual Machine (JVM) interacts with IBM WebSphere Transformation Extender in the UNIX System Services (USS) execution environment as opposed to how it interacts with IBM WebSphere Transformation Extender on other platforms. These differences are related to the native character encoding of USS and the JVM. The USS environment is based on EBCDIC whereas the Java JVM underlying encoding is based on UTF-8. LATIN-1 data is the most appropriate data type to exchange with the JVM. As a result, there are a couple of things you need to consider when writing a map to call a Java-based adapter on UNIX System Services (USS) as listed below: - All character text data items that will be passed to the adapter should be defined in the type tree with the "Data language" property set to ASCII. - The Java-based adapter will typically return an ASCII-encoded byte stream. In most cases, the format of the output results that will be returned from the adapter and passed to the map should be defined in the type tree with the "Item Subclass" property set to "Text" and the "Interpret as" property set to "Binary", especially, if the results will be the input into another map or adapter. For additional information regarding the Java programming code page considerations, see the reference information for Java on z/OS on the IBM web site. ===================================================================== 9. CONTACTING CUSTOMER SUPPORT ===================================================================== Contact Customer Support at 1-800-IBM-SERV or from the product page of the IBM Web site: www.ibm.com/software/integration/wtx ===================================================================== 10. NOTICES AND TRADEMARKS ===================================================================== This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 577 Airport Blvd., Suite 800 Burlingame, CA 94010 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, a nd represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Programming interface information --------------------------------- Programming interface information, if provided, is intended to help you create application software using this program. General-use programming interfaces allow you to write application software that obtain the services of this program's tools. However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software. Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change. Trademarks and service marks ---------------------------- The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States or other countries, or both: AIX AIX 5L Ascential Ascential DataStage Ascential Software CICS DataStage DB2 DB2 Universal Database Domino HelpNow Hiperspace IBM the IBM logo ibm.com i5/OS IMS Informix iSeries Lotus Lotus Notes MQIntegrator MQSeries MVS Notes OS/390 OS/400 Passport Advantage pSeries Redbooks SupportPac S/390 System z Tivoli WebSphere z/Architecture z/OS zSeries Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others. This product includes software developed by the Eclipse Project (http://www.eclipse.org/). WebSphere Transformation Extender, Version 8.1