IBM VisualAge® for Java™,Version3.5 IMSConnectorforJava User’s Guide and Reference Note! Before using this information and the product it supports, be sure to read the general information under Notices. Edition notice This edition applies to Version 3.5 of IBM VisualAge for Java and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 1998, 2000. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Chapter 1. Understanding IMS Connector for Java ...........1 Prerequisites for using IMS Connector for Java .............3 IMS Connector for Java concepts and terms ..............4 Chapter 2. Preparing to use IMS Connector for Java ..........17 Preparing your VisualAge for Java Environment .............17 Preparing your WebSphere Studio Environment .............21 Preparing your WebSphere Application Server Environment ........22 Chapter 3. Building Java applications and servlets ..........31 Building Java Applications and Servlets for Conversational Transactions ....32 Chapter 4. Building a Java Application to Run an IMS Transaction ....35 Chapter 5. Building a Java Application to Run a Navigator .......53 Chapter 6. Building a Java Application for an IMS Transaction with Multi-Segment Output Messages.................69 Chapter 7. Building a Java Application for an IMS Transaction with Multi-Segment Input Messages .................75 Chapter 8. Building an Application to Run an IMS Transaction with Synchronization Level Confirm .................81 Chapter 9. Building the Graphical User Interface ...........87 Chapter 10. Building a Java Servlet to Run an IMS Transaction .....95 Chapter 11. Building a Web Application that Uses One Servlet to Run an IMS Conversation ......................107 Chapter 12. Building a Web Application that Uses Two Servlets to Run an IMS Conversation ......................121 Appendix A. IMS INSTALL/IVP Sample Application ..........129 Appendix B. IMS Connector for Java Conversational Programming Models ..........................131 Appendix C. Using the trace and error logging facility ........137 Customizing the trace facility ...................137 Reading the trace log ......................138 Reading the error log ......................139 Appendix D. Diagnosing problems related to sockets .........141 Diagnosing problems related to connection pooling ...........142 Appendix E. Messages and exceptions ..............143 Notices ...........................153 Programming interface information .................154 Trademarks and service marks ..................155 © Copyright IBM Corp. 1998, 2000 iii iv IMS Connector for Java User’s Guide Chapter 1. Understanding IMS Connector for Java The purpose of this documentation is to help you create Java application programs or servlets that access IMS transactions by using IMS Connector for Java with IBM VisualAge for Java, IBM WebSphere Studio, and IBM WebSphere Application Server. IMS Connector for Java provides a way to create Java applications that can access IMS transactions. In conjunction with the VisualAge for Java development environment, IMS Connector for Java lets you rapidly develop Java applications that run your transactions. With additional support from the IBM WebSphere Studio and IBM WebSphere Application Server, you can build and run Java servlets that access your transactions from Web sites. IMS Connector for Java provides a Common Connector Framework-compliant Java interface to IMS Connect. IMS Connector for Java is a class library that consists of two packages: com.ibm.connector.imstoc and com.ibm.imstoc. All of the classes in the com.ibm.imstoc package and many of the classes in the com.ibm.connector.imstoc package are ″support″ classes that are not used by application developers during the development of applications that use IMS Connector for Java. The classes and methods that are needed during the development process are documented with Javadoc in the Reference section of the VisualAge for Java web help. IMS Connector for Java includes the following documented classes: v IMSCommunication v IMSConnectionSpec v IMSConvContext v IMSConvHttpSessionCleanup v IMSInteractionSpec v IMSLogonInfoItems v DFSMsg To view the Javadoc for these classes, click: Help —>Reference —> IBM APIs —> Connectors —> IMS Connector EAB commands that use IMS Connector for Java are developed with the VisualAge for Java Command Editor. An EAB command is a composite Java bean that consists of the following: v A Java bean (page 5) representing the input to the IMS transaction v One or more Java beans representing the output from the IMS transaction v An IMSConnectionSpec bean, representing the connection between the EAB command and the IMS Connect host component v An IMSInteractionSpec bean, containing information about the type of interaction that the EAB command has with IMS via IMS Connect, as well as the name of the target IMS datastore. In addition, the EAB command should contain a bean to process potential error or status messages from IMS. These messages begin with the three characters DFS; the bean that processes these messages is the DFSMsg bean. All beans that are provided by IMS Connector for Java are nonvisual beans. Figure 1 shows an overview of three environments involved in developing Java application programs and servlets that use IMS Connector for Java to access IMS © Copyright IBM Corp. 1998, 2000 1 transactions, as well as some of the class libraries that are used in each environment. A Java application typically includes a graphical user interface (GUI). A Java servlet typically uses a Web browser with HTML files as the user interface. Figure 1. Developing Java Applications and Servlets Using IMS Connector for Java The steps illustrated in Figure 1 are as follows: 1. Provide your COBOL source file to VisualAge for Java. The COBOL file contains definitions of the IMS transaction input and output messages, and might be the IMS application program that corresponds to the transaction. 2. Use the VisualAge for Java Command Editor to create an Enterprise Access Builder (EAB) command. The EAB command can be used to build either a stand-alone Java application program or a Java servlet that accesses IMS transactions. 3. VisualAge for Java can be used to quickly build and run a Java application from the EAB command. 4. If you are building a servlet, provide the EAB command to WebSphere Studio and its servlet generation wizard to generate HTML and .jsp files and a Java servlet. 5. Move the HTML and .jsp files and the Java servlet to the WebSphere Application Server environment to enable users to access your IMS transactions from a Web browser. Figures 2 and Figure 3 show how you run either a stand-alone Java application program or a Java servlet to access your IMS transactions. Figure 2. Running a Java Application That Uses IMS Connector for Java In Figure 2, the steps involved are explained as follows: 1. A GUI is used to provide the IMS transaction input and to display the output from the transaction. 2 IMS Connector for Java User’s Guide 2. If the environment of the workstation that is running the Java application does not include all of the class libraries used by the Java application, these class libraries can be deployed onto the workstation in the form of .jar files. 3. The execute method of the EAB command uses IMS Connector for Java to submit the IMS OTMA message that runs the IMS transaction. Figure 3. Running a Servlet That Uses IMS Connector for Java In Figure 3, the steps involved are explained as follows: 1. The input to the IMS transaction is provided on the Web browser in the input HTML file. WebSphere Application Server schedules the servlet. 2. The execute method of the EAB command in the servlet uses IMS Connector for Java to submit the IMS OTMA message that runs the IMS transaction. 3. The output of the IMS transaction is displayed on the Web browser. Prerequisites for using IMS Connector for Java You can use IMS Connector for Java in the following three environments: v The VisualAge for Java environment enables you to develop Enterprise Access Builder (EAB) commands that use IMS Connector for Java to access IMS transactions. VisualAge for Java also allows you to run programs that you develop from these commands. v The WebSphere Studio environment enables you to develop Java servlets from the EAB commands that you develop in VisualAge for Java. v The WebSphere Application Server enables you to run servlets that you develop in WebSphere Studio. A prerequisite to using IMS Connector for Java is IMS Connect (formerly called IMS TCP/IP OTMA Connection, or simply ITOC). IMS Connect allows client applications to send messages to IMS TM through the IMS Open Transaction Manager Access (OTMA) interface, providing connection to IMS transactions from a variety of platforms, including both workstation and mainframe products. Beginning with the release of IMS Version 7, ITOC will be called IMS Connect, and will be offered as a separately priced feature of IMS. IMS Connect will provide enhancements in usability, performance, and SMP installability. Before you attempt to run a Java application program or servlet that uses IMS Connector for Java, Version 3.5, be sure that the following products are installed on the target host machine: Chapter 1. Understanding IMS Connector for Java 3 v IMS Version 7 Connect Feature and IMS Version 7 (recommended); or v IMS