IMS Connector for Java User's Guide and Reference - CiteSeerX

IMS Connect

IMS Connector for JavaUser’s Guide and ReferenceVersion 1 Release 2 Modification 2

��

IMS Connect

IMS Connector for JavaUser’s Guide and ReferenceVersion 1 Release 2 Modification 2

��

Edition Notice

This edition applies to IMS Connector for Java, a component of Version 1 Release 2 Modification 2 of IMS Connect(product number 5655–E51) and to all subsequent releases and modifications until otherwise indicated in neweditions.

© Copyright International Business Machines Corporation 1998, 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Note!Before using this information and the product it supports, be sure to read thegeneral information under Notices.

Contents

Chapter 1. Understanding IMS Connector for Java . . . . . . . . . . . 1Prerequisites for using IMS Connector for Java . . . . . . . . . . . . . 8

VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . 8WebSphere Application Server . . . . . . . . . . . . . . . . . . 9IMS Connect . . . . . . . . . . . . . . . . . . . . . . . . . 9IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Platform Configurations for IMS Connector for Java and IMS Connect . . . . 10IMS Connector for Java concepts and terms . . . . . . . . . . . . . . 32IMS Connector for Java conversational programming models . . . . . . 34Migrating from CCF architecture to J2EE connector architecture. . . . . . . 40

Migrating IMS Connector for Java EAB Commands to J2EE . . . . . . . 41Running a CCF Servlet in WebSphere Application Server 4.0 for Windows 42Running a CCF Servlet in WebSphere Application Server 4.0 for z/OS and

OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Chapter 2. Preparing to use IMS Connector for Java . . . . . . . . . . 53Preparing your VisualAge for Java environment . . . . . . . . . . . . . 54Preparing your WebSphere Studio environment . . . . . . . . . . . . . 58Preparing your WebSphere Application Server environment for Windows . . . 59Preparing your WebSphere Application Server environment for z/OS and

OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Chapter 3. Building Java applications and servlets . . . . . . . . . . 77Building CCF Java applications and servlets . . . . . . . . . . . . . . 77Building J2C Java applications and servlets . . . . . . . . . . . . . . 78Building Java applications and servlets for conversational transactions . . . . 79

Chapter 4. Building a Java application to run an IMS transaction . . . . . 81

Chapter 5. Building a Java application to run a navigator . . . . . . . . 95

Chapter 6. Building a Java application for an IMS transaction withmulti-segment output messages . . . . . . . . . . . . . . . . 109

Chapter 7. Building a Java application for an IMS transaction withmulti-segment input messages . . . . . . . . . . . . . . . . . 117

Chapter 8. Building an application to run an IMS transaction withsynchronization level confirm . . . . . . . . . . . . . . . . . 125

Chapter 9. Building the graphical user interface . . . . . . . . . . . 129

Chapter 10. Building a Java servlet to run an IMS transaction . . . . . 137

Chapter 11. Building a Web application that uses one servlet to run anIMS conversation . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 12. Building a Web application that uses two servlets to run anIMS conversation . . . . . . . . . . . . . . . . . . . . . . 165

Chapter 13. Building a J2C phonebook sample application . . . . . . . 173Part 1: Building the J2C phonebook sample application . . . . . . . . . 173Part 2: Assembling the J2C phonebook sample application . . . . . . . . 188

© Copyright IBM Corp. 1998, 2002 iii

Part 2A: Assembling and deploying the J2C phonebook sample application forWindows . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Part 2B: Assembling and deploying the J2C phonebook sample application forz/OS and OS/390 . . . . . . . . . . . . . . . . . . . . . . 192

Part 3: Running the J2C phonebook sample application . . . . . . . . . 196

Chapter 14. Building a J2C conversational phonebook sample application 197Part 1: Building a J2C conversational phonebook sample application 198Part 2A: Assembling and deploying the J2C conversational phonebook

sample application for Windows . . . . . . . . . . . . . . . . 210Part 2B: Assembling and deploying the J2C conversational phonebook

sample application for z/OS or OS/390 . . . . . . . . . . . . . . 214Part 3: Running the J2C conversational phonebook sample application 217

Chapter 15. Building Container-Managed and Component-ManagedTransactional EJBs to Run IMS Transactions . . . . . . . . . . . 219

Part 1: Preparing for the sample . . . . . . . . . . . . . . . . . . 220Part 2: Creating the sample. . . . . . . . . . . . . . . . . . . . 221Part 3: Packaging and Deploying the sample . . . . . . . . . . . . . 241Part 4: Running the sample . . . . . . . . . . . . . . . . . . . . 248

Appendix A. IMS INSTALL/IVP sample application . . . . . . . . . . 251

Appendix B. Using the trace and error logging facility . . . . . . . . 253Turning on the trace and error logging facility for IMS Connector for Java CCF

components. . . . . . . . . . . . . . . . . . . . . . . . . 253Turning on the trace and error logging facility for IMS Connector for Java J2C

components. . . . . . . . . . . . . . . . . . . . . . . . . 257Customizing the trace facility . . . . . . . . . . . . . . . . . . . 257Reading the error log . . . . . . . . . . . . . . . . . . . . . . 258Reading the trace log . . . . . . . . . . . . . . . . . . . . . . 259

Appendix C. Diagnosing problems related to sockets . . . . . . . . . 261Diagnosing problems related to connection pooling . . . . . . . . . . . 262If your Java application or servlet does not respond . . . . . . . . . . . 262

Appendix D. Messages and exceptions . . . . . . . . . . . . . . 263Exceptions generated by IMS Connector for Java CCF applications . . . . . 264Exceptions generated by IMS Connector for Java J2C applications . . . . . 274

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Programming interface information . . . . . . . . . . . . . . . . 289

Trademarks and service marks . . . . . . . . . . . . . . . . . . 291

iv IMS Connector for Java User’s Guide and Reference

Chapter 1. Understanding IMS Connector for Java

IMS Connector for Java provides a way to create Java applications that can accessIMS transactions. In conjunction with the VisualAge for Java developmentenvironment, IMS Connector for Java lets you rapidly develop Java applications thatrun your transactions. With additional support from IBM WebSphere ApplicationServer, you can build and run Java servlets that access your transactions from Webpages.

IMS Connector for Java uses IMS Connect to access IMS. IMS Connect is a facilitythat runs on the host IMS machine and supports TCP/IP and Local Optioncommunication to IMS. A Java application or servlet accesses IMS OpenTransaction Manager Access (OTMA) through IMS Connect. IMS Connect acceptsmessages from its TCP/IP clients and routes them to IMS OTMA using theCross-System Coupling Facility (XCF).

IMS Connector for Java is comprised of 2 components:

v The development component of IMS Connector for Java is provided withVisualAge for Java. The VisualAge for Java Enterprise Access Builderenvironment enables you to develop Enterprise Access Builder (EAB) commands,Enterprise JavaBeans (EJBs), servlets, and Java applications that use IMSConnector for Java to access IMS transactions. VisualAge for Java also providesa WebSphere test environment that you can use to test the programs youdevelop.

v The runtime component of IMS Connector for Java is provided as a componentof IMS Connect Version 1 Release 2 (Program Number 5655-E51). The Java 2Platform (J2EE) Connector (J2C) Architecture implementation of this runtimecomponent is also referred to as the IBM WebSphere Adapter for IMS. It ispackaged as a RAR file, imsico.rar, for deployment into the J2C compliantWebSphere Application Server. The RAR file is installed to a target directory fromthe IBM IMS Connect, Version 1 Release 2.

WebSphere Application Server provides an environment in which you can run theservlets and EJBs that you develop from Web pages. WebSphere ApplicationServer is the primary runtime environment for the servlets and EJBs. In theWebSphere Application Server environment, IMS Connector for Java is alsoreferred to as the IBM WebSphere Adapter for IMS.

Related Reading: See “Prerequisites for using IMS Connector for Java” for moreinformation.

This section describes IMS Connector for Java. It includes:

v What’s New in IMS Connector for Java Version 1.2.2 (page 1)

v Overview of IMS Connector for Java (page 2)

v Java 2 Platform Enterprise Edition (J2EE) support in IMS Connector for Java(page 4)

v Sample Applications (page 6)

What’s New in IMS Connector for Java Version 1.2.2

The current release of IMS Connector for Java introduces the following:

v J2C support for WebSphere Application Server for z/OS and OS/390

© Copyright IBM Corp. 1998, 2002 1

v Global transaction (2-phase commit) support when using Local Optioncommunication in the z/OS and OS/390 environment

v Container-managed security support when using Local Option communication inthe z/OS and OS/390 environment

v Local Option support for J2C applications

Overview of IMS Connector for Java

Figure 1 shows an overview of the environments involved in developing and runningJava application programs and servlets that use IMS Connector for Java to accessIMS transactions. A Java application typically includes a graphical user interface(GUI). A Java servlet typically uses a Web browser with HTML or JSP files as theuser interface.

Figure 1. Developing Java applications and servlets using IMS Connector forJava

The steps illustrated in Figure 1 are as follows:

1. Provide your COBOL source file to VisualAge for Java’s Enterprise AccessBuilder tool. The COBOL file contains data structures for the IMS transactioninput and output messages. The COBOL file is typically the source of the IMSapplication program for the transaction. However, if your IMS applicationprogram is not written in COBOL you can represent the input and outputmessages as COBOL data structures and provide them to the EnterpriseAccess Builder tool.

2. Use the VisualAge for Java Command Editor, an Enterprise Access Builder tool,to create an Enterprise Access Builder (EAB) command. The EAB command isa composite Java bean that can be used to build either a Java servlet or astand-alone Java application program that accesses IMS transactions. A Javaservlet runs on a Java application server such as IBM’s WebSphere ApplicationServer and uses a Web browser for transaction input and output. A stand-aloneJava application does not use a Java application server and typically uses agraphical user interface (GUI) for transaction input and output. In either case,VisualAge for Java can be used to quickly build a simple Java applicationprogram to execute the IMS transaction. This program can be easily run, withinVisualAge for Java, in order to prove that the EAB command runs the IMStransaction.

3. If you are building a Java servlet to run your IMS transaction:

a. Use VisualAge for Java’s Create Servlet SmartGuide to generate HTML,JSP, and Java files for the servlet from the EAB command which youprovide to the wizard.

2 IMS Connector for Java User’s Guide and Reference

b. Deploy the HTML files, JSP files, and Java servlet files to your WebSphereApplication Server environment to enable users to access the IMStransaction from a Web browser.

VisualAge for Java provides the IBM WebSphere Test Environment that you canuse to test and debug your servlet prior to deploying it to a productionWebSphere Application Server.

4. If you are building a stand-alone Java application to run your IMS transaction:

a. Build a user interface for transaction input and output. Typically this is doneby using VisualAge for Java to build the GUI and to execute the EABcommand.

b. Deploy the Java application files to the machine on which you wish to runthe application.

Deploying stand-alone applications involves updating a CLASSPATH environmentvariable so that they can access the IMS Connector for Java runtime classes. Whendeploying applications to WebSphere Application Server, the CLASSPATHenvironment variable in updated in the deployment process. The ApplicationAssembly Tool is used to create an Enterprise Archive (EAR) file which is thendeployed to WebSphere Application Server. For more information about EAR files,see the “J2EE Modules” section in “IMS Connector for Java Concepts and Terms.”

Figures 2 and 3 show how you run either a stand-alone Java application program ora Java servlet to access your IMS transactions.

Figure 2. Running a Java application that uses IMS Connector for Java


1. Typically for Java applications, a GUI is used to provide input for the IMStransaction (1) and display the output from the IMS transaction (4).

2. The Java application accesses IMS Connector for Java via class libraries and,in the case of Local Option, a shared library.

3. IMS Connector for Java builds an OTMA message containing the transactioninput message and sends it to IMS Connect, which in turn sends it to OTMAusing XCF. OTMA passes the IMS transaction input message to IMS andreceives the IMS transaction output message from IMS. OTMA returns anOTMA message containing the transaction output message to IMS Connect,which in turn sends it to IMS Connector for Java.

4. The output of the IMS transaction is displayed by the Java application using theGUI.

Chapter 1. Understanding IMS Connector for Java 3

Figure 3. Running a servlet that uses IMS Connector for Java


1. The HTML file containing the input HTML form is displayed on the Web browser.The user provides the input data for the IMS transaction on this HTML form andpresses the ″Submit″ button (or its equivalent). WebSphere Application Serverschedules the servlet.

2. The servlet executes the EAB command, which in turn invokes IMS Connectorfor Java. If the version of WebSphere Application Server that is running theJava servlet does not include the class libraries used by the servlet, these classlibraries can be deployed to WebSphere Application Server in the form of JARfiles.

3. IMS Connector for Java builds an OTMA message and sends it to IMS Connect,which in turn sends it to OTMA using XCF. OTMA sends the IMS transactioninput message to IMS and receives the IMS transaction output message fromIMS. The IMS transaction output message is sent back to IMS Connect byOTMA. IMS Connect then sends it to the servlet using IMS Connector for Java.

4. The output of the IMS transaction is displayed on the Web browser by the Javaservlet using a JSP file.

The method used by IMS Connector for Java to send and receive OTMA messagesdepends on the runtime environment of IMS Connector for Java and IMS Connect.If both your Web server and IMS Connect are running in the same MVS image, youcan choose to use either TCP/IP or Local Option for communication between IMSConnector for Java in the servlet and IMS Connect. Otherwise, only TCP/IP can beused for communications between IMS Connector for Java and IMS Connect.

Java 2 Platform Enterprise Edition (J2EE) Support in IMS Connector for Java

IMS Connector for Java includes both a Common Connector Framework (CCF)implementation and a Java 2 Platform (J2EE) Connector (J2C) Architectureimplementation.

This release of IMS Connector for Java introduces J2C support for the z/OS andOS/390 platform. See “Prerequisites for using IMS Connector for Java” for moreinformation on getting this support.

The J2EE Connector architecture defines a standard architecture for connecting theJ2EE platform to heterogeneous Enterprise Information Systems (EISs) such asIMS. The J2C architecture uses an J2EE connector (also known as a resourceadapter), such as IMS Connector for Java. By conforming to the J2EE Connectorarchitecture, which is defined and standardized as part of the Java 2 Platform,Enterprise Edition (J2EE), the resource adapter no longer needs to be customized


for each J2EE application server to connect to the EIS. In addition, the J2EEConnector Architecture defines a set of standard programming interfaces thatdetermine how a J2EE application interacts with a J2EE Resource Adapter toconnect to the EIS. As a result, by using the J2EE Connector Architecture, theJ2EE applications do not require the addition of custom code to connect to differentEISs.

For more information on the J2EE architecture and its concepts, see the J2EEConnector Architecture Specification at http://java.sun.com/j2ee/download.html fordetails.

IMS Connector for Java’s implementation of the J2EE Connector Architecture willbe provided in phases. The list below is an overview of the support provided in thisrelease of IMS Connector for Java for J2C. For a list of classes provided, see “IMSConnector for Java concepts and terms.”

v Common Client Interface

IMS Connector for Java provides an implementation of the J2C Common ClientInterface (CCI).

Java clients use the CCI in the following ways:

– Using the IMS Connector for Java in conjunction with the EnterpriseApplication Integration (EAI) frameworks that are based on the CCI, such asthe Enterprise Access Builder for Transactions (EAB). This method isillustrated by the J2C samples provided in the Connector IMS Samples projectand described in “Building a J2C phonebook sample application” and “Buildinga conversational phonebook sample application.”

– Programming directly against the CCI. This method is not described in theIMS Connector for Java documentation. For more information on the J2EEprogramming model, including use of the CCI, see VisualAge for Java’s Helpby clicking Help > Concepts > Access to transaction systems >Connectors > J2EE Application Programming Model.

v Connection Management

IMS Connector for Java, in collaboration with WebSphere Application Server,provides connection pooling that is transparent to the servlet or EnterpriseJavaBean (EJB). Connection pooling implies connection reuse. For example, aconnection consisting of a TCP/IP socket between IMS Connector for Java andIMS Connect is reused for multiple transaction requests. A socket is not closedand re-opened between transaction requests.

v Error Logging and Tracing

IMS Connector for Java provides error logging and tracing through a traceLevelcontrol. Allowable values for traceLevel are defined in the interfaceIMSTraceLevelProperties. “Using the trace and error logging facility” describeshow to use WebSphere Application Server in conjunction withIMSTraceLevelProperties to control tracing and logging.

v Migration

IMS Connector for Java provides the class IMSConnectorMigrator for use byVisualAge for Java tooling to migrate Enterprise Access Builder (EAB) commandsfrom IBM’s Common Connector Framework (CCF) Architecture to Sun’s Java 2Platform, Enterprise Edition (J2EE) Connector Architecture (J2C). Information onmigration of IMS Connector for Java applications can be found in “Migrating fromCCF architecture to J2EE connector architecture.”

v Packaging and Deployment

The runtime piece of IMS Connector for Java is packaged as the ResourceAdapter Archive (RAR) file imsico.rar for deployment into the J2C compliant


WebSphere Application Server. For instructions on deploying this RAR file, see“Preparing your WebSphere Application Server Environment for Windows” or“Preparing your WebSphere Application Server Environment for z/OS andOS/390.”

v Security

For WebSphere Application Server for workstation platforms, IMS Connector forJava currently supports component-managed sign-on only.

For WebSphere Application Server for z/OS and OS/390, IMS Connector for Javasupports both container and component-managed sign-on. For more informationabout the J2C security support for IMS Connector for Java, see “IMS SecurityInformation for J2C” in “IMS Connector for Java concepts and terms.”

v Supported Platforms

In this release, J2C support is provided for the following platforms:

– AIX

– z/OS and OS/390

– Solaris

– Windows

v Transaction Management

In the current release, IMS Connector for Java provides global transactionsupport known as 2-phase commit using MVS Resource Recovery Service (RRS)with WebSphere Application Server for OS/390 and z/OS.

This release of IMS Connector for Java does not provide transaction support withWebSphere Application Server on workstation platforms. For more informationabout J2C transaction support for IMS Connector for Java, see “TransactionManagement for J2C” in the “IMS Connector for Java concepts and terms.”

Generally, the process for developing J2C applications and servlets is as follows:

1. Ensure that the IMS Connector for Java RAR file (imsico.rar) has beendeployed on the WebSphere Application Server. For more information on how todeploy IMS Connector for Java to your target WebSphere Application Server,see “Preparing your WebSphere Application Server environment for Windows”or “Preparing your WebSphere Application Server Environment for z/OS andOS/390” for more information.

2. Ensure that connection factories have been created and configured for theWebSphere Application Server. For more information on how to create andconfigure connection factories, see “Preparing your WebSphere ApplicationServer environment for Windows” or “Preparing your WebSphere ApplicationServer Environment for z/OS and OS/390” for more information.

3. Import COBOL source to VisualAge for Java. See “Building a Java application torun an IMS transaction” for an example of how to complete this step and thesteps below.

4. Create a servlet or EJB using VisualAge for Java’s Enterprise tooling.

5. Create an Enterprise Application using the Application Assembly Tool (AAT).

6. Deploy the Enterprise Application to WebSphere Application Server.

7. Run the Enterprise Application in WebSphere Application Server.

Sample Applications

IMS Connector for Java provides a number of CCF and J2C sample applicationsand information about them. The following is a list of the provided samples:

v CCF samples:


– Building a Java application to run an IMS transaction

– Building a Java application to run a navigator

– Building a Java application for an IMS transaction with multi-segment outputmessages

– Building a Java application for an IMS transaction with multi-segment inputmessages

– Building an application to run an IMS transaction with synchronization levelconfirm

– Building the graphical user interface

– Building a Java servlet to run an IMS transaction

– Building a Web application that uses one servlet to run an IMS conversation

– Building a Web application that uses two servlets to run an IMS conversation

v J2C samples:

– Building a J2C phonebook sample application

– Building a J2C conversational phonebook sample application

– Building container-managed and component-managed transactional EJBs torun IMS transactions

Preparing to deploy J2C samples

Before you can deploy any of the J2C samples described in this documentation,you must package them into enterprise archive (EAR) and Web archive (WAR) files.To do this, use the Application Assembly Tool (AAT), provided with WebSphereApplication Server. Two AATs are available, depending on the platform on which youare deploying the samples:

v AAT for distributed platforms (such as Windows, AIX, and Solaris)

v AAT for the z/OS and OS/390 platform

The AAT for distributed platforms allows you to create EAR and WAR files.

The AAT for OS/390 and z/OS does not provide the functionality to create WARfiles. This AAT is required when creating EAR files that will be deployed on thez/OS and OS/390 platform. You can also import any EAR files that were built for thedistributed platforms into this AAT and rebuild it for a z/OS and OS/390 system.

If you don’t have an AAT for distributed platforms, you can build the WAR filesneeded to create EAR files using the JAR command provided with a JavaDevelopment Kit (JDK). See below for more information.

v AAT for distributed platforms

The AAT for distributed platforms is shipped with WebSphere Application Serverfor that specific platform. For more information on assembling an application on adistributed platform, see the IBM WebSphere Application Server InformationCenter at http://www-3.ibm.com/software/webservers/appserv/infocenter.html.

v AAT for z/OS and OS/390

The AAT for z/OS or OS/390 platforms is shipped with WebSphere ApplicationServer for that specific platform. The tool and the documentation for it are alsoavailable for download on the Web at http://www-3.ibm.com/software/webservers/appserv/zos_os390/index.html. The samples forz/OS and OS/390 described in this documentation require an additional classpathconfiguration to avoid warnings about missing classes. Add theAAT_USER_PATH variable to the list of system variables for the platform on


which the AAT will be run. You should set this variable to point to the foldercontaining the JAR files that are required by the IMS Connector for Java (forexample, C:\IBMCON~1\classes\). For more information, see the section ″Noteon updating the AAT classpath″ in the AAT readme.txt file.

v Java Development Kit

Ensure that a Java Development Kit (JDK) is installed on your system. Todownload and set up JDKs, see the products and documentation available athttp://java.sun.com.

Note: You can find additional files associated with the samples in theC:\<IBM_Connectors_install_dir>\imsconn\samples directory, where<IBM_Connectors_install_dir> is the IBM Connectors installation directory (forexample, C:\IBM Connectors).

Three subdirectories exist under the ”samples“ directory: J2C, servlets and misc.The ”J2C“ directory contains folders for J2C samples, the ”servlet“ directorycontains folders for each CCF sample and the ”misc“ directory containsmiscellaneous files relating to the samples. For more information about the files,see context.txt in the ”samples“ directory.

For the J2C samples, a pre-built EAR file is provided for you. This EAR file can beinstalled and run in WebSphere Application Server for distributed platforms (such asWindows, AIX, Solaris) and z/OS and OS/390. You can find the EAR files in the”was“ subfolder for your J2C sample.

Prerequisites for using IMS Connector for JavaThe following is a list of minimum software requirements for IMS Connector forJava:

v VisualAge for Java Enterprise Edition Version 4.0

v WebSphere Application Server (for version information, see below)

v IMS Connect Version 1 Release 2

v IMS Version 7 Release 1

To run a Java application that uses the J2C implementation of IMS Connector forJava, IMS and IMS Connect must be installed and running on your host machine.

VisualAge for JavaVisualAge for Java Enterprise Edition 4.0 is the required development environmentfor the IMS Connector for Java.

The installation of VisualAge for Java 4.0 provides you with the CCF (CommonConnector Framework) implementation of IMS Connector for Java.

To use the J2EE Connector Architecture (J2C) implementation of IMS Connector forJava, you need to add the following updates to your VisualAge for Java 4.0environment:

v VisualAge for Java Beta J2EE Connectors support is required to use the J2Csupport. Follow the instructions in “IBM Enterprise Access Builder BETA NOTES4.0” on the VisualAge for Java 4.0 Additional Features installation CD. Thisinformation is in the readme.eab file in the \extras\BetaJ2EEConnectors folder onthe Additional Features installation CD.


v The J2C implementation of IMS Connector for Java is provided as an update toIBM VisualAge for Java Enterprise Edition Version 4.0. This update is availableon the VisualAge Developer Domain at http://www7.software.ibm.com/vad.nsf.Once this update is applied, both the Common Connector Framework (CCF) andJ2C implementations are available when you add the IMS Connector feature toyour VisualAge for Java workbench. This feature allows you to developapplications using VisualAge for Java’s Enterprise Access Builder and the J2Cimplementation of IMS Connector for Java.

WebSphere Application ServerIMS Connector for Java using the Common Connector Framework (CCF) supportsthe following WebSphere Application Server platforms:

v AIX

v Linux for zSeries and S/390

v z/OS and OS/390

v Solaris

v Windows

The J2C implementation of IMS Connector for Java supports deployment toWebSphere Application Server on the following platforms:

v WebSphere Application Server Advanced Edition 4.0 for Windows

v WebSphere Application Server Advanced Edition 4.0 for AIX

v WebSphere Application Server Advanced Edition 4.0 for Solaris

v WebSphere Application Server V4.0.1 for z/OS and OS/390

Important: APAR PQ55873 is required for running the J2C implementation ofIMS Connector for Java on z/OS and OS/390.

IMS ConnectIBM IMS Connect Version 1 Release 2 is required to use the J2C implementation ofIMS Connector for Java.

The runtime component of IMS Connector for Java is provided as an update to theIMS Connector for Java component of the IMS Connect Version 1 Release 2product.

If you plan to use the J2C implementation of IMS Connector for Java runningWebSphere Application Server on the z/OS and OS/390 platform, the followingAPARs for IBM IMS Connect, Version 1 Release 2 (Program Number 5655-E51)are required:

v APAR PQ57192

This APAR updates the IMS Connector for Java component with J2C and2-phase commit support for WebSphere Application Server for z/OS and OS/390.It installs the IMS Connector for Java runtime component (the RAR file forWebSphere Application Server for z/OS and OS/390) to a target directory onyour system.

v APAR PQ57191

This APAR updates the IMS Connect component with 2-phase commit support tobe used by IMS Connector for Java.


IMSIBM IMS Version 7 Release 1 or later is required to use IMS Connector for Java.

v APAR PQ57868

This APAR must be applied to your IMS V7.1 system if you plan to use J2C andglobal transaction (2-phase commit) support on WebSphere Application Serveron z/OS and OS/390.

Platform Configurations for IMS Connector for Java and IMS ConnectIMS Connector for Java can be deployed and configured to run on WebSphereApplication Server on various platforms. The TCP/IP and Local Optioncommunication protocols are supported for both CCF and J2C applications toconnect to IMS Connect. Additionally, using Local Option for 2-phase committransactions is supported in a z/OS and OS/390 environment. For moreinformation, see “IMS Connector for Java Concepts and Terms.”

IMS Connector for Java can be configured to run on WebSphere Application Serveron various platforms and uses TCP/IP or Local Option communication protocols toconnect to IMS Connect. The Local Option communication protocol is nowsupported for both CCF and J2C applications. In addition to TCP/IP, you can nowuse Local Option to establish communication between IMS Connector for Java andIMS Connect V1.2 for both CCF and J2C applications, provided that both IMSConnector for Java and IMS Connect exist in the same MVS image.

The following table summarizes the available communication protocols and the levelof transaction support supplied by the runtime component of IMS Connector forJava on various platforms. In this table, the heading “Platform of WebSphereApplication Server with IMS Connector for Java” refers to the fact that theWebSphere Application Server can be configured to access all of the IMSConnector for Java class libraries. See “Preparing your WebSphere ApplicationServer environment for Windows)” or “Preparing your WebSphere ApplicationServer Environment for z/OS and OS/390” for more information.

Platform of WebSphereApplication Server withIMS Connector for Java

Supported CommunicationProtocols

Transactional (2-phasecommit) Support

AIX TCP/IP (CCF and J2C) No

Linux for zSeries and S/390 TCP/IP (CCF) No

z/OS, OS/390 TCP/IP (CCF and J2C)

Local Option* (CCF and J2C)

Yes with Local Option (J2Conly)**

Solaris TCP/IP (CCF and J2C) No

Windows TCP/IP (CCF and J2C) No

Restrictions:

* To use Local Option for communication between IMS Connector for Java and IMSConnect, both IMS Connector for Java and IMS Connect must exist in the sameMVS image.

** To use Transactional (2-phase commit) support in this release, IMS Connector forJava, IMS Connect, WebSphere Application Server, and IMS must exist in the sameMVS image. Future releases of IMS Connector for Java will remove this restriction.


Important: Throughout this documentation, platform specific information in thesamples and examples pertains to the Windows platform. Information for all othersupported platforms is available on the IMS Connector for Java Web pages, locatedin the IMS Web site at www.ibm.com/ims. You can also find some additionalsamples and examples for non-Windows platforms on the Web. CCF examples andsamples for non-Windows platforms can be found on this Web site.

IMS Connector for Java concepts and termsThis section provides an overview of some of the concepts and terminology neededto understand IMS Connector for Java. It includes:

v Connecting with Local Option (page 11)

v Connection Management in the CCF implementation (page 12)

v Connection Management in the J2C implementation (page 14)

v EAB commands that use IMS Connector for Java (page 15)

v Enterprise JavaBeans (EJB) (page 15)

v IMS Conversations (page 16)

v IMS Messages (page 17)

v IMS Security Information (page 19)

– For CCF (page 19)

– (For J2C)

v Java Classes that are Provided with IMS Connector for Java for CCF (page 22)

v Java Classes that are Provided with IMS Connector for Java for J2C (page 27)

v J2EE Modules (page 28)

v MFS Formatting (page 29)

v Synchronization Level (page 29)

v Transaction Management for J2C (page 31)

– Global Transaction and 2-Phase commit processing

– Types of J2C transactions:

- Component-managed (or bean-managed) transactions

- Container-managed transactions

- IMS Connector for Java J2C transaction support

The information in this section pertains to IMS Connector for Java using both theCommon Connector Framework (CCF) and the Java 2 Platform Enterprise Edition(J2EE) Connector (J2C) Architecture, unless otherwise indicated.

Connecting with Local Option

IMS Connector for Java allows you to use either TCP/IP or the Local Option supportfor connections between IMS Connector for Java and IMS Connect. Local Optionprovides non-socket access to IMS transactions and data from z/OS and OS/390WebSphere Application Servers (where the servlet or Enterprise JavaBean usingIMS Connector for Java is running).

You can use Local Option in both CCF and J2C implementations of IMS Connectorfor Java.

Using Local Option in the CCF Implementation


To use Local Option in the CCF implementation of IMS Connector for Java,set the Host Name property of the IMSConnectionSpec bean to LOCALHOST:ims_connect_name. The IMS Connect name is case-sensitive and must matchthe ’HWS ID’ of the target IMS Connect. Local Option will then be used forcommunication between servlets executing IMS Connector for Java EABcommands and IMS Connect. If LOCALHOST: ims_connect_name is notspecified (that is, the first ten characters of the host name are anything otherthan “LOCALHOST:”,) then IMS Connector for Java will assume that it is aTCP/IP host name and will attempt to use TCP/IP communications. Thecharacters in LOCALHOST are not case-sensitive; the ims_connect_name iscase-sensitive.

Development of EAB commands for use by servlets that use Local Option isdone on VisualAge for Java for Windows. Setup of IMS Connector for JavaLocal Option on an OS/390 machine requires deployment of an additionalclass library, the Local Option shared library libimsconn.so, which is shippedwith the IMS Connector for Java runtime component and packaged inside theimsico.rar file.

Using Local Option in the J2C Implementation

To use Local Option with J2C, define the IMS Connect name property of theIMSManagedConnectionFactory with a 1 to 8 alphanumeric character name ofthe target IMS Connect. The IMS Connect name is case-sensitive and mustmatch the ’HWS ID’ of the target IMS Connect. Local Option is then used forcommunication between IMS Connector for Java and IMS Connect. If the IMSConnect name property is not specified, IMS Connector for Java uses thevalue specified in the Hostname and Port number property and defaults tousing TCP/IP communications instead.

Setting up IMS Connector for Java Local Option for J2C on a z/OS andOS/390 machine requires deployment of an additional class library, the LocalOption shared library libimsico.so, which is shipped with the IMS Connector forJava runtime component.

Connection Management in the CCF implementation

Connection management support is a set of functions that allow the connectorframework for both CCF and J2C to automatically provide and manage connectionsto your backend enterprise information systems. Connection pooling and reuse areimportant aspects of this connection management support. Connection pooling,through the reuse of connections, is key to enhancing the performance of Javaapplications or servlets that access IMS transactions. Reuse of connectionsminimizes the overhead of connection initialization and significantly enhancesperformance.

Connection management is a feature provided by the IBM Common ConnectorFramework (CCF). CCF is a set of Java APIs that provides infrastructure serviceslike connection management, transaction services, security, and tracing facilities toJava applications and servlets. CCF currently provides two types of connectionmanager:

com.ibm.connector.internal.DefaultConnectionManagerDefaultConnectionManager is the default connection manager used by theRuntimeContext classes (specifically, RuntimeContext andJavaRuntimeContext) shipped with VisualAge for Java. It does not support


connection pooling. A new connection is created for each transactionrequest and the connection is disconnected when the transaction iscomplete.

com.ibm.connector.connectionmanager.ConnectionManagerConnectionManager is a ’real’ connection manager that supports connectionpooling. It maintains one or more pools of reusable connections for IMSConnect.

For TCP/IP connections, there is a separate pool of reusable connectionsfor each Hostname/Port number combination used by IMS Connector forJava.

For Local Option connections, there is a separate pool of reusableconnections for each IMS Connect used by IMS Connector for Java.

When the ConnectionManager class is used with IMS Connector for Java, aconnection with IMS Connect is obtained for each transaction request.When the request has been completed (or the last request, in the case of aconversational application, has been completed), the connection is thenreturned back to the pool to be reused by subsequent requests.

There should be one instance of the ConnectionManager class used within acomponent server (for example, WebSphere Application Server). If your componentserver supports the CCF infrastructure, a single instance connection manager wouldbe established and be accessed by the servlets using IMS Connector for Java. Ifyour component server does not support the CCF infrastructure, you can use aseparate servlet to implement a single global instance of the ConnectionManagerobject. This single instance can then be accessed by any other servlet whoseconnection manager in RuntimeContext has been set to this ConnectionManagerobject.

As a result, to ensure connection pooling is established properly in your componentserver for running your servlet requests with CCF connectors, there must be oneinstance of connection manager AND the type of connection manager being usedmust support connection pooling (for example, the typecom.ibm.connector.connectionmanager.ConnectionManager).

IMS Connector for Java has provided a sample implementation of a servlet thatstores a single global connection manager of typecom.ibm.connector.connectionmanager.ConnectionManager in the ServletContext.The source code of the servlet is in the RegisterConnectionManager servlet in thecom.ibm.connector.ims.sample.cm package included in the IMS Connector Samplefeature. This sample could be used when your component server does not supportthe CCF infrastructure or it does not use a type of connection manager thatsupports connection pooling. This sample servlet must be loaded once when thecomponent server starts to establish the connection manager. To load the sampleservlet, invoke the following URL from your web browser:http://serverhostname/servlet/com.ibm.connector.ims.sample.cm.

RegisterConnectionManager

where serverhostname is the hostname of your component server.

To access the global instance of the ConnectionManager from the ServletContext inyour servlet code, add the following sample code in the method that uses executesthe EAB command (for example, for a servlet generated by WebSphere Studio, itwill be placed in the performTask() method). This code should be placed before theexecute() method of the EAB command is called:


// Access the global instance of ConnectionManager from the ServletContext.ServletConfig sc = getServletConfig();ServletContext sctx = sc.getServletContext();com.ibm.connector.connectionmanager.ConnectionManager connMgr =

(com.ibm.connector.connectionmanager.ConnectionManager)sctx.getAttribute(“CCFConnectionManager);

// Setup the Connection Manager with the RuntimeContextRuntimeContext.getCurrent().setConnectionManager(connMgr);

A sample usage of the above code can be found in the servlet examples included inthe Connector IMS Samples project of Visual Age for Java.

Note: IMS Connector for Java always uses a persistent connection (sometimesreferred to as a persistent socket) with IMS Connect. IMS Connect enforces thisconnection type for both TCP/IP socket and Local Option PC connections. WhenIMS Connector for Java is running with CCF connection pooling, the connection willbe returned to the CCF connection pool when the transaction is complete. Theconnection will remain active for reuse by another client and the connection will notbe disconnected. When IMS Connector for Java is not running with CCF connectionpooling, the connection type between IMS Connector for Java and IMS Connect isstill persistent. However, at the end of the client transaction, the connection will bedisconnected. Thus, when CCF connection pooling is not being used, theconnection is still a persistent one but has the appearance of a transactionconnection (also known as a transaction socket). In this case, IMS Connector forJava (instead of IMS Connect) disconnects the connection upon completion of eachIMS transaction request.

Connection Management in the J2C implementation

Application components using the J2C implementation of IMS Connector for Javaare targeted for the WebSphere Application Server implementation of the J2Cconnection management contract, which supports connection pooling and reuse.WebSphere Application Server’s Connection Manager maintains a connection poolfor each hostName/portNumber combination for TCP/IP connections. For LocalOption connections, a separate pool of reusable connections exist for each IMSConnect used by IMS Connector for Java.

For WebSphere Application Server for workstation platforms (like Windows, AIX,Solaris), you can configure the pooling properties for each connection pool. Forinstructions on how to edit the connection pooling properties, see the WebSphereApplication Server Advanced Edition Information Center for workstation platforms.For a description of connection pooling properties, see the VisualAge for Javadocumentation by clicking Help > Help Home Page > Reference > IBM APIs >Enterprise Access Builder for Transactions > Packagecom.ibm.connector2.spi.ConnectionPoolProperties.

When you are testing your application components in VisualAge for Java’sWebSphere Test Environment, you must run additional code in order to haveconnection pooling. For details, read the information provided for the J2EE JSP andservlet sample in the VisualAge for Java documentation by clicking Help > HelpHome Page > Samples > Enterprise Access Builder for Transactions >WebSphere Set > J2EE JSP and servlet sample.

In addition, samples of servlets that can be used when running in VisualAge forJava’s WebSphere Test Environment can be found in packagecom.ibm.ivj.eab.sample.ws.j2ee.servlet of the IBM Enterprise Access BuilderWebSphere Samples project.


Note: IMS Connector for Java always uses a persistent connection (sometimesreferred to as a persistent socket) with IMS Connect. IMS Connect enforces thisconnection type for both TCP/IP socket and Local Option PC connections. WhenIMS Connector for Java is running in a managed environment that supportsconnection pooling, such as WebSphere Application Server, the connection will bereturned to the connection pool when the transaction is complete. The connectionwill remain active for reuse by another client and the connection will not bedisconnected. When IMS Connector for Java is running in an environment that doesnot support connection pooling, the connection type between IMS Connector forJava and IMS Connect is still persistent. However, at the end of the clienttransaction, the connection will be disconnected. Thus, when connection pooling isnot being used, the connection is still a persistent one but has the appearance of atransaction connection (also known as a transaction socket).

EAB commands that use IMS Connector for Java

EAB commands that use IMS Connector for Java are developed with the VisualAgefor Java Command Editor. An EAB command built for IMS Connector for Java is acomposite Java bean that consists of the following:

v A Java bean (page 22) representing the input to the IMS transaction

v One or more Java beans representing the output from the IMS transaction

v An IMSConnectionSpec bean (for CCF), representing the connection betweenthe EAB command and the IMS Connect host component

v A Connection Factory Configuration object (for J2C) for specification ofconnection information.

v An IMSInteractionSpec bean containing information about the type of interactionthat the EAB command has with IMS using IMS Connect. The CCFIMSInteractionSpec also contains the name of the target IMS datastore.

v A DFSMsg bean

This bean processes potential error or status messages (DFS messages) fromIMS. These messages begin with the three characters DFS.

For the differences between building CCF and J2C EAB commands, see theVisualAge for Java documentation by clicking Help > Help Home Page >Concepts > Access to transaction systems > Enterprise Access Builder forTransactions > EAB constructs > How Commands in J2EE and CCF differ.

Enterprise JavaBeans (EJB)

The IMS Connector for Java implementation of Sun’s Java 2 Platform, EnterpriseEdition Connector (J2C) Architecture introduces the use of Enterprise JavaBeans(EJB) to build your applications. An EJB defines how server-side components arewritten and provides a standard architectural contract between the components andthe application servers and containers that manage them.

The two types of EJBs are entity beans and session beans.

Entity beanAn entity bean is an EJB that represents the data in your database directly.It handles multiple instances of that data being called by multiple clients.Entity beans do not contain business process logic. They are only used tomodel data within the database and contain functions that are used todirectly initialize, modify, or remove that data.


Session beanThe bean class of session beans implement business logic. The lifetime ofa session bean is shorter than that of an entity bean. Generally, sessionbeans have the lifetime equivalent of a client session. The client sessionlasts as long as the client is connected to the application. Session beansare unique to each client. Session bean information and state are notshared between clients. The two types of session beans are statefulsession beans and stateless session beans.

Stateful session beanA stateful session bean holds a conversation that can span manymethod calls. The same bean can be used to serve all of themethod calls that come from a single client. During thisconversation, the bean holds conversational state for that client.Conversational state is information sent to or acquired by the beanthat can be referenced throughout the life of the conversation. Theconversational state of a stateful session bean is stored in the beaninstance fields.

Stateless session beanA stateless session bean holds a conversation that spans a singlemethod call. After each method call, a stateless session beanreleases any information from the previous method call andbecomes available to serve a new request.

VisualAge for Java Version 4.0 offers the EJB Development Environment featurethat helps you create EJBs.

Related Information: For more information on EJB and J2EE, see the VisualAgeDeveloper Domain at http://www7.software.ibm.com/vad.nsf. For more informationon session beans and these two types, see the IBM Redbook EJB Developmentwith VisualAge for Java for WebSphere Application Server, SG24-6144-00, availableat http://www.ibm.com/redbooks.

IMS Conversations

IMS Connector for Java Conversational Support allows customers to build Javaapplications and Web applications to access IMS conversational transactions.

A conversational IMS transaction is a transaction that is defined to IMS as beingconversational, meaning that it can be invoked repeatedly to process the individualsteps of a conversation. An IMS conversation is made up of a connected series ofclient-to-program-to-client interactions. Although multiple IMS application programsmay be involved in the processing of a conversation or even the processing of asingle interaction, only a single client can participate in a conversation. In order toparticipate in an ongoing IMS conversation, a transaction must be conversational. Inother words, it must be defined as conversational to IMS and it must conform to therequirements of IMS conversational processing. If control is passed to anonconversational program during a conversation, IMS will terminate theconversation. The IMS conversational program receives messages from the client,processes the requests and replies to the client. It also saves the intermediate datafrom the transaction in the scratch pad area (SPA). When the user enters moredata from the client, the program has access to the data it saved from the lastmessage in the SPA, and thus can continue processing the request without having


the user enter that data again. When the client sends a message to initiate the nextiteration of the conversation, the program uses the data in the new message alongwith the data it saved in the SPA at the end of the last iteration of the conversationas its input. In more complex conversations, different transactions can be invokedusing an immediate or deferred program switch.

Related Reading: For more information on IMS conversations in general, as wellas information on more in-depth topics such as program switching, refer to IMSConversations in Application Programming: Transaction Manager and GatheringRequirements for Conversational Processing in Application Programming: DesignGuide of the IMS books.

In a Web application that takes part in an IMS conversation, the user submits aseries of requests each of which invokes a Java servlet which in turn processes aniteration of the conversation. In fact, different servlets can be used to process theiterations of a given conversation depending on how you program the input HTMLand input/output JSP pages of the application. However, all of the servlets must usethe same connection. This is handled automatically by the connection managerwhen you use a connection manager that supports connection pooling. For eachiteration, the Java servlet receives an input request from the browser and utilizesIMS Connector for Java to send a conversational transaction request to IMS usingIMS Connect. IMS Connect then forwards the transaction request to IMS throughOTMA. IMS schedules the conversational transaction that either continues theexisting conversation or starts a new IMS conversation (if this is the first iteration ofa conversation). The IMS application processes the request and sends the outputback to the Java servlet using IMS Connect and IMS Connector for Java. The Javaservlet then loads the appropriate JavaServer Page to display the output of thatiteration to the user in the browser.

IMS Connector for Java Conversational Support provides two programming modelsfrom which to build a conversational Web application. The programming models arethe Conversational HttpSession Model and the Conversational Navigator Model.

The following commands, however, are not supported for IMS conversations thatare initiated using IMS Connector for Java Conversational Support:/EXIT*/HOLD/RELEASE

*Note: For a servlet that simulates the /EXIT command, see the packagecom.ibm.connector.ims.sample.conv.forcend.servlet in the Connector IMS Sampleproject.

IMS Messages

An EAB command for a typical IMS transaction includes Java beans that representthe IMS transaction input and output messages. These beans are constructed byVisualAge for Java’s Enterprise Access Builder by first parsing the COBOL sourceof the IMS transaction’s application program. The Enterprise Access Builder toolthen uses this information to create the transaction input and output beans thatmatch the input and output messages received and sent by that IMS applicationprogram.

The degree to which VisualAge for Java can create Java beans that accuratelyrepresent an IMS transaction’s input and output messages is limited by the way inwhich messages are defined in the COBOL application program. To overcome these


limitations, if any, you can create files that contain 01 level COBOL definitions forthe input and output messages used by your COBOL IMS application program. Youcan then use these files in the Enterprise Access Builder instead of the originalCOBOL IMS application program. This technique can also be used if your IMSapplication program is not written in COBOL

Related Reading: For more information on the COBOL parser and its limitations,see the VisualAge for Java documentation. Click Help > Help Home Page >Concepts > Access to transaction systems > Enterprise Access Builder forTransactions > Limitations.

The messages sent to IMS or received from IMS by a Java application or servletusing IMS Connector for Java can be any of the following:

v IMS transaction input messages

v IMS transaction output messages

v IMS status or error messages (also called ”DFS“ messages)

v IMS commands

v IMS command output messages

IMS Connector for Java is primarily designed to handle the first three types ofmessages. IMS messages, both input and output, can consist of multiple segments.“Building a Java application for an IMS transaction with multi-segment outputmessages” and “Building a Java application for an IMS transaction withmulti-segment input messages” provide examples of how to create Javaapplications that run IMS transactions with multiple segment messages. For atransaction input or output message, no restrictions exist on the number ofsegments. The IMS Connector for Java-supplied bean, DFSMsg, supports bothsingle-segment IMS output messages and multiple-segment IMS output messagesof 22 segments or less. These ”DFS“ output messages are sent by IMS to reflectIMS errors or status changes in response to a transaction request received by IMS.They are also returned as the output response from an IMS command. While it ispossible to submit a command to IMS from a Java application or servlet using IMSConnector for Java that generates more than 22 segments of command output, thatJava application or servlet is restricted to receiving a maximum of the first 22segments of that command output.

Message segments that are sent to and received from IMS transactions alwaysbegin with a 2-byte segment length field (called LL), followed by a 2-byte field thatcontains IMS information (called ZZ). The 2-byte segment length field representsthe length of the entire message segment, including the LL and ZZ fields. The dataof the message segment follows the LL and ZZ fields. In the case of the firstsegment of the transaction’s input message, up to the first the first n+1 bytes of thedata portion of the segment contain the n-byte transaction code, followed by ablank.

COBOL definitions that represent transaction input and output message segmentsmust contain fields for the segment length, the IMS information, and the dataportions of a segment. A Java application or servlet must ”set“ the individual fieldsof a transaction input message segment before sending that segment to IMS. Thefields are set by doing the following:

v Set the individual fields of the data portion of message segments using ”set“methods. Typically values for these methods are provided by the end user usinga GUI or input HTML page. In some cases values for ”set“ methods, such as thetransaction code, can be ”hard-coded“ in the Java program.


v Set the segment length field (LL) to be the sum of the defined lengths of all thedata fields, plus 4. If LL is not set correctly, IMS Connector for Java might throwan exception or unpredictable results might occur, depending upon the IMSapplication program. Consider adding a method to your EAB command that usesthe getSize() method of com.ibm.record.CustomRecord to return the size of yourtransaction input message.

v Setting the IMS information field (ZZ) is optional.

Note: If your IMS application program is written in PLI, you must represent thetransaction input and output messages in COBOL in order to use the EnterpriseAccess Builder to generate Java beans for the EAB command. The COBOL datastructures are created by ”mapping“ the message data structures in the PLI IMSapplication program. The only exception is that the segment length field, LL, mustbe mapped to a COBOL definition that represents 2 bytes. When the PLITDLIinterface is used, IMS adjusts the LL field of the input message presented to theIMS application program from 2 bytes to 4 bytes, and conversely, from 4 bytes to 2bytes on output. As is normally the case for the PLITDLI interface, the segmentlength field (LLLL) is defined in the IMS application program as 4 bytes and thevalue in the LLLL field is the input message length minus 2.

IMS Security Information

The IMS logon information (user ID, password, and group name) provided to a Javaapplication or servlet is used by IMS Connector for Java for both CCF and J2Cimplementations as follows:

The user ID, password, and group name are placed in the OTMA message sent byIMS Connector for Java to the host component, IMS Connect. IMS Connect thencalls the host’s Security Authorization Facility (SAF) under control of the IMSConnect RACF state SETRACF command:

v If RACF=Y (the SETRACF ON command has been issued), the SAF is called. Ifuser authentication succeeds, the UTOKEN built by the SAF is passed on to IMSfor authorization. If user authentication fails, IMS Connect returns an error to IMSConnector for Java.

v If RACF=N (the SETRACF OFF command has been issued), the SAF is notcalled by IMS Connect. The user ID and group name are passed on to IMS forauthorization.

Four levels of authorization are available in IMS. These levels are controlled by theIMS command, /SECURE OTMA, as follows:

1. If /SEC OTMA NONE is issued, no authorization is performed.

2. If /SEC OTMA CHECK is issued, the UTOKEN or user ID and group name arepassed to the SAF to ensure the user (in the group) is authorized to execute thetransaction (or command).

3. If /SEC OTMA FULL is issued, in addition to performing CHECK levelauthorization, a user security profile is built in the MPP region for use bynon-IMS services.

4. If /SEC OTMA PROFILE is issued, the result is the same as if /SEC OTMAFULL is issued, because IMS Connector for Java sets the Security Data sectionof the OTMA message prefix for each transaction to the FULL option.

For CCF:


Be sure to read the section under ”IMS Security Information (page 19)“ (above),which applies to both CCF and J2C implementations.

Relationship of IMS logon information to EAB commandsIMS logon information is set in the run-time context of a Java application or servlet.For example:com.ibm.connector.imstoc.IMSLogonInfoItems logon =

new com.ibm.connector.imstoc.IMSLogonInfoItems(runtimeContext.getLogonInfo(),cmd.getConnectionSpec());

logon.setUser(”yourUID“);logon.setPassword(”yourPwd“);logon.setGroup(”setGroup“);

Typically this is performed at the beginning of an application or servlet, and lasts forthe duration of the application or servlet. However, in some situations, it might bedesirable to change the IMS logon information within an application or servlet. Forexample, an application or servlet might run multiple transactions that belong todifferent groups. In this case, the setGroup() method must be invoked before eachexecute of an EAB command in order to set the appropriate group name for thetransaction that the command runs. This applies to both of the following cases:

v A different EAB command is used for each transaction

v The same EAB command is used for all the transactions

In certain situations the same EAB command can be used for multiple transactions.For example, multiple transactions might have the same input and output messagestructure but different transaction codes.

The IMS logon information can be changed between invocations of the execute()method for the same EAB command. This is useful if, for example, the same EABcommand is used for different transactions, and the transactions have differentgroup names.

For J2C:

Be sure to read the section under ”IMS Security Information (page 19)“ (above),which applies to both CCF and J2C implementations.

The following table summarizes the J2C security support for the current release ofIMS Connector for Java.

WebSphere Application Server with IMSConnector for Java platform

Supported Resource Authentication Type

Application(Component-managed)

Container(Container-managed)

Windows, AIX, Solaris Yes No

z/OS, OS/390 Yes Yes (with LocalOption only)

When a J2C application component requests a connection to an EnterpriseInformation System (EIS) resource (such as IMS Connect or IMS), the EIS mightrequire a sign-on to that resource. Two options are available to the J2C applicationfor managing EIS sign-on: component-managed and container-managed sign-on.

Definitions:


Component-managed Sign-onThe J2C application sets the res-auth deployment descriptor element to beApplication. The component code performs a programmatic sign-on to theEIS (IMS Connect/IMS) by passing the explicit security information(username, password, and groupname) to the getConnection method ofthe IMSConnectionFactory instance. To pass security information to aconnection for IMS Connect/IMS, you must use the IMSConnectionSpecclass. The component sets values for username, password, and groupnamein an instance of the IMSConnectionSpec class and provides that instanceto the getConnection method. For example:com.ibm.connector2.ims.ico.IMSConnectionSpec connSpec =

new com.ibm.connector2.ims.ico.IMSConnectionSpec();connSpec.setUserName(”yourUID“);connSpec.setPassword(”yourPwd“);connSpec.setGroupName(”yourGrp“);

Connection conn = connectionFactory.getConnection(connSpec);

If you use EAB commands in your application, you can specify the securityinformation by editing the connectionSpec property of theConnectionFactoryConfiguration property of your EAB command:

1. Edit your EAB command using the EAB Command Editor and select the″ConnectionFactoryConfiguration″ class inside the Connection folder.

2. Select the com.ibm.connector2.ims.ico.IMSConnectionSpec class for theconnectionSpec property. Then provide security information as desired.

3. Optionally, you can promote the connectionSpec property to generate asetter method for the connectionSpec property on the EAB command.Then you can invoke the setter method on the EAB command toprovide the security information.

For more information about EAB commands, please refer to the VisualAgefor Java documentation.

The security information is then sent by IMS Connector for Java to IMSConnect and IMS for the appropriate security validation. See ”IMS SecurityInformation (page 19)“ for more information.

Container-managed Sign-onThe J2C application component sets the res-auth deployment descriptorelement to be Container. The application server (WebSphere ApplicationServer) takes the responsibility of managing sign-on to the EIS (IMSConnect/IMS). The component code invokes the getConnection method onthe IMSConnectionFactory instance with no security-related parameters.The application runs with the identity associated with the current thread ofexecution set up by the application server.

Note: If the component code passes an IMSConnectionSpec instance withexplicit security information to the getConnection method on theIMSConnectionFactory instance, that security information is ignored.

Related Reading: Currently, IMS Connector for Java supportscontainer-managed sign-on for WebSphere Application Server for z/OS andOS/390 only. To set up your J2EE application with the appropriate securityidentity to use the container-managed sign-on on WebSphere ApplicationServer for z/OS and OS/390, see the document titled ”WebSphereApplication Server V4.0.1 for z/OS and OS/390: WebSphere for


z/OS-supported Connectors.“ This document is available with APARPQ55873 for WebSphere Application Server V4.0.1 for z/OS and OS/390.

To download the document, go tohttp://www.ibm.com/software/webservers/appserv/zos_os390/support.html,then click Product information. At a later time, the information in thisdocument will be integrated into the WebSphere for z/OS formalpublications. To access the latest publications, go to the product librarypage at http://www.ibm.com/software/webservers/appserv/.

When the connection is successfully established, all application-level invocations tothe EIS instance using the connection occurs under the security context of theauthenticated user.

When you configure an IMSConnectionFactory you can specify default values forusername, password, and groupname (see ”Creating and Configuring a ConnectionFactory for use by the IVP“ in ”Preparing your WebSphere Application ServerEnvironment for Windows“ or ”Preparing your WebSphere Application ServerEnvironment for z/OS and OS/390“). These default values will be used for allconnections created by that connection factory and placed in the OTMA messagefor authentication and authorization by IMS Connect and IMS under the followingcircumstances:

v The J2C application specifies component-managed sign-on, but the applicationcomponent does not pass an IMSConnectionSpec instance to thegetConnection method.

v The J2C application specifies component-managed sign-on, but the applicationcomponent passes an IMSConnectionSpec instance with no security informationto the getConnection method.

Note: When any value (username, password, or groupname) in theIMSConnectionSpec instance is null, the default value from theIMSConnectionFactory is used.

v The J2C application specifies container-managed sign-on, but IMS Connector forJava does not support container-managed sign-on with the application server onthat platform.

Java Classes that are Provided by IMS Connector for Java for CCF

IMS Connector for Java provides a number of Java classes to aid you in buildingJava programs and servlets. All of these classes are in the IMS Connector for Javapackage com.ibm.connector.imstoc. Some of these classes are also Java beans.You can combine these beans into a composite bean that accesses an IMStransaction. The beans are available to VisualAge for Java’s Command Editor andVisual Composition Editor.

Definitions:

A Java bean is a reusable software component, an element of a program that mayor may not be seen by the end user at run time and is made up of one or moreJava classes. A visual Java bean is an element of a program that is seen by theend user at run time while a nonvisual bean is an element of a program that is notnecessarily seen by the end user.

1. Visual Java beans can be used to construct a graphical user interface for anEAB command. The interface can provide input to and display output from anIMS transaction. An example of a visual Java bean is a button that the userclicks to perform some action.


2. Nonvisual Java beans are beans which do not have visual representations atruntime. For example, all beans that are provided by IMS Connector for Javasuch as IMSConnectionSpec and IMSInteractionSpec, are nonvisual beans.

3. A composite Java bean is a Java bean that is comprised of other Java beans,either visual or nonvisual. In the context of this document, an Enterprise AccessBuilder (EAB) command is a composite bean that is constructed using theVisual Age for Java Command Editor.

For additional definitions, see the glossary in the VisualAge for Java online help.

The following classes are supplied by IMS Connector for Java:

IMSConnectionSpecThe IMSConnectionSpec bean provides information about the connectionbetween a Java program and an IMS Connect host component, as well asinformation about connection management. The IMSConnectionSpec Hostname and Port properties are specific to IMS Connector for Java, while theother properties are inherited from the Common Connector Frameworkinterface com.ibm.connector.ConnectionSpecManagementProperties.IMSConnectionSpec properties include the following:

Host nameFor a TCP/IP connection, the host name is set to the TCP/IP hostname of the machine running the IMS Connect that the EABcommand (IMS transaction) will be using.

For a connection that utilizes the Local Option of IMS Connector forJava, the host name is set to LOCALHOST: ims_connect_namewhere ims_connect_name is the IMS Connect ID (referred to in IMSConnect as ”HWS ID“) Once IMS Connect has been configured andstarted, the ims_connect_name will appear in the outstanding IMSConnect reply message on the MVS console of the host machinewhere it is running. For more information on the IMS Connect ID,see Creating the IMS Connect Configuration Member in the IMSConnect Guide and Reference.

Port The Port is a numeric value that may be used by the EABcommand for communication with IMS Connect. For a TCP/IPconnection, Port is a port used by IMS Connect on the specifiedhost machine where IMS Connect is running. For a Local Optionconnection, the Port value is not used.

IMSConvContextThe IMSConvContext bean is used to comply with the IMS Connectrequirement that the same connection is used for all iterations of an IMSconversation. A connection is a communications link, a socket in the case ofTCP/IP, and is analogous to the phone line that connects two telephonesduring a telephone conversation. IMS Connector for Java includes this classin its programming model for use by conversational Web applications. AJava application or servlet should create a single instance of theIMSConvContext class at the start of a conversation and associate thissingle instance with the connection used for the conversation. This willensure that the connection will be preserved for the lifetime of the IMS


conversation and that the CCF ConnectionManager will always return thesame connection for each iteration of the IMS Conversation.

IMSConvUnboundHttpSessionCleanupIMS Connector for Java includes this class in its programming model foruse by conversational Web applications only. This class implements theHttpSessionBindingListener interface and is used to determine when theIMS conversation is unbound from the session. It then performs theappropriate cleanup.

WebSphere Application Server creates an HttpSession object to representthe HTTP session of the Web application (the connection between thebrowser and WebSphere Application Server.) An HttpSession object fires anunbound event when the associated HTTP session becomes unbound.When an HTTP session becomes unbound, the connection needs to bereturned for reuse and the IMS conversation needs to be terminated. Thiscleanup work is performed by methods of the IMSConvHttpSessionCleanupclass.

For example, an HTTP session becomes unbound when the user closesthe browser while the IMS conversation is still active. When the userprematurely exits the browser, the HTTP session associated with thebrowser eventually times out, as there is no more user interaction from thebrowser. At this point, the HttpSession object associated with the HTTPsession becomes unbound, causing an unbound event to be fired. TheIMSConvHttpSessionCleanup object receives this unbound event, which inturn triggers the calling of its valueUnbound() method. The valueUnbound()method issues a MODE_END_CONVERSATION request to end the IMSconversation and also performs any cleanup required to allow theconnection to be reused.

IMSConvHttpSessionCleanup implements the HttpSessionListener interfaceand has the following methods:

void setConvContext()Sets the IMSConvContext object of the current IMS conversation in theIMSConvHttpSessionCleanup object such that the appropriate resourcescan be cleaned up following an unbound event.

void valueUnbound()This method implements the valueUnbound() method of theHttpSessionBindingListener interface to terminate the IMS conversation andcleanup conversation resources.

IMSInteractionSpecThe IMSInteractionSpec bean provides information about the interactionbetween a Java program and a datastore. Interaction properties include:

ConvTerminatedThis property is set to TRUE if the host IMS application programends the IMS conversation. The Java application program checksthe value of this property after invocation of the execute() methodfor the EAB command, to determine whether or not theconversation has been terminated by the host. The following twomethods can be used:


void setConvTerminated(boolean)Sets the value of the convTerminated property. Thisproperty is set to TRUE when the conversation isterminated by the host.

boolean getConvTerminated()Gets the value of the convTerminated property. It is used bythe Java application program to determine whether or notthe conversation has been terminated by the host.

Datastore nameThe name of the target IMS datastore that is defined in the IMSConnect configuration file.

LTERM NameThe LTERM name used to override the LTERM name in the IMSapplication program I/O PCB.

Map nameAlso known as the MFS MOD name, the map name can beprovided by an IMS application program when returning the outputof a transaction. It can also be provided by IMS when returning astatus message, such as the output from a /DIS command, or anerror message. If a value for Map name is specified on input to anIMS transaction, it will be made available to the IMS applicationprogram.

Mode The type of interaction to be carried out between the Java programand the IMS datastore. The modes that are currently supportedinclude MODE_SEND_RECEIVE, MODE_ACK, MODE_NACK, andMODE_END_CONVERSATION.

Synchronization LevelSpecifies the transaction synchronization level — the way in whichthe Java client (for example, an application or servlet) and IMSinteract with respect to transaction output messages. Stated simply,the synchronization level determines whether or not the transactionoutput messages must be acknowledged either as accepted (ACK)or rejected (NACK) by the client.

For more information, see ”Synchronization Level.“ (page 29)

DFSMsgThe DFSMsg bean represents IMS status or error messages that arereturned to a Java application or servlet in response to a command or atransaction. These messages typically begin with the characters DFS. Oftentimes, DFS messages are returned to a Java application or servlet. SomeDFS messages indicate error situations, while others are returned as theoutput of IMS commands. In all cases, because OTMA is used to returnthe message, MFS formatting is not performed. However, IMS includes anMFS MOD name (Map name) with DFS messages. IMS Connector for Javachecks the MOD name field of messages that it receives from IMSConnect. If the MOD has one of the following names, the message isprocessed as a DFS message. If the name is not listed below, it isprocessed as transaction output.


v DFSMO1

v DFSMO2

v DFSMO3

v DFSMO4

v DFSMO5

v DFSDSPO1

IMS Connector for Java builds a buffer containing one or more segments of a DFSmessage, up to a maximum of 22 segments. Any output data beyond the 22ndsegment is discarded. The buffer structure is as follows:

DFSLL1Two-byte length (LL) of the first segment of the output message. The length(LL) of a message segment includes the length of the LL and ZZ fields ofthe segment.

DFSZZ1Two-byte flag field (ZZ) of the first segment of the output message.

DFSDATA1The data of the first segment of the output message, blank-padded ortruncated to 119 bytes. DFSLL1 represents the length of the segmentreceived from IMS or the truncated length and, as such, is less than orequal to 123 (119 + 4).

...

...

...

DFSLL22Two-byte length (LL) of the 22nd segment of the output message. Thelength (LL) of a message segment includes the length of the LL and ZZfields of the segment.

DFSZZ22Two-byte flag field (ZZ) of the 22nd segment of the output message.

DFSDATA22The data of the 22nd segment of the output message, blank-padded ortruncated to 119 bytes. DFSLL22 represents the length of the segmentreceived from IMS or the truncated length and, as such, is less than orequal to 123 (119 + 4).

The buffer structure is used to populate a DFSMsg object. A Java program canobtain a DFS message from a DFSMsg object in the following ways:

getDFSMessage()Returns the message segments concatenated together as a singlestring.

getDFSMessageSegments()Returns a vector of the segments of the message.

In addition, the individual fields of the message segments (DFSLL1, DFSZZ1,DFSDATA1, etc.) can be accessed by a Java application or servlet.

Any of the above methods can be used by Java applications. Currently, however,WebSphere Studio does not allow selection of a method for use in displaying data


on a servlet’s output template. In order for a servlet to display a DFS message, theindividual fields of the DFSMsg object should be selected (DFSLL1, DFSZZ1,DFSDATA1, etc.) while in WebSphere Studio.

A composite bean that uses IMS Connector for Java should include a DFSMsgbean as well as bean(s) representing the output of the IMS transaction. VisualAgefor Java’s Enterprise Access Builder populates the appropriate output bean, basedon the data that is returned by IMS.

Related Reading: For more information on displaying a DFS message with aservlet, see ”Building a Java servlet to run an IMS transaction.“

Java Classes that are Provided by IMS Connector for Java for J2C

All classes mentioned below are in IMS Connector for Java packagecom.ibm.connector2.ims.ico. Interfaces beginning with javax.resource are part ofthe J2C architecture.

To view the Javadoc for these classes, go to VisualAge for Java and click Help >API Reference > Reference >IBM APIs > Connectors > IMS Connector.

IMS Connector for Java’s implementation of the J2C architecture will be provided inphases. Classes provided in this phase are summarized below. IMS Connector forJava uses these classes in collaboration with WebSphere Application Server toprovide connection pooling in the J2C environment. Connection pooling istransparent to the servlet or EJB.

IMS Connector for Java implements the J2C System Contracts by providing thefollowing classes. J2C interfaces are noted in parentheses:

v com.ibm.connector2.ims.ico.IMSManagedConnectionFactory(javax.resource.spi.ManagedConnectionFactory)

An IMSManagedConnectionFactory instance is a factory of bothIMSManagedConnection instances and IMSConnectionFactory instances.

v com.ibm.connector2.ims.ico.IMSManagedConnection(javax.resource.spi.ManagedConnection)

An abstract class that represents the physical connection to IMS Connect. TheIMSManagedConnection has 2 subclasses:

– com.ibm.connector2.ims.ico.IMSTCPIPManagedConnection

– com.ibm.connector2.ims.ico.IMSLocalOptionManagedConnection

An IMSTCPIPManagedConnection instance represents a TCP/IP connection toIMS Connect. An IMSLocalOptionManagedConnection instance represents aconnection using Local Option to communicate with IMS Connect.

v com.ibm.connector2.ims.ico.IMSManagedConnectionMetaData(javax.resource.spi.ManagedConnectionMetaData)

Provides information about an IMSManagedConnection.

IMS Connector for Java implements the J2C Common Client Interface (CCI) byproviding the following classes. J2C interfaces are noted in parentheses:

v Classes that represent a connection factory and an application level connection:

– com.ibm.connector2.ims.ico.IMSConnectionFactory(javax.resource.cci.ConnectionFactory)

An IMSConnectionFactory instance is a factory for IMSConnection instances.


– com.ibm.connector2.ims.ico.IMSConnection(javax.resource.cci.Connection)

An IMSConnection instance is an application level handle than is used by acomponent to access IMS using IMS Connect.

– com.ibm.connector2.ims.ico.IMSConnectionSpec(javax.resource.cci.ConnectionSpec

An IMSConnectionSpec instance is used by components, when obtaining aconnection, to provide specific values for UserName, Password, andGroupName. These values are used instead of the default values provided bythe IMSConnectionFactory instance.

v Classes that enable a component to drive an interaction (specified through anInteractionSpec) with IMS using IMS Connect:

– com.ibm.connector2.ims.ico.IMSInteraction(javax.resource.cci.Interaction)

An IMSInteraction instance enables a component to interact (run atransaction) with IMS using IMS Connect.

– com.ibm.connector2.ims.ico.IMSInteractionSpec(javax.resource.cci.InteractionSpec)

An IMSInteractionSpec instance provides properties for driving the interactionwith IMS using IMS Connect.

v Classes that provide basic meta information about the IMS Connector for Javaimplementation and a connection to IMS using IMS Connect:

– com.ibm.connector2.ims.ico.IMSConnectionMetaData(javax.resource.cci.ConnectionMetaData)

Provides information about an IMSConnection.

– com.ibm.connector2.ims.ico.IMSResourceAdapterMetaData(javax.resource.cci.ResourceAdapterMetaData)

Provides information about IMS Connector for Java.

v Additional classes and interfaces provided by IMS Connector for Java are:

– IMSInteractionSpecProperties

IMSInteractionSpecProperties is an interface that defines named constantsthat are used to configure an IMSInteractionSpec instance.

– IMSTraceLevelProperties

IMSTraceLevelProperties is an interface that defines named constants that areused for controlling the level of tracing and logging that is performed by IMSConnector for Java.

– IMSConnectorMigrator

IMSConnectorMigrator is a class that is used by VisualAge for Java to migratea CCF EAB command to a J2EE EAB command.

– DFSMsg

A DFSMsg bean is used to capture ”DFS“ messages returned by IMS. For adescription of this bean, see the section ”Java Classes that are Provided forIMS Connector for Java for CCF“ (page 22) above.

J2EE Modules

A Java 2 Enterprise Edition (J2EE) application is comprised of J2EE modules.These modules are comprised of the following J2EE components:

v Enterprise beans

v Web components, specifically servlets or JavaServer Pages (JSPs)


v Application clients

v Applets

J2EE modules are archives: Java archive (JAR) files or Web application archive(WAR) files. A J2EE application, with all of its modules, is packaged and deliveredin an Enterprise Archive (EAR) file. An EAR file is a standard JAR file with an .earextension. You can install J2EE applications in WebSphere for z/OS and OS/390only when they are packaged in EAR files.

MFS Formatting

Transaction input and output messages that are provided to IMS through OTMAbypass online MFS processing. MFS is the online processing component in IMSthat performs message formatting, such as field padding, truncation, justification,and insertion of literal data in messages.

Currently, although VisualAge for Java includes an MFS parser, it does not supportcreating input and output record beans that are based on MFS message definitions(the MIDs and MODs in an MFS source file), and no MFS-like formatting isperformed.

When using IMS Connector for Java you need to consider any dependencies theIMS application program has on MFS online formatting and decide whether or notyou want to perform this function in your Java servlet or application.

Synchronization Level

Important: The current release of J2C implementation in IMS Connector for Javadoes not provide applications with the ability to specify synchronization level. IMSConnector for Java can use the IMS OTMA synchronization level internally tointeract with IMS OTMA and IMS Connect.

For the CCF implementation, the synchronization level can be specified for an EABcommand that runs an IMS transaction. Synchronization level determines the way inwhich IMS and the client that contains the EAB command interact. An EABcommand that runs an IMS transaction can execute with a synchronization of levelof None or Confirm.

Currently, all IMS Connector for Java interactions use the OTMA protocol CommitMode 1, also referred to as send-then-commit. Under this protocol, if thesynchronization level is Confirm, IMS sends the output message to the client andthen waits for a response from the client. It is the responsibility of the client torespond to IMS. If the synchronization level is None, IMS commits any changesmade by the IMS application without waiting for a response from the client.

Synchronization level noneWhen an EAB command uses a synchronization level of NONE, the transactionruns and IMS sends the output message to the client. Any database changes arethen committed. IMS does not require that the client send a message in responseto the transaction output message in order to commit the database changes.Synchronization level NONE is typically used for Java applications and servlets thatrun IMS transactions that browse or query host databases.

Synchronization level confirmWhen an EAB command uses the synchronization level Confirm, the transactionruns and IMS sends the output message to the client without committing any


database changes. IMS does not complete the transaction until the client respondsto the transaction output message by sending a positive or negativeacknowledgment to IMS. If the client is satisfied with the transaction output, itresponds by sending a positive acknowledgment. IMS then completes thetransaction by committing the database changes, if necessary. If the client is notsatisfied with the transaction output (or does not want to continue with thetransaction for any reason) it responds by sending a negative acknowledgment. IMSthen rolls back any changes to the database.

If IMS Connect on the host encounters any errors from the Java application, it canalso send a negative acknowledgment to IMS to abort the transaction. For example,this might occur if communication with the Java application and IMS Connect is lostwhile processing the transaction.

The client application can respond to IMS in one of two ways.

1. If the coordinator object obtained from the current run-time context iscom.ibm.connector.infrastructure.NullCoordinator, the client sends a positive ornegative acknowledgement to IMS. This is done by executing a separate EABcommand with interaction mode MODE_ACK (for a positive acknowledgment) orMODE_NACK (for a negative acknowledgment) to send the appropriateacknowledgement message to IMS. Because a MODE_ACK or MODE_NACKEAB command only sends acknowledgment messages to IMS, it does notcontain any input or output beans.

2. If the coordinator object obtained from the current runtime context is notNullCoordinator, and is insteadcom.ibm.connector.infrastructure.java.JavaCoordinator, for example, then theclient invokes the commit() or rollback() method on the coordinator object,following receipt of the output message. The implementation of these methodswill, in turn, send the corresponding acknowledgement message to IMS.

In the case of an IMS conversation, different synchronization levels may be used forone or more of the iterations of the conversation. Since the conversationalprogramming model presented by IMS Connector uses a new instance of the EABcommand for each iteration of the conversation, the synchronization level must beexplicitly set for each iteration. Otherwise, the synchronization level set for thecommand at development time (usually the default, SYNC_LEVEL_NONE) will beused for the iteration.

If SYNC_LEVEL_CONFIRM is specified for a given iteration of an IMSconversation, either the commit() or rollback() method of JavaCoordinator must beexecuted following receipt of the output message for that iteration of theconversation. These messages can also be sent to IMS by creating two additionalEAB commands which would be used in a NullCoordinator environment. However, itis recommended that applications use the simpler JavaCoordinator interface. See”Building an application to run an IMS transaction with synchronization levelconfirm“ for an illustration of an application that uses an IMS nonconversationaltransaction with SYNC_LEVEL_CONFIRM. Iterations of IMS conversations that useSYNC_LEVEL_CONFIRM would be handled in a similar fashion, as far as commitand rollback processing is concerned.

Most likely the synchronization level will be the same for all iterations of the IMSconversation, in which case it would be appropriate to set it in theIMSInteractionSpec when the EAB command is developed.

A typical application scenario might be:


1. The application invokes a transaction EAB command with interaction modeMODE_SEND_RECEIVE and the synchronization level isSYNC_LEVEL_CONFIRM.

2. The application receives the transaction output from IMS.

3. The application performs some logic (or interacts with the end-user) to decidewhether the transaction should be completed.

4. Based on the results from the previous step, the application invokes thecommit() or rollback() methods of JavaCoordinator to respond to IMS.

5. IMS completes the transaction by committing or rolling back the databasechanges, based on the type of response (positive or negative acknowledgment)that it received.

Related Reading: For more information on building an application to run an IMStransaction with synchronization level, see ”Building an application to run an IMStransaction with synchronization level confirm.“)

Transaction Management for J2C

Global Transaction and 2-Phase commit processing

Many computer resources (for example, enterprise databases) are very critical to acompany’s work and the integrity of these resources must be guaranteed. Whenmaking changes to these protected resources, an application can group the set ofchanges into a transaction (also known as a unit of work), such that all the changesmade within a transaction are either fully completed or fully rolled back (also knownas all-or-nothing changes). There are two types of transactions: global and localtransactions.

Global TransactionA transaction is categorized as global when an external coordinator isavailable and is coordinating a transaction that could involve more than oneresource managers. The external coordinator uses the 2-phase commitprotocol to coordinate between different resource managers.

Local TransactionA local transaction is coordinated locally by the resource manager and thereis no external coordinator involved.

Related Reading: For more information about RRS and 2-phase commitprocessing, see z/OS and OS/390 MVS Programming: Resource Recovery.

IMS Connector for Java supports two types of interactions in terms of J2Ctransaction management:

v No Transaction

An IMS transaction request is submitted from a J2EE application to IMS throughIMS Connect for processing. Changes made by IMS in the processing of the IMStransaction will be committed before returning the transaction output to the J2EEapplication.

v Global Transaction

An IMS transaction request is submitted from a J2EE application to IMS throughIMS Connect for processing in the context of a global transaction. Changes madeby IMS are coordinated using the 2-phase commit protocol.

v Local Transaction

Local transaction support is not available in this release.


The following table shows the J2C transaction support provided by IMS Connectorfor Java in this release:

Platform of WebSphere ApplicationServer with IMS Connector for Java

J2C Transaction Support

Windows, AIX, Solaris No transaction support

z/OS, OS/390 No transaction support when configured withTCP/IP communication

Global transaction support when configured withLocal Option*

* WebSphere Application Server, IMS, IMS Connect, and IMS Connector for Javamust exist on the same MVS image when using global transaction support.

Types of J2C transactions in your J2EE applications

The J2EE platform defines the Java Transaction API (JTA) which specifies theinterfaces between a transaction manager and other parties involved in transactionprocessing (such as the application programs, resource managers and theapplication server). Particularly, JTA defines two ways to demarcate a transaction ina J2EE application: component-managed and container-managed transaction.

Component-managed (or Bean-managed) transaction

The J2EE application uses the JTA javax.transaction.UserTransaction interfaceto demarcate a transaction boundary to a set of changes to the protectedresource or resources programmatically. Component-managed transaction canbe used in both the servlet and the EJB environment. In the case of an EJB,you sets the transaction attribute in its deployment descriptor asTX_BEAN_MANAGED.

A transaction normally begins with a UserTransaction.begin() call. When theapplication component is ready to commit the changes, it invokesUserTransaction.commit() to coordinate and commit the changes. If theapplication component prefers to rollback the transaction, it invokesUserTransaction.rollback() and all changes will be backed out. For example:// Get User Transactionjavax.transaction.UserTransaction transaction =ejbcontext.getUserTransaction();

// Start transactiontransaction.begin();

// Make changes to the protected resources.// For example, use the J2EE/CA’s CCI Interaction interface// to submit changes to an EIS system(s)interaction.execute(interactionSpec, input, output);

// Commit the transactiontransaction.commit();

Container-managed transaction

A container-managed transaction used in an EJB environment is managed bythe EJB container. The container calls the appropriate methods (such asbegin, commit or rollback) on behalf of the EJB component. The EJB specifies


a container-managed transaction declaratively through the transaction attributein the deployment descriptor (such as TX_REQUIRED). This declarativeapproach simplifies the programming calls in the EJB.

Related Reading: For more information the J2EE architecture and JTAspecifications, see http://java.sun.com/j2ee/docs.html for details.

IMS Connector for Java J2C transaction support

In this release, IMS Connector for Java adds support for global transactions and 2phase commit processing for WebSphere Application Server for z/OS and OS/390.This support allows J2EE application components (such as EJBs and JavaServlets) running under WebSphere Application Server for z/OS and OS/390 tosubmit IMS transaction messages in the context of global transaction and toparticipate in 2-phase commit processing. The Resource Recover Services (RRS)of z/OS or OS/390 coordinates this transaction processing. With this support,WebSphere for z/OS, RRS, and the IMS subsystem work together to makeconsistent changes to multiple protected resources.

To use this global transaction support, the following configuration is required:

v IMS Connector for Java must be configured with the Local Option communicationprotocol to process global transaction in this release. If configured with TCP/IP,IMS Connector for Java will process the requests with no transaction support.

v WebSphere Application for z/OS and OS/390, IMS Connector for Java, IMSConnect, IMS and RRS must all be running under the same MVS image forglobal transaction processing on the z/OS and OS/390 platform. This restrictionwill be lifted in the future updates of IMS Connector for Java.

When a J2EE application (such as a servlet or EJB) is running under a globaltransaction with the above configuration, the IMS transaction request is sent to IMSfor processing using the IMS OTMA synchronization level Syncpt protocol. Allchanges made to IMS will be part of a global transaction coordinated by RRS.

If the processing is not under a global transaction or if IMS Connector for Java isconfigured with no transaction processing (such as when it is configured to useTCP/IP communication), all requests to IMS are performed using the IMS OTMAsynchronization level None protocol. In this case, all changes to IMS are committedwhen the output is returned to the J2EE application.

Notes:

v Transaction support in IMS Connector for Java will be provided in phases. Futurereleases of IMS Connector for Java will provide enhanced J2C support includingXA transaction support for distributed platforms.

v IMS Connector for Java uses the RRS-Transaction support provided byWebSphere Application Server for z/OS and OS/390 in which the Localtransaction and XA transaction support as described by the J2EE ConnectorArchitecture is not supported.

Related Reading: More information about the RRS-transaction support isavailable in WebSphere Application Server for OS/390 and z/OS documentation.The document titled ”WebSphere Application Server V4.0.1 for z/OS and OS/390:WebSphere for z/OS-supported Connectors″ is available with APAR PQ55873 forWebSphere Application Server V4.0.1 for z/OS and OS/390. To download thedocument, go to the Web site athttp://www.ibm.com/software/webservers/appserv/zos_os390/support.html, thenclick ″Product information.″ At a later time, the information in this document will


be integrated into the WebSphere for z/OS formal publications. To access thelatest publications, go to the product library page athttp://www.ibm.com/software/webservers/appserv/.

For information on the synchronization level protocol, see the IMS Connect Guideand Reference and the IMS Open Transaction Manager Access Guide andReference, available on the IMS Web site at (www.ibm.com/ims).

A provided sample (described in “Building Container-managed andComponent-managed Transactional EJBs to Run IMS Transactions”) demonstrateshow to build an J2EE application to access your IMS transaction using IMSConnector for Java with global transaction and 2-phase commit processing.Additional samples (such as global transactions with IMS and DB2 databases) willbecome available on the IMS Connector for Java Web page, located in the IMSWeb site at www.ibm.com/ims. Be sure to check this Web site periodically for thesesamples and supporting documentation.

IMS Connector for Java conversational programming modelsIMS Connector for Java Conversational Support provides users with twoprogramming models from which to build Java applications and Web applicationsthat iterate through the interactions of an IMS conversational program. Theprogramming models are based on the existing application model that uses IMSConnector for Java to invoke IMS transactions using IMS Connect. Applications builtfrom the programming model with CCF support use VisualAge for Java andWebSphere Studio. Applications built from the programming model with J2C supportuse VisualAge for Java and Application Assembly Tool (a WebSphere ApplicationServer tool). VisualAge for Java tools have been enhanced to help customersgenerate the record components specifically needed for generating the input andoutput messages of an IMS conversational transaction.

IMS Connector for Java provides both Common Connector Framework (CCF) andJava 2 Platform, Enterprise Edition (J2EE) Connector (J2C) architecture support forIMS conversations.

Restriction: When invoking an IMS Conversation within a global transaction with2-Phase commit processing (for example, with TX_REQUIRED), IMS OTMAsupports the execution of one iteration of an IMS Conversation only. Subsequentiteration invocations to an IMS Conversation within a global transaction will resultwith an error in IMS.

The information in this section includes the following:

v Considerations in Choosing a Model (page 35)

v Conversational HttpSession Model with CCF Support (page 35)

v Conversational HttpSession Model with J2C Support (page 38)

v Conversational Navigator Model with CCF Support (page 39)

v Conversational Navigator Model with J2C Support (page 40)

Generally, a Java application is built with a GUI interface that consists of multiplewindow panels. The user provides the input data and views the output data withinseparate panels of the same Java application when stepping through the iterationsof the IMS conversation. The Java application contains logic that utilizes Javaclasses in the IMS Connector for Java Conversational Support to invoke the IMSconversational transactions.


A Web application is made up of a group of application components that can beaccessed from the Web and consists of one or more Java servlets that contain theapplication logic, an HTML page which serves as the initial input page used to startthe application and one or more JSPs (Java Server Pages) for obtaining input datafrom and displaying output data to the user. The Java servlets within a Webapplication share the same servlet context. The user starts an IMS conversationaltransaction from a web browser by first providing some input data via an HTMLform. The web server then invokes the Java servlet running inside the WebSphereApplication Server. The servlet utilizes the Java classes in IMS Connector for Java(including the Conversational Support classes) to send the conversationaltransaction request and receive the transaction output via IMS Connect. The outputwill be displayed back to the user through a JSP in the web browser.

Although this documentation focuses primarily on modeling an IMS conversationwith a Web application, many of the same rules that pertain to Web applicationscan be applied to building Java applications, as well. Generally, the rules governingthe logic of a Java servlet can be applied to the logic of a Java application.Similarly, the rules governing the use of HTML and JSP pages can be applied tothe GUI interfaces of a Java application.

Considerations in Choosing a Model

You should choose the Navigator model if it is suitable for your IMS conversationsince it provides a simpler development paradigm and a more effective use ofconnections. From a development perspective, the conversational Navigator modeleliminates the need to deal with issues such as using the ″back″ button,bookmarking, browser caching or tracking the state of the IMS conversation. Inaddition, issues such as scaling, cloning, and clustering might affect your decisionof which model to use. Consult the WebSphere Application Server documentationfor a detailed discussion of these issues.

The Conversational Navigator model is suitable when a particular sequence ofinteractions representing a well defined task and the data required by all of thoseinteractions can be pre-determined. A conversational IMS application can be usedto process any number of tasks some of which may be suitable for the Navigatormodel and some of which are not. You will probably find that some small number oftasks for a given IMS conversational application can be implemented withconversational Navigators but the majority will require HttpSession based servlets.

Conversational HttpSession Model with CCF Support

IMS Connector for Java Conversational Support introduces a session-enabled Webapplication model for an IMS conversational transaction, the ConversationalHttpSession Model. A session encompasses a series of requests originating fromthe same browser to the Java servlet or servlets of a Web application. A session isanalogous to an SNA connection between a terminal user and an IMSconversational application program.

The Conversational HttpSession Model for building a Web application to invoke anIMS conversational transaction is similar to the programming model used forbuilding a Web application to invoke a non-conversational IMS transaction. Thesteps involve the use of VisualAge for Java and WebSphere Studio and are asfollows:

1. Provide your COBOL source files to VisualAge for Java to generate the inputand output Java record beans.


2. Use the VisualAge for Java Command Editor to create an Enterprise AccessBuilder (EAB) command.

3. Supply the EAB command to WebSphere Studio and use WebSphere Studio togenerate a template for a Web application. Build a Web application from thetemplate using the guidelines outlined below. This process can be summarizedas follows:

a. Create additional JSP pages for the iterations.

b. Modify the JSP pages.

c. Modify the Java servlet.

The user submits a series of requests from the same browser to iterate throughdifferent interactions of an IMS Conversation. The user starts an IMS conversationaltransaction from a web browser by submitting a request to IMS to schedule (or run)a conversational transaction. The HTTP session associated with the browser isused to group the series of interactions from that browser. The conversationcontinues through any number of iterations until it is terminated, either by a useraction (i.e., the client) or by transaction program logic that directs IMS to end theconversation at the conclusion of that iteration. The conversational transaction canalso be terminated automatically by IMS Connector for Java’s classes whenever thesession-enabled Web application times out, for example, when the browser remainsidle for a specified period of time. This timeout is set using the JavaServlet APIs(the default is 30 minutes).

The JavaServlet specification provides a class, HttpSession, that is used byWebSphere Application Server to create an object associated with the HTTPsession used by the Web application. Once a session is established between thebrowser and the Java servlet, the Java servlet maintains a reference to this uniqueHttpSession object (i.e., the HttpSession object is bound to the servlet) throughoutall of the iterations for the duration of the conversation. The Java servlet uses thisunique HttpSession object to obtain information about the state of the session aswell as the state of the conversation that is running in that session.

An HttpSession object is associated with (bound to) a servlet at the start of the firstiteration of an IMS conversation. It remains bound to that servlet, or a succeedingservlet in the case of a multi-servlet Web application, until the servlet detects thateither the user has taken some action which will cause the IMS conversation to beterminated or the IMS application program has terminated the conversation.Program your servlets so that the session becomes unbound if there are any errorsencountered in the application flow. Possible errors include communication failurebetween components and abnormal termination of components. Program your Javaservlet to handle these errors appropriately. Generally, when an error occurs, yourservlet should terminate the conversation and clean up the connection resource forreuse.

For example, a browser session becomes unbound from a servlet when thebrowser times out waiting for input from the user. When this happens, the servletshould terminate the conversation and clean up the CCF connection resources. IMSConnector for Java Conversational Support provides theIMSConvHttpSessionCleanup class to capture the notification from the HttpSessionobject when the HttpSession object becomes unbound. TheIMSConvHttpSessionCleanup object instantiated by the servlet will then terminatethe conversational transaction and clean up the connection resources appropriately.

Since the HTTP protocol, which is used as the connection mechanism between theweb browser and the Java servlet, is stateless, it is often useful to bind objects to


the HttpSession object in order to save intermediate state data of the Webapplication. For example, you may want to save information about the currentiteration of the IMS conversation for use when the next iteration of the conversationis executed.

Another use for the HttpSession object is to save information about the connectionbeing used for a particular conversation. This is necessary since IMS Connectrequires a dedicated connection for the entire duration of an IMS conversation. Inother words, IMS Connect requires that the same connection be used for all of thecommunications between the Web application (Java servlet or servlets) and IMSConnect. Furthermore, that connection cannot be used for any othercommunications until that conversation has ended. A connection for purposes of thisdiscussion is the communications link between the Java application or servlet andIMS Connect. In a TCP/IP communications environment, this connection isrepresented as a socket.

In order to provide a mechanism for saving information about the connection beingused for an IMS conversation in the HttpSession object, IMS Connector for Javaincludes the IMSConvContext class in its Conversational HttpSession programmingmodel for conversational Web applications. This class provides a token which isstored in the HttpSession object and used to bind a particular CCF connection to aservlet that is part of an IMS Conversation. Therefore this servlet needs to create asingle IMSConvContext object at the start of each IMS conversation. This object isthen stored in the HttpSession object. The HttpSession object and therefore theIMSConvContext are then used by the CCF ConnectionManager to initially bind aconversation to a particular connection and later to ensure that the CCFConnectionManager will use that same connection for each iteration of theconversation. When the HttpSession object becomes unbound or an error occursduring the conversation, or at the end of the conversation, the IMSConvContextreference must be unbound from its connection in order to allow theConnectionManager to reuse that connection for new requests.

When the HttpSession object becomes unbound this is handled automatically by theIMSConvHttpSessionCleanup object that was instantiated in the Web applicationservlet when the conversation began. In the case of an error being detected in aservlet during a conversation, the unbinding is handled through the use of thehttpSession.invalidate() which in turn causes the IMSConvHttpSessionCleanupobject to be invoked. When a conversation ends normally, the IMSConvContextreference is unbound from its connection through the use of theRuntimeContext.getCurrent().close() method.

After the conversational transaction is completed, a new conversational ornon-conversational transaction can be run next from the client. However, if the IMSconversation is not completed, then you cannot run a new transaction with thesame connection resource.

In the Conversational HttpSession model, the application flow for an IMSconversational transaction starts when the user initiates a conversation from thebrowser. The flow continues with a series of interactions between the Webapplication and the IMS conversational application program performing the businesslogic of the application. Finally, the conversation is terminated by the user or by theIMS application program. The application flow is illustrated as follows:

Iterating in the IMS Conversation

1. The user starts an IMS conversational Web application by displaying the inputHTML page of the Web application in a Web browser.


2. The user provides the initial input data of the IMS conversational transaction inthe input HTML page.

3. The Web browser sends the request with the input data to the WebSphereApplication Server, which then starts the appropriate Java servlet to process therequest.

4. The Java servlet obtains the HttpSession object and creates anIMSConvContext object which it saves in that HttpSession object for use by theCCF ConnectionManager to ensure that the same connection is usedthroughout a conversation. The servlet then invokes the execute() method of theEAB command, passing the input data received from the browser. The EABcommand uses IMS Connector for Java APIs to send the transaction request toIMS via IMS Connect.

5. IMS receives the request and schedules the IMS conversational applicationprogram. The IMS application program processes the request and the reply isreturned to the Java servlet.

6. The Java servlet populates the EAB command with the output data of the replyand loads the appropriate result JSP page to display the output data on theWeb browser. The Java servlet or the end user determines if the output datareceived is acceptable. If it is, the Java servlet invokes the commit() method ofJavaCoordinator to accept the output and commit that iteration of theconversation (by sending an ACK message to IMS Connect). Otherwise, itinvokes the rollback() method of JavaCoordinator to reject the output and backout that iteration of the conversation (by sending a NACK message to IMSConnect.)

7. The user provides the data for the second iteration on the JSP page used todisplay the output data of the first iteration, then submits the next request toIMS. This invokes the second iteration of the IMS conversational transaction.

Subsequent iterations of the conversation repeat steps 3-7 until the user or the IMSapplication program terminates the conversation. In step 4, on the second and allsubsequent iterations of the conversation, the Java servlet obtains theIMSConvContext object from its HttpSession object.

Note: The steps described above may differ when used with differentsynchronization levels. The above scenario describes an application flow withSYNC_LEVEL_CONFIRM. When used with SYNC_LEVEL_NONE, the call to theJavaCoordinator commit() or rollback() method in step 6 will not be made.

Terminating an IMS Conversation

In the IMS Connector for Java Conversational HttpSession model, an IMSconversation is typically terminated in one of two ways. For these procedures, see“Terminating a Conversation” in “Building Java applications and servlets forconversational transactions”.

Conversational HttpSession Model with J2C Support

A similar programming model is provided for using IMS Connector for Java with J2Csupport to invoke IMS conversations. In this model, you build J2C applications toaccess IMS conversational transactions.

In this Conversational HttpSession Model, a user submits a series of requests fromthe same browser to iterate through different interactions of an IMS conversation.The user starts an IMS conversation transaction from a web browser, which invokes


a J2C application to interact with the IMS conversation. An HttpSession object isused to group a series of browser requests and associated J2C applicationinteractions together in a session.

IMS Connect requires a dedicated connection for the duration of an IMSconversation. The conversational HttpSession model ensures that the sameconnection is used when iterating through an IMS conversation from multiplebrowser requests.

For definitions of the types of session beans, see “IMS Connector for Java conceptsand terms.”

At a high level, the following steps occur in this conversational model:

1. The user starts an IMS conversational transaction from a web browser.

2. The browser invokes a Java servlet which saves the HttpSession object in anEJB object handle.

An EJB object handle is a long-lived proxy for an EJB object. If for some reasonyou disconnect from the EJB container/server, you can use the EJB objecthandle to reconnect to your EJB object without losing the conversational statewith that bean. The EJB object handle references the stateful session beans tointeract with the IMS conversation.

3. Methods that execute different iterations of the IMS conversation build statefulsession beans. Each method normally represents a particular iteration of theIMS conversation and uses IMS J2EE Connector classes to execute theiteration of the IMS conversation. In addition, the stateful session beans keep areference to the IMS connection handle that is dedicated to the IMSconversation.

4. This connection handle will remain active for the duration of the IMSconversation. Information related to each iteration of the IMS conversation (forexample, conversation state, current iteration, intermediate data) can also besaved in the stateful session beans.

5. At the end of the IMS conversation, the close() method will be called on theconnection handle so that the connection can be reused by a new request.

Note: The conversational transaction can also end during an ejbPassivation ora HttpSession invalidation (such as a timeout). In IMS Connector for Java withthe IBM Common Connector Framework (CCF), you can clean up theconnection resources when a browser session becomes unbound using theclass IMSConvHttpSessionCleanup (shipped with IMS Connector for Java). InIMS Connector for Java with J2C support, this class is not available. The IMSJ2EE Connector Samples provides a similar solution to that class. This class isin the package com.ibm.connector2.ims.ico.sample.conv.phonebook.servlet.However, the implementation of IMSConvHttpSessionCleanup is modified for theJ2C architecture, such that the connection handle is saved instead of theIMSConvContext class. Please note that the IMSConvContext class does notexist in the IMS J2EE Connector conversational support.

Conversational Navigator Model with CCF Support

Like the conversational HttpSession model, the Conversational NavigatorProgramming Model for building a Web application to invoke an IMS conversationaltransaction is also similar to the programming model for building a Web applicationto invoke a non-conversational IMS transaction. The steps involve the use ofVisualAge for Java and WebSphere Studio and are as follows:


1. Provide your COBOL source file or files to VisualAge for Java to generate theinput and output Java record beans.

2. Use the VisualAge for Java Command Editor to create an Enterprise AccessBuilder (EAB) command for each iteration of the IMS conversation.

3. Using the VisualAge for Java Visual Composition Editor, create an EABNavigator.

4. Generate a Web application using WebSphere Studio and VisualAge for Java.

5. Customize the HTML/JSP pages.

6. Modify the Java servlet

An EAB Navigator can be used to model any IMS conversation where all of thedata required for all of the interactions that make up that particular conversation isknown in advance. A conversational Navigator consists of EAB Commands and/orother Navigators linked together to form a more complex Navigator whichencapsulates all of the interactions that make up a given IMS conversation. Eachcomponent EAB Command and Navigator within the conversational Navigator isthen executed in the pre-determined order programmed into the conversationalNavigator. For example, each iteration of an IMS conversation could be modeled asan EAB command. Then, a navigator can be built to encapsulate a sequence ofEAB command iterations to model the whole IMS conversation for a particular task.

When you execute a conversational EAB Navigator, as with any other EABNavigator, it provides its input to the EAB Commands and Navigators of which it iscomprised. The output of the component EAB Commands and Navigators isavailable to the conversational Navigator to be used as output, again depending onhow the conversational Navigator is programmed.

Once a conversational Navigator has started executing, control will not be returnedto the user until all of the component EAB Commands and Navigators (whichrepresent the iterations of the conversation) have completed and the conversationhas ended. No user interaction with an EAB Navigator is possible once execution ofthe Navigator has started. There is no mechanism available to provide additionaldata to be used by subsequent Navigator components after a given Navigatorcomponent has finished execution. It is for this reason that all of the input dataneeded by each component EAB Command or Navigator must be provided to theconversational Navigator before it begins executing.

Conversational Navigator Model with J2C Support

This model remains the same as the IMS Connector for Java with CCF supportConversational Navigator model in which an EAB Navigator is used to map theiterations of the IMS conversation. An EAB Navigator can be used in J2Capplications. After the Navigator is run, all iterations of the IMS conversationaltransaction is complete. When the Navigator completes its tasks, the connectionbeing used by the Navigator is closed automatically for reuse.

Migrating from CCF architecture to J2EE connector architectureThe availability of IMS Connector for Java 1.2 marks the transition from the IBMCommon Connector Framework (CCF) architecture to Sun’s Java 2 Platform,Enterprise Edition (J2EE) Connector (J2C) architecture. This change of architectureaffects both your existing and new applications. Information on this transition can befound in VisualAge for Java’s documentation by clicking Help > Help Home Page >Concepts > Access to transaction systems > Enterprise Access Builder forTransactions > Impact of CCF to J2EE transition.


This section provides you with information on migrating EAB commands andNavigators, and should be used in conjunction with “Migrating IMS Connector forJava EAB Commands to J2EE” below.

Information on migrating servlets coded with the CCF architecture to the J2Carchitecture is available in the VisualAge for Java documentation in Help > HelpHome Page > Samples > Enterprise Access Builder for Transactions >WebSphere set > J2EE JSP and servlet.

If you want to run your CCF servlet in WebSphere Application Server 4.0 withoutmigrating to the J2C architecture, you can do so. The sections “Running a CCFServlet in WebSphere Application Server 4.0 for Windows” on page 42 and“Running a CCF Servlet in WebSphere Application Server 4.0 for z/OS and OS/390”on page 46 below describe how to deploy one of the CCF samples provided withan earlier release of IMS Connector for Java to WebSphere Application Server 4.0.

Migrating IMS Connector for Java EAB Commands to J2EEMigrating IMS Connector for Java EAB Commands from a CCF-based applicationto a J2EE-based application can be done using the migration tool provided withVisualAge for Java. A description of how to migrate an EAB command using thistool can be found in the VisualAge for Java documentation by clicking Help > HelpHome Page > Tasks > Accessing transaction systems > Accessing CICS, IMS,Encina, MQSeries, HOD > Getting started with Enterprise Access Builder forTransactions > Working with EAB Commands > Migrating EAB Commands toJ2EE.

This VisualAge for Java information also contains links to the migration of recordsand Navigators to J2EE. The records of an EAB command can be migrated whenyou migrate the EAB command or they can be migrated separately. The generatedrecords are backward compatible with CCF applications. In addition, the DFSMsgbean in package com.ibm.connector2.ims.ico has already been migrated.

When you migrate an IMS Connector for Java EAB command, you might receiveone or both of the following warnings:

v IVJC1604W: The property, syncLevel, could not be migrated for command_name.It has been omitted.

v IVJC1604W: The property, dataStoreName, could not be migrated forcommand_name. It has been omitted.

These warnings result from the difference in support of synchronization level anddatastore name between the CCF and J2C implementations of IMS Connector forJava.

Synchronization level is not supported

IMS Connector for Java’s CCF implementation allows you to select from twosynchronization levels (SYNC_LEVEL_CONFIRM and SYNC_LEVEL_NONE) for aniteration of a transaction. IMS Connector for Java’s J2C implementation in thisrelease does not support the specification of synchronization level for an interaction.In this release, SYNC_LEVEL_NONE, the default synchronization level, is alwaysused. Support for selecting a synchronization level will be provided in a futurerelease.

IMS datastore name is no longer an InteractionSpec property


The datastore name property has been moved to theIMSManagedConnectionFactory class to be more consistent with the use of theJNDI naming service by the J2EE programming model. A connection factory for aparticular combination of hostname, port, and datastore name is deployed in theJNDI name space and used by all applications targeting that datastore using thehostname/port combination. Note, however, that only hostname and port areconsidered for the purposes of connection pooling.

Running a CCF Servlet in WebSphere Application Server 4.0 forWindows

If you are not ready to migrate your CCF application to J2C, you can still run it inWebSphere Application Server 4.0 for Windows. There are many ways to do this.These instructions show how you can do this with minimal changes, using one ofthe samples provided with an earlier release of IMS Connector for Java,com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet. This servletwas developed as a Web application (“webapp”), imsconn, for WebSphereApplication Server 3.5.

Step 1: Deploy imsconn.jar to WebSphere Application Server

Connectors that implement J2C architecture are packaged as “resource adapters.”Resource adapters are deployed in WebSphere Application Server 4.0 fordistributed platforms from a Resource Adapter Archive (RAR) file. IMS Connectorfor Java also implements IBM’s Common Connector Framework architecture. Thisimplementation is available as a Java Archive (JAR) file, imsconn.jar. To deployimsconn.jar in WebSphere Application Server 4.0 for distributed platforms, copyimsconn.jar from <ico_install_dir>/IMSICO/CCF, where <ico_install_dir> is thedirectory where you installed IMS Connector for Java to<was_install_dir>/WebSphere/AppServer/lib, where <was_install_dir> is thedirectory where you installed WebSphere Application Server 4.0.

Note: In the past it was necessary to copy ccf.jar, eablib.jar, and recjava.jar fromVisualAge for Java to a directory accessible to WebSphere Application Server. Itwas also necessary to modify the classpath used by WebSphere Application Serverto point to these JAR files as required. This in no longer necessary becauseWebSphere Application Server 4.0 for distributed platforms includes these JAR files.

Step 2: Make the Servlet Files Accessible to WebSphere Application Server4.0

Copy the contents (files and folders) from the following folder:

<vaj_install_drive>\IBM Connectors\IMSCONN\samples\servlets\phonebook

where <vaj_install_drive> is the VisualAge for Java installation directory to a folderof your choice on the target WebSphere Application Server 4.0 machine. Forexample, CCFWAS40. The CCFWAS40 folder should now contain the followingfolders and files:

v com

v theme

v DFSMsg.jsp

v Ex01Servlet.jar

v Ex01ServletHTMLError.jsp

v Ex01ServletHTMLInput.html


v Ex01ServletHTMLResults.jsp

Step 3: Modify the Servlet’s Input HTML

Remove the “servlet” keyword from the FORM statement of the servlet’s inputHTML, Ex01ServletHTMLInput.html. For example:

<!— <FORM METHOD=“post”ACTION=“/webapp/imsconn/servlet/com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet”

<FORM METHOD=“post”ACTION=“/webapp/imsconn/com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet”>

Step 4: Start WebSphere’s Application Assembly Tool

1. From your Windows desktop, click Start > Programs > IBM WebSphere >Application Server 4.0 > Application Assembly Tool.

2. When the “Welcome to Application Assembly Tool” appears, select Cancel.

Step 5: Create a Web Module

1. Name your Web module.

a. From the menu bar of WebSphere’s Application Assembly Tool, select File >New > Web Module.

b. Ensure that the General tab is selected and enter a Display name for yourWeb module. For example, Ex01ServletWebMod. Enter an optionaldescription of your Web module.

c. When you select the Apply you will notice that the name you chose for yourWeb module will replace the default name in the left pane of theApplication Assembler window.

2. Add files to your Web module.

a. Expand the Files folder in the left pane of the Application Assemblerwindow.

b. Right-click on the Class Files folder and select Add Files.

c. Select the Browse button beside the Root Directory or Archive entry field.If your files are in a folder (rather than an archive):

1) Locate and select the folder containing your servlet class file and itspackage directory structure. For example, select CCFWAS40.

2) Verify that the root directory (for example, CCFWAS40) appears in theFiles of Type: entry field and click the Select button.

3) You should see the files contained in the selected folder listed in theupper right pane of the Add Files window.

4) Expand the directory structure of the servlet class package foundunderneath your root directory by clickingthe plus signs next to each folder that makes up your servlet’s packagename. For example, click the plus sign next to thefollowing folders in order: com, ibm, connector, ims, sample, phonebook,servlet.

5) Select the folder at the bottom of this structure, which should contain theclass of your servlet. For example, select the servlet folder. This shouldthen display your servlet’s class in the upper right pane.

6) Select your servlet’s class (for example, Ex01Servlet.class) and click theAdd button. This should list the servlet’s package directory structure andclass name in the Selected Files: pane.


7) Click OK.

8) Right-click on the Jar Files folder and select Add Files. Repeat theprocess used to add class files, but this time add the following:

v Ex01Servlet.jar

9) Right-click on the Resource Files folder and select Add Files. Repeatthe process used to add class files, but this time add the following:

v DFSMsg.jsp


v Ex01ServeltHTMLInput.html

v Ex01ServeltHTMLResults.jsp

v com/ibm/connector/ims/sample/phonebook/servlet/Ex01Servlet.servlet

v theme/Master.css

3. Add a Web component to your Web module.

A Web module is used to assemble servlets, JavaServer Pages, Web pages,and other static content into a single deployable unit. A Web component is aservlet or JavaServer Page. In this case, you are adding a servlet Webcomponent to your Web module, Ex01ServletWebMod.

a. Right-click on Web Components in the left pane of the ApplicationAssembler window, then select New.

b. In the New Web Component window:

1) Enter the name of your servlet in the Component name: entry field. Forexample, Ex01Servlet.

2) In the Display name: entry field, enter the name of this web componentas it will be listed in your web module. For example, Ex01Servlet.

3) Select the Servlet radio button, then select the Browse button besidethe Class name: field.

4) Locate and select your servlet class file in the WEB_INF folder. Thenclick OK.

5) In the New Web Component window, verify that the full package andclass name of the servlet are displayed in theClass name field. Click the OK button.

4. Provide your servlet’s mapping information. A servlet mapping associates aservlet with a client request by using a URL pattern.

a. Right-click Servlet Mapping in the left pane of the Application Assemblerwindow, then click New.

b. Enter /com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet in theURL pattern: entry field, then click OK. (See the statement that beginsFORM METHOD=“post” ACTION= of the file Ex01ServletHTMLInput.html.)

5. Save your Web module in a WAR file.

a. Select your Web module in the left pane of the Application Assemblerwindow. For example, select Ex01ServletWebMod.

b. Select File > Save as... from the menu of the Application Assembly Toolwindow and save your WAR file with a name you choose. For example,Ex01Servlet.war.

Step 6: Create an Enterprise Application from your Web Module

1. Select File > New > Application from the menu of the Application AssemblyTool window.


2. In the Display name: entry field of the right pane of the ApplicationAssembler window, enter a name for your enterprise application, then selectthe Apply button. For example, Ex01ServletApp.

3. In the left pane of the Application Assembler window, right-click on WebModules under your enterprise application, Ex01ServletApp, and selectImport.

4. Locate the WAR file for your Web module (for example, Ex01Servlet.war), selectit, then select the Open button.

5. In the Confirm values window, enter /webapp/imsconn in the Context rootentry field, then select OK.

6. Save your Enterprise application in an .ear file.

a. Select your Enterprise application in the left pane of the ApplicationAssembler window. For example, select Ex01ServletApp.

b. Select File > Save as... from the menu of the Application Assembly Toolwindow and save your .ear file with a name you choose. For example,Ex01ServletApp.ear.

7. You may now exit from the Application Assembler if you wish.

Step 7: Start the WebSphere Advanced Administrative Console

1. From your Windows desktop, click Start > Programs > IBM WebSphere >Application Server 4.0 > Start Admin Server. You must start this serverbefore you start the Administrative Console.

2. Click Start > Programs > IBM WebSphere > Application Server 4.0 >Administrator’s Console.

Step 8: Deploy your Enterprise Application

Using the instructions for “Deploying the IMS Connector for Java IVP in WebSphereApplication Server” in “Preparing your WebSphere Application Server environmentfor Windows” as a guideline, deploy your enterprise application (for example,Ex01ServletApp) to WebSphere Application Server.

Step 9: Run your Enterprise Application

Do the following in a browser of your choice:

1. In the Web address field, enter“http://localhost:9080/webapp/imsconn/Ex01ServletHTMLInput.html” (where/webapp/imsconn is the context root of your enterprise application in thisexample).

2. Provide values for the input fields as required. Values for dataStoreName,hostName, IN_CMD, IN_NAME1, IN_TRCD, and portNumber are required torun ivtno, one of the IMS INSTALL/IVP sample transactions on which thisEx01Servlet sample is based.

Values for IN_EXTN, IN_NAME1, IN_ZIP, User Name, Password, and Groupmight be required, depending on the value of IN_CMD that you entered and thesecurity settings for OTMA and IMS Connect.

Click the Submit button when you have finished entering the required values.The browser will submit a request to the application server to run Ex01Servlet.


Running a CCF Servlet in WebSphere Application Server 4.0 for z/OSand OS/390

If you are not ready to migrate your CCF applications to J2C, you can continue torun it them WebSphere Application Server 4.0 for z/OS and OS/390. The followinginstructions show how to do this with minimal changes, using one of the samplesprovided with an earlier release of IMS Connector for Java,com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet. This servletwas developed as a Web application (“webapp”), imsconn, for WebSphereApplication Server 3.5.

Part 1: Assembling the Application

In this part, you will assemble your application into an enterprise archive (EAR) file.You will deploy this EAR file in the next part. This ear file contains a Web modulethat includes your HTML and JSP files and CCF servlet to run in WebSphereApplication Server for z/OS and OS/390.

To assemble your application for deployment to WebSphere Application Server forz/OS and OS/390, the Application Assembly Tool (AAT) for z/OS and OS/390 isrequired. See “Preparing to deploy the J2C Samples” section for more information.

1. Create a Web module. In this step, you will build a Web archive (WAR) file thatincludes your HTML and JSP files and CCF servlet.

If you have AAT for Windows, it is recommended that you first complete Steps 2to 5 in ““Running a CCF Servlet in WebSphere Application Server 4.0 forWindows” on page 42” to create a WAR file that contains your Web modulebefore moving on to the step. If you are planning to use tools other than theAAT for Windows to create a WAR file and import into AAT for z/OS andOS/390, make sure that you have used the appropriate values as discussed inthat section.

If you do not have tools (for example, AAT for Windows) to build a WAR file,you can build the WAR file by archiving the pieces of it (the HTML, JSP, Servletand the web.xml file) using the JAR command available with the JavaDevelopment Kit (JDK) as follows:

a. On your workstation, create a new directory (for example,c:\CCFServletWar) as the root directory for building your WAR file.

b. Create the following subdirectories under the root directory that you createdin the previous step:

v C:\CCFServletWar\WEB-INF\lib\

v C:\CCFServletWar\\WEB-INF\classes\

c. Create the web.xml file for your WAR:

1) Using a text editor, create a file named web.xml in the WEB-INF foldercreated in the previous step (for example, C:\CCFServletWar\WEB-INF\web.xml). This web.xml contains the deployment descriptorinformation for your web module.

2) Insert the following XML code into the web.xml file:<?xml version=“1.0” encoding=“UTF-8”?><!DOCTYPE web-app PUBLIC “-//Sun Microsystems,Inc.//DTD Web Application 2.2//EN”

“http://java.sun.com/j2ee/dtds/web-app_2_2.dtd”><web-app><display-name>Ex01ServletWebMod</display-name><servlet><servlet-name>Ex01Servlet</servlet-name><display-name>Ex01Servlet</display-name><servlet-class>


com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet</servlet-class></servlet><servlet-mapping><servlet-name>Ex01Servlet</servlet-name><url-pattern>

/com.ibm.connector.ims.sample.phonebook.servlet.Ex01Servlet</url-pattern></servlet-mapping></web-app>

3) Save the web.xml file.

d. Copy the following HTML and JSP files (which are also available with thesample in the <vaj_install_dir>\IBMConnectors\IMSCONN\samples\servlets\phonebook directory) to the rootdirectory for building your WAR file (for example, c:\CCFServletWar):

v Ex01ServletHTMLInput.html

v Ex01ServletHTMLResults.jsp


v DFSMsg.jsp

v com/ibm/connector/ims/sample/phonebook/servlet/Ex01Servlet.servlet

v theme/Master.css

e. Modify Ex01ServletHTMLInput.html by removing the servlet keyword fromthe FORM statement. For example: [[email protected]()]

The right-arrow symbol (—>) represents the entry of a method. The left-arrowsymbol (<—) represents the exit of a method. All the information within the sectionof a —> and a <— of the same method shows all of the execution call stack withinthat method.

A double arrow symbol (<—>) indicates that the method has been entered andexited. No specific information within the method is logged. The name before the @sign shows the class name. The alphanumeric number after the @ sign shows thehash code of the class. The name after the ’.’ of the hash code shows the methodname.

RAS_TRACE_INTERNAL

At this level, the internal state of an object and other important information aredumped to the trace log. The dump of an object normally starts with the name ofthe class to be dumped in brackets []. This is similar to the entry/exit, as shownabove, but without any symbol at the beginning. It looks similar to the following:[com.ibm.connector.imstoc.communication@1c27]

Each field value of the class is shown.

The OTMA messages ″Buffer to send:″ and ″Buffer received:″ are sent to andreceived from IMS Connect. If you understand the structure of these OTMAmessages, you can examine the information in the buffers containing these inputand output messages to help diagnose problems. An example of a problem that can


be diagnosed by examining a buffer is when the output record bean of the EABcommand doesn’t match the data being returned by the IMS application program.

RAS_TRACE_INTERNAL_NATIVE

At this level, more information about the internal state of other objects being usedby the connector are dumped tothe trace log. The dump format of the object is similar to theRAS_TRACE_INTERNAL trace level.


Appendix C. Diagnosing problems related to sockets

If the IMS Connect environment appears to be suspended or if the Java applicationor servlet (using a valid host name and port for the target IMS Connect system)fails to make a connection to that IMS Connect system, you might have reached themaximum number of sockets. The number of sockets that can exist between a Javaclient (a Java application or servlet) and the host component, IMS Connect, iscontrolled by two parameters that need to be synchronized. These parameters arethe following:

MAXSOCThe maximum number of sockets for an IMS Connect port. MAXSOCapplies to all of the ports associated with an instance of IMS Connect.MAXSOC is displayed in the MAXSOC field of the IMS Connect commandVIEWHWS. The default value for MAXSOC is 50.

Important: The value displayed in the MAXSOC field reflects one socketdedicated to Listen State and the remainder available for connections. Forexample, if MAXSOC is 50, only 49 can be used by connections from Javaclients (Java applications or servlets).

Example: If a particular host machine has a single instance of IMS Connectwith 2 ports, and if MAXSOC is 50, each port can have 49 sockets(connections) from Java clients, yielding a maximum of 98 sockets into theIMS Connect instance.

When the MAXSOC limit is reached, IMS Connect enters a wait state, fromwhich it returns at regular time intervals to check for available sockets. Ifthe Java applications or servlets are not releasing their sockets, yourenvironment can appear to be suspended. If this situation occurs, take oneof the following actions:

v Consider increasing the maximum number of sockets to 2000. Themaximum connections would then be 1999.

Related Reading: For information on increasing the maximum socketvalue, see the section on configuring IMS Connect in the IMS Connectdocumentation at http://www-4.ibm.com/software/data/db2imstools/.

v Make sockets available by cancelling one or more of the Javaapplications or servlets that are holding sockets to the particular IMSConnect.

v Avoid setting the value of the disconnectedCommunication property tofalse using the setDisconnectCommunication method of thecom.ibm.ivj.eab.command.CommunicationCommand class. If thedisconnectedCommunication property is false, the communicationremains connected after execution.

Maximum connectionsA property of the IMSConnectionSpec class that specifies the maximumnumber of connections (sockets) registered with the connection manager forthe host name and port of the associated IMSConnectionSpec. In the caseof the “real” connection manager(com.ibm.connector.connectionmanager.ConnectionManager), a pool ofconnections is kept for each host name and port combination. Therefore,Maximum connections determines the maximum number of connectionsfor a pool.

After the Maximum connections number is reached, no new connectionsare created. The NoConnectionAvailableException is thrown.


Recommendation: When synchronizing Maximum connections and MAXSOC, itis strongly recommended that Maximum connections be less than or equal toMAXSOC.

Diagnosing problems related to connection poolingIf the number of connections used by your Java application or servlet iscontinuously increasing, such that the connections are not reused by newtransaction requests nor released at the end of transaction executions, you may nothave connection pooling established appropriately in your environment. Forinformation about connection pooling, see the connection management informationin “IMS Connector for Java Concepts and Terms.”

If your Java application or servlet does not respondIn some situations, a Java application or servlet might not respond, which usuallymeans that it has sent a message to the host system and is waiting for a reply. Forexample, this situation can occur when a transaction input message is sent to IMS,but a message processing region is not available to process the transaction. In thiscase, the input message is placed on the IMS message queue, and remains thereuntil a message region is available to process it. The Java application or servletwaits for a reply.

If you do not want your Java application to wait for such a reply, change the defaulttimeout value in the configuration member of IMS Connect. Change the value of theTIMEOUT parameter in the TCP/IP statement to a value greater than 0. Setting thetimeout value to something greater than 0 will cause IMS Connect to close thesocket to the Java application if it does not receive a response from IMS within thespecified time. The TIMEOUT value is specified in hundredths of seconds. Forexample, a TIMEOUT value of 1000 specifies a 10 second timeout.

The Java application receives the exception message HWSJ029E in CCF andICO0005E in J2C. The connection will not be available for reuse. When the IMSapplication program completes and returns the output message to IMS Connect,IMS Connect will display the message HWSD0252W with service code NFNDSVTon the console (because the connection is not available to return the message tothe Java application).

Related Reading: For more information on IMS Connect, see the IMS Connectdocumentation at http://www-4.ibm.com/software/data/db2imstools.


Appendix D. Messages and exceptions

While you develop Java programs that use IMS Connector for Java, you mightencounter situations in which your program throws exceptions. Some of theseexceptions are thrown by IMS Connector for Java, while others are thrown by otherclass libraries (such as the IBM Common Connector Framework or the Java classlibraries) that your program uses.

This section provides information on:

v “Exceptions generated by IMS Connector for Java CCF applications” onpage 264

v “Exceptions generated by IMS Connector for Java J2C applications” on page 274

An example of an exception that is thrown by Java is:java.lang.NoClassDefFoundError: com/ibm/connector/infrastructure/java/JavaRuntimeContext

A common cause for this exception is an incomplete class path. When testing yourapplication in the VisualAge for Java development environment, ensure that youcompute the class path using the Class path tab of the Properties window for yourapplication.

Related Reading:

v For information on exceptions that are thrown from other class libraries, see theJavadoc information for the specific class library.

v For information on exceptions related to Local Option support, see IBM IMSConnect User’s Guide and Reference. Some exceptions are thrown based onIMS, IMS OTMA or IMS Connect errors returned by IMS Connect. Forinformation on IMS OTMA and IMS Connect errors, see IBM IMS OpenTransaction Manager Access Guide and IBM IMS Connect User’s Guide andReference, respectively. For information on IMS errors, see IBM IMS Messagesand Codes.

The following terms, in italics in the message descriptions that follow, are replacedby specific values at runtime.

hostnameThe TCP/IP host name of the machine that is running IMS Connect.

innermethodnameThe name of the method that originally throws this exception. Thisexception has been caught by IMS Connector for Java and is beingre-thrown to another exception, according to the Common ConnectorFramework specification.

lengthThe length of the data.

libraryFileNameThe Local Option native library file name.

llvalueThe value of LL.

maxlengthThe maximum valid length of the data.


methodnameThe name of the method that is throwing this exception.

mode The type of interaction between IMS Connector for Java and the IMSConnect component on the host (as defined in the interactionspec).

nativeMethodNameThe Local Option native method name.

portnumberThe port number that is assigned to IMS Connect.

propertynameThe name of the property.

propertyvalueThe value of the property.

reasoncodeThe reason code that is returned by IMS Connect.

rectypeThe type of the record.

returncodeThe return code, formatted in decimal, that is returned by IMS Connect.

sensecodeThe sense code, formatted in decimal, that is returned from IMS OTMA.

socketexceptionThe socket exception.

source_exceptionThe exception thrown when the error first occurred in an internal method.

source_methodnameThe internal method in which the error first occurred.

state The internal state of IMS Connector for Java.

Exceptions generated by IMS Connector for Java CCF applicationsThe following exception messages are produced by applications built using the IMSConnector for Java Common Connector Framework (CCF) class libraries when anerror condition is detected.

HWSJ001E

com.ibm.connector.imstoc.IMSTOCResourceException:HWSJ001E: methodname error.IMS Connect returned error:RETCODE=[returncode],REASONCODE=[reasoncode].

Explanation: An error code has been returned by IMS Connect on the host.

User Action: For diagnostic information on the return code (returncode) andreason code (reasoncode) values, see the IMS Connect Messages and Codesmanual.

HWSJ002E


com.ibm.connector.imstoc.IMSTOCResourceException:HWSJ002E: methodname error.IMS returned error:SENSECODE=[sensecode].REASONCODE=[otmareasoncode].

Explanation: A NAK error message has been returned from IMS OTMA.

User Action: Related Reading: For diagnostic information on the sense code(sensecode) and OTMA reason code (otmareasoncode) values of the NAKmessage, see the IMS OTMA Guide and Reference.

HWSJ003E

com.ibm.connector.CommunicationException:HWSJ003E: methodname error.Failed to connect to Host name[hostname], Port [portnumber].[socketexception].

Explanation: socketexception is one of the following:[java.net.UnknownHostException: hostname]Hostname is invalid. Check the spelling of the Host name, and use the fullyqualified path for Host name. Correct the application, if necessary.[java.net.SocketException: Connection refused] One of the followingoccurred:

v Port number is invalid.

v The IMS Connect host component with the specified host name is down.

v TCP/IP restarted without canceling and restarting IMS Connect (HWS) onthe host machine, or issuing stopport followed by openport.

Take the following actions:

v Verify that the port number for IMS Connect on the host with the specifiedhost name.

v Start IMS Connect (HWS) on the host machine.

v Do one of the following:

– Cancel and restart the IMS Connect component on the host machine.

– Issue stopport dddd, followed by openport dddd, where dddd is theport number for IMS Connect.

[java.net.SocketException: Connection timed out] One of the followingoccurred:

v The machine with the specified host name is inaccessible on the TCP/IPnetwork.

v TCP/IP on the host system is down.

Take the following actions:

v Ensure that the host machine is accessible from the TCP/IP network. Verifyby issuing the ping command to the host machine.

v Restart TCP/IP on the host and do one of the following:

– Cancel and restart the IMS Connect component on the host machine.

Appendix D. Messages and exceptions 265

– Issue stopport dddd, followed by openport dddd, where dddd is theport number for IMS Connect.

HWSJ004E

com.ibm.connector.CommunicationException:HWSJ004E: methodname error.Failed to close the connection.[socketexception]

Explanation: The connection failed to close. The connection with the host hasbeen reset, or the TCP/IP connection is down.

User Action: Refer to the socketexception for more details for the cause offailure. Restart IMS Connect and TCP/IP on the host, if appropriate.

HWSJ005E

com.ibm.connector.CommunicationException:HWSJ005E: methodname error.Failed to send the data.[socketexception]

Explanation: Failed to write to a socket to send the transaction message toIMS Connect on the host. The connection with the host has been reset or theTCP/IP connection is down.

User Action: Refer the socketexception for more details of the failure. RestartIMS Connect and TCP/IP on the host, if appropriate.

HWSJ006E

com.ibm.connector.NotConnectedException:HWSJ006E: methodname error.The connection resource is notconnected.

Explanation: An application programming error occurred while attempting toexecute a transaction. The connection has not been established.

User Action: Correct the application program.

HWSJ007E

com.ibm.connector.AlreadyConnectedException:HWSJ007E: methodname error.The connection resource is alreadyconnected.

Explanation: An application programming error occurred while attempting toconnect to IMS Connect on the host. The connection has already beenestablished.



HWSJ008E

java.lang.IllegalArgumentException:HWSJ008E: methodname error.The property [propertyname] exceededmaximum length.Length is [length],maximum length is [maxlength].

Explanation: An application programming error occurred. The property valueis invalid (the length exceeded the maximum value).

User Action: Verify the property value. The length must be less than themaximum length value. Correct the application program.

HWSJ009E

java.lang.IllegalArgumentException:HWSJ009E: methodname error.The [propertyname] property value[propertyvalue] is invalid.

Explanation: An application programming error occurred. The property valueis invalid.

User Action: Verify the property value. Correct the application program.

Related Reading: For a list of supported values for property, see theVisualAge for Java documentation by clicking Help > Help Home Page >Reference > IBM Tool APIs > Connectors > IMS Connect.

HWSJ010E

java.lang.IllegalArgumentException:HWSJ010E: methodname error.The input record type is invalid.The type currently supported is[rectype].

Explanation: An application programming error occurred. The type of inputrecord bean is invalid.

User Action: Verify the type of input record bean. The record type of the inputbean must be rectype. Correct the application program.

HWSJ011E

java.lang.IllegalArgumentException:HWSJ011E: methodname error.The output record type is invalid.The type currently supported is[rectype].


Explanation: An application programming error occurred. The type of outputrecord bean is invalid.

User Action: Verify the type of output record bean. The record type of theoutput bean must be rectype. Correct the application program.

HWSJ012E

com.ibm.connector.BadInvOrderException:HWSJ012E: methodname error.Protocol violation.The connection resource is inan inappropriate state [state]for the execution [execution].

Explanation: An application programming error occurred during the orderedsequence of methods invocation of an interaction with IMS Connect on thehost. Connector is in an inappropriate state for the requested execution. Apossible cause might be that command.execute() is called beforecommunication.connect().

User Action: Correct the application program. Correct the execution flow:communication.connect() > communication.execute() >communication.disconnect()

Related Reading: For the suggested execution flow, see the VisualAge forJava documentation by clicking Help > Help Home Page > Reference > IBMTool APIs > Connectors > IMS Connect.

HWSJ013E

com.ibm.connector.BadInvOrderException:HWSJ013E: methodname error.Protocol violation.The Interaction Mode [mode]is not allowed for thecurrent state [state].

Explanation: An application programming error occurred in the orderedsequence of methods invocation of an interaction with IMS Connect on thehost. The execution of the command with the specified interaction mode is notallowed in the state. A possible cause might be the execution of the secondinteraction of a command with the synchronization level ofSYNC_LEVEL_CONFIRM (as specified in the IMSConnectionSpec bean)without previously executing an ACK or NACK command to reply to IMSConnect on the host for the first interaction.

For example, (1st interaction) command.execute() > (2nd interaction)command.execute() ... An ACK or NACK command is an EAB command withinteraction mode MODE_ACK or MODE_NACK.

User Action: Correct the application program. Correct the execution flow tothe following: (1st interaction) command.execute() > ackCommand.execute (to


reply to IMS Connect on the host as it is waiting for a response because ofthe synchronization level of Confirm) > (2nd interaction) command.execute()

Related Reading: For suggested execution flow, see the VisualAge for Javadocumentation by clicking Help > Help Home Page > Reference > IBM ToolAPIs > Connectors > IMS Connect.

HWSJ014E

com.ibm.connector.ResourceException:HWSJ014E: methodname error.The connection resource is inan invalid state [state].

Explanation: An application programming error occurred. The value of thestate field is invalid.


Related Reading: For the valid values of state, see the VisualAge for Javadocumentation by clicking Help > Help Home Page > Reference > IBM ToolAPIs > Connectors > IMS Connect.

HWSJ015E

java.lang.IllegalArgumentException:HWSJ015E: methodname error.This was an error in building theOTMA message. [exception]

Explanation: The exception is one of the following:

vcom.ibm.imstoc.IMSException:HWSJ501E: innermethodname error.The LL value of the input message is incorrect.

The LL value of the input message is incorrect. Ensure that the LL value ofthe input object that is provided by the application program matches the reallength of the message data. Correct the application program.

vcom.ibm.imstoc.IMSException:HWSJ502E: innermethodname error.The input byte array is not pure DBCS.There is an odd number of bytes.

The input byte array is not pure DBCS. An odd number of bytes exists.Ensure that this exception is being handled properly in your applicationprogram. See the exception for the specific cause of the error.

v For other exception types that are not listed above, see the exception of thespecific cause of the error. An error building the OTMA message for theinteraction request occurred. Ensure that the values provided by theapplication program are valid for building the interaction request. Correct theapplication program.

HWSJ016E


com.ibm.connector.ResourceException:HWSJ016E: methodname error.Two phase commit is not supported.

Explanation: An application programming error occurred while attempting touse two-phase commit to coordinate the transaction. Currently, two-phasecommit is not supported.

User Action: Use IMSConnection.commitOnePhase(). Correct the applicationprogram.

As suggested in the IMS Connector for Java User’s Guide, the applicationimplementation should invoke the Coordinator.commit() in order to commit aconnection. If the application is using the original Coordinator class from CCF,the IMSConnection.commitOnePhase() method is automatically invoked.Therefore, this exception is not thrown. However, if the application uses themethod (IMSConnection.commit()) directly to commit the connection, thisexception is thrown.

HWSJ017E

com.ibm.connector.TransactionRolledBack:HWSJ017E: methodname error.An exception occurred during commit.Transaction was rolled back andthe connection will be closed[exception].

Explanation: An exception occurred while attempting to commit thetransaction. This exception notifies the application program that the transactionhas been rolled back and that the connection is closed.

Definition: A connection is marked as dirty when severe exceptions, such ascommunications or protocol violations, occur during the execution.

User Action: Ensure that this exception is handled properly by the applicationprogram. See the exception for the specific causes of the error.

HWSJ018E

HWSJ018E: methodname error.An exception occurred whileattempting to close the dirty connection[socketexception].

Explanation: An exception has occurred while attempting to close the dirtyconnection. This warning message is normally displayed after anotherexception is shown during the execution of the command.


User Action: See the socketexception for the specific cause of the exception.Because this is a warning message, no specific action is needed. However, if


the exception impacts the subsequent execution of the application program,ensure that the application can handle the situation properly.

HWSJ019E

com.ibm.connector.ResourceException:HWSJ019E: methodname error.Resource is registered with thecoordinator.

Explanation: An application programming error occurred. The connectionresource is still registered with the Coordinator while preparing the connectionto be reused.

User Action: Verify that the managed connection has been unregistered withthe Coordinator by invoking commit()/rollback() before reusing the connectionin the application program. Correct the application program.

HWSJ021E

com.ibm.connector.ResourceException:HWSJ021E: methodname error.Attempted to execute on a dirtyconnection.

Explanation: An application programming error occurred while attempting toexecute or commit on a dirty connection.


If the application program attempts to commit on a dirty connection, thisexception notifies the application program that the transaction has been rolledback.

User Action: Correct the application program. Ensure that this exception ishandled properly in the application program. Do not perform any furtherexecution using a dirty connection.

HWSJ022E

com.ibm.connector.TransactionRolledBack:HWSJ022E: methodname error.Attempted to commit on a dirtyconnection.

Explanation: An application programming error occurred while attempting tocommit on a dirty connection.


User Action: Correct the application program. Ensure that this exception ishandled properly by the application program. Do not perform any furtherexecution using a dirty connection.


HWSJ024E

java.lang.IllegalArgumentException:HWSJ024E: methodname error.Invalid segment length (LL) of [llvalue]in input object.

Explanation: The segment length LL of the input object is invalid.

User Action: Verify that the segment length LL in the segment messagematches the real length of the segment. Correct the application program.

HWSJ025E

java.lang.IllegalArgumentException:HWSJ025E: methodname error.Invalid segment length (LL) of [llvalue]in OTMA message.

Explanation: The segment length LL of the OTMA message is invalid whileprocessing the output transaction message from IMS.

User Action: Verify that the transaction output message that is being sentback from the IMS transaction is correct. Verify that the segment length LL inthe OTMA message that is received is valid and matches the real length of thesegment. Correct the application program.

HWSJ026E

java.lang.IllegalArgumentException:HWSJ026E: methodname error.There was an error in processing theoutput message. [exception]

Explanation: An error occurred while processing the output message that isreceived from IMS. The output message that is sent from the IMS transactionmight be invalid.

User Action: Verify that the output message that is sent from the IMStransaction is valid. See the exception for the specific cause of the error.Correct the application program.

HWSJ027E

java.lang.IllegalArgumentException:HWSJ027E: methodname error.An error occurred when completingthe interaction request. [exception]

Explanation: An error occurred while completing the interaction request of thecommand. For example, the connection with IMS Connect on the host mightbe down while completing the interaction. The interaction request might ormight not be completed successfully.

User Action: Ensure that this exception is handled properly by the applicationprogram. See the exception for the specific cause of the error.


HWSJ028E

com.ibm.connector.TransactionRolledBack:HWSJ028E: methodname error.An exception occurred duringrollback. [exception]

Explanation: An exception occurred while attempting to perform a roll back onthe transaction. The connection is closed.

User Action: Ensure that this exception is handled properly by the applicationprogram. See the exception for the specific cause of the error.

HWSJ029E

com.ibm.connector.CommunicationException:HWSJ029E: methodname error.A communication error occurred whilereceiving the output message. [exception].

Explanation: Failed to read the output message from the socket. One of thefollowing may have occurred:

v The client on IMS Connect was closed. (For example, the IMS ConnectSTOPCLNT command was issued).

v The connection with the host has been reset or the TCP/IP connection isdown.

v The output message is incomplete or corrupted.


User Action: Refer to the exception for more details of the failure. The “dirty”connection will be closed and will not be reused. A new connection will becreated for the next request.

HWSJ030E

java.lang.lllegalArgumentException:HWSJ030E: methodname error.errortext1 error: errortext2.

Explanation: An error has been detected by IMS Connector for Java duringLocal Option processing. This is a generic exception that may apply to avariety of different error conditions.

User Action: An invalid argument was supplied to one of the Local Optionprocessing classes. For example, if the IMS Connect name supplied in thehostname property of IMSConnectionSpec is null or blanks, this exceptionwould be thrown. Examine the argument identified in the message error textand verify that it is a valid value for the property that it represents. In theabove example, errortext2 would be ″IMS Connect name is null.″ You wouldneed to ensure that the IMS_connect_name portion of theIMSConnectionSpec hostname property is set to the correct value.


Exceptions generated by IMS Connector for Java J2C applicationsThe following exception messages are produced by applications built with the Java2 Platform, Enterprise Edition (J2EE) Connector Architecture (J2C) class librarieswhen an error condition is detected.

ICO0001E

javax.resource.spi.EISSystemException:ICO0001E: methodname error.IMS Connect returned error:RETCODE=[returncode], REASONCODE=[reasoncode].[source_methodname: source_exception]

Explanation: IMS Connect returned an error. The connection in error will notbe reused.

User Action: For diagnostic information on the return code (returncode) andreason code (reasoncode) values, see the IMS Connect Messages and Codesmanual.

ICO0002E

javax.resource.spi.EISSystemException:ICO0002E: methodname error.IMS OTMA returned error:SENSECODE=[sensecode], REASONCODE=[otmareasoncode].[source_methodname: source_exception]

Explanation: IMS OTMA returned a NAK error.

User Action: Related Reading: For diagnostic information on the sense code(sensecode) and OTMA reason code (otmareasoncode) values of the NAKerror, see the IMS OTMA Guide and Reference.

ICO0003E

javax.resource.spi.CommException:ICO0003E: methodname error.Failed to connect to host [hostname],port [portnumber].[java_exception]

Explanation: IMS Connector for Java was unable to connect to the host andport combination. java_exception indicates the reason for the failure toconnect. For additional information see User Action: below.

User Action: Examine java_exception to determine the reason for the failureto connect to the host. Some suggested actions to take, based on the value ofjava_exception are:

v java.net.UnknownHostException: hostname The host name you specifiedwhen configuring the Connection Factory used by your application is invalidor your application specified an invalid host name. Check the spelling of thehost name. You may have to use the fully qualified path for host name.


v java.net.ConnectException: Connection refused One of the followingoccurred:

– The port number is invalid. Ensure that you are using a valid portnumber for the target IMS Connect (indicated by hostname).

– The specified port is stopped. Use the IMS Connect command,OPENPORT dddd, where dddd is the specified port number, to start theport.

– IMS Connect on the specified host machine is not running. Start IMSConnect (HWS) on the host machine.

– TCP/IP restarted without canceling and restarting IMS Connect orissuing STOPPORT followed by OPENPORT on the host machine.

v java.io.InterruptedIOException: Operation timed out

One of the following occurred:

–

– The machine with the specified host name is inaccessible on the TCP/IPnetwork. Ensure that the host machine is accessible from the TCP/IPnetwork. Verify by issuing the ping command to the specified hostmachine. Enter the ping command on the machine on which IMSConnector for Java is running.

– TCP/IP on the host system is down. Restart the TCP/IP on the host anddo one of the following:

- Cancel and restart the IMS Connect component on the host machine.

- Issue the IMS Connect command STOPPORT dddd, then issue thecommand OPENPORT dddd, where dddd is the port number for IMSConnect.

ICO0005E

javax.resource.spi.CommException:ICO0005E: methodname error.A communication error occurred while sending or receiving the IMSmessage.[java_exception]

Explanation: IMS Connector for Java was unable to successfully complete asend and receive interaction with the target host. java_exception indicates thereason for the failure to complete the interaction. For additional informationsee User Action: below.

User Action: Examine java_exception to determine the reason for the failureto connect to the host. Some suggested actions to take, based on the value ofjava_exception are:

v java.io.EOFException

The client sees this exception when the timeout specified in the IMSConnect configuration causes it to expire before receiving a response fromIMS. The connection in error will not be reused. This exception typicallyhappens when there is no region available in IMS to run the transaction toprocess the client’s request. If this is the case, ensure that an appropriateregion is started and available to process work. It can also happen if theIMS application program associated with the transaction is stopped. If this isthe case, use the IMS command /START PROGRAM to start the IMSapplication program.


A client also receives this exception if it tries to use a previously activeclient (for example, a connection from the pool) for which an IMS ConnectSTOPCLNT command has been issued.

v java.net.SocketException: socket closed

A client might receive this exception after an IMS Connect STOPCLNTcommand has been issued.

v java.net.SocketException: Connection reset by peer

A client would receive this exception if the client uses a previously workingconnection but TCP/IP on the host has gone down.

ICO0006E

javax.resource.ResourceException:ICO0006E: methodname error.The value provided for DataStoreName is null or an empty string.

Explanation: The method indicated in methodname was invoked using anempty DatastoreName parameter.

User Action: Provide a valid DatastoreName parameter. In a managedenvironment, the DatastoreName is specified when you are configuring aConnection Factory to be used by WebSphere Application Server. In anon-managed environment, the DatastoreName is specified in your Javaapplication.

ICO0007E

javax.resource.NotSupportedException:ICO0007E: methodname error.The [propertyName] property value [propertyValue] is not supported.

Explanation: The value propertyValue specified for the propertypropertyName is not supported.

User Action: Provide a supported value for the named property. For example,certain values of the InteractionVerb property of the InteractionSpec class thatare be defined by the J2C architecture might not be supported by this releaseof IMS Connector for Java.

ICO0008E

javax.resource.ResourceException:ICO0008E: methodname error.The value [propertyValue] of the [propertyName] property exceeds themaximum allowable length of [maxPropertyLength].

Explanation: The length of the value propertyValue supplied for propertypropertyName exceeds maxPropertyLength, the maximum length allowed forvalues of property propertyName.

User Action: Provide a value for the named property which does not exceedmaxPropertyLength.

ICO0009E


javax.resource.ResourceException:ICO0009E: methodname error.The [propertyName] property value [propertyValue] is invalid.

Explanation: The value propertyValue specified for the propertypropertyName is not valid.

User Action: Provide a value which is valid for the named property. Validvalues for the InteractionVerb property of the InteractionSpec class of IMSConnector for Java are listed in the Javadoc for the IMSInteractionSpec class.See the VisualAge for Java documentation by clicking Help > API Reference> IBM APIs > Connectors > IMS Connector > Packagecom.ibm.connector2.ims.ico > methodsetInteractionVerb of classIMSInteractionSpec.

ICO0010E

javax.resource.spi.IllegalStateException:ICO0010E: methodname error.Method invoked on invalid IMSConnection instance.

Explanation: The method indicated in methodname was invoked on an invalidIMSConnection instance.

User Action: The named method was most likely issued on anIMSConnection instance that was already closed. Ensure that theIMSConnection instance is not already closed before you attempt to use it orclose it.

ICO0011E

javax.resource.spi.IllegalStateException:ICO0011E: methodname error.Method invoked on invalid IMSInteraction instance.

Explanation: The method indicated in methodname was invoked on an invalidIMSInteraction instance.

User Action: The named method was most likely issued on an IMSInteractioninstance that was already closed. Ensure that the IMSInteraction instance isnot already closed before you attempt to use it or close it.

ICO0012E

javax.resource.ResourceException:ICO0012E: methodname error.The value provided for HostName is null or an empty string.

Explanation: The method indicated in methodname was invoked using amnull or empty HostName parameter.

User Action: Provide a valid HostName parameter. In a managedenvironment, the property value is specified when you are configuring aConnection Factory to be used by WebSphere Application Server. In anon-managed environment, the property value is specified in your Javaapplication.


ICO0013E

javax.resource.ResourceException:ICO0013E: methodname error.ConnectionManager is null.

Explanation: The method indicated in methodname was invoked. Theapplication server invoked the createConnectionFactory method of theIMSManagedConnectionFactory class with a null ConnectionManager object.

User Action: Provide a valid HostName parameter. This form of thecreateConnectionFactory method is used in a managed environment. It isnot typically invoked by a client program. Contact the service personnel foryour application server.

ICO0014E

javax.resource.ResourceException:ICO0014E: methodname error.Input record contains no data.

Explanation: The method indicated in methodname was invoked with an inputrecord that contained no data.

User Action: Verify that the input record that you provide is not empty.

ICO0015E

ResourceAdapterInternalExceptionICO0015E: methodname error.Unexpected error encountered while processing the OTMA message.[java_exception]

Explanation: An unexpected internal error was encountered while processingthe OTMA message.

User Action: Contact your IBM service representative.

ICO0017E

ResourceAdapterInternalExceptionICO0017E: methodname error.Invalid value provided for TraceLevel.

Explanation: An invalid trace level was specified.

User Action: Specify a valid trace level. Optionally, this exception can beignored due to the fact that the default trace level will be used for thisconnection factory. In this case, the connection factory is still usable but thetrace level will be the default trace level. For valid trace level values, see theVisualAge for Java documentation by clicking Help > API Reference > IBMAPIs > Connectors > IMS Connector > Packagecom.ibm.connector2.ims.ico > interface IMSTraceLevelProperties.

ICO0018E


javax.resource.ResourceException:ICO0018E: methodname error.The value provided for PortNumber is null.

Explanation: The method indicated in methodname was invoked using a nullPortNumber.

User Action: Provide a valid PortNumber parameter. In a managedenvironment, the property value is specified when you are configuring aConnection Factory to be used by WebSphere Application Server. In anon-managed environment, the property value is specified in your Javaapplication.

ICO0024E

javax.resource.ResourceException:ICO0024E: methodname error.Invalid segment length (LL) of [llvalue] in input object.[java_exception]

Explanation: The input message provided by the Java program for the IMSapplication program contains a value for its segment length which is eithernegative, 0, or greater than the number of bytes of data in the messagesegment.

User Action: Provide the correct value for the segment length of the inputmessage.

ICO0025E

javax.resource.IllegalArgumentException:ICO0025E: methodname error.Invalid segment length (LL) of [{1}] in OTMA message.

Explanation: The output message provided by the IMS application programcontains a value for its segment length which is either negative, 0, or greaterthan the number of bytes of data in the message segment. The outputmessage provided by the IMS application program is contained in the OTMAmessage.

User Action: Ensure that your IMS application program provides valid lengthsfor the segments of its output message.

ICO0026E

javax.resource.ResourceException:ICO0026E: methodname error.An error was encountered while processing the IMS message.[source_methodname:source_exception]

Explanation: An error occurred while processing the IMS transaction input oroutput message. source_exception provides additional information regardingthe cause of the error.


User Action: Examine source_exception for additional information regardingthe cause of the error. Some suggested actions to take, based on the value ofsource_exception are:

v java.io.IOException

Error preparing input or output record. Ensure that the objects you areproviding to IMS Connector for Java for use as the IMS transaction inputand output are defined properly for the J2C architecture. For example,ensure that they implement the interfaces javax.resource.cci.Record andjavax.resource.cci.Streamable. This is done for you when you useVisualAge for Java’s Enterprise Access Builder to create you input andoutput records.

v com.ibm.ims.ico.IMSConnResourceException

The OTMA message containing the IMS transaction output messagecontained an invalid length field (i.e., LLLL was <= 0). If this error continuesto occur after verifying that your IMS application program is returning a validoutput message, contact your IBM service representative.

ICO0031E

javax.resource.spi.IllegalStateException:ICO0031E: methodname error.Protocol violation. The Interaction Verb [interactionverb] is not allowed forthe current state [state].[java_exception]

Explanation: The action attempted has resulted in a protocol violation. Forexample, a protocol violation would occur if your Java program is not inconversation, but you attempt an interaction with IMS using theSYNC_END_CONVERSATION value for the InteractionVerb property of anIMSInteractionSpec instance.

User Action: Ensure that you are using an appropriate value for theInteractionVerb property of IMSInteractionSpec.

ICO0033E

javax.resource.NotSupportedException:ICO0033E: methodname error.XAResource interface not supported.

Explanation: XA Transactions are currently not supported by IMS Connectorfor Java.

User Action: Ensure that your Java application uses classes and methodsthat are appropriate for the level of support currently provided by IMSConnector for Java.

ICO0034E

javax.resource.NotSupportedException:ICO0034E: methodname error.Auto-commit not supported.

Explanation: Auto-commit is currently not supported by IMS Connector forJava.



ICO0035E

javax.resource.NotSupportedException:ICO0035E: methodname error.Local Transaction not supported.

Explanation: Local Transactions are not currently supported by IMSConnector for Java.


ICO0037E

javax.resource.NotSupportedException:ICO0037E: methodname error.ResultSet not supported.

Explanation: ResultSets are currently not supported by IMS Connector forJava.


ICO0039E

javax.resource.spi.IllegalStateException:ICO0039E: methodname error.IMS Connect returned error:Not in CONNECT state.

Explanation: The sequence of interactions between IMS Connector for Javaand IMS Connect is invalid. The current state of the interaction is not theCONNECT state as it needs to be at this point in the interaction.


ICO0040E

javax.resource.NotSupportedException:ICO0040E: methodname error.IMSConnector does not support this version of execute method.

Explanation: IMS Connector for Java does not currently support the form ofthe execute method that takes two input parameters and returns an object oftype javax.resource.cci.Record.

User Action: Use the form of the execute method in class IMSInteraction withthe following signature:boolean execute(InteractionSpec, Record input, Record output)


ICO0041E

javax.resource.ResourceException:ICO0041E: methodname error.Invalid interactionSpec specified [interactionSpec].

Explanation: An invalid InteractionSpec object was passed to the executemethod of class com.ibm.connector2.ims.ico.IMSInteraction.

User Action: Verify that they InteractionSpec object you passed to theexecute method of class com.ibm.connector2.ims.ico.IMSInteraction is oftype com.ibm.connector2.ims.ico.IMSInteractionSpec.

ICO0042E

javax.resource.ResourceException:ICO0042E: methodname error.Input is not of type Streamable.

Explanation: The input object provided to the execute method of the classcom.ibm.connector2.ims.ico.IMSInteraction was either null or did notimplement the interface javax.resource.cci.Streamable.

User Action: Ensure that you are providing a valid input object to the executemethod. For example, ensure that it implements the interfacesjavax.resource.cci.Record and javax.resource.cci.Streamable. This is donefor you when you use VisualAge for Java’s Enterprise Access Builder to createyour input record.

ICO0043E

javax.resource.ResourceException:ICO0043E: methodname error.Output is not of type Streamable.

Explanation: The output object provided to the execute classcom.ibm.connector2.ims.ico.IMSInteraction was either null or did notimplement the interface javax.resource.cci.Streamable.

User Action: Ensure that you are providing a valid output object to theexecute method. For example, ensure that it implements the interfacesjavax.resource.cci.Record and javax.resource.cci.Streamable. This is donefor you when you use VisualAge for Java’s Enterprise Access Builder to createyour output record.

ICO0044E

javax.resource.NotSupportedException:ICO0044E: methodname error.RecordFactory is not supported by IMS Connector for Java.

Explanation: RecordFactory is currently not supported by IMS Connector forJava.



ICO0045E

javax.resource.NotSupportedException:ICO0045E: methodname error.Invalid type of ConnectionRequestInfo.

Explanation: An invalid ConnectionRequestInfo object was passed to an IMSConnector for Java method.

User Action: Contact the service personnel for your application server.

ICO0049E

javax.resource.NotSupportedException:ICO0049E: methodname error.The security credentials passed to getConnection do not match existingsecurity credentials.

Explanation: The security credentials in the request do not match the securitycredentials of the IMSManagedConnection instance that was being used toprocess the request.


ICO0054E

javax.resource.ResourceException:ICO0054E: methodname error.Invalid ConnectionSpec.

Explanation: IMS Connector for Java was unable to cast the connectionSpecprovided for this connection to type IMSConnectionSpec. While the CommonClient Interface will accept a connectionSpec object for any supportedconnector, IMS Connector for Java will only work with an IMSConnectionSpecor a derivative of IMSConnectionSpec as its connectionSpec.

User Action: Ensure that the connectionSpec used in your application is anIMSConnectionSpec or inherits from IMSConnectionSpec.

ICO0055E

javax.resource.ResourceException:ICO0055E: methodname error.Failed to cast the connection object to IMSConnection.

Explanation: IMS Connector for Java was unable to cast the connectionobject allocated by the ConnectionManager for this connection to typeIMSConnection. IMS Connector for Java will only work with an IMSConnectionor a derivative of IMSConnection as its connection object. This error might bethe result of a problem with the ConnectionManager.

User Action: Please contact your IBM service representative.


ICO0057E

javax.resource.spi.IllegalStateException:ICO0057E: methodname error.Invoked with invalid connection handle.

Explanation: The application is in an illegal state: the connection handle(IMSConnection instance) used for this interaction is not valid. This could notoccur if the application attempted to use a connection handle for a previouslyused connection or the handle for the wrong connection if the application hasmore than one connection open.

User Action: Ensure that the application is using the currently validIMSConnection instance for that connection.

ICO0060E

java.lang.UnsatisfiedLinkError:ICO0060E: methodname error.Error loading Local Option native library: libname=libraryFileName.[source_exception].

Explanation: The Local Option native library cannot be found in one of thedirectory listed in the libpath.

User Action: Verify the LIBPATH environment variable and en sure that theLocal Option native library exists in one of the directories listed in the libpath.If you are using IMS Connector for Java with WebSphere Application Serverfor z/OS and OS/390, ensure that the full name of the directory that containsthe Local Option native library file is defined in the LIBPATH environmentvariable for your J2EE server. For more information, see “Preparing yourWebSphere Application Server environment for z/OS and OS/390.”

ICO0061E

javax.resource.ResourceException:ICO0061E: methodname error.Local Option runs only in z/OS and OS/390.

Explanation: You can use Local Option to communicate with IMS Connectonly if your application using IMS Connector for Java is running on the z/OSor OS/390 platform.

User Action: Ensure that your application using IMS Connector for Java isrunning on the z/OS or OS/390 platform. If you plan to run your application ona workstation platform, correct your application to use TCP/IP communication.

ICO0062E

javax.resource.ResourceException:ICO0062E: methodname error.Error loading Local Option native method: libfilename=libraryFileName,methodname=nativeMethodName. [source_exception].

Explanation: The Local Option native method cannot be found.


User Action: Verify that you have the correct level of the IMS Connector Javasuch that the correct level of the Local Option native library is being installedon your system. See “Prerequisites for using IMS Connector for Java” formore information.

ICO0063E

javax.resource.spi.ResourceAdapterInternalException:ICO0063E: methodname error.Exception thrown in native method. [source_exception].

Explanation: An internal error occurred in the Local Option native library.


ICO0064E

javax.resource.spi.SecurityException:ICO0064E: methodname error.Invalid security credential.

Explanation: The security credential provided by WebSphere ApplicationServer is invalid. There is no appropriate security credential available for useby IMS Connector for Java.

User Action: Ensure that you have the correct level of WebSphere ApplicationServer for z/OS and OS/390 installed. See the “Prerequisites for using IMSConnector for Java” section for details.

ICO0065E

javax.resource.spi.SecurityException:ICO0065E: methodname error.Error obtaining credential data from the securitycredential.[source_exception].

Explanation: There is an error in obtaining the credential data from thesecurity credential provided by WebSphere Application Server.


ICO0066E

javax.resource.ResourceException:ICO0066E: methodname error.Error loading WebSphere Application Server Transaction Manager.[source_exception].

Explanation: An error occurred when accessing the Transaction Manager ofthe WebSphere Application Server for processing the transaction request.



ICO0068E

javax.resource.ResourceException:ICO0068E: methodname error.Error obtaining the transaction object. [source_exception].

Explanation: An error occurred while obtaining the transaction objectassociated with your transaction request provided by WebSphere ApplicationServer.


ICO0069E

javax.resource.spi.ResourceAllocationException:ICO0069E: methodname error.Error obtaining RRS transaction context token. [source_exception].

Explanation: An unexpected internal error occurred while obtaining an RRStransaction context token for processing the global transaction.

User Action: Ensure that you have the correct level of IMS Connect, IMSConnector for Java and WebSphere Application Server for z/OS and OS/390installed. See the “(Prerequisites for using IMS Connector for Java)” sectionfor details.


Notices

Note to U.S. Government Users Restricted Rights — Use, duplication or disclosurerestricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A. IBMmay not offer the products, services, or features discussed in this document in othercountries. Consult your local IBM representative for information on the products andservices 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, orservice that does not infringe any IBM intellectual property right may be usedinstead. However, it is the user’s responsibility to evaluate and verify the operationof any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give you anylicense to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of expressor implied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvements and/orchanges in the product(s) and/or the program(s) described in this publication at anytime without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not part of the materials for thisIBM 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 believesappropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose ofenabling: (i) the exchange of information between independently created programsand other programs (including this one) and (ii) the mutual use of the informationwhich has been exchanged, should contact:

Lab DirectorIBM Canada Ltd.1150 Eglinton Avenue EastToronto, Ontario M3C 1H7Canada

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 availablefor it are provided by IBM under terms of the IBM Customer Agreement, IBMInternational Program License Agreement or any equivalent agreement between us.

Information concerning non-IBM products was obtained from the suppliers of thoseproducts, their published announcements or other publicly available sources. IBMhas not tested those products and cannot confirm the accuracy of performance,compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of thoseproducts.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples may includethe names of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates 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 programsconforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughlytested under all conditions. IBM, therefore, cannot guarantee or imply reliability,serviceability, or function of these programs. You may copy, modify, and distributethese sample programs in any form without payment to IBM for the purposes ofdeveloping, using, marketing, or distributing application programs conforming toIBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

(C) (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. (C) Copyright IBM Corp. 1997, 2000. All rights reserved.


Programming interface information

Programming interface information is intended to help you create applicationsoftware using this program.

General-use programming interfaces allow the customer to write applicationsoftware that obtain the services of this program’s tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to help youdebug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as aprogramming interface because it is subject to change.



Trademarks and service marks

The following terms are trademarks of International Business Machines Corporationin the United States, or other countries, or both:

v AIX

v AS/400

v DB2

v CICS

v CICS/ESA

v IBM

v IMS

v Language Environment

v MQSeries

v Network Station

v OS/2

v OS/390

v OS/400

v RS/6000

v S/390

v VisualAge

v VTAM

v WebSphere

Lotus, Lotus Notes and Domino are trademarks or registered trademarks of LotusDevelopment Corporation in the United States, or other countries, or both.

Tivoli Enterprise Console and Tivoli Module Designer are trademarks of TivoliSystems Inc. in the United States, or other countries, or both.

Encina and DCE Encina Lightweight Client are trademarks of Transarc Corporationin the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

ActiveX, Microsoft, SourceSafe, Visual C++, Visual SourceSafe, Windows, WindowsNT, Win32, Win32s and the Windows logo are trademarks or registered trademarksof Microsoft Corporation in the United States, or other countries, or both.

UNIX is a registered trademark in the United States and other countries licensedexclusively through X/Open Company Limited.

Intel and Pentium are trademarks of Intel Corporation in the United States, or othercountries, or both.

Other company, product, and service names, which may be denoted by a doubleasterisk(**), may be trademarks or service marks of others.



Readers’ Comments — We’d Like to Hear from You

IMS ConnectIMS Connector for JavaUser’s Guide and ReferenceVersion 1 Release 2 Modification 2

Overall, how satisfied are you with the information in this book?

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedOverall satisfaction h h h h h

How satisfied are you that the information in this book is:

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedAccurate h h h h h

Complete h h h h h

Easy to find h h h h h

Easy to understand h h h h h

Well organized h h h h h

Applicable to your tasks h h h h h

Please tell us how we can improve this book:

Thank you for your responses. May we contact you? h Yes h No

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in anyway it believes appropriate without incurring any obligation to you.

Name Address

Company or Organization

Phone No.

Readers’ Comments — We’d Like to Hear from You��

Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM CorporationDepartment HHX/H1555 Bailey AvenueSAN JOSE CAU. S. A.95141-1003

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

Printed in the United States of Americaon recycled paper containing 10%recovered post-consumer fiber.

Documents

IMS Connector for Java User's Guide and Reference - CiteSeerX