IMSConnectorforJava User s Guide and Reference

Transcription

1 IMS Connect IMSConnectorforJaa User s Guide and Reference Version1Release2Modification2

2

3 IMS Connect IMSConnectorforJaa User s Guide and Reference Version1Release2Modification2

4 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 IMS Connector for Jaa, 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 new editions. Copyright International Business Machines Corporation 1998, All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Chapter 1. Understanding IMS Connector for Jaa Prerequisites for using IMS Connector for Jaa VisualAge for Jaa WebSphere Application Serer IMS Connect IMS Platform Configurations for IMS Connector for Jaa and IMS Connect IMS Connector for Jaa concepts and terms IMS Connector for Jaa conersational programming models Migrating from CCF architecture to J2EE connector architecture Migrating IMS Connector for Jaa EAB Commands to J2EE Running a CCF Serlet in WebSphere Application Serer 4.0 for Windows 42 Running a CCF Serlet in WebSphere Application Serer 4.0 for z/os and OS/ Chapter 2. Preparing to use IMS Connector for Jaa Preparing your VisualAge for Jaa enironment Preparing your WebSphere Studio enironment Preparing your WebSphere Application Serer enironment for Windows Preparing your WebSphere Application Serer enironment for z/os and OS/ Chapter 3. Building Jaa applications and serlets Building CCF Jaa applications and serlets Building J2C Jaa applications and serlets Building Jaa applications and serlets for conersational transactions Chapter 4. Building a Jaa application to run an IMS transaction Chapter 5. Building a Jaa application to run a naigator Chapter 6. Building a Jaa application for an IMS transaction with multi-segment output messages Chapter 7. Building a Jaa application for an IMS transaction with multi-segment input messages Chapter 8. Building an application to run an IMS transaction with synchronization leel confirm Chapter 9. Building the graphical user interface Chapter 10. Building a Jaa serlet to run an IMS transaction Chapter 11. Building a Web application that uses one serlet to run an IMS conersation Chapter 12. Building a Web application that uses two serlets to run an IMS conersation Chapter 13. Building a J2C phonebook sample application Part 1: Building the J2C phonebook sample application Part 2: Assembling the J2C phonebook sample application Copyright IBM Corp. 1998, 2002 iii

6 Part 2A: Assembling and deploying the J2C phonebook sample application for Windows Part 2B: Assembling and deploying the J2C phonebook sample application for z/os and OS/ Part 3: Running the J2C phonebook sample application Chapter 14. Building a J2C conersational phonebook sample application 197 Part 1: Building a J2C conersational phonebook sample application 198 Part 2A: Assembling and deploying the J2C conersational phonebook sample application for Windows Part 2B: Assembling and deploying the J2C conersational phonebook sample application for z/os or OS/ Part 3: Running the J2C conersational phonebook sample application 217 Chapter 15. Building Container-Managed and Component-Managed Transactional EJBs to Run IMS Transactions Part 1: Preparing for the sample Part 2: Creating the sample Part 3: Packaging and Deploying the sample Part 4: Running the sample Appendix A. IMS INSTALL/IVP sample application Appendix B. Using the trace and error logging facility Turning on the trace and error logging facility for IMS Connector for Jaa CCF components Turning on the trace and error logging facility for IMS Connector for Jaa J2C components Customizing the trace facility Reading the error log Reading the trace log Appendix C. Diagnosing problems related to sockets Diagnosing problems related to connection pooling If your Jaa application or serlet does not respond Appendix D. Messages and exceptions Exceptions generated by IMS Connector for Jaa CCF applications Exceptions generated by IMS Connector for Jaa J2C applications Notices Programming interface information Trademarks and serice marks i IMS Connector for Jaa User s Guide and Reference

7 Chapter 1. Understanding IMS Connector for Jaa IMS Connector for Jaa proides a way to create Jaa applications that can access IMS transactions. In conjunction with the VisualAge for Jaa deelopment enironment, IMS Connector for Jaa lets you rapidly deelop Jaa applications that run your transactions. With additional support from IBM WebSphere Application Serer, you can build and run Jaa serlets that access your transactions from Web pages. IMS Connector for Jaa uses IMS Connect to access IMS. IMS Connect is a facility that runs on the host IMS machine and supports TCP/IP and Local Option communication to IMS. A Jaa application or serlet accesses IMS Open Transaction Manager Access (OTMA) through IMS Connect. IMS Connect accepts messages from its TCP/IP clients and routes them to IMS OTMA using the Cross-System Coupling Facility (XCF). IMS Connector for Jaa is comprised of 2 components: The deelopment component of IMS Connector for Jaa is proided with VisualAge for Jaa. The VisualAge for Jaa Enterprise Access Builder enironment enables you to deelop Enterprise Access Builder (EAB) commands, Enterprise JaaBeans (EJBs), serlets, and Jaa applications that use IMS Connector for Jaa to access IMS transactions. VisualAge for Jaa also proides a WebSphere test enironment that you can use to test the programs you deelop. The runtime component of IMS Connector for Jaa is proided as a component of IMS Connect Version 1 Release 2 (Program Number 5655-E51). The Jaa 2 Platform (J2EE) Connector (J2C) Architecture implementation of this runtime component is also referred to as the IBM WebSphere Adapter for IMS. It is packaged as a RAR file, imsico.rar, for deployment into the J2C compliant WebSphere Application Serer. The RAR file is installed to a target directory from the IBM IMS Connect, Version 1 Release 2. WebSphere Application Serer proides an enironment in which you can run the serlets and EJBs that you deelop from Web pages. WebSphere Application Serer is the primary runtime enironment for the serlets and EJBs. In the WebSphere Application Serer enironment, IMS Connector for Jaa is also referred to as the IBM WebSphere Adapter for IMS. Related Reading: See Prerequisites for using IMS Connector for Jaa for more information. This section describes IMS Connector for Jaa. It includes: What s New in IMS Connector for Jaa Version (page 1) Oeriew of IMS Connector for Jaa (page 2) Jaa 2 Platform Enterprise Edition (J2EE) support in IMS Connector for Jaa (page 4) Sample Applications (page 6) What s New in IMS Connector for Jaa Version The current release of IMS Connector for Jaa introduces the following: J2C support for WebSphere Application Serer for z/os and OS/390 Copyright IBM Corp. 1998,

8 Global transaction (2-phase commit) support when using Local Option communication in the z/os and OS/390 enironment Container-managed security support when using Local Option communication in the z/os and OS/390 enironment Local Option support for J2C applications Oeriew of IMS Connector for Jaa Figure 1 shows an oeriew of the enironments inoled in deeloping and running Jaa application programs and serlets that use IMS Connector for Jaa to access IMS transactions. A Jaa application typically includes a graphical user interface (GUI). A Jaa serlet typically uses a Web browser with HTML or JSP files as the user interface. Figure 1. Deeloping Jaa applications and serlets using IMS Connector for Jaa The steps illustrated in Figure 1 are as follows: 1. Proide your COBOL source file to VisualAge for Jaa s Enterprise Access Builder tool. The COBOL file contains data structures for the IMS transaction input and output messages. The COBOL file is typically the source of the IMS application program for the transaction. Howeer, if your IMS application program is not written in COBOL you can represent the input and output messages as COBOL data structures and proide them to the Enterprise Access Builder tool. 2. Use the VisualAge for Jaa Command Editor, an Enterprise Access Builder tool, to create an Enterprise Access Builder (EAB) command. The EAB command is a composite Jaa bean that can be used to build either a Jaa serlet or a stand-alone Jaa application program that accesses IMS transactions. A Jaa serlet runs on a Jaa application serer such as IBM s WebSphere Application Serer and uses a Web browser for transaction input and output. A stand-alone Jaa application does not use a Jaa application serer and typically uses a graphical user interface (GUI) for transaction input and output. In either case, VisualAge for Jaa can be used to quickly build a simple Jaa application program to execute the IMS transaction. This program can be easily run, within VisualAge for Jaa, in order to proe that the EAB command runs the IMS transaction. 3. If you are building a Jaa serlet to run your IMS transaction: a. Use VisualAge for Jaa s Create Serlet SmartGuide to generate HTML, JSP, and Jaa files for the serlet from the EAB command which you proide to the wizard. 2 IMS Connector for Jaa User s Guide and Reference

9 b. Deploy the HTML files, JSP files, and Jaa serlet files to your WebSphere Application Serer enironment to enable users to access the IMS transaction from a Web browser. VisualAge for Jaa proides the IBM WebSphere Test Enironment that you can use to test and debug your serlet prior to deploying it to a production WebSphere Application Serer. 4. If you are building a stand-alone Jaa application to run your IMS transaction: a. Build a user interface for transaction input and output. Typically this is done by using VisualAge for Jaa to build the GUI and to execute the EAB command. b. Deploy the Jaa application files to the machine on which you wish to run the application. Deploying stand-alone applications inoles updating a CLASSPATH enironment ariable so that they can access the IMS Connector for Jaa runtime classes. When deploying applications to WebSphere Application Serer, the CLASSPATH enironment ariable in updated in the deployment process. The Application Assembly Tool is used to create an Enterprise Archie (EAR) file which is then deployed to WebSphere Application Serer. For more information about EAR files, see the J2EE Modules section in IMS Connector for Jaa Concepts and Terms. Figures 2 and 3 show how you run either a stand-alone Jaa application program or a Jaa serlet to access your IMS transactions. Figure 2. Running a Jaa application that uses IMS Connector for Jaa The steps illustrated in Figure 2 are as follows: 1. Typically for Jaa applications, a GUI is used to proide input for the IMS transaction (1) and display the output from the IMS transaction (4). 2. The Jaa application accesses IMS Connector for Jaa ia class libraries and, in the case of Local Option, a shared library. 3. IMS Connector for Jaa builds an OTMA message containing the transaction input message and sends it to IMS Connect, which in turn sends it to OTMA using XCF. OTMA passes the IMS transaction input message to IMS and receies the IMS transaction output message from IMS. OTMA returns an OTMA message containing the transaction output message to IMS Connect, which in turn sends it to IMS Connector for Jaa. 4. The output of the IMS transaction is displayed by the Jaa application using the GUI. Chapter 1. Understanding IMS Connector for Jaa 3

10 Figure 3. Running a serlet that uses IMS Connector for Jaa The steps illustrated in Figure 3 are as follows: 1. The HTML file containing the input HTML form is displayed on the Web browser. The user proides the input data for the IMS transaction on this HTML form and presses the Submit button (or its equialent). WebSphere Application Serer schedules the serlet. 2. The serlet executes the EAB command, which in turn inokes IMS Connector for Jaa. If the ersion of WebSphere Application Serer that is running the Jaa serlet does not include the class libraries used by the serlet, these class libraries can be deployed to WebSphere Application Serer in the form of JAR files. 3. IMS Connector for Jaa builds an OTMA message and sends it to IMS Connect, which in turn sends it to OTMA using XCF. OTMA sends the IMS transaction input message to IMS and receies the IMS transaction output message from IMS. The IMS transaction output message is sent back to IMS Connect by OTMA. IMS Connect then sends it to the serlet using IMS Connector for Jaa. 4. The output of the IMS transaction is displayed on the Web browser by the Jaa serlet using a JSP file. The method used by IMS Connector for Jaa to send and receie OTMA messages depends on the runtime enironment of IMS Connector for Jaa and IMS Connect. If both your Web serer and IMS Connect are running in the same MVS image, you can choose to use either TCP/IP or Local Option for communication between IMS Connector for Jaa in the serlet and IMS Connect. Otherwise, only TCP/IP can be used for communications between IMS Connector for Jaa and IMS Connect. Jaa 2 Platform Enterprise Edition (J2EE) Support in IMS Connector for Jaa IMS Connector for Jaa includes both a Common Connector Framework (CCF) implementation and a Jaa 2 Platform (J2EE) Connector (J2C) Architecture implementation. This release of IMS Connector for Jaa introduces J2C support for the z/os and OS/390 platform. See Prerequisites for using IMS Connector for Jaa for more information on getting this support. The J2EE Connector architecture defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EISs) such as IMS. The J2C architecture uses an J2EE connector (also known as a resource adapter), such as IMS Connector for Jaa. By conforming to the J2EE Connector architecture, which is defined and standardized as part of the Jaa 2 Platform, Enterprise Edition (J2EE), the resource adapter no longer needs to be customized 4 IMS Connector for Jaa User s Guide and Reference

11 for each J2EE application serer to connect to the EIS. In addition, the J2EE Connector Architecture defines a set of standard programming interfaces that determine how a J2EE application interacts with a J2EE Resource Adapter to connect to the EIS. As a result, by using the J2EE Connector Architecture, the J2EE applications do not require the addition of custom code to connect to different EISs. For more information on the J2EE architecture and its concepts, see the J2EE Connector Architecture Specification at for details. IMS Connector for Jaa s implementation of the J2EE Connector Architecture will be proided in phases. The list below is an oeriew of the support proided in this release of IMS Connector for Jaa for J2C. For a list of classes proided, see IMS Connector for Jaa concepts and terms. Common Client Interface IMS Connector for Jaa proides an implementation of the J2C Common Client Interface (CCI). Jaa clients use the CCI in the following ways: Using the IMS Connector for Jaa in conjunction with the Enterprise Application Integration (EAI) frameworks that are based on the CCI, such as the Enterprise Access Builder for Transactions (EAB). This method is illustrated by the J2C samples proided in the Connector IMS Samples project and described in Building a J2C phonebook sample application and Building a conersational phonebook sample application. Programming directly against the CCI. This method is not described in the IMS Connector for Jaa documentation. For more information on the J2EE programming model, including use of the CCI, see VisualAge for Jaa s Help by clicking Help > Concepts > Access to transaction systems > Connectors > J2EE Application Programming Model. Connection Management IMS Connector for Jaa, in collaboration with WebSphere Application Serer, proides connection pooling that is transparent to the serlet or Enterprise JaaBean (EJB). Connection pooling implies connection reuse. For example, a connection consisting of a TCP/IP socket between IMS Connector for Jaa and IMS Connect is reused for multiple transaction requests. A socket is not closed and re-opened between transaction requests. Error Logging and Tracing IMS Connector for Jaa proides error logging and tracing through a traceleel control. Allowable alues for traceleel are defined in the interface IMSTraceLeelProperties. Using the trace and error logging facility describes how to use WebSphere Application Serer in conjunction with IMSTraceLeelProperties to control tracing and logging. Migration IMS Connector for Jaa proides the class IMSConnectorMigrator for use by VisualAge for Jaa tooling to migrate Enterprise Access Builder (EAB) commands from IBM s Common Connector Framework (CCF) Architecture to Sun s Jaa 2 Platform, Enterprise Edition (J2EE) Connector Architecture (J2C). Information on migration of IMS Connector for Jaa applications can be found in Migrating from CCF architecture to J2EE connector architecture. Packaging and Deployment The runtime piece of IMS Connector for Jaa is packaged as the Resource Adapter Archie (RAR) file imsico.rar for deployment into the J2C compliant Chapter 1. Understanding IMS Connector for Jaa 5

12 WebSphere Application Serer. For instructions on deploying this RAR file, see Preparing your WebSphere Application Serer Enironment for Windows or Preparing your WebSphere Application Serer Enironment for z/os and OS/390. Security For WebSphere Application Serer for workstation platforms, IMS Connector for Jaa currently supports component-managed sign-on only. For WebSphere Application Serer for z/os and OS/390, IMS Connector for Jaa supports both container and component-managed sign-on. For more information about the J2C security support for IMS Connector for Jaa, see IMS Security Information for J2C in IMS Connector for Jaa concepts and terms. Supported Platforms In this release, J2C support is proided for the following platforms: AIX z/os and OS/390 Solaris Windows Transaction Management In the current release, IMS Connector for Jaa proides global transaction support known as 2-phase commit using MVS Resource Recoery Serice (RRS) with WebSphere Application Serer for OS/390 and z/os. This release of IMS Connector for Jaa does not proide transaction support with WebSphere Application Serer on workstation platforms. For more information about J2C transaction support for IMS Connector for Jaa, see Transaction Management for J2C in the IMS Connector for Jaa concepts and terms. Generally, the process for deeloping J2C applications and serlets is as follows: 1. Ensure that the IMS Connector for Jaa RAR file (imsico.rar) has been deployed on the WebSphere Application Serer. For more information on how to deploy IMS Connector for Jaa to your target WebSphere Application Serer, see Preparing your WebSphere Application Serer enironment for Windows or Preparing your WebSphere Application Serer Enironment for z/os and OS/390 for more information. 2. Ensure that connection factories hae been created and configured for the WebSphere Application Serer. For more information on how to create and configure connection factories, see Preparing your WebSphere Application Serer enironment for Windows or Preparing your WebSphere Application Serer Enironment for z/os and OS/390 for more information. 3. Import COBOL source to VisualAge for Jaa. See Building a Jaa application to run an IMS transaction for an example of how to complete this step and the steps below. 4. Create a serlet or EJB using VisualAge for Jaa s Enterprise tooling. 5. Create an Enterprise Application using the Application Assembly Tool (AAT). 6. Deploy the Enterprise Application to WebSphere Application Serer. 7. Run the Enterprise Application in WebSphere Application Serer. Sample Applications IMS Connector for Jaa proides a number of CCF and J2C sample applications and information about them. The following is a list of the proided samples: CCF samples: 6 IMS Connector for Jaa User s Guide and Reference

13 Building a Jaa application to run an IMS transaction Building a Jaa application to run a naigator Building a Jaa application for an IMS transaction with multi-segment output messages Building a Jaa application for an IMS transaction with multi-segment input messages Building an application to run an IMS transaction with synchronization leel confirm Building the graphical user interface Building a Jaa serlet to run an IMS transaction Building a Web application that uses one serlet to run an IMS conersation Building a Web application that uses two serlets to run an IMS conersation J2C samples: Building a J2C phonebook sample application Building a J2C conersational phonebook sample application Building container-managed and component-managed transactional EJBs to run 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 archie (EAR) and Web archie (WAR) files. To do this, use the Application Assembly Tool (AAT), proided with WebSphere Application Serer. Two AATs are aailable, depending on the platform on which you are deploying the samples: AAT for distributed platforms (such as Windows, AIX, and Solaris) 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 proide the functionality to create WAR files. This AAT is required when creating EAR files that will be deployed on the z/os and OS/390 platform. You can also import any EAR files that were built for the distributed platforms into this AAT and rebuild it for a z/os and OS/390 system. If you don t hae an AAT for distributed platforms, you can build the WAR files needed to create EAR files using the JAR command proided with a Jaa Deelopment Kit (JDK). See below for more information. AAT for distributed platforms The AAT for distributed platforms is shipped with WebSphere Application Serer for that specific platform. For more information on assembling an application on a distributed platform, see the IBM WebSphere Application Serer Information Center at AAT for z/os and OS/390 The AAT for z/os or OS/390 platforms is shipped with WebSphere Application Serer for that specific platform. The tool and the documentation for it are also aailable for download on the Web at 3.ibm.com/software/webserers/appser/zos_os390/index.html. The samples for z/os and OS/390 described in this documentation require an additional classpath configuration to aoid warnings about missing classes. Add the AAT_USER_PATH ariable to the list of system ariables for the platform on Chapter 1. Understanding IMS Connector for Jaa 7

14 which the AAT will be run. You should set this ariable to point to the folder containing the JAR files that are required by the IMS Connector for Jaa (for example, C:\IBMCON~1\classes\). For more information, see the section Note on updating the AAT classpath in the AAT readme.txt file. Jaa Deelopment Kit Ensure that a Jaa Deelopment Kit (JDK) is installed on your system. To download and set up JDKs, see the products and documentation aailable at Note: You can find additional files associated with the samples in the C:\<IBM_Connectors_install_dir>\imsconn\samples directory, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory (for example, C:\IBM Connectors). Three subdirectories exist under the samples directory: J2C, serlets and misc. The J2C directory contains folders for J2C samples, the serlet directory contains folders for each CCF sample and the misc directory contains miscellaneous 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 proided for you. This EAR file can be installed and run in WebSphere Application Serer for distributed platforms (such as Windows, 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 Jaa The following is a list of minimum software requirements for IMS Connector for Jaa: VisualAge for Jaa Enterprise Edition Version 4.0 WebSphere Application Serer (for ersion information, see below) IMS Connect Version 1 Release 2 IMS Version 7 Release 1 To run a Jaa application that uses the J2C implementation of IMS Connector for Jaa, IMS and IMS Connect must be installed and running on your host machine. VisualAge for Jaa VisualAge for Jaa Enterprise Edition 4.0 is the required deelopment enironment for the IMS Connector for Jaa. The installation of VisualAge for Jaa 4.0 proides you with the CCF (Common Connector Framework) implementation of IMS Connector for Jaa. To use the J2EE Connector Architecture (J2C) implementation of IMS Connector for Jaa, you need to add the following updates to your VisualAge for Jaa 4.0 enironment: VisualAge for Jaa Beta J2EE Connectors support is required to use the J2C support. Follow the instructions in IBM Enterprise Access Builder BETA NOTES 4.0 on the VisualAge for Jaa 4.0 Additional Features installation CD. This information is in the readme.eab file in the \extras\betaj2eeconnectors folder on the Additional Features installation CD. 8 IMS Connector for Jaa User s Guide and Reference

15 The J2C implementation of IMS Connector for Jaa is proided as an update to IBM VisualAge for Jaa Enterprise Edition Version 4.0. This update is aailable on the VisualAge Deeloper Domain at Once this update is applied, both the Common Connector Framework (CCF) and J2C implementations are aailable when you add the IMS Connector feature to your VisualAge for Jaa workbench. This feature allows you to deelop applications using VisualAge for Jaa s Enterprise Access Builder and the J2C implementation of IMS Connector for Jaa. WebSphere Application Serer IMS Connector for Jaa using the Common Connector Framework (CCF) supports the following WebSphere Application Serer platforms: AIX Linux for zseries and S/390 z/os and OS/390 Solaris Windows The J2C implementation of IMS Connector for Jaa supports deployment to WebSphere Application Serer on the following platforms: WebSphere Application Serer Adanced Edition 4.0 for Windows WebSphere Application Serer Adanced Edition 4.0 for AIX WebSphere Application Serer Adanced Edition 4.0 for Solaris WebSphere Application Serer V4.0.1 for z/os and OS/390 Important: APAR PQ55873 is required for running the J2C implementation of IMS Connector for Jaa on z/os and OS/390. IMS Connect IBM IMS Connect Version 1 Release 2 is required to use the J2C implementation of IMS Connector for Jaa. The runtime component of IMS Connector for Jaa is proided as an update to the IMS Connector for Jaa component of the IMS Connect Version 1 Release 2 product. If you plan to use the J2C implementation of IMS Connector for Jaa running WebSphere Application Serer on the z/os and OS/390 platform, the following APARs for IBM IMS Connect, Version 1 Release 2 (Program Number 5655-E51) are required: APAR PQ57192 This APAR updates the IMS Connector for Jaa component with J2C and 2-phase commit support for WebSphere Application Serer for z/os and OS/390. It installs the IMS Connector for Jaa runtime component (the RAR file for WebSphere Application Serer for z/os and OS/390) to a target directory on your system. APAR PQ57191 This APAR updates the IMS Connect component with 2-phase commit support to be used by IMS Connector for Jaa. Chapter 1. Understanding IMS Connector for Jaa 9

16 IMS IBM IMS Version 7 Release 1 or later is required to use IMS Connector for Jaa. APAR PQ57868 This APAR must be applied to your IMS V7.1 system if you plan to use J2C and global transaction (2-phase commit) support on WebSphere Application Serer on z/os and OS/390. Platform Configurations for IMS Connector for Jaa and IMS Connect IMS Connector for Jaa can be deployed and configured to run on WebSphere Application Serer on arious platforms. The TCP/IP and Local Option communication protocols are supported for both CCF and J2C applications to connect to IMS Connect. Additionally, using Local Option for 2-phase commit transactions is supported in a z/os and OS/390 enironment. For more information, see IMS Connector for Jaa Concepts and Terms. IMS Connector for Jaa can be configured to run on WebSphere Application Serer on arious platforms and uses TCP/IP or Local Option communication protocols to connect to IMS Connect. The Local Option communication protocol is now supported for both CCF and J2C applications. In addition to TCP/IP, you can now use Local Option to establish communication between IMS Connector for Jaa and IMS Connect V1.2 for both CCF and J2C applications, proided that both IMS Connector for Jaa and IMS Connect exist in the same MVS image. The following table summarizes the aailable communication protocols and the leel of transaction support supplied by the runtime component of IMS Connector for Jaa on arious platforms. In this table, the heading Platform of WebSphere Application Serer with IMS Connector for Jaa refers to the fact that the WebSphere Application Serer can be configured to access all of the IMS Connector for Jaa class libraries. See Preparing your WebSphere Application Serer enironment for Windows) or Preparing your WebSphere Application Serer Enironment for z/os and OS/390 for more information. Platform of WebSphere Application Serer with IMS Connector for Jaa Supported Communication Protocols Transactional (2-phase commit) 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) Yes with Local Option (J2C only)** Local Option* (CCF and J2C) 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 Jaa and IMS Connect, both IMS Connector for Jaa and IMS Connect must exist in the same MVS image. ** To use Transactional (2-phase commit) support in this release, IMS Connector for Jaa, IMS Connect, WebSphere Application Serer, and IMS must exist in the same MVS image. Future releases of IMS Connector for Jaa will remoe this restriction. 10 IMS Connector for Jaa User s Guide and Reference

17 Important: Throughout this documentation, platform specific information in the samples and examples pertains to the Windows platform. Information for all other supported platforms is aailable on the IMS Connector for Jaa Web pages, located in the IMS Web site at You can also find some additional samples and examples for non-windows platforms on the Web. CCF examples and samples for non-windows platforms can be found on this Web site. IMS Connector for Jaa concepts and terms This section proides an oeriew of some of the concepts and terminology needed to understand IMS Connector for Jaa. It includes: Connecting with Local Option (page 11) Connection Management in the CCF implementation (page 12) Connection Management in the J2C implementation (page 14) EAB commands that use IMS Connector for Jaa (page 15) Enterprise JaaBeans (EJB) (page 15) IMS Conersations (page 16) IMS Messages (page 17) IMS Security Information (page 19) For CCF (page 19) (For J2C) Jaa Classes that are Proided with IMS Connector for Jaa for CCF (page 22) Jaa Classes that are Proided with IMS Connector for Jaa for J2C (page 27) J2EE Modules (page 28) MFS Formatting (page 29) Synchronization Leel (page 29) 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 Jaa J2C transaction support The information in this section pertains to IMS Connector for Jaa using both the Common Connector Framework (CCF) and the Jaa 2 Platform Enterprise Edition (J2EE) Connector (J2C) Architecture, unless otherwise indicated. Connecting with Local Option IMS Connector for Jaa allows you to use either TCP/IP or the Local Option support for connections between IMS Connector for Jaa and IMS Connect. Local Option proides non-socket access to IMS transactions and data from z/os and OS/390 WebSphere Application Serers (where the serlet or Enterprise JaaBean using IMS Connector for Jaa is running). You can use Local Option in both CCF and J2C implementations of IMS Connector for Jaa. Using Local Option in the CCF Implementation Chapter 1. Understanding IMS Connector for Jaa 11

18 To use Local Option in the CCF implementation of IMS Connector for Jaa, set the Host Name property of the IMSConnectionSpec bean to LOCALHOST: ims_connect_name. The IMS Connect name is case-sensitie and must match the HWS ID of the target IMS Connect. Local Option will then be used for communication between serlets executing IMS Connector for Jaa EAB commands and IMS Connect. If LOCALHOST: ims_connect_name is not specified (that is, the first ten characters of the host name are anything other than LOCALHOST:,) then IMS Connector for Jaa will assume that it is a TCP/IP host name and will attempt to use TCP/IP communications. The characters in LOCALHOST are not case-sensitie; the ims_connect_name is case-sensitie. Deelopment of EAB commands for use by serlets that use Local Option is done on VisualAge for Jaa for Windows. Setup of IMS Connector for Jaa Local Option on an OS/390 machine requires deployment of an additional class library, the Local Option shared library libimsconn.so, which is shipped with the IMS Connector for Jaa runtime component and packaged inside the imsico.rar file. Using Local Option in the J2C Implementation To use Local Option with J2C, define the IMS Connect name property of the IMSManagedConnectionFactory with a 1 to 8 alphanumeric character name of the target IMS Connect. The IMS Connect name is case-sensitie and must match the HWS ID of the target IMS Connect. Local Option is then used for communication between IMS Connector for Jaa and IMS Connect. If the IMS Connect name property is not specified, IMS Connector for Jaa uses the alue specified in the Hostname and Port number property and defaults to using TCP/IP communications instead. Setting up IMS Connector for Jaa Local Option for J2C on a z/os and OS/390 machine requires deployment of an additional class library, the Local Option shared library libimsico.so, which is shipped with the IMS Connector for Jaa runtime component. Connection Management in the CCF implementation Connection management support is a set of functions that allow the connector framework for both CCF and J2C to automatically proide and manage connections to your backend enterprise information systems. Connection pooling and reuse are important aspects of this connection management support. Connection pooling, through the reuse of connections, is key to enhancing the performance of Jaa applications or serlets that access IMS transactions. Reuse of connections minimizes the oerhead of connection initialization and significantly enhances performance. Connection management is a feature proided by the IBM Common Connector Framework (CCF). CCF is a set of Jaa APIs that proides infrastructure serices like connection management, transaction serices, security, and tracing facilities to Jaa applications and serlets. CCF currently proides two types of connection manager: com.ibm.connector.internal.defaultconnectionmanager DefaultConnectionManager is the default connection manager used by the RuntimeContext classes (specifically, RuntimeContext and JaaRuntimeContext) shipped with VisualAge for Jaa. It does not support 12 IMS Connector for Jaa User s Guide and Reference

19 connection pooling. A new connection is created for each transaction request and the connection is disconnected when the transaction is complete. com.ibm.connector.connectionmanager.connectionmanager ConnectionManager is a real connection manager that supports connection pooling. It maintains one or more pools of reusable connections for IMS Connect. For TCP/IP connections, there is a separate pool of reusable connections for each Hostname/Port number combination used by IMS Connector for Jaa. For Local Option connections, there is a separate pool of reusable connections for each IMS Connect used by IMS Connector for Jaa. When the ConnectionManager class is used with IMS Connector for Jaa, a connection with IMS Connect is obtained for each transaction request. When the request has been completed (or the last request, in the case of a conersational application, has been completed), the connection is then returned back to the pool to be reused by subsequent requests. There should be one instance of the ConnectionManager class used within a component serer (for example, WebSphere Application Serer). If your component serer supports the CCF infrastructure, a single instance connection manager would be established and be accessed by the serlets using IMS Connector for Jaa. If your component serer does not support the CCF infrastructure, you can use a separate serlet to implement a single global instance of the ConnectionManager object. This single instance can then be accessed by any other serlet whose connection manager in RuntimeContext has been set to this ConnectionManager object. As a result, to ensure connection pooling is established properly in your component serer for running your serlet requests with CCF connectors, there must be one instance of connection manager AND the type of connection manager being used must support connection pooling (for example, the type com.ibm.connector.connectionmanager.connectionmanager). IMS Connector for Jaa has proided a sample implementation of a serlet that stores a single global connection manager of type com.ibm.connector.connectionmanager.connectionmanager in the SerletContext. The source code of the serlet is in the RegisterConnectionManager serlet in the com.ibm.connector.ims.sample.cm package included in the IMS Connector Sample feature. This sample could be used when your component serer does not support the CCF infrastructure or it does not use a type of connection manager that supports connection pooling. This sample serlet must be loaded once when the component serer starts to establish the connection manager. To load the sample serlet, inoke the following URL from your web browser: RegisterConnectionManager where sererhostname is the hostname of your component serer. To access the global instance of the ConnectionManager from the SerletContext in your serlet code, add the following sample code in the method that uses executes the EAB command (for example, for a serlet generated by WebSphere Studio, it will be placed in the performtask() method). This code should be placed before the execute() method of the EAB command is called: Chapter 1. Understanding IMS Connector for Jaa 13

20 // Access the global instance of ConnectionManager from the SerletContext. SerletConfig sc = getserletconfig(); SerletContext sctx = sc.getserletcontext(); com.ibm.connector.connectionmanager.connectionmanager connmgr = (com.ibm.connector.connectionmanager.connectionmanager) sctx.getattribute( CCFConnectionManager); // Setup the Connection Manager with the RuntimeContext RuntimeContext.getCurrent().setConnectionManager(connMgr); A sample usage of the aboe code can be found in the serlet examples included in the Connector IMS Samples project of Visual Age for Jaa. Note: IMS Connector for Jaa always uses a persistent connection (sometimes referred to as a persistent socket) with IMS Connect. IMS Connect enforces this connection type for both TCP/IP socket and Local Option PC connections. When IMS Connector for Jaa is running with CCF connection pooling, the connection will be returned to the CCF connection pool when the transaction is complete. The connection will remain actie for reuse by another client and the connection will not be disconnected. When IMS Connector for Jaa is not running with CCF connection pooling, the connection type between IMS Connector for Jaa and IMS Connect is still persistent. Howeer, at the end of the client transaction, the connection will be disconnected. Thus, when CCF connection pooling is not being used, the connection is still a persistent one but has the appearance of a transaction connection (also known as a transaction socket). In this case, IMS Connector for Jaa (instead of IMS Connect) disconnects the connection upon completion of each IMS transaction request. Connection Management in the J2C implementation Application components using the J2C implementation of IMS Connector for Jaa are targeted for the WebSphere Application Serer implementation of the J2C connection management contract, which supports connection pooling and reuse. WebSphere Application Serer s Connection Manager maintains a connection pool for each hostname/portnumber combination for TCP/IP connections. For Local Option connections, a separate pool of reusable connections exist for each IMS Connect used by IMS Connector for Jaa. For WebSphere Application Serer for workstation platforms (like Windows, AIX, Solaris), you can configure the pooling properties for each connection pool. For instructions on how to edit the connection pooling properties, see the WebSphere Application Serer Adanced Edition Information Center for workstation platforms. For a description of connection pooling properties, see the VisualAge for Jaa documentation by clicking Help > Help Home Page > Reference > IBM APIs > Enterprise Access Builder for Transactions > Package com.ibm.connector2.spi.connectionpoolproperties. When you are testing your application components in VisualAge for Jaa s WebSphere Test Enironment, you must run additional code in order to hae connection pooling. For details, read the information proided for the J2EE JSP and serlet sample in the VisualAge for Jaa documentation by clicking Help > Help Home Page > Samples > Enterprise Access Builder for Transactions > WebSphere Set > J2EE JSP and serlet sample. In addition, samples of serlets that can be used when running in VisualAge for Jaa s WebSphere Test Enironment can be found in package com.ibm.ij.eab.sample.ws.j2ee.serlet of the IBM Enterprise Access Builder WebSphere Samples project. 14 IMS Connector for Jaa User s Guide and Reference

21 Note: IMS Connector for Jaa always uses a persistent connection (sometimes referred to as a persistent socket) with IMS Connect. IMS Connect enforces this connection type for both TCP/IP socket and Local Option PC connections. When IMS Connector for Jaa is running in a managed enironment that supports connection pooling, such as WebSphere Application Serer, the connection will be returned to the connection pool when the transaction is complete. The connection will remain actie for reuse by another client and the connection will not be disconnected. When IMS Connector for Jaa is running in an enironment that does not support connection pooling, the connection type between IMS Connector for Jaa and IMS Connect is still persistent. Howeer, at the end of the client transaction, the connection will be disconnected. Thus, when connection pooling is not being used, the connection is still a persistent one but has the appearance of a transaction connection (also known as a transaction socket). EAB commands that use IMS Connector for Jaa EAB commands that use IMS Connector for Jaa are deeloped with the VisualAge for Jaa Command Editor. An EAB command built for IMS Connector for Jaa is a composite Jaa bean that consists of the following: A Jaa bean (page 22) representing the input to the IMS transaction One or more Jaa beans representing the output from the IMS transaction An IMSConnectionSpec bean (for CCF), representing the connection between the EAB command and the IMS Connect host component A Connection Factory Configuration object (for J2C) for specification of connection information. An IMSInteractionSpec bean containing information about the type of interaction that the EAB command has with IMS using IMS Connect. The CCF IMSInteractionSpec also contains the name of the target IMS datastore. A DFSMsg bean This bean processes potential error or status messages (DFS messages) from IMS. These messages begin with the three characters DFS. For the differences between building CCF and J2C EAB commands, see the VisualAge for Jaa documentation by clicking Help > Help Home Page > Concepts > Access to transaction systems > Enterprise Access Builder for Transactions > EAB constructs > How Commands in J2EE and CCF differ. Enterprise JaaBeans (EJB) The IMS Connector for Jaa implementation of Sun s Jaa 2 Platform, Enterprise Edition Connector (J2C) Architecture introduces the use of Enterprise JaaBeans (EJB) to build your applications. An EJB defines how serer-side components are written and proides a standard architectural contract between the components and the application serers and containers that manage them. The two types of EJBs are entity beans and session beans. Entity bean An 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 to model data within the database and contain functions that are used to directly initialize, modify, or remoe that data. Chapter 1. Understanding IMS Connector for Jaa 15

22 Session bean The bean class of session beans implement business logic. The lifetime of a session bean is shorter than that of an entity bean. Generally, session beans hae the lifetime equialent of a client session. The client session lasts as long as the client is connected to the application. Session beans are unique to each client. Session bean information and state are not shared between clients. The two types of session beans are stateful session beans and stateless session beans. Stateful session bean A stateful session bean holds a conersation that can span many method calls. The same bean can be used to sere all of the method calls that come from a single client. During this conersation, the bean holds conersational state for that client. Conersational state is information sent to or acquired by the bean that can be referenced throughout the life of the conersation. The conersational state of a stateful session bean is stored in the bean instance fields. Stateless session bean A stateless session bean holds a conersation that spans a single method call. After each method call, a stateless session bean releases any information from the preious method call and becomes aailable to sere a new request. VisualAge for Jaa Version 4.0 offers the EJB Deelopment Enironment feature that helps you create EJBs. Related Information: For more information on EJB and J2EE, see the VisualAge Deeloper Domain at For more information on session beans and these two types, see the IBM Redbook EJB Deelopment with VisualAge for Jaa for WebSphere Application Serer, SG , aailable at IMS Conersations IMS Connector for Jaa Conersational Support allows customers to build Jaa applications and Web applications to access IMS conersational transactions. A conersational IMS transaction is a transaction that is defined to IMS as being conersational, meaning that it can be inoked repeatedly to process the indiidual steps of a conersation. An IMS conersation is made up of a connected series of client-to-program-to-client interactions. Although multiple IMS application programs may be inoled in the processing of a conersation or een the processing of a single interaction, only a single client can participate in a conersation. In order to participate in an ongoing IMS conersation, a transaction must be conersational. In other words, it must be defined as conersational to IMS and it must conform to the requirements of IMS conersational processing. If control is passed to a nonconersational program during a conersation, IMS will terminate the conersation. The IMS conersational program receies messages from the client, processes the requests and replies to the client. It also saes the intermediate data from the transaction in the scratch pad area (SPA). When the user enters more data from the client, the program has access to the data it saed from the last message in the SPA, and thus can continue processing the request without haing 16 IMS Connector for Jaa User s Guide and Reference

23 the user enter that data again. When the client sends a message to initiate the next iteration of the conersation, the program uses the data in the new message along with the data it saed in the SPA at the end of the last iteration of the conersation as its input. In more complex conersations, different transactions can be inoked using an immediate or deferred program switch. Related Reading: For more information on IMS conersations in general, as well as information on more in-depth topics such as program switching, refer to IMS Conersations in Application Programming: Transaction Manager and Gathering Requirements for Conersational Processing in Application Programming: Design Guide of the IMS books. In a Web application that takes part in an IMS conersation, the user submits a series of requests each of which inokes a Jaa serlet which in turn processes an iteration of the conersation. In fact, different serlets can be used to process the iterations of a gien conersation depending on how you program the input HTML and input/output JSP pages of the application. Howeer, all of the serlets must use the same connection. This is handled automatically by the connection manager when you use a connection manager that supports connection pooling. For each iteration, the Jaa serlet receies an input request from the browser and utilizes IMS Connector for Jaa to send a conersational transaction request to IMS using IMS Connect. IMS Connect then forwards the transaction request to IMS through OTMA. IMS schedules the conersational transaction that either continues the existing conersation or starts a new IMS conersation (if this is the first iteration of a conersation). The IMS application processes the request and sends the output back to the Jaa serlet using IMS Connect and IMS Connector for Jaa. The Jaa serlet then loads the appropriate JaaSerer Page to display the output of that iteration to the user in the browser. IMS Connector for Jaa Conersational Support proides two programming models from which to build a conersational Web application. The programming models are the Conersational HttpSession Model and the Conersational Naigator Model. The following commands, howeer, are not supported for IMS conersations that are initiated using IMS Connector for Jaa Conersational Support: /EXIT* /HOLD /RELEASE *Note: For a serlet that simulates the /EXIT command, see the package com.ibm.connector.ims.sample.con.forcend.serlet in the Connector IMS Sample project. IMS Messages An EAB command for a typical IMS transaction includes Jaa beans that represent the IMS transaction input and output messages. These beans are constructed by VisualAge for Jaa s Enterprise Access Builder by first parsing the COBOL source of the IMS transaction s application program. The Enterprise Access Builder tool then uses this information to create the transaction input and output beans that match the input and output messages receied and sent by that IMS application program. The degree to which VisualAge for Jaa can create Jaa beans that accurately represent an IMS transaction s input and output messages is limited by the way in which messages are defined in the COBOL application program. To oercome these Chapter 1. Understanding IMS Connector for Jaa 17

24 limitations, if any, you can create files that contain 01 leel COBOL definitions for the input and output messages used by your COBOL IMS application program. You can then use these files in the Enterprise Access Builder instead of the original COBOL IMS application program. This technique can also be used if your IMS application program is not written in COBOL Related Reading: For more information on the COBOL parser and its limitations, see the VisualAge for Jaa documentation. Click Help > Help Home Page > Concepts > Access to transaction systems > Enterprise Access Builder for Transactions > Limitations. The messages sent to IMS or receied from IMS by a Jaa application or serlet using IMS Connector for Jaa can be any of the following: IMS transaction input messages IMS transaction output messages IMS status or error messages (also called DFS messages) IMS commands IMS command output messages IMS Connector for Jaa is primarily designed to handle the first three types of messages. IMS messages, both input and output, can consist of multiple segments. Building a Jaa application for an IMS transaction with multi-segment output messages and Building a Jaa application for an IMS transaction with multi-segment input messages proide examples of how to create Jaa applications that run IMS transactions with multiple segment messages. For a transaction input or output message, no restrictions exist on the number of segments. The IMS Connector for Jaa-supplied bean, DFSMsg, supports both single-segment IMS output messages and multiple-segment IMS output messages of 22 segments or less. These DFS output messages are sent by IMS to reflect IMS errors or status changes in response to a transaction request receied by IMS. They are also returned as the output response from an IMS command. While it is possible to submit a command to IMS from a Jaa application or serlet using IMS Connector for Jaa that generates more than 22 segments of command output, that Jaa application or serlet is restricted to receiing a maximum of the first 22 segments of that command output. Message segments that are sent to and receied from IMS transactions always begin with a 2-byte segment length field (called LL), followed by a 2-byte field that contains IMS information (called ZZ). The 2-byte segment length field represents the length of the entire message segment, including the LL and ZZ fields. The data of the message segment follows the LL and ZZ fields. In the case of the first segment of the transaction s input message, up to the first the first n+1 bytes of the data portion of the segment contain the n-byte transaction code, followed by a blank. COBOL definitions that represent transaction input and output message segments must contain fields for the segment length, the IMS information, and the data portions of a segment. A Jaa application or serlet must set the indiidual fields of a transaction input message segment before sending that segment to IMS. The fields are set by doing the following: Set the indiidual fields of the data portion of message segments using set methods. Typically alues for these methods are proided by the end user using a GUI or input HTML page. In some cases alues for set methods, such as the transaction code, can be hard-coded in the Jaa program. 18 IMS Connector for Jaa User s Guide and Reference

25 Set the segment length field (LL) to be the sum of the defined lengths of all the data fields, plus 4. If LL is not set correctly, IMS Connector for Jaa might throw an exception or unpredictable results might occur, depending upon the IMS application program. Consider adding a method to your EAB command that uses the getsize() method of com.ibm.record.customrecord to return the size of your transaction input message. Setting the IMS information field (ZZ) is optional. Note: If your IMS application program is written in PLI, you must represent the transaction input and output messages in COBOL in order to use the Enterprise Access Builder to generate Jaa beans for the EAB command. The COBOL data structures are created by mapping the message data structures in the PLI IMS application program. The only exception is that the segment length field, LL, must be mapped to a COBOL definition that represents 2 bytes. When the PLITDLI interface is used, IMS adjusts the LL field of the input message presented to the IMS application program from 2 bytes to 4 bytes, and conersely, from 4 bytes to 2 bytes on output. As is normally the case for the PLITDLI interface, the segment length field (LLLL) is defined in the IMS application program as 4 bytes and the alue in the LLLL field is the input message length minus 2. IMS Security Information The IMS logon information (user ID, password, and group name) proided to a Jaa application or serlet is used by IMS Connector for Jaa for both CCF and J2C implementations as follows: The user ID, password, and group name are placed in the OTMA message sent by IMS Connector for Jaa to the host component, IMS Connect. IMS Connect then calls the host s Security Authorization Facility (SAF) under control of the IMS Connect RACF state SETRACF command: If RACF=Y (the SETRACF ON command has been issued), the SAF is called. If user authentication succeeds, the UTOKEN built by the SAF is passed on to IMS for authorization. If user authentication fails, IMS Connect returns an error to IMS Connector for Jaa. If RACF=N (the SETRACF OFF command has been issued), the SAF is not called by IMS Connect. The user ID and group name are passed on to IMS for authorization. Four leels of authorization are aailable in IMS. These leels are controlled by the IMS 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 are passed to the SAF to ensure the user (in the group) is authorized to execute the transaction (or command). 3. If /SEC OTMA FULL is issued, in addition to performing CHECK leel authorization, a user security profile is built in the MPP region for use by non-ims serices. 4. If /SEC OTMA PROFILE is issued, the result is the same as if /SEC OTMA FULL is issued, because IMS Connector for Jaa sets the Security Data section of the OTMA message prefix for each transaction to the FULL option. For CCF: Chapter 1. Understanding IMS Connector for Jaa 19

26 Be sure to read the section under IMS Security Information (page 19) (aboe), which applies to both CCF and J2C implementations. Relationship of IMS logon information to EAB commands IMS logon information is set in the run-time context of a Jaa application or serlet. 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 serlet, and lasts for the duration of the application or serlet. Howeer, in some situations, it might be desirable to change the IMS logon information within an application or serlet. For example, an application or serlet might run multiple transactions that belong to different groups. In this case, the setgroup() method must be inoked before each execute of an EAB command in order to set the appropriate group name for the transaction that the command runs. This applies to both of the following cases: A different EAB command is used for each transaction 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 hae the same input and output message structure but different transaction codes. The IMS logon information can be changed between inocations of the execute() method for the same EAB command. This is useful if, for example, the same EAB command is used for different transactions, and the transactions hae different group names. For J2C: Be sure to read the section under IMS Security Information (page 19) (aboe), which applies to both CCF and J2C implementations. The following table summarizes the J2C security support for the current release of IMS Connector for Jaa. WebSphere Application Serer with IMS Connector for Jaa platform Supported Resource Authentication Type Application (Component-managed) Container (Containermanaged) Windows, AIX, Solaris Yes No z/os, OS/390 Yes Yes (with Local Option only) When a J2C application component requests a connection to an Enterprise Information System (EIS) resource (such as IMS Connect or IMS), the EIS might require a sign-on to that resource. Two options are aailable to the J2C application for managing EIS sign-on: component-managed and container-managed sign-on. Definitions: 20 IMS Connector for Jaa User s Guide and Reference

27 Component-managed Sign-on The J2C application sets the res-auth deployment descriptor element to be Application. The component code performs a programmatic sign-on to the EIS (IMS Connect/IMS) by passing the explicit security information (username, password, and groupname) to the getconnection method of the IMSConnectionFactory instance. To pass security information to a connection for IMS Connect/IMS, you must use the IMSConnectionSpec class. The component sets alues for username, password, and groupname in an instance of the IMSConnectionSpec class and proides that instance to 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 security information by editing the connectionspec property of the ConnectionFactoryConfiguration 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 the connectionspec property. Then proide security information as desired. 3. Optionally, you can promote the connectionspec property to generate a setter method for the connectionspec property on the EAB command. Then you can inoke the setter method on the EAB command to proide the security information. For more information about EAB commands, please refer to the VisualAge for Jaa documentation. The security information is then sent by IMS Connector for Jaa to IMS Connect and IMS for the appropriate security alidation. See IMS Security Information (page 19) for more information. Container-managed Sign-on The J2C application component sets the res-auth deployment descriptor element to be Container. The application serer (WebSphere Application Serer) takes the responsibility of managing sign-on to the EIS (IMS Connect/IMS). The component code inokes the getconnection method on the IMSConnectionFactory instance with no security-related parameters. The application runs with the identity associated with the current thread of execution set up by the application serer. Note: If the component code passes an IMSConnectionSpec instance with explicit security information to the getconnection method on the IMSConnectionFactory instance, that security information is ignored. Related Reading: Currently, IMS Connector for Jaa supports container-managed sign-on for WebSphere Application Serer for z/os and OS/390 only. To set up your J2EE application with the appropriate security identity to use the container-managed sign-on on WebSphere Application Serer for z/os and OS/390, see the document titled WebSphere Application Serer V4.0.1 for z/os and OS/390: WebSphere for Chapter 1. Understanding IMS Connector for Jaa 21

28 z/os-supported Connectors. This document is aailable with APAR PQ55873 for WebSphere Application Serer V4.0.1 for z/os and OS/390. To download the document, go to then click Product information. At a later time, the information in this document will be integrated into the WebSphere for z/os formal publications. To access the latest publications, go to the product library page at When the connection is successfully established, all application-leel inocations to the EIS instance using the connection occurs under the security context of the authenticated user. When you configure an IMSConnectionFactory you can specify default alues for username, password, and groupname (see Creating and Configuring a Connection Factory for use by the IVP in Preparing your WebSphere Application Serer Enironment for Windows or Preparing your WebSphere Application Serer Enironment for z/os and OS/390 ). These default alues will be used for all connections created by that connection factory and placed in the OTMA message for authentication and authorization by IMS Connect and IMS under the following circumstances: The J2C application specifies component-managed sign-on, but the application component does not pass an IMSConnectionSpec instance to the getconnection method. The J2C application specifies component-managed sign-on, but the application component passes an IMSConnectionSpec instance with no security information to the getconnection method. Note: When any alue (username, password, or groupname) in the IMSConnectionSpec instance is null, the default alue from the IMSConnectionFactory is used. The J2C application specifies container-managed sign-on, but IMS Connector for Jaa does not support container-managed sign-on with the application serer on that platform. Jaa Classes that are Proided by IMS Connector for Jaa for CCF IMS Connector for Jaa proides a number of Jaa classes to aid you in building Jaa programs and serlets. All of these classes are in the IMS Connector for Jaa package com.ibm.connector.imstoc. Some of these classes are also Jaa beans. You can combine these beans into a composite bean that accesses an IMS transaction. The beans are aailable to VisualAge for Jaa s Command Editor and Visual Composition Editor. Definitions: A Jaa bean is a reusable software component, an element of a program that may or may not be seen by the end user at run time and is made up of one or more Jaa classes. A isual Jaa bean is an element of a program that is seen by the end user at run time while a nonisual bean is an element of a program that is not necessarily seen by the end user. 1. Visual Jaa beans can be used to construct a graphical user interface for an EAB command. The interface can proide input to and display output from an IMS transaction. An example of a isual Jaa bean is a button that the user clicks to perform some action. 22 IMS Connector for Jaa User s Guide and Reference

29 2. Nonisual Jaa beans are beans which do not hae isual representations at runtime. For example, all beans that are proided by IMS Connector for Jaa such as IMSConnectionSpec and IMSInteractionSpec, are nonisual beans. 3. A composite Jaa bean is a Jaa bean that is comprised of other Jaa beans, either isual or nonisual. In the context of this document, an Enterprise Access Builder (EAB) command is a composite bean that is constructed using the Visual Age for Jaa Command Editor. For additional definitions, see the glossary in the VisualAge for Jaa online help. The following classes are supplied by IMS Connector for Jaa: IMSConnectionSpec The IMSConnectionSpec bean proides information about the connection between a Jaa program and an IMS Connect host component, as well as information about connection management. The IMSConnectionSpec Host name and Port properties are specific to IMS Connector for Jaa, while the other properties are inherited from the Common Connector Framework interface com.ibm.connector.connectionspecmanagementproperties. IMSConnectionSpec properties include the following: Host name For a TCP/IP connection, the host name is set to the TCP/IP host name of the machine running the IMS Connect that the EAB command (IMS transaction) will be using. For a connection that utilizes the Local Option of IMS Connector for Jaa, the host name is set to LOCALHOST: ims_connect_name where ims_connect_name is the IMS Connect ID (referred to in IMS Connect as HWS ID ) Once IMS Connect has been configured and started, the ims_connect_name will appear in the outstanding IMS Connect reply message on the MVS console of the host machine where it is running. For more information on the IMS Connect ID, see Creating the IMS Connect Configuration Member in the IMS Connect Guide and Reference. Port The Port is a numeric alue that may be used by the EAB command for communication with IMS Connect. For a TCP/IP connection, Port is a port used by IMS Connect on the specified host machine where IMS Connect is running. For a Local Option connection, the Port alue is not used. IMSConContext The IMSConContext bean is used to comply with the IMS Connect requirement that the same connection is used for all iterations of an IMS conersation. A connection is a communications link, a socket in the case of TCP/IP, and is analogous to the phone line that connects two telephones during a telephone conersation. IMS Connector for Jaa includes this class in its programming model for use by conersational Web applications. A Jaa application or serlet should create a single instance of the IMSConContext class at the start of a conersation and associate this single instance with the connection used for the conersation. This will ensure that the connection will be presered for the lifetime of the IMS Chapter 1. Understanding IMS Connector for Jaa 23

30 conersation and that the CCF ConnectionManager will always return the same connection for each iteration of the IMS Conersation. IMSConUnboundHttpSessionCleanup IMS Connector for Jaa includes this class in its programming model for use by conersational Web applications only. This class implements the HttpSessionBindingListener interface and is used to determine when the IMS conersation is unbound from the session. It then performs the appropriate cleanup. WebSphere Application Serer creates an HttpSession object to represent the HTTP session of the Web application (the connection between the browser and WebSphere Application Serer.) An HttpSession object fires an unbound eent when the associated HTTP session becomes unbound. When an HTTP session becomes unbound, the connection needs to be returned for reuse and the IMS conersation needs to be terminated. This cleanup work is performed by methods of the IMSConHttpSessionCleanup class. For example, an HTTP session becomes unbound when the user closes the browser while the IMS conersation is still actie. When the user prematurely exits the browser, the HTTP session associated with the browser eentually times out, as there is no more user interaction from the browser. At this point, the HttpSession object associated with the HTTP session becomes unbound, causing an unbound eent to be fired. The IMSConHttpSessionCleanup object receies this unbound eent, which in turn triggers the calling of its alueunbound() method. The alueunbound() method issues a MODE_END_CONVERSATION request to end the IMS conersation and also performs any cleanup required to allow the connection to be reused. IMSConHttpSessionCleanup implements the HttpSessionListener interface and has the following methods: oid setconcontext() Sets the IMSConContext object of the current IMS conersation in the IMSConHttpSessionCleanup object such that the appropriate resources can be cleaned up following an unbound eent. oid alueunbound() This method implements the alueunbound() method of the HttpSessionBindingListener interface to terminate the IMS conersation and cleanup conersation resources. IMSInteractionSpec The IMSInteractionSpec bean proides information about the interaction between a Jaa program and a datastore. Interaction properties include: ConTerminated This property is set to TRUE if the host IMS application program ends the IMS conersation. The Jaa application program checks the alue of this property after inocation of the execute() method for the EAB command, to determine whether or not the conersation has been terminated by the host. The following two methods can be used: 24 IMS Connector for Jaa User s Guide and Reference

31 oid setconterminated(boolean) Sets the alue of the conterminated property. This property is set to TRUE when the conersation is terminated by the host. boolean getconterminated() Gets the alue of the conterminated property. It is used by the Jaa application program to determine whether or not the conersation has been terminated by the host. Datastore name The name of the target IMS datastore that is defined in the IMS Connect configuration file. LTERM Name The LTERM name used to oerride the LTERM name in the IMS application program I/O PCB. Map name Also known as the MFS MOD name, the map name can be proided by an IMS application program when returning the output of a transaction. It can also be proided by IMS when returning a status message, such as the output from a /DIS command, or an error message. If a alue for Map name is specified on input to an IMS transaction, it will be made aailable to the IMS application program. Mode The type of interaction to be carried out between the Jaa program and the IMS datastore. The modes that are currently supported include MODE_SEND_RECEIVE, MODE_ACK, MODE_NACK, and MODE_END_CONVERSATION. Synchronization Leel Specifies the transaction synchronization leel the way in which the Jaa client (for example, an application or serlet) and IMS interact with respect to transaction output messages. Stated simply, the synchronization leel determines whether or not the transaction output messages must be acknowledged either as accepted (ACK) or rejected (NACK) by the client. For more information, see Synchronization Leel. (page 29) DFSMsg The DFSMsg bean represents IMS status or error messages that are returned to a Jaa application or serlet in response to a command or a transaction. These messages typically begin with the characters DFS. Often times, DFS messages are returned to a Jaa application or serlet. Some DFS messages indicate error situations, while others are returned as the output of IMS commands. In all cases, because OTMA is used to return the message, MFS formatting is not performed. Howeer, IMS includes an MFS MOD name (Map name) with DFS messages. IMS Connector for Jaa checks the MOD name field of messages that it receies from IMS Connect. If the MOD has one of the following names, the message is processed as a DFS message. If the name is not listed below, it is processed as transaction output. Chapter 1. Understanding IMS Connector for Jaa 25

32 DFSMO1 DFSMO2 DFSMO3 DFSMO4 DFSMO5 DFSDSPO1 IMS Connector for Jaa builds a buffer containing one or more segments of a DFS message, up to a maximum of 22 segments. Any output data beyond the 22nd segment is discarded. The buffer structure is as follows: DFSLL1 Two-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 of the segment. DFSZZ1 Two-byte flag field (ZZ) of the first segment of the output message. DFSDATA1 The data of the first segment of the output message, blank-padded or truncated to 119 bytes. DFSLL1 represents the length of the segment receied from IMS or the truncated length and, as such, is less than or equal to 123 ( ) DFSLL22 Two-byte length (LL) of the 22nd segment of the output message. The length (LL) of a message segment includes the length of the LL and ZZ fields of the segment. DFSZZ22 Two-byte flag field (ZZ) of the 22nd segment of the output message. DFSDATA22 The data of the 22nd segment of the output message, blank-padded or truncated to 119 bytes. DFSLL22 represents the length of the segment receied from IMS or the truncated length and, as such, is less than or equal to 123 ( ). The buffer structure is used to populate a DFSMsg object. A Jaa program can obtain a DFS message from a DFSMsg object in the following ways: getdfsmessage() Returns the message segments concatenated together as a single string. getdfsmessagesegments() Returns a ector of the segments of the message. In addition, the indiidual fields of the message segments (DFSLL1, DFSZZ1, DFSDATA1, etc.) can be accessed by a Jaa application or serlet. Any of the aboe methods can be used by Jaa applications. Currently, howeer, WebSphere Studio does not allow selection of a method for use in displaying data 26 IMS Connector for Jaa User s Guide and Reference

33 on a serlet s output template. In order for a serlet to display a DFS message, the indiidual fields of the DFSMsg object should be selected (DFSLL1, DFSZZ1, DFSDATA1, etc.) while in WebSphere Studio. A composite bean that uses IMS Connector for Jaa should include a DFSMsg bean as well as bean(s) representing the output of the IMS transaction. VisualAge for Jaa s Enterprise Access Builder populates the appropriate output bean, based on the data that is returned by IMS. Related Reading: For more information on displaying a DFS message with a serlet, see Building a Jaa serlet to run an IMS transaction. Jaa Classes that are Proided by IMS Connector for Jaa for J2C All classes mentioned below are in IMS Connector for Jaa package com.ibm.connector2.ims.ico. Interfaces beginning with jaax.resource are part of the J2C architecture. To iew the Jaadoc for these classes, go to VisualAge for Jaa and click Help > API Reference > Reference >IBM APIs > Connectors > IMS Connector. IMS Connector for Jaa s implementation of the J2C architecture will be proided in phases. Classes proided in this phase are summarized below. IMS Connector for Jaa uses these classes in collaboration with WebSphere Application Serer to proide connection pooling in the J2C enironment. Connection pooling is transparent to the serlet or EJB. IMS Connector for Jaa implements the J2C System Contracts by proiding the following classes. J2C interfaces are noted in parentheses: com.ibm.connector2.ims.ico.imsmanagedconnectionfactory (jaax.resource.spi.managedconnectionfactory) An IMSManagedConnectionFactory instance is a factory of both IMSManagedConnection instances and IMSConnectionFactory instances. com.ibm.connector2.ims.ico.imsmanagedconnection (jaax.resource.spi.managedconnection) An abstract class that represents the physical connection to IMS Connect. The IMSManagedConnection has 2 subclasses: com.ibm.connector2.ims.ico.imstcpipmanagedconnection com.ibm.connector2.ims.ico.imslocaloptionmanagedconnection An IMSTCPIPManagedConnection instance represents a TCP/IP connection to IMS Connect. An IMSLocalOptionManagedConnection instance represents a connection using Local Option to communicate with IMS Connect. com.ibm.connector2.ims.ico.imsmanagedconnectionmetadata (jaax.resource.spi.managedconnectionmetadata) Proides information about an IMSManagedConnection. IMS Connector for Jaa implements the J2C Common Client Interface (CCI) by proiding the following classes. J2C interfaces are noted in parentheses: Classes that represent a connection factory and an application leel connection: com.ibm.connector2.ims.ico.imsconnectionfactory (jaax.resource.cci.connectionfactory) An IMSConnectionFactory instance is a factory for IMSConnection instances. Chapter 1. Understanding IMS Connector for Jaa 27

34 com.ibm.connector2.ims.ico.imsconnection (jaax.resource.cci.connection) An IMSConnection instance is an application leel handle than is used by a component to access IMS using IMS Connect. com.ibm.connector2.ims.ico.imsconnectionspec (jaax.resource.cci.connectionspec An IMSConnectionSpec instance is used by components, when obtaining a connection, to proide specific alues for UserName, Password, and GroupName. These alues are used instead of the default alues proided by the IMSConnectionFactory instance. Classes that enable a component to drie an interaction (specified through an InteractionSpec) with IMS using IMS Connect: com.ibm.connector2.ims.ico.imsinteraction (jaax.resource.cci.interaction) An IMSInteraction instance enables a component to interact (run a transaction) with IMS using IMS Connect. com.ibm.connector2.ims.ico.imsinteractionspec (jaax.resource.cci.interactionspec) An IMSInteractionSpec instance proides properties for driing the interaction with IMS using IMS Connect. Classes that proide basic meta information about the IMS Connector for Jaa implementation and a connection to IMS using IMS Connect: com.ibm.connector2.ims.ico.imsconnectionmetadata (jaax.resource.cci.connectionmetadata) Proides information about an IMSConnection. com.ibm.connector2.ims.ico.imsresourceadaptermetadata (jaax.resource.cci.resourceadaptermetadata) Proides information about IMS Connector for Jaa. Additional classes and interfaces proided by IMS Connector for Jaa are: IMSInteractionSpecProperties IMSInteractionSpecProperties is an interface that defines named constants that are used to configure an IMSInteractionSpec instance. IMSTraceLeelProperties IMSTraceLeelProperties is an interface that defines named constants that are used for controlling the leel of tracing and logging that is performed by IMS Connector for Jaa. IMSConnectorMigrator IMSConnectorMigrator is a class that is used by VisualAge for Jaa to migrate a CCF EAB command to a J2EE EAB command. DFSMsg A DFSMsg bean is used to capture DFS messages returned by IMS. For a description of this bean, see the section Jaa Classes that are Proided for IMS Connector for Jaa for CCF (page 22) aboe. J2EE Modules A Jaa 2 Enterprise Edition (J2EE) application is comprised of J2EE modules. These modules are comprised of the following J2EE components: Enterprise beans Web components, specifically serlets or JaaSerer Pages (JSPs) 28 IMS Connector for Jaa User s Guide and Reference

35 Application clients Applets J2EE modules are archies: Jaa archie (JAR) files or Web application archie (WAR) files. A J2EE application, with all of its modules, is packaged and deliered in an Enterprise Archie (EAR) file. An EAR file is a standard JAR file with an.ear extension. You can install J2EE applications in WebSphere for z/os and OS/390 only when they are packaged in EAR files. MFS Formatting Transaction input and output messages that are proided to IMS through OTMA bypass online MFS processing. MFS is the online processing component in IMS that performs message formatting, such as field padding, truncation, justification, and insertion of literal data in messages. Currently, although VisualAge for Jaa includes an MFS parser, it does not support creating 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 is performed. When using IMS Connector for Jaa you need to consider any dependencies the IMS application program has on MFS online formatting and decide whether or not you want to perform this function in your Jaa serlet or application. Synchronization Leel Important: The current release of J2C implementation in IMS Connector for Jaa does not proide applications with the ability to specify synchronization leel. IMS Connector for Jaa can use the IMS OTMA synchronization leel internally to interact with IMS OTMA and IMS Connect. For the CCF implementation, the synchronization leel can be specified for an EAB command that runs an IMS transaction. Synchronization leel determines the way in which IMS and the client that contains the EAB command interact. An EAB command that runs an IMS transaction can execute with a synchronization of leel of None or Confirm. Currently, all IMS Connector for Jaa interactions use the OTMA protocol Commit Mode 1, also referred to as send-then-commit. Under this protocol, if the synchronization leel is Confirm, IMS sends the output message to the client and then waits for a response from the client. It is the responsibility of the client to respond to IMS. If the synchronization leel is None, IMS commits any changes made by the IMS application without waiting for a response from the client. Synchronization leel none When an EAB command uses a synchronization leel of NONE, the transaction runs and IMS sends the output message to the client. Any database changes are then committed. IMS does not require that the client send a message in response to the transaction output message in order to commit the database changes. Synchronization leel NONE is typically used for Jaa applications and serlets that run IMS transactions that browse or query host databases. Synchronization leel confirm When an EAB command uses the synchronization leel Confirm, the transaction runs and IMS sends the output message to the client without committing any Chapter 1. Understanding IMS Connector for Jaa 29

36 database changes. IMS does not complete the transaction until the client responds to the transaction output message by sending a positie or negatie acknowledgment to IMS. If the client is satisfied with the transaction output, it responds by sending a positie acknowledgment. IMS then completes the transaction by committing the database changes, if necessary. If the client is not satisfied with the transaction output (or does not want to continue with the transaction for any reason) it responds by sending a negatie acknowledgment. IMS then rolls back any changes to the database. If IMS Connect on the host encounters any errors from the Jaa application, it can also send a negatie acknowledgment to IMS to abort the transaction. For example, this might occur if communication with the Jaa application and IMS Connect is lost while 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 is com.ibm.connector.infrastructure.nullcoordinator, the client sends a positie or negatie acknowledgement to IMS. This is done by executing a separate EAB command with interaction mode MODE_ACK (for a positie acknowledgment) or MODE_NACK (for a negatie acknowledgment) to send the appropriate acknowledgement message to IMS. Because a MODE_ACK or MODE_NACK EAB command only sends acknowledgment messages to IMS, it does not contain any input or output beans. 2. If the coordinator object obtained from the current runtime context is not NullCoordinator, and is instead com.ibm.connector.infrastructure.jaa.jaacoordinator, for example, then the client inokes the commit() or rollback() method on the coordinator object, following receipt of the output message. The implementation of these methods will, in turn, send the corresponding acknowledgement message to IMS. In the case of an IMS conersation, different synchronization leels may be used for one or more of the iterations of the conersation. Since the conersational programming model presented by IMS Connector uses a new instance of the EAB command for each iteration of the conersation, the synchronization leel must be explicitly set for each iteration. Otherwise, the synchronization leel set for the command at deelopment time (usually the default, SYNC_LEVEL_NONE) will be used for the iteration. If SYNC_LEVEL_CONFIRM is specified for a gien iteration of an IMS conersation, either the commit() or rollback() method of JaaCoordinator must be executed following receipt of the output message for that iteration of the conersation. These messages can also be sent to IMS by creating two additional EAB commands which would be used in a NullCoordinator enironment. Howeer, it is recommended that applications use the simpler JaaCoordinator interface. See Building an application to run an IMS transaction with synchronization leel confirm for an illustration of an application that uses an IMS nonconersational transaction with SYNC_LEVEL_CONFIRM. Iterations of IMS conersations that use SYNC_LEVEL_CONFIRM would be handled in a similar fashion, as far as commit and rollback processing is concerned. Most likely the synchronization leel will be the same for all iterations of the IMS conersation, in which case it would be appropriate to set it in the IMSInteractionSpec when the EAB command is deeloped. A typical application scenario might be: 30 IMS Connector for Jaa User s Guide and Reference

37 1. The application inokes a transaction EAB command with interaction mode MODE_SEND_RECEIVE and the synchronization leel is SYNC_LEVEL_CONFIRM. 2. The application receies the transaction output from IMS. 3. The application performs some logic (or interacts with the end-user) to decide whether the transaction should be completed. 4. Based on the results from the preious step, the application inokes the commit() or rollback() methods of JaaCoordinator to respond to IMS. 5. IMS completes the transaction by committing or rolling back the database changes, based on the type of response (positie or negatie acknowledgment) that it receied. Related Reading: For more information on building an application to run an IMS transaction with synchronization leel, see Building an application to run an IMS transaction with synchronization leel confirm. ) Transaction Management for J2C Global Transaction and 2-Phase commit processing Many computer resources (for example, enterprise databases) are ery critical to a company s work and the integrity of these resources must be guaranteed. When making changes to these protected resources, an application can group the set of changes into a transaction (also known as a unit of work), such that all the changes made within a transaction are either fully completed or fully rolled back (also known as all-or-nothing changes). There are two types of transactions: global and local transactions. Global Transaction A transaction is categorized as global when an external coordinator is aailable and is coordinating a transaction that could inole more than one resource managers. The external coordinator uses the 2-phase commit protocol to coordinate between different resource managers. Local Transaction A local transaction is coordinated locally by the resource manager and there is no external coordinator inoled. Related Reading: For more information about RRS and 2-phase commit processing, see z/os and OS/390 MVS Programming: Resource Recoery. IMS Connector for Jaa supports two types of interactions in terms of J2C transaction management: No Transaction An IMS transaction request is submitted from a J2EE application to IMS through IMS Connect for processing. Changes made by IMS in the processing of the IMS transaction will be committed before returning the transaction output to the J2EE application. Global Transaction An IMS transaction request is submitted from a J2EE application to IMS through IMS Connect for processing in the context of a global transaction. Changes made by IMS are coordinated using the 2-phase commit protocol. Local Transaction Local transaction support is not aailable in this release. Chapter 1. Understanding IMS Connector for Jaa 31

38 The following table shows the J2C transaction support proided by IMS Connector for Jaa in this release: Platform of WebSphere Application Serer with IMS Connector for Jaa Windows, AIX, Solaris z/os, OS/390 J2C Transaction Support No transaction support No transaction support when configured with TCP/IP communication Global transaction support when configured with Local Option* * WebSphere Application Serer, IMS, IMS Connect, and IMS Connector for Jaa must exist on the same MVS image when using global transaction support. Types of J2C transactions in your J2EE applications The J2EE platform defines the Jaa Transaction API (JTA) which specifies the interfaces between a transaction manager and other parties inoled in transaction processing (such as the application programs, resource managers and the application serer). Particularly, JTA defines two ways to demarcate a transaction in a J2EE application: component-managed and container-managed transaction. Component-managed (or Bean-managed) transaction The J2EE application uses the JTA jaax.transaction.usertransaction interface to demarcate a transaction boundary to a set of changes to the protected resource or resources programmatically. Component-managed transaction can be used in both the serlet and the EJB enironment. In the case of an EJB, you sets the transaction attribute in its deployment descriptor as TX_BEAN_MANAGED. A transaction normally begins with a UserTransaction.begin() call. When the application component is ready to commit the changes, it inokes UserTransaction.commit() to coordinate and commit the changes. If the application component prefers to rollback the transaction, it inokes UserTransaction.rollback() and all changes will be backed out. For example: // Get User Transaction jaax.transaction.usertransaction transaction = ejbcontext.getusertransaction(); // Start transaction transaction.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 transaction transaction.commit(); Container-managed transaction A container-managed transaction used in an EJB enironment is managed by the EJB container. The container calls the appropriate methods (such as begin, commit or rollback) on behalf of the EJB component. The EJB specifies 32 IMS Connector for Jaa User s Guide and Reference

39 a container-managed transaction declaratiely through the transaction attribute in the deployment descriptor (such as TX_REQUIRED). This declaratie approach simplifies the programming calls in the EJB. Related Reading: For more information the J2EE architecture and JTA specifications, see for details. IMS Connector for Jaa J2C transaction support In this release, IMS Connector for Jaa adds support for global transactions and 2 phase commit processing for WebSphere Application Serer for z/os and OS/390. This support allows J2EE application components (such as EJBs and Jaa Serlets) running under WebSphere Application Serer for z/os and OS/390 to submit IMS transaction messages in the context of global transaction and to participate in 2-phase commit processing. The Resource Recoer Serices (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 make consistent changes to multiple protected resources. To use this global transaction support, the following configuration is required: IMS Connector for Jaa must be configured with the Local Option communication protocol to process global transaction in this release. If configured with TCP/IP, IMS Connector for Jaa will process the requests with no transaction support. WebSphere Application for z/os and OS/390, IMS Connector for Jaa, IMS Connect, IMS and RRS must all be running under the same MVS image for global transaction processing on the z/os and OS/390 platform. This restriction will be lifted in the future updates of IMS Connector for Jaa. When a J2EE application (such as a serlet or EJB) is running under a global transaction with the aboe configuration, the IMS transaction request is sent to IMS for processing using the IMS OTMA synchronization leel Syncpt protocol. All changes 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 Jaa is configured with no transaction processing (such as when it is configured to use TCP/IP communication), all requests to IMS are performed using the IMS OTMA synchronization leel None protocol. In this case, all changes to IMS are committed when the output is returned to the J2EE application. Notes: Transaction support in IMS Connector for Jaa will be proided in phases. Future releases of IMS Connector for Jaa will proide enhanced J2C support including XA transaction support for distributed platforms. IMS Connector for Jaa uses the RRS-Transaction support proided by WebSphere Application Serer for z/os and OS/390 in which the Local transaction and XA transaction support as described by the J2EE Connector Architecture is not supported. Related Reading: More information about the RRS-transaction support is aailable in WebSphere Application Serer for OS/390 and z/os documentation. The document titled WebSphere Application Serer V4.0.1 for z/os and OS/390: WebSphere for z/os-supported Connectors is aailable with APAR PQ55873 for WebSphere Application Serer V4.0.1 for z/os and OS/390. To download the document, go to the Web site at then click Product information. At a later time, the information in this document will Chapter 1. Understanding IMS Connector for Jaa 33

40 be integrated into the WebSphere for z/os formal publications. To access the latest publications, go to the product library page at For information on the synchronization leel protocol, see the IMS Connect Guide and Reference and the IMS Open Transaction Manager Access Guide and Reference, aailable on the IMS Web site at ( A proided sample (described in Building Container-managed and Component-managed Transactional EJBs to Run IMS Transactions ) demonstrates how to build an J2EE application to access your IMS transaction using IMS Connector for Jaa with global transaction and 2-phase commit processing. Additional samples (such as global transactions with IMS and DB2 databases) will become aailable on the IMS Connector for Jaa Web page, located in the IMS Web site at Be sure to check this Web site periodically for these samples and supporting documentation. IMS Connector for Jaa conersational programming models IMS Connector for Jaa Conersational Support proides users with two programming models from which to build Jaa applications and Web applications that iterate through the interactions of an IMS conersational program. The programming models are based on the existing application model that uses IMS Connector for Jaa to inoke IMS transactions using IMS Connect. Applications built from the programming model with CCF support use VisualAge for Jaa and WebSphere Studio. Applications built from the programming model with J2C support use VisualAge for Jaa and Application Assembly Tool (a WebSphere Application Serer tool). VisualAge for Jaa tools hae been enhanced to help customers generate the record components specifically needed for generating the input and output messages of an IMS conersational transaction. IMS Connector for Jaa proides both Common Connector Framework (CCF) and Jaa 2 Platform, Enterprise Edition (J2EE) Connector (J2C) architecture support for IMS conersations. Restriction: When inoking an IMS Conersation within a global transaction with 2-Phase commit processing (for example, with TX_REQUIRED), IMS OTMA supports the execution of one iteration of an IMS Conersation only. Subsequent iteration inocations to an IMS Conersation within a global transaction will result with an error in IMS. The information in this section includes the following: Considerations in Choosing a Model (page 35) Conersational HttpSession Model with CCF Support (page 35) Conersational HttpSession Model with J2C Support (page 38) Conersational Naigator Model with CCF Support (page 39) Conersational Naigator Model with J2C Support (page 40) Generally, a Jaa application is built with a GUI interface that consists of multiple window panels. The user proides the input data and iews the output data within separate panels of the same Jaa application when stepping through the iterations of the IMS conersation. The Jaa application contains logic that utilizes Jaa classes in the IMS Connector for Jaa Conersational Support to inoke the IMS conersational transactions. 34 IMS Connector for Jaa User s Guide and Reference

41 A Web application is made up of a group of application components that can be accessed from the Web and consists of one or more Jaa serlets that contain the application logic, an HTML page which seres as the initial input page used to start the application and one or more JSPs (Jaa Serer Pages) for obtaining input data from and displaying output data to the user. The Jaa serlets within a Web application share the same serlet context. The user starts an IMS conersational transaction from a web browser by first proiding some input data ia an HTML form. The web serer then inokes the Jaa serlet running inside the WebSphere Application Serer. The serlet utilizes the Jaa classes in IMS Connector for Jaa (including the Conersational Support classes) to send the conersational transaction request and receie the transaction output ia IMS Connect. The output will be displayed back to the user through a JSP in the web browser. Although this documentation focuses primarily on modeling an IMS conersation with a Web application, many of the same rules that pertain to Web applications can be applied to building Jaa applications, as well. Generally, the rules goerning the logic of a Jaa serlet can be applied to the logic of a Jaa application. Similarly, the rules goerning the use of HTML and JSP pages can be applied to the GUI interfaces of a Jaa application. Considerations in Choosing a Model You should choose the Naigator model if it is suitable for your IMS conersation since it proides a simpler deelopment paradigm and a more effectie use of connections. From a deelopment perspectie, the conersational Naigator model eliminates the need to deal with issues such as using the back button, bookmarking, browser caching or tracking the state of the IMS conersation. In addition, issues such as scaling, cloning, and clustering might affect your decision of which model to use. Consult the WebSphere Application Serer documentation for a detailed discussion of these issues. The Conersational Naigator model is suitable when a particular sequence of interactions representing a well defined task and the data required by all of those interactions can be pre-determined. A conersational IMS application can be used to process any number of tasks some of which may be suitable for the Naigator model and some of which are not. You will probably find that some small number of tasks for a gien IMS conersational application can be implemented with conersational Naigators but the majority will require HttpSession based serlets. Conersational HttpSession Model with CCF Support IMS Connector for Jaa Conersational Support introduces a session-enabled Web application model for an IMS conersational transaction, the Conersational HttpSession Model. A session encompasses a series of requests originating from the same browser to the Jaa serlet or serlets of a Web application. A session is analogous to an SNA connection between a terminal user and an IMS conersational application program. The Conersational HttpSession Model for building a Web application to inoke an IMS conersational transaction is similar to the programming model used for building a Web application to inoke a non-conersational IMS transaction. The steps inole the use of VisualAge for Jaa and WebSphere Studio and are as follows: 1. Proide your COBOL source files to VisualAge for Jaa to generate the input and output Jaa record beans. Chapter 1. Understanding IMS Connector for Jaa 35

42 2. Use the VisualAge for Jaa Command Editor to create an Enterprise Access Builder (EAB) command. 3. Supply the EAB command to WebSphere Studio and use WebSphere Studio to generate a template for a Web application. Build a Web application from the template using the guidelines outlined below. This process can be summarized as follows: a. Create additional JSP pages for the iterations. b. Modify the JSP pages. c. Modify the Jaa serlet. The user submits a series of requests from the same browser to iterate through different interactions of an IMS Conersation. The user starts an IMS conersational transaction from a web browser by submitting a request to IMS to schedule (or run) a conersational transaction. The HTTP session associated with the browser is used to group the series of interactions from that browser. The conersation continues through any number of iterations until it is terminated, either by a user action (i.e., the client) or by transaction program logic that directs IMS to end the conersation at the conclusion of that iteration. The conersational transaction can also be terminated automatically by IMS Connector for Jaa s classes wheneer the session-enabled Web application times out, for example, when the browser remains idle for a specified period of time. This timeout is set using the JaaSerlet APIs (the default is 30 minutes). The JaaSerlet specification proides a class, HttpSession, that is used by WebSphere Application Serer to create an object associated with the HTTP session used by the Web application. Once a session is established between the browser and the Jaa serlet, the Jaa serlet maintains a reference to this unique HttpSession object (i.e., the HttpSession object is bound to the serlet) throughout all of the iterations for the duration of the conersation. The Jaa serlet uses this unique HttpSession object to obtain information about the state of the session as well as the state of the conersation that is running in that session. An HttpSession object is associated with (bound to) a serlet at the start of the first iteration of an IMS conersation. It remains bound to that serlet, or a succeeding serlet in the case of a multi-serlet Web application, until the serlet detects that either the user has taken some action which will cause the IMS conersation to be terminated or the IMS application program has terminated the conersation. Program your serlets so that the session becomes unbound if there are any errors encountered in the application flow. Possible errors include communication failure between components and abnormal termination of components. Program your Jaa serlet to handle these errors appropriately. Generally, when an error occurs, your serlet should terminate the conersation and clean up the connection resource for reuse. For example, a browser session becomes unbound from a serlet when the browser times out waiting for input from the user. When this happens, the serlet should terminate the conersation and clean up the CCF connection resources. IMS Connector for Jaa Conersational Support proides the IMSConHttpSessionCleanup class to capture the notification from the HttpSession object when the HttpSession object becomes unbound. The IMSConHttpSessionCleanup object instantiated by the serlet will then terminate the conersational transaction and clean up the connection resources appropriately. Since the HTTP protocol, which is used as the connection mechanism between the web browser and the Jaa serlet, is stateless, it is often useful to bind objects to 36 IMS Connector for Jaa User s Guide and Reference

43 the HttpSession object in order to sae intermediate state data of the Web application. For example, you may want to sae information about the current iteration of the IMS conersation for use when the next iteration of the conersation is executed. Another use for the HttpSession object is to sae information about the connection being used for a particular conersation. This is necessary since IMS Connect requires a dedicated connection for the entire duration of an IMS conersation. In other words, IMS Connect requires that the same connection be used for all of the communications between the Web application (Jaa serlet or serlets) and IMS Connect. Furthermore, that connection cannot be used for any other communications until that conersation has ended. A connection for purposes of this discussion is the communications link between the Jaa application or serlet and IMS Connect. In a TCP/IP communications enironment, this connection is represented as a socket. In order to proide a mechanism for saing information about the connection being used for an IMS conersation in the HttpSession object, IMS Connector for Jaa includes the IMSConContext class in its Conersational HttpSession programming model for conersational Web applications. This class proides a token which is stored in the HttpSession object and used to bind a particular CCF connection to a serlet that is part of an IMS Conersation. Therefore this serlet needs to create a single IMSConContext object at the start of each IMS conersation. This object is then stored in the HttpSession object. The HttpSession object and therefore the IMSConContext are then used by the CCF ConnectionManager to initially bind a conersation to a particular connection and later to ensure that the CCF ConnectionManager will use that same connection for each iteration of the conersation. When the HttpSession object becomes unbound or an error occurs during the conersation, or at the end of the conersation, the IMSConContext reference must be unbound from its connection in order to allow the ConnectionManager to reuse that connection for new requests. When the HttpSession object becomes unbound this is handled automatically by the IMSConHttpSessionCleanup object that was instantiated in the Web application serlet when the conersation began. In the case of an error being detected in a serlet during a conersation, the unbinding is handled through the use of the httpsession.inalidate() which in turn causes the IMSConHttpSessionCleanup object to be inoked. When a conersation ends normally, the IMSConContext reference is unbound from its connection through the use of the RuntimeContext.getCurrent().close() method. After the conersational transaction is completed, a new conersational or non-conersational transaction can be run next from the client. Howeer, if the IMS conersation is not completed, then you cannot run a new transaction with the same connection resource. In the Conersational HttpSession model, the application flow for an IMS conersational transaction starts when the user initiates a conersation from the browser. The flow continues with a series of interactions between the Web application and the IMS conersational application program performing the business logic of the application. Finally, the conersation is terminated by the user or by the IMS application program. The application flow is illustrated as follows: Iterating in the IMS Conersation 1. The user starts an IMS conersational Web application by displaying the input HTML page of the Web application in a Web browser. Chapter 1. Understanding IMS Connector for Jaa 37

44 2. The user proides the initial input data of the IMS conersational transaction in the input HTML page. 3. The Web browser sends the request with the input data to the WebSphere Application Serer, which then starts the appropriate Jaa serlet to process the request. 4. The Jaa serlet obtains the HttpSession object and creates an IMSConContext object which it saes in that HttpSession object for use by the CCF ConnectionManager to ensure that the same connection is used throughout a conersation. The serlet then inokes the execute() method of the EAB command, passing the input data receied from the browser. The EAB command uses IMS Connector for Jaa APIs to send the transaction request to IMS ia IMS Connect. 5. IMS receies the request and schedules the IMS conersational application program. The IMS application program processes the request and the reply is returned to the Jaa serlet. 6. The Jaa serlet populates the EAB command with the output data of the reply and loads the appropriate result JSP page to display the output data on the Web browser. The Jaa serlet or the end user determines if the output data receied is acceptable. If it is, the Jaa serlet inokes the commit() method of JaaCoordinator to accept the output and commit that iteration of the conersation (by sending an ACK message to IMS Connect). Otherwise, it inokes the rollback() method of JaaCoordinator to reject the output and back out that iteration of the conersation (by sending a NACK message to IMS Connect.) 7. The user proides the data for the second iteration on the JSP page used to display the output data of the first iteration, then submits the next request to IMS. This inokes the second iteration of the IMS conersational transaction. Subsequent iterations of the conersation repeat steps 3-7 until the user or the IMS application program terminates the conersation. In step 4, on the second and all subsequent iterations of the conersation, the Jaa serlet obtains the IMSConContext object from its HttpSession object. Note: The steps described aboe may differ when used with different synchronization leels. The aboe scenario describes an application flow with SYNC_LEVEL_CONFIRM. When used with SYNC_LEVEL_NONE, the call to the JaaCoordinator commit() or rollback() method in step 6 will not be made. Terminating an IMS Conersation In the IMS Connector for Jaa Conersational HttpSession model, an IMS conersation is typically terminated in one of two ways. For these procedures, see Terminating a Conersation in Building Jaa applications and serlets for conersational transactions. Conersational HttpSession Model with J2C Support A similar programming model is proided for using IMS Connector for Jaa with J2C support to inoke IMS conersations. In this model, you build J2C applications to access IMS conersational transactions. In this Conersational HttpSession Model, a user submits a series of requests from the same browser to iterate through different interactions of an IMS conersation. The user starts an IMS conersation transaction from a web browser, which inokes 38 IMS Connector for Jaa User s Guide and Reference

45 a J2C application to interact with the IMS conersation. An HttpSession object is used to group a series of browser requests and associated J2C application interactions together in a session. IMS Connect requires a dedicated connection for the duration of an IMS conersation. The conersational HttpSession model ensures that the same connection is used when iterating through an IMS conersation from multiple browser requests. For definitions of the types of session beans, see IMS Connector for Jaa concepts and terms. At a high leel, the following steps occur in this conersational model: 1. The user starts an IMS conersational transaction from a web browser. 2. The browser inokes a Jaa serlet which saes the HttpSession object in an EJB object handle. An EJB object handle is a long-lied proxy for an EJB object. If for some reason you disconnect from the EJB container/serer, you can use the EJB object handle to reconnect to your EJB object without losing the conersational state with that bean. The EJB object handle references the stateful session beans to interact with the IMS conersation. 3. Methods that execute different iterations of the IMS conersation build stateful session beans. Each method normally represents a particular iteration of the IMS conersation and uses IMS J2EE Connector classes to execute the iteration of the IMS conersation. In addition, the stateful session beans keep a reference to the IMS connection handle that is dedicated to the IMS conersation. 4. This connection handle will remain actie for the duration of the IMS conersation. Information related to each iteration of the IMS conersation (for example, conersation state, current iteration, intermediate data) can also be saed in the stateful session beans. 5. At the end of the IMS conersation, the close() method will be called on the connection handle so that the connection can be reused by a new request. Note: The conersational transaction can also end during an ejbpassiation or a HttpSession inalidation (such as a timeout). In IMS Connector for Jaa with the IBM Common Connector Framework (CCF), you can clean up the connection resources when a browser session becomes unbound using the class IMSConHttpSessionCleanup (shipped with IMS Connector for Jaa). In IMS Connector for Jaa with J2C support, this class is not aailable. The IMS J2EE Connector Samples proides a similar solution to that class. This class is in the package com.ibm.connector2.ims.ico.sample.con.phonebook.serlet. Howeer, the implementation of IMSConHttpSessionCleanup is modified for the J2C architecture, such that the connection handle is saed instead of the IMSConContext class. Please note that the IMSConContext class does not exist in the IMS J2EE Connector conersational support. Conersational Naigator Model with CCF Support Like the conersational HttpSession model, the Conersational Naigator Programming Model for building a Web application to inoke an IMS conersational transaction is also similar to the programming model for building a Web application to inoke a non-conersational IMS transaction. The steps inole the use of VisualAge for Jaa and WebSphere Studio and are as follows: Chapter 1. Understanding IMS Connector for Jaa 39

46 1. Proide your COBOL source file or files to VisualAge for Jaa to generate the input and output Jaa record beans. 2. Use the VisualAge for Jaa Command Editor to create an Enterprise Access Builder (EAB) command for each iteration of the IMS conersation. 3. Using the VisualAge for Jaa Visual Composition Editor, create an EAB Naigator. 4. Generate a Web application using WebSphere Studio and VisualAge for Jaa. 5. Customize the HTML/JSP pages. 6. Modify the Jaa serlet An EAB Naigator can be used to model any IMS conersation where all of the data required for all of the interactions that make up that particular conersation is known in adance. A conersational Naigator consists of EAB Commands and/or other Naigators linked together to form a more complex Naigator which encapsulates all of the interactions that make up a gien IMS conersation. Each component EAB Command and Naigator within the conersational Naigator is then executed in the pre-determined order programmed into the conersational Naigator. For example, each iteration of an IMS conersation could be modeled as an EAB command. Then, a naigator can be built to encapsulate a sequence of EAB command iterations to model the whole IMS conersation for a particular task. When you execute a conersational EAB Naigator, as with any other EAB Naigator, it proides its input to the EAB Commands and Naigators of which it is comprised. The output of the component EAB Commands and Naigators is aailable to the conersational Naigator to be used as output, again depending on how the conersational Naigator is programmed. Once a conersational Naigator has started executing, control will not be returned to the user until all of the component EAB Commands and Naigators (which represent the iterations of the conersation) hae completed and the conersation has ended. No user interaction with an EAB Naigator is possible once execution of the Naigator has started. There is no mechanism aailable to proide additional data to be used by subsequent Naigator components after a gien Naigator component has finished execution. It is for this reason that all of the input data needed by each component EAB Command or Naigator must be proided to the conersational Naigator before it begins executing. Conersational Naigator Model with J2C Support This model remains the same as the IMS Connector for Jaa with CCF support Conersational Naigator model in which an EAB Naigator is used to map the iterations of the IMS conersation. An EAB Naigator can be used in J2C applications. After the Naigator is run, all iterations of the IMS conersational transaction is complete. When the Naigator completes its tasks, the connection being used by the Naigator is closed automatically for reuse. Migrating from CCF architecture to J2EE connector architecture The aailability of IMS Connector for Jaa 1.2 marks the transition from the IBM Common Connector Framework (CCF) architecture to Sun s Jaa 2 Platform, Enterprise Edition (J2EE) Connector (J2C) architecture. This change of architecture affects both your existing and new applications. Information on this transition can be found in VisualAge for Jaa s documentation by clicking Help > Help Home Page > Concepts > Access to transaction systems > Enterprise Access Builder for Transactions > Impact of CCF to J2EE transition. 40 IMS Connector for Jaa User s Guide and Reference

47 This section proides you with information on migrating EAB commands and Naigators, and should be used in conjunction with Migrating IMS Connector for Jaa EAB Commands to J2EE below. Information on migrating serlets coded with the CCF architecture to the J2C architecture is aailable in the VisualAge for Jaa documentation in Help > Help Home Page > Samples > Enterprise Access Builder for Transactions > WebSphere set > J2EE JSP and serlet. If you want to run your CCF serlet in WebSphere Application Serer 4.0 without migrating to the J2C architecture, you can do so. The sections Running a CCF Serlet in WebSphere Application Serer 4.0 for Windows on page 42 and Running a CCF Serlet in WebSphere Application Serer 4.0 for z/os and OS/390 on page 46 below describe how to deploy one of the CCF samples proided with an earlier release of IMS Connector for Jaa to WebSphere Application Serer 4.0. Migrating IMS Connector for Jaa EAB Commands to J2EE Migrating IMS Connector for Jaa EAB Commands from a CCF-based application to a J2EE-based application can be done using the migration tool proided with VisualAge for Jaa. A description of how to migrate an EAB command using this tool can be found in the VisualAge for Jaa documentation by clicking Help > Help Home Page > Tasks > Accessing transaction systems > Accessing CICS, IMS, Encina, MQSeries, HOD > Getting started with Enterprise Access Builder for Transactions > Working with EAB Commands > Migrating EAB Commands to J2EE. This VisualAge for Jaa information also contains links to the migration of records and Naigators to J2EE. The records of an EAB command can be migrated when you migrate the EAB command or they can be migrated separately. The generated records are backward compatible with CCF applications. In addition, the DFSMsg bean in package com.ibm.connector2.ims.ico has already been migrated. When you migrate an IMS Connector for Jaa EAB command, you might receie one or both of the following warnings: IVJC1604W: The property, syncleel, could not be migrated for command_name. It has been omitted. IVJC1604W: The property, datastorename, could not be migrated for command_name. It has been omitted. These warnings result from the difference in support of synchronization leel and datastore name between the CCF and J2C implementations of IMS Connector for Jaa. Synchronization leel is not supported IMS Connector for Jaa s CCF implementation allows you to select from two synchronization leels (SYNC_LEVEL_CONFIRM and SYNC_LEVEL_NONE) for an iteration of a transaction. IMS Connector for Jaa s J2C implementation in this release does not support the specification of synchronization leel for an interaction. In this release, SYNC_LEVEL_NONE, the default synchronization leel, is always used. Support for selecting a synchronization leel will be proided in a future release. IMS datastore name is no longer an InteractionSpec property Chapter 1. Understanding IMS Connector for Jaa 41

48 The datastore name property has been moed to the IMSManagedConnectionFactory class to be more consistent with the use of the JNDI naming serice by the J2EE programming model. A connection factory for a particular combination of hostname, port, and datastore name is deployed in the JNDI name space and used by all applications targeting that datastore using the hostname/port combination. Note, howeer, that only hostname and port are considered for the purposes of connection pooling. Running a CCF Serlet in WebSphere Application Serer 4.0 for Windows If you are not ready to migrate your CCF application to J2C, you can still run it in WebSphere Application Serer 4.0 for Windows. There are many ways to do this. These instructions show how you can do this with minimal changes, using one of the samples proided with an earlier release of IMS Connector for Jaa, com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet. This serlet was deeloped as a Web application ( webapp ), imsconn, for WebSphere Application Serer 3.5. Step 1: Deploy imsconn.jar to WebSphere Application Serer Connectors that implement J2C architecture are packaged as resource adapters. Resource adapters are deployed in WebSphere Application Serer 4.0 for distributed platforms from a Resource Adapter Archie (RAR) file. IMS Connector for Jaa also implements IBM s Common Connector Framework architecture. This implementation is aailable as a Jaa Archie (JAR) file, imsconn.jar. To deploy imsconn.jar in WebSphere Application Serer 4.0 for distributed platforms, copy imsconn.jar from <ico_install_dir>/imsico/ccf, where <ico_install_dir> is the directory where you installed IMS Connector for Jaa to <was_install_dir>/websphere/appserer/lib, where <was_install_dir> is the directory where you installed WebSphere Application Serer 4.0. Note: In the past it was necessary to copy ccf.jar, eablib.jar, and recjaa.jar from VisualAge for Jaa to a directory accessible to WebSphere Application Serer. It was also necessary to modify the classpath used by WebSphere Application Serer to point to these JAR files as required. This in no longer necessary because WebSphere Application Serer 4.0 for distributed platforms includes these JAR files. Step 2: Make the Serlet 4.0 Files Accessible to WebSphere Application Serer Copy the contents (files and folders) from the following folder: <aj_install_drie>\ibm Connectors\IMSCONN\samples\serlets\phonebook where <aj_install_drie> is the VisualAge for Jaa installation directory to a folder of your choice on the target WebSphere Application Serer 4.0 machine. For example, CCFWAS40. The CCFWAS40 folder should now contain the following folders and files: com theme DFSMsg.jsp Ex01Serlet.jar Ex01SerletHTMLError.jsp Ex01SerletHTMLInput.html 42 IMS Connector for Jaa User s Guide and Reference

49 Ex01SerletHTMLResults.jsp Step 3: Modify the Serlet s Input HTML Remoe the serlet keyword from the FORM statement of the serlet s input HTML, Ex01SerletHTMLInput.html. For example: <! <FORM METHOD= post ACTION= /webapp/imsconn/serlet/com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet <FORM METHOD= post ACTION= /webapp/imsconn/com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet > Step 4: Start WebSphere s Application Assembly Tool 1. From your Windows desktop, click Start > Programs > IBM WebSphere > Application Serer 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 your Web module. For example, Ex01SerletWebMod. Enter an optional description of your Web module. c. When you select the Apply you will notice that the name you chose for your Web module will replace the default name in the left pane of the Application Assembler window. 2. Add files to your Web module. a. Expand the Files folder in the left pane of the Application Assembler window. b. Right-click on the Class Files folder and select Add Files. c. Select the Browse button beside the Root Directory or Archie entry field. If your files are in a folder (rather than an archie): 1) Locate and select the folder containing your serlet class file and its package directory structure. For example, select CCFWAS40. 2) Verify that the root directory (for example, CCFWAS40) appears in the Files of Type: entry field and click the Select button. 3) You should see the files contained in the selected folder listed in the upper right pane of the Add Files window. 4) Expand the directory structure of the serlet class package found underneath your root directory by clicking the plus signs next to each folder that makes up your serlet s package name. For example, click the plus sign next to the following folders in order: com, ibm, connector, ims, sample, phonebook, serlet. 5) Select the folder at the bottom of this structure, which should contain the class of your serlet. For example, select the serlet folder. This should then display your serlet s class in the upper right pane. 6) Select your serlet s class (for example, Ex01Serlet.class) and click the Add button. This should list the serlet s package directory structure and class name in the Selected Files: pane. Chapter 1. Understanding IMS Connector for Jaa 43

50 7) Click OK. 8) Right-click on the Jar Files folder and select Add Files. Repeat the process used to add class files, but this time add the following: Ex01Serlet.jar 9) Right-click on the Resource Files folder and select Add Files. Repeat the process used to add class files, but this time add the following: DFSMsg.jsp Ex01SerletHTMLError.jsp Ex01SereltHTMLInput.html Ex01SereltHTMLResults.jsp com/ibm/connector/ims/sample/phonebook/serlet/ex01serlet.serlet theme/master.css 3. Add a Web component to your Web module. A Web module is used to assemble serlets, JaaSerer Pages, Web pages, and other static content into a single deployable unit. A Web component is a serlet or JaaSerer Page. In this case, you are adding a serlet Web component to your Web module, Ex01SerletWebMod. a. Right-click on Web Components in the left pane of the Application Assembler window, then select New. b. In the New Web Component window: 1) Enter the name of your serlet in the Component name: entry field. For example, Ex01Serlet. 2) In the Display name: entry field, enter the name of this web component as it will be listed in your web module. For example, Ex01Serlet. 3) Select the Serlet radio button, then select the Browse button beside the Class name: field. 4) Locate and select your serlet class file in the WEB_INF folder. Then click OK. 5) In the New Web Component window, erify that the full package and class name of the serlet are displayed in the Class name field. Click the OK button. 4. Proide your serlet s mapping information. A serlet mapping associates a serlet with a client request by using a URL pattern. a. Right-click Serlet Mapping in the left pane of the Application Assembler window, then click New. b. Enter /com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet in the URL pattern: entry field, then click OK. (See the statement that begins FORM METHOD= post ACTION= of the file Ex01SerletHTMLInput.html.) 5. Sae your Web module in a WAR file. a. Select your Web module in the left pane of the Application Assembler window. For example, select Ex01SerletWebMod. b. Select File > Sae as... from the menu of the Application Assembly Tool window and sae your WAR file with a name you choose. For example, Ex01Serlet.war. Step 6: Create an Enterprise Application from your Web Module 1. Select File > New > Application from the menu of the Application Assembly Tool window. 44 IMS Connector for Jaa User s Guide and Reference

51 2. In the Display name: entry field of the right pane of the Application Assembler window, enter a name for your enterprise application, then select the Apply button. For example, Ex01SerletApp. 3. In the left pane of the Application Assembler window, right-click on Web Modules under your enterprise application, Ex01SerletApp, and select Import. 4. Locate the WAR file for your Web module (for example, Ex01Serlet.war), select it, then select the Open button. 5. In the Confirm alues window, enter /webapp/imsconn in the Context root entry field, then select OK. 6. Sae your Enterprise application in an.ear file. a. Select your Enterprise application in the left pane of the Application Assembler window. For example, select Ex01SerletApp. b. Select File > Sae as... from the menu of the Application Assembly Tool window and sae your.ear file with a name you choose. For example, Ex01SerletApp.ear. 7. You may now exit from the Application Assembler if you wish. Step 7: Start the WebSphere Adanced Administratie Console 1. From your Windows desktop, click Start > Programs > IBM WebSphere > Application Serer 4.0 > Start Admin Serer. You must start this serer before you start the Administratie Console. 2. Click Start > Programs > IBM WebSphere > Application Serer 4.0 > Administrator s Console. Step 8: Deploy your Enterprise Application Using the instructions for Deploying the IMS Connector for Jaa IVP in WebSphere Application Serer in Preparing your WebSphere Application Serer enironment for Windows as a guideline, deploy your enterprise application (for example, Ex01SerletApp) to WebSphere Application Serer. Step 9: Run your Enterprise Application Do the following in a browser of your choice: 1. In the Web address field, enter (where /webapp/imsconn is the context root of your enterprise application in this example). 2. Proide alues for the input fields as required. Values for datastorename, hostname, IN_CMD, IN_NAME1, IN_TRCD, and portnumber are required to run itno, one of the IMS INSTALL/IVP sample transactions on which this Ex01Serlet sample is based. Values for IN_EXTN, IN_NAME1, IN_ZIP, User Name, Password, and Group might be required, depending on the alue of IN_CMD that you entered and the security settings for OTMA and IMS Connect. Click the Submit button when you hae finished entering the required alues. The browser will submit a request to the application serer to run Ex01Serlet. Chapter 1. Understanding IMS Connector for Jaa 45

52 Running a CCF Serlet in WebSphere Application Serer 4.0 for z/os and OS/390 If you are not ready to migrate your CCF applications to J2C, you can continue to run it them WebSphere Application Serer 4.0 for z/os and OS/390. The following instructions show how to do this with minimal changes, using one of the samples proided with an earlier release of IMS Connector for Jaa, com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet. This serlet was deeloped as a Web application ( webapp ), imsconn, for WebSphere Application Serer 3.5. Part 1: Assembling the Application In this part, you will assemble your application into an enterprise archie (EAR) file. You will deploy this EAR file in the next part. This ear file contains a Web module that includes your HTML and JSP files and CCF serlet to run in WebSphere Application Serer for z/os and OS/390. To assemble your application for deployment to WebSphere Application Serer for z/os and OS/390, the Application Assembly Tool (AAT) for z/os and OS/390 is required. See Preparing to deploy the J2C Samples section for more information. 1. Create a Web module. In this step, you will build a Web archie (WAR) file that includes your HTML and JSP files and CCF serlet. If you hae AAT for Windows, it is recommended that you first complete Steps 2 to5in Running a CCF Serlet in WebSphere Application Serer 4.0 for Windows on page 42 to create a WAR file that contains your Web module before moing on to the step. If you are planning to use tools other than the AAT for Windows to create a WAR file and import into AAT for z/os and OS/390, make sure that you hae used the appropriate alues as discussed in that section. If you do not hae tools (for example, AAT for Windows) to build a WAR file, you can build the WAR file by archiing the pieces of it (the HTML, JSP, Serlet and the web.xml file) using the JAR command aailable with the Jaa Deelopment Kit (JDK) as follows: a. On your workstation, create a new directory (for example, c:\ccfserletwar) as the root directory for building your WAR file. b. Create the following subdirectories under the root directory that you created in the preious step: C:\CCFSerletWar\WEB-INF\lib\ C:\CCFSerletWar\\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 folder created in the preious step (for example, C:\CCFSerletWar\WEB- INF\web.xml). This web.xml contains the deployment descriptor information for your web module. 2) Insert the following XML code into the web.xml file: <?xml ersion= 1.0 encoding= UTF-8?> <!DOCTYPE web-app PUBLIC -//Sun Microsystems,Inc.//DTD Web Application 2.2//EN > <web-app> <display-name>ex01serletwebmod</display-name> <serlet> <serlet-name>ex01serlet</serlet-name> <display-name>ex01serlet</display-name> <serlet-class> 46 IMS Connector for Jaa User s Guide and Reference

53 com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet </serlet-class> </serlet> <serlet-mapping> <serlet-name>ex01serlet</serlet-name> <url-pattern> /com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet </url-pattern> </serlet-mapping> </web-app> 3) Sae the web.xml file. d. Copy the following HTML and JSP files (which are also aailable with the sample in the <aj_install_dir>\ibm Connectors\IMSCONN\samples\serlets\phonebook directory) to the root directory for building your WAR file (for example, c:\ccfserletwar): Ex01SerletHTMLInput.html Ex01SerletHTMLResults.jsp Ex01SerletHTMLError.jsp DFSMsg.jsp com/ibm/connector/ims/sample/phonebook/serlet/ex01serlet.serlet theme/master.css e. Modify Ex01SerletHTMLInput.html by remoing the serlet keyword from the FORM statement. For example: <!-- <FORM METHOD= post ACTION= /webapp/imsconn/serlet/com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet <FORM METHOD= post ACTION= /webapp/imsconn/com.ibm.connector.ims.sample.phonebook.serlet.ex01serlet > f. Copy the directory that contains your serlet class file (for example, com\ibm\connector\ims\sample\ex01serlet.class) to the WEB-INF\classes directory under the root directory for building your WAR file (for example, c:\ccfserletwar\web-inf\classes). g. Copy your support classes JAR file (for example, Ex01Serlet.jar) that contains your EAB command and the record beans classes to the WEB-INF\lib directory under the root directory for building your WAR file (for example, C:\Ex01SerletWar\WEB-INF\lib). h. Create the WAR file (for example, Ex01Serlet.war) using the jar command as follows: 1) Using a command prompt on your workstation, naigate to the root directory for building your WAR file (for example, C:\CCFSerletWar\). You should files similar to the following in that directory: C:\CCFSerletWar\Ex01SerletInput.html C:\CCFSerletWar\Ex01SerletResults.jsp C:\CCFSerletWar\Ex01SerletError.jsp C:\CCFSerletWar\DFSMsg.jsp C:\CCFSerletWar\com\ibm\connector\ims\sample\phonebook\serlet\Ex01Serlet.clas C:\CCFSerletWar\theme\Master.css C:\CCFSerletWar\WEB-INF\web.xml C:\CCFSerletWar\WEB- INF\classes\com\ibm\connector\ims\sample\phonebook\serlet\ C:\CCFSerletWar\Ex01Serlet.class C:\CCFSerletWar\WEB-INF\lib\Ex01Serlet.jar Chapter 1. Understanding IMS Connector for Jaa 47

54 2) Create the WAR file with the name CCFSerlet.war by issuing the JAR command at the command prompt as follows: jar -cf CCFSerlet.war * The JAR command is aailable with your Jaa Deelopment Kit (JDK) 3) Verify that the WAR file (for example, CCFSerlet.war) is created in the directory (for example, c:\ccfserletwar). 2. In the Enironment Variables on your workstation, configure the classpath for the Application Assembly Tool for z/os and OS/390 to use the IMS Connector for Jaa CCF classes: a. Click Start > Settings > Control Panel. b. Double click System in the Control Panel. In the System Properties window, click the Adanced tab and click Enironmental Variables... c. Add a new system ariable with the name AAT_USER_PATH and a alue C:\IBMCON~1\classes\imsconn.jar. Note: If you hae AAT for z/os and OS/390 running on the same system with your VisualAge for Jaa enironment that contains your IMS Connector for Jaa CCF code (imsconn.jar), you can find imsconn.jar in your C:\IBM Connectors\classes folder. If your AAT and VisualAge for Jaa with the IMS Connector for Jaa CCF code are running on different systems, be sure to copy imsconn.jar to your AAT system and replace C:\IBMCON~1\classes\imsconn.jar alue with the fully qualified path name of your imsconn.jar file. 3. Start the Application Assembly Tool for z/os and OS/390 by clicking Start > Programs > IBM WebSphere for z/os > Application Assembly. 4. Right click the Applications folder and select Add from the menu. Enter the name of your application in the Display name field (for example, CCFEx01390App ). Then click Selected > Sae. 5. Double click the folder of the application you just created to list the 3 component folders of this application. Right click the Web Apps folder and click Import. In the Import Web App window, click the Choose button and naigate to the CCF Web module you created (for example, CCFSerlet.war ). Select that WAR file and click OK. Click OK again to close the Import Web App window. The web module (for example, Ex01SerletWebMod) associated with the selected WAR file should now appear underneath the Web Apps folder. 6. Select this new application folder and click Selected > Modify. Enter the context root of your application in the Context root field. The context root of your application should be synchronized with your serlet input HTML page (for example, /webapp/imsconn ). Click Selected > Sae. 7. Select the application folder you created in Step 4 aboe (for example, CCFEx01390App ). Right click it and click Validate. When the application is alidated successfully, right click the application folder again and click Deploy. 8. You might see a message BBO94053I Class com.ibm.webtools.runtime.abstractstudioserlet is not found. Do you want to import a file into application CCFEx01390App that contains this class? Click the No to All button. 9. When the application is successfully deployed, right click the application folder CCFEx01390App again and click Export... In the Export application window that appears, click Choose... In the Select output ear file window that appears, naigate to a directory in which you want to sae your application. Gie the deployed application a file name (such as CCFEx01390.ear) in the File name field. Click OK to close the Select output ear file window. Click OK to close the Export application window. 48 IMS Connector for Jaa User s Guide and Reference

55 Part 2: Deploying the Application To deploy the application to WebSphere Application Serer, use the WebSphere for z/os Administration Application. 1. Start the WebSphere for z/os Administration Application. For example, Start > Programs > IBM WebSphere for z/os > Administration and wait for the Login window to appear. 2. In the dialog, enter the Bootstrap serer IP name (for example, the DAEMON_IP enironment ariable or the name specified for the bootstrap serer s IP address in the host file on the workstation), Port (default 900), the Userid (default CBADMIN), and the Password (default CBADMIN). 3. Click OK to login and establish connections to the serers. Wait for the WebSphere for Application Serer for z/os and OS/390 Administration window to appear. 4. Add a new conersation: a. Select the Conersations folder. b. Click Selected > Add and wait for the conersation name and description fields to appear. c. In the Conersation Name text box enter the name for the new conersation (for example, CCFEx01390). d. Click Selected > Sae. e. Wait for the completion message (for example, BBON0515I Conersation IMSICO was added. ) to appear in the status text box aboe the status bar in the Administration window. 5. Install the enterprise application: a. Select the J2EE serer (for example, BBOASR2) on which this application will be installed. Select this serer by expanding the following folders in order: Conersations folder, the new conersation (for example, CCFEx01390), the Sysplexes folder, the sysplex in which your sample J2EE serer has been installed, and the J2EESerers folder. b. Click Selected > Install J2EE application... and wait for its reference window to appear (for example, the Install J2EE application on serer: BBOASR2 window). c. Click the Browse EAR File... button and wait for the Open window to appear. Locate and select your EAR file (for example,ccfex01390.ear). Click Open. d. Verify that the destination and EAR file name appears in the EAR Filename text field. Click OK and wait for the Reference and Resource Resolution window to appear. e. In the Reference and Resource Resolution dialog box: 1) On the left side of the dialog, expand the CCFEx01_WebApp.jar folder and select the J2EE application bean (for example, CCFEx01_WebApp). 2) On the right side of the dialog, click the EJB tab and click Set Default JNDI Path & Name. Click OK. 6. Modify the J2EE serer (for example, BBOASR2) classpath by adding the following: <imsconn_dir>/imsconn.jar Modify the libpath by adding the following: <imsconn_dir> Chapter 1. Understanding IMS Connector for Jaa 49

56 where <imsconn_dir> is the installation directory that contains the IMS Connector for Jaa CCF classes, namely the imsconn.jar and libimsconn.so files. For example, /usr/lpp/imsico/ccf. 7. Validate the new conersation you created in the preious step by selecting the conersation name (for example, CCFEx01390 ) to highlight it and clicking Build > Validate. 8. Commit the new conersation by selecting the conersation name to highlight it and clicking Build > Commit. 9. Ensure that all preparation tasks for the new conersation are completed. Then select the conersation name to highlight it and click Build > Complete > All Tasks to indicate completion. 10. Actiate the new conersation by selecting the conersation name to highlight it and clicking Build > Actiate. 11. Configure the HTTP serer for the context root of the CCF sample by modifying the following files: a. Ensure that the webcontainer.conf file contains the following information: Host.default_host.contextroots=/ b. Modify the httpd.conf file with the following information: Serice /webapp/imsconn/* <was_dir>/websererplugin/bin/was400plugin.so:serice_exit where <was_dir> is the installation directory for WebSphere (for example, /usr/lpp/websphere) Part 3: Starting WebSphere Application Serer for z/os and OS/390 To start WebSphere Application Serer for z/os and OS/390, follow Step 6: Starting the serer to run the IVP. in Preparing your WebSphere Application Serer Enironment for z/os and OS/390. Part 4: Running the Application 1. Open a Web browser and enter the following Web address: where the <serername> and <port> is the name and port number for your Web serer and the context root of your enterprise application is /webapp/imsconn in this example. 2. Proide alues for the input fields as required. Values for the following fields are required to run itno (one of the IMS INSTALL/IVP sample transactions on which the Ex01Serlet sample is based): DataStoreName HostName IN_CMD IN_NAME1 IN_TRCD PortNumber Values for the following fields might be required, depending on the alue of IN_CMD that you proided and on the security settings for OTMA and IMS Connect: IN_EXTN IN_NAME2 50 IMS Connector for Jaa User s Guide and Reference

57 IN_ZIP User Name Password Group 3. Click Submit when you hae entered the required alues. The browser then submits a request to the application serer to run Ex01Serlet. You should see the message Entry was displayed. Chapter 1. Understanding IMS Connector for Jaa 51

58 52 IMS Connector for Jaa User s Guide and Reference

59 Chapter 2. Preparing to use IMS Connector for Jaa This topic describes how to create an enironment in which you can deelop and run Jaa programs that use either the J2EE Connector Architecture (J2C) implementation of IMS Connector for Jaa or the Common Connector Framework (CCF) implementation of IMS Connector for Jaa. It proides installation and configuration information for the following products: VisualAge for Jaa Enterprise Edition 4.0 WebSphere Application Serer See Prerequisites for using IMS Connector for Jaa for more information on these and other prerequisites. Information on preparing a WebSphere Studio enironment pertains primarily to the earlier CCF sample, Building a Jaa serlet to run an IMS transaction. IMS Connector for Jaa proides 2 types of Installation Verification Programs (IVPs) that you can run from the following enironments: The IVP GUI, which is run in VisualAge for Jaa for Windows, erifies that VisualAge for Jaa is correctly configured to access your IMS and IMS Connect system. The IVP Serlet, which is run in either WebSphere Application Serer for Windows or WebSphere Application Serer for z/os and OS/390, erifies WebSphere Application Serer is correctly configured to access your IMS and IMS Connect system. Each of these IVPs inoke IMS commands without requiring a host IMS application. Preparing to Run the IMS Connector for Jaa IVP To run any of the proided IVPs, erify that the following components are running on your target host machine: IMS Connect Version 1.2 or higher Ensure that the outstanding IMS Connect reply appears on the target machine s system console. For example: * STC00156 *16 HWSC0000I *IMS CONNECT READY* ims_connect_name Note: IMS Connect Name is referred to in IMS Connect as HWS ID.. Verify that the PORT and DATASTORE are ACTIVE by entering the IMS Connect command VIEWHWS at the IMS Connect outstanding reply Verify that the eyecatcher in module HWSHWS00 in the HWS RESLIB is at least 120. For example:...hwshws IMS Version 7.1 or higher Ensure that the IMS outstanding reply appears on the target machine s system console. For example: JOB00175 *15 DFS996I *IMS READY* Verify that the XCF status of both the IMS and IMS Connect members is ACTIVE by entering the IMS command /DISPLAY OTMA at the outstanding IMS reply: Copyright IBM Corp. 1998,

60 DFS000I GROUP/MEMBER XCF-STATUS USER-STATUS SECURITY SYS3 DFS000I GROUPNM SYS3 DFS000I -IMSMEM ACTIVE SERVER NONE SYS3 DFS000I -ICONNMEM ACTIVE ACCEPT TRAFFIC SYS3 DFS000I *01218/111559* SYS3 When using an IVP, you can use either the TCP/IP or Local Option communication protocols. If you are using TCP/IP, ensure that you can successfully ping the target host machine from your VisualAge for Jaa workstation. If you are using Local Option, ensure that IMS Connect and the IVP are running on the same MVS image. Complete the related tasks below to run these IVPs.á Preparing your VisualAge for Jaa enironment VisualAge for Jaa Enterprise Edition can be used to both deelop and run Jaa programs that use IMS Connector for Jaa to access IMS transactions. In addition, the IBM WebSphere Test Enironment of VisualAge for Jaa can be used to test serlets and EJBs that you deelop using VisualAge for Jaa. This section describes how you prepare your VisualAge for Jaa enironment to use IMS Connector for Jaa. Configuring VisualAge for Jaa IMS Connector for Jaa is included with VisualAge for Jaa Enterprise Edition; it does not usually require a separate installation process. Because IMS Connector for Jaa is part of VisualAge for Jaa, its software prerequisites are the same as those for VisualAge for Jaa. IMS Connector for Jaa features both a J2EE Connector Architecture (J2C) implementation and a Common Connector Framework (CCF) implementation. To use IMS Connector for Jaa perform the following steps in the order indicated: 1. Install VisualAge for Jaa Enterprise Edition 4.0. Important: If you do not select the Complete installation option of VisualAge for Jaa, you must include the Transaction Access Builder feature in your installation. If you hae already installed VisualAge for Jaa 4.0 and an earlier ersion of IMS Connector for Jaa you can skip this step. The installation of VisualAge for Jaa 4.0 proides you with the CCF (Common Connector Framework) implementation of IMS Connector for Jaa. To use the J2C implementation of IMS Connector for Jaa, complete the following steps. If you plan on using the CCF implementation only, your installation is complete. 2. To use the J2C implementation of IMS Connector for Jaa, ensure that the components related to the Jaa 2 Platform Enterprise Edition (J2EE) Connector Architecture are installed in VisualAge for Jaa. Instructions for installing these components can be found in file extras/betaj2eeconnectors/readme.eab of VisualAge for Jaa s installation media. 3. Download and install the IMS Connector for Jaa update from the VisualAge Deeloper Domain at 4. Add to your VisualAge for Jaa workspace the VisualAge for Jaa features IMS Connector and, optionally, IMS Connector Samples The IMS Connector Samples project will replace any preious ersions of the project in your VisualAge for Jaa workbench. a. Start the Workbench in the VisualAge for Jaa IDE. Click the Start > Programs > IBM VisualAge for Jaa for platform > IBM VisualAge for 54 IMS Connector for Jaa User s Guide and Reference

61 Jaa, where platform is the platform on which you hae VisualAge for Jaa. If the VisualAge Welcome to VisualAge dialog box appears, click Go to the Workbench and click OK. The IDE workbench appears. b. From the File menu, click Quick Start. c. In the Quick Start window, click Features on the left pane. Then, click Add Feature on the right pane and click OK. d. Select the feature IBM EJB Deelopment Enironment and click OK to add it to the VisualAge for Jaa workspace. This step is required. e. Repeat the aboe step to add the features IMS Connector and IMS Connector Samples The feature IMS Connector will be added to your workbench as project Connector IMS and the feature Connector IMS Samples will be added as project Connector IMS Samples. Check the All Problems tab of your workbench when adding a feature to see if additional projects (such as the IBM Common Connector Framework, IBM Common Connector Framework2, and J2EE Connector Architecture) need to be added in order to resole any problems. After you add the IMS Connector features to your VisualAge for Jaa workspace, you hae access to the following: Connector IMS, a VisualAge for Jaa project that consists of four packages: com.ibm.connector2.ims.ico This package includes the classes of IMS Connector for Jaa s J2C implementation. com.ibm.ims.ico This package includes the classes that implement the internal logic of IMS Connector for Jaa s J2C implementation. com.ibm.connector.imstoc This package includes the classes of IMS Connector for Jaa s CCF implementation. Many of the classes in this package are support classes, and are not used by VisualAge for Jaa application deelopers. com.ibm.imstoc This package includes the classes that implement the internal logic of IMS Connector for Jaa s CCF implementation. All of the classes in this package are support classes, and are not used by VisualAge for Jaa application deelopers. The classes and methods that are used in the VisualAge for Jaa application deelopment process are documented in the Reference section of the VisualAge for Jaa web help. To iew this documentation, click Help >API Reference > IBM APIs > Connectors > IMS Connector IMS Connector for Jaa Online Help in HTML format. The PDF format of the IMS Connector for Jaa User s Guide and Reference is aailable on the IMS Connector for Jaa Web page in the IMS Web site at Two IMS Connector for Jaa IVPs (Installation Verification Programs) that you can use to erify that a Jaa application using either the CCF or the J2C implementation of IMS Connector for Jaa can access IMS from within the VisualAge for Jaa enironment. These programs are in the IMSConnIVPMainDialog class in the Connector IMS Samples project in the package com.ibm.connnector.ims.sample.ip (for the CCF IVP) and in the package com.ibm.connector2.ims.ico.sample.ip (for the J2C IVP). Two IMS Connector for Jaa (IVP) serlets that you can use to erify that a serlet using either the CCF or the J2C implementation of IMS Connector for Chapter 2. Preparing to use IMS Connector for Jaa 55

62 Jaa can access IMS from within a WebSphere Application Serer enironment. The source for these programs are in the Connector IMS Samples project in the com.ibm.connnector.ims.sample.ip.was35.serlet (for the CCF erification) and in the package com.ibm.connector2.ims.ico.sample.ip.serlet package (for the J2C IVP). Important: The CCF IMS Connector for Jaa IVP serlet is currently proided only with VisualAge for Jaa. For instructions on how to run this program in the WebSphere Application Serer enironment, see Preparing your WebSphere Application Serer enironment for Windows. The source for the J2C IMS Connector for Jaa IVP serlet is proided with VisualAge for Jaa for illustration purposes only. The runtime of the J2C IMS Connector for Jaa IVP serlet is included with the IMS Connector for Jaa runtime component packaged with the IMS Connect product. Instructions on how to use this serlet to erify your WebSphere Application Serer enironment are included with the installation instructions for the IMS Connector for Jaa runtime component and in Preparing your WebSphere Application Serer enironment for Windows. Sample code is aailable to aid in the deelopment of your Jaa applications using either the J2C or CCF implementations of IMS Connector for Jaa. This code is aailable in the Connector IMS Samples project. Preparing to run the Installation Verification Program See Preparing to run the IVP serlet in Preparing to use IMS Connector for Jaa for information on IVP prerequisites. Using the VisualAge for Jaa IVP to Verify Your VisualAge for Jaa Enironment The CCF and J2C IMS Connector for Jaa Installation Verification Programs (IVPs) are Jaa applications that are included with VisualAge for Jaa. You can use one of these IVPs to erify that a Jaa application that uses either the CCF or J2C implementation of IMS Connector for Jaa can run within VisualAge for Jaa on Windows and can successfully access the target IMS enironment. The CCF IMS Connector for Jaa IVP sample program is contained in the com.ibm.connector.ims.sample.ip package in the Connector IMS Samples project that is added to your workbench when you add the IMS Connector Samples feature. The J2C IMS Connector for Jaa IVP sample program is contained in the com.ibm.connector2.ims.ico.sample.ip package in the Connector IMS Samples project that is added to your workbench when you add the IMS Connector Samples feature. Note: The IVP is a VisualAge for Jaa for Windows program and therefore does not use the Local Option connections. Instead, use TCP/IP for communication and to run the IVP. Running the VisualAge for Jaa IVP Update VisualAge for Jaa s class path to point to the locations of the required class libraries. Do the following: 1. Right-click the IMSICOIVPMainDialog class in package com.ibm.connector2.ims.ico.sample.ip (for J2C) or the IMSConnIVPMainDialog class in package com.ibm.connector.ims.sample.ip (for CCF), then select Properties. 56 IMS Connector for Jaa User s Guide and Reference

63 2. Ensure that the Class path tab is selected on the Properties window and click Compute now to compute the class path for the IVP. Click OK. To run the IVP, select either the IMSICOIVPMainDialog class in package com.ibm.connector2.ims.ico.sample.ip (for J2C) or the IMSConnIVPMainDialog class in package com.ibm.connector.ims.sample.ip (for CCF). From the Selected menu, click Run > Run main... The IMS Connector for Jaa IVP window appears. Because execution of the IVP causes the IMS /STA OTMA command to be sent to the target IMS machine, you must proide alues for the fields described below before clicking SUBMIT. Figure 4. The VisualAge for Jaa IVP GUI Host name The TCP/IP host name of the machine running IMS Connect. Port The TCP/IP port assigned to IMS Connect. Datastore The Datastore ID you specified when you installed IMS Connect. User ID The SAF user ID to be passed to OTMA. For example, the RACF user ID. User ID may be optional depending on how you specify IMS OTMA and IMS Connect security. Howeer, you can proide it, along with a password, if you want to erify your installation s security configuration. Password Password can be optional (see User ID). Group name Group name can be optional (see User ID). The objectie of the IVP is to receie a message from IMS in reply to the /STA OTMA command. One of two possible messages is returned, depending on the security configuration of your host enironment and whether the gien user ID is permitted to issue the /STA command. Either message indicates successful execution of the IVP: DFS1292E SECURITY VIOLATION DFS058I 17:33:32 START COMMAND COMPLETED Chapter 2. Preparing to use IMS Connector for Jaa 57

64 This test does not erify that a particular IMS transaction can run, only that the path to IMS is aailable. If an exception is returned in response to the command, check the console window. The exception and stack trace proide diagnostic information. The following are common causes for IVP failure: Host name is misspelled or is not sufficiently qualified IMS Connect is not actie Incorrect port Port is not actie TCP/IP failure. Always ensure a successful ping prior to running the IVP Datastore name is incorrect or is misspelled. Datastore name must be in uppercase characters. Datastore is not actie. Wrong leel of IMS Connect running on the host. See Prerequisites for using IMS Connector for Jaa for the required leel of IMS Connect. Important: If you do not compute the class path for class IMSConnIVPMainDialog as described aboe, the IMS Connector for Jaa IVP throws an exception, indicating that one of the classes cannot be found. In some cases, the IVP might not respond. Preparing your WebSphere Studio enironment You can use WebSphere Studio to deelop serlets that access IMS transactions. These serlets are generated from Enterprise Access Builder (EAB) commands that use IMS Connector for Jaa. This section describes what you need to do to prepare for using these commands in the WebSphere Studio enironment. Important: WebSphere Studio is required only if you are creating the CCF sample Building a Jaa serlet to run an IMS transaction. WebSphere Studio is not required by IMS Connector for Jaa. You can now create serlets using the VisualAge for Jaa Create Serlet SmartGuide instead of WebSphere Studio. Installing Class Libraries If you hae both VisualAge for Jaa and WebSphere Studio installed on the same machine, you must modify your WebSphere Studio s CLASSPATH enironment ariable to point to the class libraries being installed by VisualAge for Jaa as follows: 1. In WebSphere Studio, select Tools > Preferences from the menu bar. 2. Click on the Jaa tab and then enter the following in the Classpath field: {StudioClasspath};<VAJ_Install_dir>\eab\runtime30; If you do not hae both VisualAge for Jaa and WebSphere Studio installed on the same machine, then you must install the following class libraries on the WebSphere Studio workstation to generate a serlet from an EAB command that uses IMS Connector for Jaa: IBM Common Connector Framework IBM Enterprise Access Builder Library IBM Jaa Record Library Connector IMS 58 IMS Connector for Jaa User s Guide and Reference

65 The following steps show you where to obtain the class libraries (JAR files) and how to set up the CLASSPATH enironment ariable to point to the JAR files. WebSphere Studio generates the serlet using the EAB command and these class libraries. In this section, the parameters represent the following: <VAJ_install_dir> The VisualAge for Jaa installation directory. For example, d:\program Files\IBM\VisualAge for Jaa. <IBM_Connectors_install_dir> The IBM Connectors installation directory. For example, d:\ibm Connectors. <target_dir> The path on your WebSphere Studio workstation where the JAR files are placed. For example, c:\imsconn. 1. Copy the following class libraries (JAR files) from their directories (indicated below) to your WebSphere Studio target directory (<target_dir>): IBM Common Connector Framework File ccf.jar is located in the <IBM_Connectors_install_dir>\classes directory. IBM Enterprise Access Builder Library File eablib.jar is located in the <VAJ_Install_dir>\eab\runtime30 directory. IBM Jaa Record Library File recjaa.jar is located in the <VAJ_Install_dir>\eab\runtime30 directory. IMS Connector for Jaa File imsconn.jar is located in the <IBM_Connectors_install_dir>\classes directory. 2. Modify (or append to) your WebSphere Studio s CLASSPATH enironment ariable for WebSphere Studio to point to the aboe JAR files. Modify the CLASSPATH enironment ariable in WebSphere Studio by clicking Tools > Preference. Click on the Jaa tab and enter the following in the Classpath field {StudioClasspath};<target_dir>\ccf.jar;<target_dir>\eablib.jar; <target_dir>\recjaa.jar;<target_dir>\imsconn.jar; Preparing your WebSphere Application Serer enironment for Windows You can use WebSphere Application Serer to run serlets that use IMS Connector for Jaa to access IMS transactions. This section describes what you need to do to prepare for using these serlets in the WebSphere Application Serer enironment. Important: This section assumes that you hae already installed the J2C connection architecture support for your WebSphere Application Serer. For instructions on how to install this support, see the document Installing the Connector Architecture for WebSphere Application Serer (J2C) in the WebSphere Application Serer Adanced Edition Information Center. Note: These instructions apply to IBM WebSphere Application Serer 4.0. Information for earlier ersions of IBM WebSphere Application Serer can be found in earlier ersions of IMS Connector for Jaa documentation. See the IMS Connector for Jaa Web page in the IMS Web site at for earlier ersions of the documentation. Chapter 2. Preparing to use IMS Connector for Jaa 59

66 The runtime component of IMS Connector for Jaa with J2C support is proided as a component of IMS Connect Version 1 Release 2. This runtime component is also referred to as the IBM WebSphere Adapter for IMS. To prepare to run Jaa applications (for example, serlets or EJBs) that use the J2C implementation of IMS Connector for Jaa in WebSphere Application Serer, you should complete the following steps: 1. Installing the runtime component IMS Connector for Jaa with J2C support on the target WebSphere Application Serer 2. Deploying IMS Connector for Jaa with J2C support into WebSphere Application Serer 3. Preparing to run the Installation Verification Program (IVP) 4. Creating and Configuring a Connection Factory for use by the IVP Serlet 5. Deploying the IVP Serlet in WebSphere Application Serer 6. Running the IVP Serlet to access the target IMS Each of the aboe steps is described in detail below. Step 1: Installing the runtime component IMS Connector for Jaa with J2C support on the target WebSphere Application Serer The following executable files are proided with the IMS Connector for Jaa runtime component. Select and start the executable for the platform on which you are performing the installation, then follow the instructions in the installation wizard. For AIX - select imsicosetup_aix For Sun Solaris - select imsicosetup_solaris For Windows - select imsicosetup_win.exe Running one of these executable files will place the files listed below into a target directory for later deployment in WebSphere Application Serer. Note: For AIX and Solaris you must hae root authority to perform the installation. Successful completion of the installation places the following files in directory IMSICO/J2C of a target directory (<target_dir>) of your choice or the default target directory. The default target directory is c:\program Files for Windows platforms and /opt for the AIX and Solaris platforms. <target_dir>/imsico/j2c/readme Information about the files in directory J2C. <target_dir>/imsico/j2c/imsico.rar Resource Adapter Archie file for IMS Connector for Jaa (J2C). <target_dir>/imsico/j2c/en_us/howto.html Information about IMS Connector for Jaa. <target_dir>/imsico/j2c/en_us/imsicoivp.html Information about the IVP. <target_dir>/imsico/j2c/ivp/imsicoivp.ear The Enterprise Application Archie file for IMS Connector for Jaa s Installation Verification Program (IVP). Step 2: Deploying IMS Connector for Jaa with J2C support into WebSphere Application Serer 60 IMS Connector for Jaa User s Guide and Reference

67 A Resource Adapter Archie (RAR) file is used to deploy a resource adapter in an application serer. In this case, the resource adapter is IMS Connector for Jaa with J2C support. This section describes how to deploy the IMS Connector for Jaa RAR file (imsico.rar) into the operational enironment of WebSphere Application Serer. This section assumes the RAR file has been installed in <target_dir>\imsico\j2c. 1. Start the WebSphere Adanced Administratie Console: a. From your Windows desktop, click Start > Programs > IBM WebSphere > Application Serer 4.0 > Start Admin Serer. You must start this serer before you start the Administratie Console. b. Click Start > Programs > IBM WebSphere > Application Serer 4.0 > Administrator s Console. 2. In the WebSphere Adanced Administratie Console, expand WebSphere Administratie Domain by clicking the plus sign (+) next to WebSphere Administratie Domain. 3. Click the plus sign next to Resources. 4. In the expanded directory, right-click the J2C Resources Adapters folder and click New from the menu options to start the J2C Resource Adapter Properties dialog box. 5. In this dialog box, ensure that the General tab is selected. In the Name field, enter <Your Resource Adapter>, where <Your Resource Adapter> is the name you want for your Resource Adapter (for example, IMS J2C Connector ). 6. Click the small square to the right of the Archie file name field to start the Install Drier dialog box. In this dialog, highlight the node on which you want to install the resource adapter, then click the Browse button and locate IMS Connector for Jaa s RAR file (<target_dir>\imsico\j2c\imsico.rar). Click the Open button. 7. Click the Install button. 8. The archie file name should now contain the directory and name of the RAR file. 9. Click OK. When you hae successfully deployed the IMS Connector for Jaa resource adapter you will see a confirmation message. Related Reading: Instructions for deploying RAR files in WebSphere Application Serer can also be found in the WebSphere Application Serer Information Center. From the WebSphere Adanced Administratie Console, select Help > Task Help or Help > Information Center. Step 3: Prepare to run the Installation Verification Program (IVP) See Preparing to run the IMS Connector for Jaa IVP in Preparing to use IMS Connector for Jaa for information on IVP prerequisites. Restriction: Because you are using a workstation platform to run this IVP, you must use TCP/IP to communicate with IMS Connect. Step 4: Creating and Configuring a Connection Factory for use by the IVP Serlet This section describes how to create a Connection Factory, for use by the IVP to create a connection between the IVP and your IMS Connect and IMS. You must deploy the IMS Connector for Jaa RAR file before you begin this task. Chapter 2. Preparing to use IMS Connector for Jaa 61

68 1. Create a Connection Factory: a. In the WebSphere Adanced Administratie Console, expand the WebSphere Administratie Domain directory by clicking the plus sign (+) next to it. b. By clicking the plus signs, expand the following folders in this order: Resources, J2C Resource Adapters, and <Your Resource Adapter>, where <Your Resource Adapter> is the name you chose when you deployed the IMS Connector for Jaa RAR file. For example, IMS J2C Connector. c. Right-click the J2C Connection Factories folder under IMS J2C Connector and click New from the menu options. This will start the J2C Connection Factory Properties dialog box. d. In this dialog box, ensure that the General tab is selected. In the Name field, enter a name for the connection between the IVP application and your IMS backend system. For example, for the IVP enter MyIMS. e. For the IVP, leae the JNDI binding path field blank. This will result in a default of eis/myims being used for the JNDI binding path. Enter an optional description for the Connection Factory. f. Click OK. When you hae successfully created the connection factory, you should see a confirmation dialog box. 2. Configure your Connection Factory: a. In the WebSphere Adanced Administratie Console, locate your connection factory in the upper-right section of the Console window ( MyIMS in the example aboe). Click the name of your connection factory once to work with it. b. Click the Connections tab. c. Specify alues for each of the following connection properties. To edit a property, scroll down to find the Value field. Use this field to enter the alue you want for each property. When you are done, click anywhere outside the field to set the alue. DataStoreName The name of the target IMS datastore. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member when IMS Connect is installed. It also seres as the XCF member name for IMS during internal XCF communications between IMS Connect and OTMA. You must replace the default alue mydstrnm with a alue that is alid for your IMS enironment. GroupName The default IMS group name that will be used for all connections created by this Connection Factory. Whether or not you proide a alue for GroupName will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, and your security enironment requires that you use GroupName, you must replace the default alue of 8 blanks with a alid alue. HostName The IP address or host name of the machine running the target IMS Connect. You must replace the alue myhostnm with a alue that is alid for your IMS enironment. 62 IMS Connector for Jaa User s Guide and Reference

69 Password The default password that will be used for all connections created by this Connection Factory. Whether or not you proide a alue for Password will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, you must replace the default alue of 8 blanks with a alid alue. PortNumber The number of a port used by the target IMS Connect for TCP/IP connections (sockets). Multiple sockets can be open on a single TCP/IP port. See Configuring IMS Connect in the IMS Connect Guide and Reference for additional information about PortNumber. You must replace the alue 0 with a alue that is alid for your IMS enironment. TraceLeel Leel of information to be traced. See the Jaadoc for the IMSTraceLeelProperties class or the IMS Connector for Jaa User s Guide for a description of trace leels. UserName The default security authorization facility (SAF) user name that will be used for all connections created by this Connection Factory. For example, for some installations this would be the RACF user ID. Whether or not you proide a alue for UserName will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, you must replace the default alue of 8 blanks with a alid alue. d. Click the Apply button to complete your command. Step 5: Deploying the IVP Serlet in WebSphere Application Serer The IVP is packaged as an Enterprise Application Archie (EAR) file. The EAR file contains a WebSphere Adapter Archie (WAR) file containing a serlet Web component consisting of the following parts: IMSICOIVPSerlet.class IMSICOIVP.jar IMSICOIVPSerletError.jsp IMSICOIVPSerletResults.jsp IMSICOIVPSerletInput.html To deploy the IVP in your WebSphere Application Serer enironment, do the following: 1. In the WebSphere Adanced Administratie Console, deploy the IVP using the Install Enterprise Application Wizard. Click Console > Wizards > Install Enterprise Application. Complete the following steps in this wizard: a. Select the Install Application (*.ear) radio button. Click Browse and select the EAR file for the IVP, imsicoip.ear. Note: These instructions assume the file imsicoip.ear is on the node selected in the list associated with the Browse for the file on node field. The imsicoip.ear file is placed in a directory of your choice as part of the installation process of IMS Connector for Jaa (for example, < targetdir >\IMSICO\J2C\ip). Chapter 2. Preparing to use IMS Connector for Jaa 63

70 b. Gie the application a name in the Application Name field. For this example use the name IMSICOIVPApp. c. Click Next until you see the Mapping Resource References to Resources page. d. In the Mapping Resource References to Resources page, select the resource reference, MyIMS(IMSICOIVPWar), and click Select Resource. The Select Resource dialog box appears with a list of resources defined. Select the resource MyIMS and click OK. Note: If no resources are listed in the Select Resource dialog, you hae not deployed the RAR file and/or created a connection factory. See IMS Connector for Jaa s HowTo.html for instructions for deploying IMS Connector for Jaa s RAR file. See Step 4: Creating and Configuring the Connection Factory (page 61) in this document for instructions for creating a connection factory. e. Click Next until you see the Selecting the Virtual Hosts for WAR Modules page. f. In the Selecting the Virtual Hosts for WAR Modules page, select the web module, IMSICOIVPWar, and click Select Virtual Host. In the dialog box that appears, select the irtual host, default_host, and click OK. (This step chooses which serer will run the serlet.) Then click Next. g. In the Selecting the Application Serer page, select the module, IMSICOIVPWar, and click the Select Serer... button. In the dialog box that opens, select the Default Serer and click OK. Then click Next. h. Verify the information displayed, then click Finish. When the command has completed successfully, you will see a confirmation dialog box. Click OK to close the box. 2. Start the Default Serer: a. Click the plus (+) sign to expand the iew of the WebSphere Administratie Domain. b. Click the plus (+) sign beside Nodes to iew the nodes in the WebSphere Administratie Domain. c. Click the plus (+) sign to expand the iew of the node that has the TCP/IP host name of your Web serer machine. d. Click the plus (+) sign beside Application Serers to iew the node s application serers. e. Right click on Default Serer under the host node in the preious step, and select Start. A dialog box displaying Command DefaultSerer.start completed successfully will appear when the serer has been started. Step 6: Running the IVP Serlet to access the target IMS From a Web browser, enter the following Web address: where serername and port is the name and port number of your Web serer machine, and imsicoip is the context root of the WAR file. Clicking Submit on the input form causes the IMS /STA OTMA command to be sent to IMS using the properties you specified in the Connection Factory named MyIMS. The objectie of the IVP is to receie a message from IMS in reply to the /STA OTMA command. One of two possible messages is returned, depending on the leel of security checking in place for your installation and whether the 64 IMS Connector for Jaa User s Guide and Reference

71 UserName/Password/GroupName is permitted to issue the /STA command. Either message indicates successful execution of the IVP, since it is IMS that issues the DFS message. DFS1292E SECURITY VIOLATION DFS058I 17:33:32 START COMMAND COMPLETED The IVP does not run an IMS application program and therefore does not erify that IMS transactions can run successfully. It only erifies that the path to IMS is aailable. Troubleshooting IVP Failures If the IVP does not run successfully, you should first check for information in the WebSphere Application Serer logs in folder \WebSphere\AppSerer\logs. This file lists exceptions and stack traces that are useful for diagnosing the failure. In addition, the following are possible causes for IVP failure: The IBM WS Admin Serer is not started. The Application Serer used for the IVP (for example, default_serer) is not started. The IVP s Enterprise Application, IMSICOIVPApp, is not started. To determine the status of the Enterprise Application, right-click on the Enterprise Application IMSICOIVPApp and select Show Status. If the status is not Running in the Module Status window, close the window then right-click on the Enterprise Application IMSICOIVPApp and select Start. Inalid data was specified when configuring the MyIMS Configuration Factory. For example: HostName was misspelled or was not sufficiently qualified (for TCP/IP communication). An incorrect PortNumber was specified for the target IMS Connect. Datastore name is inalid for the target IMS or is misspelled. Datastore name must be in uppercase characters. IMS is not running. IMS Connect is not running. The IMS Connect port is not actie. Use the IMS Connect command VIEWHWS to determine if the port is actie. Use the IMS Connect command OPENPORT to actiate an IMS Connect port. The target IMS datastore is not actie. Use the IMS Connect command VIEWHWS to determine if the datastore is actie. Use the IMS Connect command OPENDS to actiate a IMS datastore. TCP/IP failure. Always ensure a successful ping prior to running the IVP. The wrong leel of IMS Connect is running on the host. See Preparing to run the IVP in Preparing your VisualAge for Jaa Enironment for the required leel of IMS Connect. Chapter 2. Preparing to use IMS Connector for Jaa 65

72 Preparing your WebSphere Application Serer enironment for z/os and OS/390 The information in this section applies to the J2C implementation of IMS Connector for Jaa only and to IBM WebSphere Application Serer 4.0. For information on using the IVP in the CCF implementation or on earlier ersions of IBM WebSphere Application Serer, see preious editions of the IMS Connector for Jaa User s Guide and Reference, aailable on the IMS Connector for Jaa Web page in the IMS Web site at Related Reading: More information about Resource Recoer Serices (RRS) transaction support is aailable in the WebSphere Application Serer for OS/390 and z/os documentation. The document titled WebSphere Application Serer V4.0.1 for z/os and OS/390: WebSphere for z/os-supported Connectors is aailable with APAR PQ55873 for WebSphere Application Serer V4.0.1 for z/os and OS/390. To download the document, go to the Web site at then click Product information. At a later time, the information in this document will be integrated into the WebSphere for z/os formal publications. To access the latest publications, go to the product library page at To prepare to run Jaa applications (for example, serlets or EJBs) that use the J2C implementation of IMS Connector for Jaa in WebSphere Application Serer for z/os and OS/390, you should complete the following steps: 1. Installing the runtime component IMS Connector for Jaa with J2C support on the target z/os and OS/390 system 2. Configuring IMS Connector for Jaa with J2C support on the target z/os and OS/390 system 3. Preparing to run the Installation Verification Program (IVP) 4. Deploying and Configuring IMS Connector for Jaa as a J2EE serer resource in WebSphere Application Serer for z/os and OS/ Deploying the IMS Connector for Jaa IVP 6. Starting the serer to run the IVP 7. Running the IVP to access the target IMS Each of the aboe steps is described in detail below. Important: Before you can deploy and run the IVP serlet, the following components and configurations are required: WebSphere Application Serer V4.0.1 or higher for z/os and OS/390 that has been tested by the supplied J2EE Web Application Installation Verification Programs (IVPs) The IMS Connector for Jaa sample J2EE applications require a definition of a J2EE application serer and the initial modifications to the web container configuration files of this serer. They also require additional modifications to the enironment ariables of the HTTP serer. For details, see WebSphere Application Serer V4.0.1 for z/os and OS/390 Installation and Customization, GA This manual proides an example of defining a J2EE application serer (BBOASR2) and creating an instance of this serer (BBOASR2A) for running the WebSphere Application Serer IVPs. The initial modifications to the web 66 IMS Connector for Jaa User s Guide and Reference

73 container configuration files and HTTP serer enironment ariables can also be found within the steps for setting up the serer s J2EE web application erification programs. Additionally, be sure that you hae met the prerequisites for WebSphere Application Serer described in Prerequisites for running IMS Connector for Jaa. WebSphere for z/os and OS/390 Administration application The Administration application is packaged in a self-extracting executable file supplied by the WebSphere Application Serer for z/os and OS/390. This executable file also proides the Operations application. Together these programs are often called the system management enhanced user interface (SMEUI). For details on installing the Administration and Operations applications, see WebSphere Application Serer V4.0.1 for z/os and OS/390 Installation and Customization, GA The Administration application manages administration tasks for the WebSphere Application Serer from the terminal side and defines an IMS Connection Factory, creates an instance of this resource, and installs J2EE applications bundled within enterprise archie (EAR) files. Step 1: Installing the runtime component IMS Connector for Jaa with J2C support on the target z/os and OS/390 system Using SMP, install the required APARs (APAR PQ57191 and corequisite APAR PQ57192) for the IMS Connect 1.2 product on the z/os or OS/390 system image where you will start the WebSphere Application Serer for z/os and OS/390 serer for running EJBs and serlets that use the IMS Connector for Jaa. Successful completion of the installation places the following files in directory imsico of a target directory (<target_dir>) of your choice or the default target directory. The default target installation directory is /usr/lpp on the z/os and OS/390 system. <target_dir>/imsico/readme Information about the files installed for IMS Connector for Jaa <target_dir>/imsico/j2c/readme Information about the files in the J2C directory <target_dir>/imsico/j2c/imsico.rar Resource Adapter Archie file for IMS Connector for Jaa (J2C) <target_dir>/imsico/j2c/howto.html Information about IMS Connector for Jaa <target_dir>/imsico/j2c/imsicoivpzos.html Information about the IVP <target_dir>/imsico/j2c/imsicoivpzos.ear The Enterprise Application Archie file for IMS Connector for Jaa s Installation Verification Program (IVP) <target_dir>/imsico/ccf/readme Information about the files in the CCF directory <target_dir>/imsico/ccf/imsiconn.jar IMS Connector for Jaa class libraries for CCF <target_dir>/imsico/ccf/libimsconn.so IMS Connector for Jaa Local Option natie library for CCF Chapter 2. Preparing to use IMS Connector for Jaa 67

74 Step 2: Configuring IMS Connector for Jaa with J2C support on the target z/os and OS/390 system 1. Create an HFS work directory that allows read, write, and execute authority. Use a meaningful name for the directory (for example: /usr/lpp/connectors). 2. In the install directory for IMS Connector for Jaa, look for the file imsico.rar and copy it into the work directory you created in the preious step. Tip: If your installation used the default directory for installing IMS Connector for Jaa, you will find the imsico.rar in the directory /usr/lpp/imsico/j2c. 3. Under the work directory, expand the imsico.rar file by entering the following command: jar -xf imsico.rar Result: The expansion extracts the following files into the directory: imsico.jar libimsico.so Note: Additional files are also extracted, but they are not used for the deployment of the connector. 4. Use the following command to gie execute permission to the imsico.jar and libimsico.so files under the work directory: chmod ugo+x imsico.jar chmod ugo+x libimsico.so Step 3: Preparing to run the Installation Verification Program (IVP) See Preparing to run the IMS Connector for Jaa IVP in Preparing to use IMS Connector for Jaa for information on IVP prerequisites. Step 4: Deploying and Configuring IMS Connector for Jaa as a J2EE serer resource in WebSphere Application Serer for z/os and OS/390 This section describes how to: Deploy IMS Connector for Jaa Create and configure a Connection Factory for IMS Connector for Jaa as a J2EE serer resource to your target WebSphere Application Serer for z/os and OS/390 The Connection Factory will be used by the IVP to create a connection between the IVP, your IMS Connect, and IMS. 1. Verify that the bootstrap deamon is started. a. On the host machine display the actie jobs, by entering the command: D A,L b. If the BBODMN is not an actie job displayed in the list, start the bootstrap serer by issuing the command: S BBODMN.DAEMON01 c. Verify that these messages are displayed: BBOU0016I INITIALIZATION COMPLETE FOR DAEMON DAEMON01. BBOU0020I INITIALIZATION COMPLETE FOR CB SERIES CONTROL REGION SYSMGT01. BBOU0020I INITIALIZATION COMPLETE FOR CB SERIES CONTROL REGION NAMING01. BBOU0020I INITIALIZATION COMPLETE FOR CB SERIES CONTROL REGION INTFRP Start the Operations application and connect to the serers. 68 IMS Connector for Jaa User s Guide and Reference

75 a. Open the Operations application. For example: click Start > Programs > IBM WebSphere for z/os > Operations and wait for the Login window to appear. b. Fill in the dialog with the Bootstrap serer IP name (for example, the DAEMON_IP enironment ariable or the name specified for the bootstrap serer s IP address in the host file on the workstation), Port (default 900), the Userid (default CBADMIN), and the Password (default CBADMIN). c. Click OK to login and establish connections to the serers. Wait for the WebSphere for Application Serer for z/os and OS/390 Operations window to appear and the icons for the serers aailable on the host machine. 3. Ensure that the web serer is not actie: a. On the host machine, display all actie jobs by issuing the following command: D A, L b. If the web serer (for example, IMWEBSRV) is an actie job, issue the following command to stop it: STOP IMWEBSRV 4. Ensure that the J2EE serer is not actie: a. In the WebSphere Application Serer for z/os and OS/390 window, highlight the instance of the J2EE serer (for example, BBOASR2A). b. Click Selected > Stop. Note: You also can stop the serer manually by issuing the following command: STOP BBOASR2.BBOASR2A 5. Start the Administration application and connect to the serers. a. Open the Administration application. For example: click Start > Programs > IBM WebSphere for z/os > Administration and wait for the Login window to appear. b. Fill in the dialog with the Bootstrap serer IP name (for example, the DAEMON_IP enironment ariable or the name specified for the bootstrap serer s IP address in the host file on the workstation), Port (default 900), the Userid (default CBADMIN), and the Password (default CBADMIN). c. Click OK to login and establish connections to the serers. Wait for the WebSphere for Application Serer for z/os and OS/390 Administration window to appear. 6. Add a new conersation. a. Select the Conersations folder. b. Under the Selected drop down menu choose Add and wait for the conersation name and description fields to appear. c. In the Conersation Name text box enter the name for the new conersation (for example, IMSICO). d. Click Selected > Sae. e. Wait for the completion message (for example, BBON0515I Conersation IMSICO was added.) to appear in the status text box aboe the status bar in the Administration window. 7. Ensure that connection management is configured into the sysplex by completing the following steps: a. Expand the Conersations folder (by clicking the plus sign next to it). b. Expand the new conersation (for example, IMSICO). Chapter 2. Preparing to use IMS Connector for Jaa 69

76 c. Expand the Sysplexes folder and highlight the sysplex name (for example, PLEX1). d. Click Selected > Modify to update the sysplex definition. e. Under the Configuration Extensions section of the sysplex definition, check the box labeled Connection Management. f. Click Selected > Sae to sae your changes. 8. Set up the IMS Connector for Jaa classes to be used by WebSphere Application Serer by setting up the following CLASSPATH and LIBPATH enironment ariable alues. Do the following: a. Expand the sysplex name in the conersation (for example, PLEX1). b. Expand the J2EESerers folder and highlight the J2EE serer name (for example, BBOASR2). c. Click Selected > Modify to update the J2EE serer definition. d. Under the Enironment ariable list section of the J2EE serer definition, double click any enironment ariable (for example, the CLASSPATH ariable) to open the Enironment Editing Dialog window and modify the following enironment ariables: For the CLASSPATH enironment ariable, add the full directory name for the file imsico.jar as noted in Step 2. Configuring IMS Connector for Jaa with J2C support on the target z/os and OS/390 system (page 68). To do so, complete the following steps: 1) Under the Name drop down box in the Enironment Editing Dialog window, select the CLASSPATH ariable. 2) Click the Modify button. 3) Append the full directory name for the file imsico.jar to the current classpath in the Variable Value textbox (for example, <current_classpath>:/usr/lpp/connectors/imsico.jar). For the LIBPATH enironment ariable, add the full name of the work directory that contains the libimsico.so file as noted in Step 2. Configuring IMS Connector for Jaa with J2C support on the target z/os and OS/390 system (page 68). To do so, complete the following steps: 1) Under the Name drop down box in the Enironment Editing Dialog window, select the LIBPATH ariable. 2) Click the Modify button. 3) Append the work directory that contains the libimsico.so file to the current libpath (for example, <current_libpath>:/usr/lpp/connectors). e. Click OK to close the Enironment Editing Dialog window (to complete the enironment ariables changes). f. Click Selected > Sae. 9. Add an IMS Connector for Jaa connection factory as a new J2EE Serer Resource. a. Select the J2EE Resources folder under your sysplex name (for example, PLEX1). b. Click Selected > Add and wait for the J2EE resource description fields to appear in the right panel. c. In the J2EE Resource Name text box, enter the name that will represent an IMS connection factory resource for this example (for example, IMSRes). d. Set the J2EE Resource type to IMSConnectionFactory. 70 IMS Connector for Jaa User s Guide and Reference

77 e. Click Selected > Sae. Wait for the completion message (for example, BBON0515I J2EE Resources IMSRes was added.) to appear in the status text box aboe the status bar in the Administration window. f. Expand the J2EE Resources folder. g. Expand the resource name that was added (for example, IMSRes). h. Select the J2EE Resource Instances folder. i. Click Selected > Add and wait for the J2EE resource instance description fields to appear in the right panel. j. In the IMSConnectionFactory text box, enter the name of an instance of an IMS connection factory resource (for example, IMSRes_Instance). k. Verify that the appropriate System name is displayed in its drop down box (for example, SY1). l. Fill in the appropriate alue for the remaining fields. Datastore name The name of the target IMS datastore. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member when IMS Connect is installed. It also seres as the XCF member name for IMS during internal XCF communications between IMS Connect and OTMA. You must replace the default alue mydstrnm with a alue that is alid for your IMS enironment. Datastore name is a1to8alphanumeric character name of the target IMS datastore defined in IMS Connect. Note: This information can be acquired by executing the nnviewhws command, where nn is the response number to the IMS Connect reply message on the host. Group name The default IMS group name that will be used for all connections created by this Connection Factory. Whether or not you proide a alue for GroupName will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, and your security enironment requires that you use GroupName, you must replace the default alue of 8 blanks with a alid alue. Group name is a1to8alphanumeric character alue to be used as the default group name for the user if neither the container nor the application proides a group name to IMS Connector for Jaa. Host name This field is the TCP/IP host name of the target IMS Connect. This property applies only when using TCP/IP communication between IMS Connector for Jaa and IMS Connect to run the IVP. Note: This property is ignored if the IMS Connect name property is specified or if you are using Local Option. IMS Connect name The IMS Connect name must match the HWS ID of the target IMS Connect. This property applies only when using Local Option communication between IMS Connector for Jaa and IMS Connect to run the IVP. Fill out this field with the appropriate information. A 1 to 8 alphanumeric character name of the target IMS Connect. Note: If you are using TCP/IP, you must leae this field blank. Chapter 2. Preparing to use IMS Connector for Jaa 71

78 LogWriter Recording You can either enable or disable LogWriter recording for use by IMS Connector for Jaa in WebSphere Application Serer for z/os and OS/390. See Using the trace and error logging facility for more information. Password The default password that will be used for all connections created by this Connection Factory. Whether or not you proide a alue for Password will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, you must replace the default alue of 8 blanks with a alid alue. Password is a1to8alphanumeric character alue to be used as the default password for the user if neither the container nor the application proides a password to IMS Connector for Jaa. Port number This field is the TCP/IP port number of the target IMS Connect. This property applies only when using TCP/IP communication between IMS Connector for Jaa and IMS Connect to run the IVP. User name The default security authorization facility (SAF) user name that will be used for all connections created by this Connection Factory. For example, for some installations this would be the RACF user ID. Whether or not you proide a alue for UserName will depend on the leel of security checking in place for your installation. If, additionally, you wish to use the IVP to erify your installation s security enironment, you must replace the default alue of 8 blanks with a alid alue. User name is a1to8alphanumeric character alue to be used as the default name for the user if neither the container nor the application proides a user name to IMS Connect for Jaa. Trace leel Leel of information to be traced. See the Jaadoc for the IMSTraceLeelProperties class or the IMS Connector for Jaa User s Guide and Reference for a description of trace leels. m. Click Selected > Sae. Wait for the completion message (for example, BBON0515I J2EE Resource instance IMSRes_Instance was added.) to appear in the status text box aboe the status bar in the Administration window. Step 5: Deploying the IMS Connector for Jaa IVP The IVP is packaged as an Enterprise Archie (EAR) file. An EAR file represents a J2EE application that can be deployed in a WebSphere application serer. This file contains one Web Module and its WebSphere configuration files. This Web Module consists of one Web Archie (WAR) file that packages its deployment configuration files and the following basic components: IMSICOIVPSerlet.class IMSICOIVPSerletError.jsp IMSICOIVPSerletResults.jsp IMSICOIVPSerletInput.html 72 IMS Connector for Jaa User s Guide and Reference

79 Before you begin, you must hae the IVP EAR file (IMSICOIVPzOS.ear) in a directory of a workstation system that can be accessed by your WebSphere for z/os Administration Application. This IVP EAR has been installed with the IMS Connector for Jaa runtime component on your host z/os or OS/390 serer. For more information on this, see Step 1: Installing the runtime component IMS Connector for Jaa with J2C support on the target z/os and OS/390 system (page 67). You can download this IVP ear file your workstation machine. Be sure to download the IVP EAR file in binary format. In the instructions below, the IVP EAR file is assumed to be the c:\temp directory of your workstation. To deploy the IVP in your WebSphere Application Serer for z/os and OS/390 enironment, complete the following steps in the same conersation in the WebSphere for z/os Administration Application that you started in Step 4: Deploying and Configuring IMS Connector for Jaa as a J2EE serer resource in WebSphere Application Serer for z/os and OS/390 (page 68). 1. Install the enterprise application. a. Select the J2EE serer on which this application will be installed (for example, BBOASR2). Select this serer by expanding the following folders in order: Conersations folder, the conersation (for example, IMSICO), the Sysplexes folder, the sysplex in which your sample J2EE serer has been installed (for example, PLEX1), and the J2EESerers folder. b. Click Selected > Install J2EE application... and wait for its reference window to appear (for example, the Install J2EE application on serer: BBOASR2 window). c. Click the Browse EAR File... button and wait for the Open window to appear. Locate and select your EAR file (for example, select the IMSICOIVPzOS.ear file that you downloaded in the C:\Temp directory). Click Open. d. Verify that the destination and EAR file name appears in the EAR Filename text field. Click OK and wait for the Reference and Resource Resolution window to appear. e. In the Reference and Resource Resolution dialog box: 1) On the left side of the dialog, under the IMSICOIVPApp folder, expand the imsicoip_webapp.jar folder and select the J2EE application bean (for example, imsicoip_webapp) 2) On the right side of the dialog, click the EJB tab and click Set Default JNDI Path & Name. 3) Click the J2EE Resource tab, click the empty box under J2EE Resource, then select the Connection Factory you just created for the Serer (for example, IMSRes). Click OK. 2. You hae now deployed IMS Connector for Jaa as J2EE resources. You hae also deployed the IMS Connector for Jaa IVP. You can complete and actiate the changes in the conersation to your WebSphere Application Serer for z/os and OS/390 with the following steps: a. Validate the new conersation you just created in the preious step by selecting the conersation name (for example, IMSICO) to highlight it and clicking Build > Validate. b. Commit the new conersation by selecting the conersation name to highlight it and clicking Build > Commit. Chapter 2. Preparing to use IMS Connector for Jaa 73

80 c. Ensure that all preparation tasks for the new conersation are completed. Then select the conersation name to highlight it and click Build > Complete > All Tasks to indicate completion. d. Actiate the new conersation by selecting the conersation name to highlight it and clicking Build > Actiate. 3. Configure the HTTP serer for the context root of the IVP by modifying the following files: a. Modify the webcontainer.conf file with the following information: host.default_host.contextroots=/ b. Modify the httpd.conf file by adding the following information: Serice /imsicoip/* <was_dir>/websererplugin/bin/was400plugin.so:serice_exit where <was_dir> is the installation root directory of WebSphere Application Serer (for example, /usr/lpp/websphere). Step 6: Starting the serer to run the IVP The following steps show how to start the Web and WebSphere Application serers to run the IVP serlet from a browser. 1. Start the J2EE serer. a. In the WebSphere Application Serer for z/os and OS/390 Operations window, highlight the instance of the J2EE serer (for example, BBOASR2A). b. Click Selected > Start. c. Wait for a message indicating that the serer has been issued a start command (for example, BBON0600I Start issued for serer instance BBOASR2A.) to appear in the status text box aboe the status bar in the Administration window. d. Click View > Refresh. e. Wait for a green check mark to appear oer the icon of the instance of the J2EE serer indicating that the serer has become actie. (Note: The serer can be started manually by issuing the S BBOASR2.BBOASR2A command). 2. Start the Web serer. a. Issue the command to start the Web serer on the host machine. For example (if the default webserer setup is used) S IMWEBSRV b. Wait for a message indicating that the Web serer has completely started. For example there may be a messages similar to these IMW3534I PID: SERVER STARTING IMW3536I SA :8080 * * READY Step 7: Running the IVP to access the target IMS 1. From a Web browser, enter the following URL: where serername and port is the name and port number for your Web serer machine and imsicoip is the context root of the IVP Web module. 2. Click Submit on the input form. This action causes the IMS /STA OTMA command to be sent to IMS using the properties you specified in the Connection Factory named IMSRes. 74 IMS Connector for Jaa User s Guide and Reference

81 The objectie of the IVP is to receie a message from IMS in reply to the /STA OTMA command. One of two possible messages is returned, depending on the leel of security checking in place for your installation and whether the UserName/Password/GroupName is permitted to issue the /STA command. Either message indicates successful execution of the IVP, since it is IMS that issues the DFS message. DFS1292E SECURITY VIOLATION DFS058I 17:33:32 START COMMAND COMPLETED The IVP does not run an IMS application program, therefore it does not erify that IMS transactions can run successfully. It only erifies that the path to IMS is aailable. Troubleshooting IVP Failures If an error occurs, check for information in WebSphere Application Serer s logs in folder \WebSphere\AppSerer\logs. This file lists exceptions and stack traces that are useful for diagnosing the failure. In addition, the following are possible causes for IVP failure: Verify webcontainer.conf file that host.default_host.alias points to the correct IP address of the WebSphere Serer. Verify webcontainer.conf file includes the appropriate context root (for example, host.default_host.contextroots=/) Verify httpd.conf file has the Serice Directies set up for the IVP sample. (for example, Serice /imsicoip/* /usr/lpp/websphere/websererplugin/bin/was400plugin.so:serice_exit) The IBM Http Serer is not started. The WebSphere Application Serer used for the IVP (for example, default_serer) is not started. Inalid data was specified when configuring the IMS Connector for Jaa Configuration Factory as J2EE Resource instance. For example: Incorrect IMS Connect name (for Local Option communication). HostName was misspelled or was not sufficiently qualified (for TCP/IP communication). An incorrect PortNumber was specified for the target IMS Connect (for TCP/IP communication). Datastore name is inalid for the target IMS or is misspelled. Datastore name must be in uppercase characters. IMS is not running. IMS Connect is not running. The IMS Connect port is not actie. Use the IMS Connect command VIEWHWS to determine if the port is actie. Use the IMS Connect command OPENPORT to actiate an IMS Connect port. The target IMS datastore is not actie. Use the IMS Connect command VIEWHWS to determine if the datastore is actie. Use the IMS Connect command OPENDS to actiate a IMS datastore. TCP/IP failure. Always ensure a successful ping prior to running the IVP. Chapter 2. Preparing to use IMS Connector for Jaa 75

82 The wrong leel of IMS Connect is running on the host. See Prerequisites for running the IVP for the required leel of IMS Connect. 76 IMS Connector for Jaa User s Guide and Reference

83 Chapter 3. Building Jaa applications and serlets To access IMS from a Jaa application or serlet, IMS and IMS Connect must be installed and running on the host machine. This section describes how to build Building CCF Jaa applications and serlets and Building J2C Jaa applications and serlets on page 78 applications and serlets. Building CCF Jaa applications and serlets This section proides a high-leel oeriew of how to build a CCF Jaa application or serlet that accesses an IMS transaction. The following steps describe how to build an Enterprise Access Builder (EAB) command using the Command Editor of VisualAge for Jaa s Enterprise Access Builder. 1. Create an IMSConnectionSpec object to be used for information about the connection to IMS Connect on the host machine. Proide the following information to the IMSConnectionSpec object: For a TCP/IP connection: The TCP/IP host name of the machine running IMS Connect The port associated with IMS Connect For a local connection: LOCALHOST: ims_connect_name, where ims_connect_name is the IMS Connect ID (the ID parameter in the HWS statement of the IMS Connect configuration member The port property is not used For this step, IMS Connector for Jaa proides an IMSConnectionSpec Jaa bean, which can be accessed by the Enterprise Access Builder. 2. Create an IMSInteractionSpec object to be used for the interaction between the Jaa application or serlet and IMS. Proide the following information to the IMSInteractionSpec object: Type of interaction that the Jaa application or serlet is to hae with IMS (for example, MODE_SEND_RECEIVE and SYNC_LEVEL_NONE) Name of the target datastore. This is the datastore ID that is proided when configuring IMS Connect on the host machine. For this step, IMS Connector for Jaa proides an IMSInteractionSpec Jaa bean, which can be accessed by the Enterprise Access Builder. 3. Create an object to represent the input to the IMS transaction. Currently, VisualAge for Jaa s Enterprise Access Builder enables you to create a COBOL Record Type, from which an input Jaa record bean is created. This support uses a COBOL 01 commarea (I/O PCB input/output area descriptor) to define the structure of the input bean. 4. Create an object to represent the output from the IMS transaction. Currently, VisualAge for Jaa s Enterprise Access Builder enables you to create a COBOL Record Type, from which an output Jaa record bean is created. This support uses a COBOL 01 commarea to define the structure of the output bean. 5. Combine the Jaa beans created in steps 1-4 into an Enterprise Access Builder (EAB) command using the Command Editor. Copyright IBM Corp. 1998,

84 After you hae an EAB command that corresponds to an IMS transaction, you can create a Jaa application in VisualAge for Jaa that runs the transaction by inoking the execute() method of the EAB command. The execute() method performs the following steps: 1. Creates a Communication object using the createcommunication method of the IMSConnectionSpec object. 2. Connects to the IMS Connect host component by inoking the Communication object s connect() method. 3. Executes the request specified in the IMSInteractionSpec object by inoking the execute() method of the Communication object. In general, once you hae an EAB command that represents an IMS transaction, you can run the IMS transaction by performing the following steps: 1. Proide the user ID, password, group name, and a ConnectionManager object to a runtime context object. 2. Proide the input data for the IMS transaction to the EAB command by inoking the appropriate set methods of the EAB command. 3. Inoke the execute() method of the EAB command to run the IMS transaction. 4. Display the output of the IMS transaction by using the appropriate get methods of the EAB command to retriee the output data. If you want to build a serlet to run the IMS transaction, do the following: 1. Use the serlet generation wizard in the IBM WebSphere Studio to generate a serlet and associated input and output HTML and JSP files from the EAB command. The HTML and JSP files are used to proide the input to the IMS transaction and to display the output from the IMS transaction. 2. Run the serlet using the IBM WebSphere Application Serer. Examples of these steps are presented in subsequent sections of this documentation. Related Reading: For installation and configuration information for IMS Connect, see the IMS Connect documentation at the IMS Web site: Building J2C Jaa applications and serlets The IMS Connector for Jaa implementation of Sun s Jaa 2 Platform, Enterprise Edition (J2EE) introduces the use of Enterprise JaaBeans (EJB) to build your applications. EJB defines how serer-side components are written and proides a standard architectural contract between the components and the application serers and containers that manage them. VisualAge for Jaa Version 4.0 offers the EJB Deelopment Enironment feature to help you create session EJBs. VisualAge for Jaa Version 4.0 also proides tooling to help you create a serlet to access your IMS transactions. The Create Serlet SmartGuide is a wizard that steps you through the process of creating a serlet. You can access the serlet using a Web browser and the serlet accesses the EJB, which in turn initiates the transaction between your browser and IMS. See the Related Task below to link to a description of how to use these tools. Related Reading: See Chapter 1: Enterprise JaaBeans and J2EE the IBM Redbook EJB Deelopment with VisualAge for Jaa for WebSphere Application Serer, SG , aailable at 78 IMS Connector for Jaa User s Guide and Reference

85 Building Jaa applications and serlets for conersational transactions The following steps proide a high-leel oeriew of how a Jaa application or serlet that accesses an IMS conersational transaction works. You can use this information along with the information in Building Jaa applications and serlets to build a Jaa application or serlet that accesses an IMS conersational transaction. 1. The user starts an IMS conersational Web application by displaying the input HTML page of the Web application in a Web browser. 2. The user proides the initial input data of the IMS conersational transaction in the input HTML page. This starts the first iteration of the IMS conersational transaction. 3. The Web browser sends the request with the input data to a Jaa serlet running in WebSphere Application Serer. 4. The Jaa serlet obtains the HttpSession object and creates an IMSConContext object and IMSConUnboundHttpSessionCleanup object. It sets up the IMSConContext object with the CCF ConnectionManager and saes it in the HttpSession object. The serlet then inokes the execute() method of the EAB command, passing the input data receied from the browser. The EAB command uses IMS Connector for Jaa APIs to send the transaction request to IMS ia IMS Connect. 5. IMS receies the request and schedules the IMS conersational application program. The IMS application program processes the request and the reply is returned to the Jaa serlet. 6. The Jaa serlet populates the EAB command with the output data of the reply and loads the appropriate result JSP page to display the output data on the Web browser. 7. The Jaa serlet or the end user determines if the output data receied is acceptable. If it is, the Jaa serlet inokes the commit() method of JaaCoordinator to accept the output and commit the iteration of the conersation. Otherwise, it inokes the rollback() method of JaaCoordinator to reject the output and back out the iteration of conersation. 8. The user proides the data for the second iteration on the JSP page used to display the output data of the first iteration, then submits the next request to IMS. This inokes the second iteration of the IMS conersational transaction. Subsequent iterations of the conersation repeat steps 3-8 until the user or the IMS application program terminates the conersation. In step 4, for second and subsequent iterations of the conersation, the Jaa serlet obtains the IMSConContext object from the unique HttpSession object. Note: The steps described aboe may differ when used with different synchronization leels. The aboe scenario describes an application flow with SYNC_LEVEL_CONFIRM. When used with SYNC_LEVEL_NONE, Step 7 would not be executed. Examples of how to create Web applications that perform these similar steps for nonconersational Web applications are presented in other sections of this documentation. Terminating a Conersation In the IMS Connector for Jaa conersational models, an IMS conersation is typically terminated in one of two ways: The client terminates the IMS conersational transaction: Chapter 3. Building Jaa applications and serlets 79

86 1. The end user submits a request to end the IMS conersation from the browser. 2. The Jaa serlet inokes an EAB command with the MODE_END_CONVERSATION interaction mode. MODE_END_CONVERSATION is a send only interaction. IMS terminates the conersation. The transaction is not scheduled and no output message is sent back to the serlet from IMS. 3. The Jaa serlet should inalidate the HttpSession object and cleanup the connection resource for reuse. 4. The serlet should also load a customized JSP page to display a message indicating that a request was sent to IMS Connect. Ending the conersation in this way is illustrated by the class com.ibm.connector.ims.sample.con.phonebook.endconersationcommand in the Connector IMS Samples project. The EndConersationCommand class is used by the serlet com.ibm.connector.ims.sample.con.forceend.serlet.conforceenditerations. The IMS application program terminates the conersation: 1. The end user submits a request to IMS to run the IMS conersational transaction. The input message may contain a specific request to terminate the conersation. Please note that the IMS application program may also terminate the conersation based on criteria other than the contents of the input message. 2. IMS schedules the IMS conersational application program, the program processes the input message, then sends the transaction output message back to the serlet. The OTMA message containing the transaction output message contains a bit signifying that the conersation has been ended. IMS ends the conersation after sending the transaction output message back to the serlet. 3. IMS Connector for Jaa receies the OTMA message and sets the boolean property in the IMSInteractionSpec to true. The EAB command is populated with the output data. 4. The serlet uses the getconended() method of IMSInteractionSpec to determine that the conersation has ended. 5. The Jaa serlet should inalidate the HttpSession object and clean up the connection resource. 6. The serlet should also load a customized JSP page to display a message on the Web browser indicating that the conersation was ended. Ending the conersation in this way is illustrated by the serlet com.ibm.connector.ims.sample.con.phonebook.serlet.coniterations. 80 IMS Connector for Jaa User s Guide and Reference

87 Chapter 4. Building a Jaa application to run an IMS transaction This section describes how to build an Enterprise Access Builder (EAB) command that uses IMS Connector for Jaa to run an IMS transaction. It includes descriptions of how to create record beans that represent the input and output messages of the IMS transaction, as well as how to use the VisualAge for Jaa Command Editor to build the EAB command. The section also describes how to create and run a Jaa application that uses an EAB command. This example uses the IMS transaction that is described in IMS INSTALL/IVP sample application This example corresponds to one of the samples included in the IMS Connect or Samples feature. The Jaa source relating to this example is contained in the com.ibm.connector.ims.sample.phonebook.command package of the Connector IMS Samples project which is added to your workspace when the IMS Connector Samples feature is added. See Preparing your VisualAge for Jaa enironment for instructions on installing the IMS Connector Samples feature if you hae not already done so. By following the instructions in this section, you will create an application which is the same as the corresponding sample except that it uses different project and package names than are used in the sample since you can t hae duplicate package or project names within your VisualAge enironment. As a result, you will be able to check your work against the sample, helping you to resole any difficulties you encounter as you progress through the steps that follow. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at Using the Enterprise Access Builder The Enterprise Access Builder consists of frameworks and tools that allow you to create Jaa applications that access existing host applications and data. An interaction with a back-end system often inoles sending input data to a host application, which would respond with some output data. In the Enterprise Access Builder, this interaction is called an EAB command. EAB commands dictate the data that is passed to and from the back-end system in a single interaction. Records are used as input and output for the EAB commands. Records define the layout of the input and output data within the back-end system. An EAB command is a composite, the main elements being connection specification, interaction specification, input bean, and output bean. When constructing an EAB command, you must proide the following information: Input data The input data is required by the EAB command to perform the execution. Output data The output data is the result of the EAB command s execution. Communication information This information is a set of classes used to communicate with the host system. A connection specification and an interaction specification define how an EAB command communicates with a host system. You use the Copyright IBM Corp. 1998,

88 ConnectionSpec interface to specify the connection to the host system. You use the InteractionSpec interface to specify to the EAB command which program to call through the connection deried from ConnectionSpec. The input of an EAB command is defined by a record bean. The output of an EAB command is also defined by a record bean; howeer, there might exist multiple output record beans defined as candidates. An EAB command can show an entire RecordBean in its interface, or only selected record bean properties. Using the Command Editor The Command Editor is a tool that guides you through the steps of constructing a command, allowing you to focus on the specific composition patterns of a command. You can use the Command Editor to create EAB commands from components (beans) representing the input, output, and communication information. Step 1: Creating IMS Transaction Input and Output Beans This section describes how to create IMS transaction input and output beans that you can use in an EAB command that runs an IMS transaction. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create a Project and Package for the Application 3. Create a COBOL Record Type Class for the IMS Transaction Input Message 4. Create a Transaction Input Record Bean 5. Create a COBOL Record Type Class for the IMS Transaction Output Message 6. Create a Transaction Output Record Bean The COBOL source used in steps C and E of this example can be found in <IBM_Connectors_install_dir>\imsconn\samples\misc\Ex01.ccp, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. For example, d:\ibm Connectors. Step 1A: Start the Workbench in the VisualAge for Jaa IDE Click the Start icon and click Programs > IBM VisualAge for Jaa for Windows > IBM VisualAge for Jaa. Step 1B: Create a Project and Package for the Application This step creates a project, called Examples, that contains a package named ex01. Do the following: 1. From the Selected menu, click Add > Project. The Add Project wizard appears. Enter a name for the new project (for example, Examples), and click Finish. 2. To add a new package to this project, ensure that the correct project is selected. Then, from the Selected menu, click Add > Package. The AddPackage wizard appears. Ensure that the correct project name is specified and that the Create a new package named: radio button is selected. Enter a name for the new package (for example, ex01) and click Finish. Definition: 82 IMS Connector for Jaa User s Guide and Reference

89 A project is a unit of organization that is used to group packages. A VisualAge for Jaa project is the starting point for your deelopment work in the IDE. Step 1C: Create a COBOL Record Type Class for the IMS Transaction Input Message This step parses the COBOL commarea that represents the input message for the IMS transaction, and creates a COBOL Record Type class that encapsulates the information in the commarea. This class will be used in Step 1D: Create a Transaction Input Record Bean to build a Jaa bean that represents the input message. Do the following: 1. Ensure that the new package, ex01, is selected. From the Selected menu, click Tools > Enterprise Access Builder > Import COBOL to Record Type... The Import COBOL to Record Type wizard appears. 2. On the Import COBOL to Record Type wizard, do the following: Enter the path and file name of the COBOL file that contains the commarea representing the IMS transaction input message. Click Next. The next Import COBOL to Record Type wizard appears, and contains a list of the aailable leel 01 commareas. Select the commarea representing the IMS transaction input message from the Aailable leel 01 commarea list (for example, INPUT_MSG)) and add it to the Selected commareas list by clicking the > button. Select the Use BigDecimal check box. This will generate the COBOL type as a BigDecimal Jaa type. Click Next. Ensure that the correct names appear in the Project Name and Package entry fields. Enter a name for the new class that will represent the COBOL Record Type. For example, InMsgInfo. To continue to generate the record bean from this record type, ensure that both the Continue working with newly created record type check box and the Create record from record type radio button are selected. Click Finish. A new class named InMsgInfo appears in the package named ex01 in the IDE Workbench. The following fragment of COBOL source code is the 01 commarea for the IMS transaction input message: 01 INPUT-MSG. 02 IN-LL PICTURE S9(3) COMP. 02 IN-ZZ PICTURE S9(3) COMP. 02 IN-TRCD PICTURE X(10). 02 IN-CMD PICTURE X(8). 02 IN-NAME1 PICTURE X(10). 02 IN-NAME2 PICTURE X(10). 02 IN-EXTN PICTURE X(10). 02 IN-ZIP PICTURE X(7). Related Reading: For more information on importing COBOL source to a record type, see the VisualAge for Jaa Enterprise Access Builder documentation. Step 1D: Create a Transaction Input Record Bean This step creates a record bean that represents the transaction input message from the COBOL Record Type class created in Step 1C: Create a COBOL Record Type Class for the IMS Transaction Input Message. A record bean contains properties Chapter 4. Building a Jaa application to run an IMS transaction 83

90 that map to the fields in a record in a host program. In this case, the record in the host program is the IMS transaction input message. Do the following: 1. If both the Continue working with newly created record type check box and the Create record from record type radio button are selected in Step 1C: Create a COBOL Record Type Class for the IMS Transaction Input Message, the Create Record from Record Type wizard appears. To manually start the Create Record from Record Type wizard, ensure that the COBOL Record Type class, InMsgInfo, is selected. From the Selected menu, click Tools > Enterprise Access Builder > Create Record from Record Type... The Create Record from Record Type wizard appears. 2. On the Create Record from Record Type wizard, enter the following: Ensure that the correct names appear in the Project Name and Package entry fields. Enter a name for the new class that will represent the input message. For example, InMsg. Click Access Method: Direct. Click Record Style: Custom Records. In Additional Options, ensure that the Generate with Notification check box is not selected. Do not check Use Inner Classes or Shorten Names. Click Next to iew the next page of the Create Record from Record Type wizard. Ensure that this page shows the following alues, which indicate that the IMS transaction input message is processed on an MVS host machine: Floating Point Format is IBM. Endian is Big Endian. Remote Integer Endian is Big Endian. Code Page is 037. Machine Type is MVS. 3. Click Finish on the Create Record from Record Type wizard. Two new classes, called InMsgBeanInfo and InMsg, appear in the package ex01 in the IDE Workbench. The InMsg Jaa bean represents the IMS transaction input message. Notes: Code page refers to the data of the IMS transaction. If your transaction data is other than U.S. English (code page 037), you must enter a different code page in this field. Ensure that all alues on the Create Record from Record Type wizard hae been accepted. That is, all of the field alues should appear gray before you select Finish. Related Reading: For more information on additional options, see the VisualAge for Jaa Enterprise Access Builder documentation. Step 1E: Create a COBOL Record Type Class for the IMS Transaction Output Message Repeat the instructions in Step 1C: Create a COBOL Record Type Class for the IMS Transaction Input Message to create a class named OutMsgInfo from the 01 commarea representing the IMS transaction output message. 84 IMS Connector for Jaa User s Guide and Reference

91 The following fragment of COBOL source code is the 01 commarea for the IMS transaction output message: 01 OUTPUT-MSG. 02 OUT-LL PICTURE S9(3) COMP VALUE OUT-ZZ PICTURE S9(3) COMP VALUE OUT-MSG PICTURE X(40) VALUE SPACES. 02 OUT-CMD PICTURE X(8) VALUE SPACES. 02 OUT-NAME1 PICTURE X(10) VALUE SPACES. 02 OUT-NAME2 PICTURE X(10) VALUE SPACES. 02 OUT-EXTN PICTURE X(10) VALUE SPACES. 02 OUT-ZIP PICTURE X(7) VALUE SPACES. 02 OUT-SEGNO PICTURE X(4) VALUE SPACES. Step 1F: Create a Transaction Output Record Bean Repeat the instructions in Step 1D: Create a Transaction Input Record Bean aboe to create classes named OutMsgBeanInfo and OutMsg. The OutMsg Jaa bean represents the IMS transaction output message. Step 2: Creating an EAB Command Using the Command Editor This section describes how you can create an Enterprise Access Builder (EAB) command using the VisualAge for Jaa Command Editor. The Command Editor guides you through the steps of constructing a command, allowing you to focus on the specific composition patterns of a command. For a definition of the EAB command, see IMS Connector for Jaa Concepts and Terms. The Jaa source for this example can be found in the package com.ibm.connector.ims.sample.phonebook.command in the WorkBench. Initially, <IBM_Connectors_install_dir> is <aj_install_drie>\ibm Connectors, where <aj_install_drie> is the drie on which VisualAge for Jaa is installed. The steps include the following: 1. Create a Command Class for the IMS Transaction 2. Promote the IMS Transaction Input Properties 3. Promote the IMS Transaction Output Properties 4. Promote the DFS Message Properties 5. Promote the Interaction Specification Properties 6. Promote the Connection Specification Properties 7. Create the Command Bean Step 2A: Create a Command Class for the IMS Transaction This step creates a class for the EAB command. Do the following: 1. Ensure that the package ex01 is selected. From the Selected menu, click Tools > Enterprise Access Builder > Create Command... The Create Command wizard appears. 2. On the Create Command wizard, do the following: a. Ensure that the correct names appear in the Project Name and Package entry fields. b. Enter a name for the new class that represents the EAB command (for example, Ex01Command). Chapter 4. Building a Jaa application to run an IMS transaction 85

92 c. Ensure that the Edit when finished check box is selected to edit the Command class when it is created. d. Associate a connection specification with the EAB command. Click the Browse... button. All aailable ConnectionSpec classes are shown. Choose IMSConnectionSpec and click OK. e. Click Edit to edit the connection specification properties. Select the property name and specify the alue as follows: Host name Enter the TCP/IP host name of the machine running IMS Connect that the command (IMS transaction) will be using. If you are using Local Option, enter LOCALHOST:IMS Connect Name. Note that IMS Connect Name is referred to in the IMS Connect documentation as HWS ID. Port Enter the port for IMS Connect that the command (IMS transaction) will be using. You can also proide alues for the following connection properties using: Realm Connection timeout Maximum connections Minimum connections Reap time Unused timeout See the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of these properties. f. Associate an interaction specification with the EAB command. Click the Browse... button. All aailable InteractionSpec classes are shown. Choose IMSInteractionSpec and click OK. g. Click Edit to edit the interaction specification properties. Select the property name and specify the alue as follows: Datastore name Enter the name of the target IMS datastore for this command (IMS transaction). The Datastore Name is a maximum of 8 uppercase characters. LTERM Name Leae as is. Map Name Leae as is. Mode Leae as MODE_SEND_RECEIVE Synchronization Leel Leae as SYNC_LEVEL_NONE h. Click Next to use the Add Input/Output Beans wizard. 3. On the Add Input/Output Beans wizard, enter the following: a. In the Input record bean section, ensure that the Implements IByteBuffer check box is selected. Enter the class name of the Transaction Input bean. 86 IMS Connector for Jaa User s Guide and Reference

93 Click the Browse... button to display a list of all aailable classes that implement IByteBuffer. Select the appropriate Type Name (InMsg) and Package Name (ex01) and click OK. b. Proide the Mapper class, if necessary. In this example, no additional Mapper class is needed. c. In the Output record bean section, ensure that Select output record beans is selected. Click the Add button. A dialog box appears to enter the output record bean. In this dialog box, ensure that the Implements IByteBuffer check box is selected. Enter the class name of the Transaction Output bean. Click the Browse... button to display a list of all aailable classes that implement IByteBuffer. Select the appropriate Type Name (OutMsg) and Package Name (ex01) and click OK. d. Repeat the preious step to add additional output record beans, if necessary. In this example, repeat the preious step to add the output record bean with DFSMsg as Type Name and com.ibm.connector.imstoc as the Package Name. Proide the Mapper class, if necessary. e. You can use Modify... or Delete to modify or delete the output record beans from the list. 4. Click Finish to generate the EAB command. If the Edit with finished check box is selected in Item 2, the new EAB command appears in the Command Editor. 5. You can use the Command Editor to create a new command, open existing commands, add or delete beans and properties, and promote or change properties. To launch an existing command with the Command Editor, ensure that the EAB command class is selected, then select Tools > Enterprise Access Builder > Edit Command... To change the bean properties with the Command Editor, do the following: 1. Select a folder icon (for example, Connector) under the command bean icon (for example, ex01.ex01command) in the top left pane. The bean appears in the top right pane. 2. Select the bean (com.ibm.connector.imstoc.imsconnectionspec) in the top right pane. The properties and their alues appear in the bottom pane. 3. Select the property name that you want to change and specify the new alue. Related Reading: For more information on the Mapper class, see the VisualAge for Jaa Enterprise Access Builder documentation. Step 2B: Promote the IMS Transaction Input Properties When creating a composite bean (such as the EAB command bean) you might want some features of beans that are embedded within it to appear in the interface of the composite bean. To add features of a transaction input bean to the interface of a composite bean, promote them to the composite s interface by doing the following: 1. In the Command Editor, select the Input folder under the ex01.ex01command icon in the top left pane. The input bean appears in the top right pane. 2. Select the input bean ( ex01.inmsg). The properties and their alues appear in the bottom pane. 3. Select the IN LL property in the bottom pane with the right mouse button. Choose Promote Property on the pop-up context menu. The promoted Chapter 4. Building a Jaa application to run an IMS transaction 87

94 property is marked with a green dot in front of the property name. By default, properties are promoted with the same name as the originating bean. 4. Repeat the preious step to promote the following properties: IN ZZ IN TRCD IN CMD IN NAME1 IN NAME2 IN EXTN IN ZIP Step 2C: Promote the IMS Transaction Output Properties To add features of an output transaction bean to the interface of a composite bean, promote them to the composite s interface by doing the following: 1. In the Command Editor, select the Output folder under the ex01.ex01command icon in the top left pane. The output beans appear in the top right pane. 2. Select the output bean ( ex01.outmsg). The properties and their alues appear in the bottom pane. 3. Select the OUT LL property in the bottom pane with the right mouse button. Choose Promote Property on the pop-up context menu. The promoted property is marked with a green dot in front of the property name. By default, properties are promoted with the same name as the originating bean. 4. Repeat the preious step to promote the following properties: OUT MSG OUT CMD OUT NAME1 OUT NAME2 OUT EXTN OUT ZIP Step 2D: Promote the DFS Message Properties To add features of embedded beans to the interface of a composite bean, you must promote them to the composite bean s interface. In the case of the DFSMsg message bean, a number of options exist for promoting properties: Option 1 If you want to use the EAB command in a Jaa application program (rather than in a Jaa serlet), promote either the getdfsmessage() method or the getdfsmessagesegments() method. The method getdfsmessage returns the message as a string of its concatenated segments. Method getdfsmessagesegments() returns each segment of the message as a string. Since the Command Editor does not allow promotion of methods, you must add the appropriate method to the EAB Command as follows: 1. Right-click on the EAB Command (for example, Ex01Command). 2. Select Add >Method... The Create Method SmartGuide appears. 3. Select the Create a new method radio button on the Create Method SmartGuide, then press Next. The Attributes SmartGuide appears. 4. If the method being added is getdfsmessage(): 88 IMS Connector for Jaa User s Guide and Reference

95 a. Enter getdfsmessage in the Method Name: entry field. b. Enter String in the Return Type: entry field. c. Select the public radio button in Access Modifiers, then press Finish. d. Modify the code of the newly added method by replacing the statement return null; with the following statement: return getceoutputi().getdfsmessage(); where getceoutputi() is the method that returns the corresponding message bean. If the method being added is getdfsmessagesegments(): 1. Enter getdfsmessagesegments in the Method Name: entry field. 2. Enter jaa.util.vector in the Return Type: entry field. 3. Select the public radio button in Access Modifiers, then press Finish. 4. Modify the code of the newly added method by replacing the statement return null; with the following statement: return getceoutputi().getdfsmessagesegments() where getceoutputi() is the method that returns the corresponding message bean. Option 2 If you want to use the EAB command to generate a Jaa serlet using WebSphere Studio, promote one or more data properties of the message, rather than the getdfsmessage() method or the getdfsmessagesegments() method. The WebSphere Serlet Generation wizard currently only supports string properties for display on the output HTML. Option 3 Methods getdfsmessage() and getdfsmessagesegments() can still be used in.jsp pages, but must be manually coded rather than generated by WebSphere Studio. To promote data properties of the message: 1. In the Command Editor, select the Output folder under the ex01.ex01command icon in the top left pane. The output beans appear in the top right pane. 2. Select the DFS message bean (com.ibm.connector.imstoc.dfsmsg). The properties and their alues appear in the bottom pane. 3. Select, for example, the DFSDATA1 property in the bottom pane with the right mouse button. Choose Promote Property on the pop-up context menu. The promoted property is marked with a green dot in front of the property name. By default, properties are promoted with the same name as the originating bean. Step 2E: Promote the Interaction Specification Properties If you want your Jaa application or serlet to accept alues for IMSInteractionSpec properties as input, you must promote features of the embedded bean to the interface of the EAB Command bean. For example, to proide input alues for Datastore Name, do the following: 1. In the Command Editor, select the Connector folder under the ex01.ex01command icon in the top left pane. The connector beans appear in the top right pane. Chapter 4. Building a Jaa application to run an IMS transaction 89

96 2. Select the IMS interaction specification bean (com.ibm.connector.imstoc.imsinteractionspec). The properties and their alues appear in the bottom pane. 3. Select the Datastore name property in the bottom pane with the right mouse button. Choose Promote Property on the pop-up context menu. The promoted property is marked with a green dot in front of the property name. By default, properties are promoted with the same name as the originating bean. Step 2F: Promote the Connection Specification Properties If you want your Jaa application or serlet to accept alues for IMSConnectionSpec properties as input, you must promote features of the embedded bean to the interface of the EAB Command bean. For example, to proide input alues for Hostname or Port, do the following: 1. In the Command Editor, select the Connector folder under the ex01.ex01command icon in the top left pane. The connector beans appear in the top right pane. 2. Select the IMS connection specification bean (com.ibm.connector.imstoc.imsconnectionspec). The properties and their alues appear in the bottom pane. 3. Select the Host name property in the bottom pane with the right mouse button. Choose Promote Property on the pop-up context menu. The promoted property is marked with a green dot in front of the property name. By default, properties are promoted with the same name as the originating bean. 4. Repeat the preious step to promote the Port property. Figure 7. The completed command bean as shown in the command editor Step 2G: Create the Command Bean 90 IMS Connector for Jaa User s Guide and Reference

97 To sae the command bean, select Command > Sae from the menu bar. Select Command > Exit Editor from the menu bar to exit the Command Editor. The Workbench now shows two classes associated with the EAB command: Ex01Command and Ex01CommandBeanInfo. An EAB command that is created using the Create Command wizard and the Command Editor can only be opened and edited using the Command Editor. An EAB command that is created using the Visual Composition Editor must be edited using the Visual Composition Editor. When using the Command Editor to open an EAB command that is created using the Visual Composition Editor, you are prompted to conert the command to the appropriate format for the Command Editor. After this conersion, howeer, it must be edited with the Command Editor. Step 3: Writing a Jaa Application to Use the EAB Command This section demonstrates how you can use the EAB command that was created in Creating an EAB Command Using the Command Editor to create a Jaa application. You can use the Jaa application to run the IMS transaction. This example illustrates only basic concepts, and does not include sophisticated input and output processing. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create an Executable Class 3. Add Jaa Code to the Class Jaa source for the EAB command that you created in Creating an EAB Command Using the Command Editor can be found in class Ex01Command of package com.ibm.connector.ims.sample.phonebook.command in the Connector IMS Samples project on your Workbench. Step 3A: Start the Workbench in the VisualAge for Jaa IDE If you are using VisualAge for Jaa on Windows, click the Start icon and click Programs > IBM VisualAge for Jaa for Windows > IBM VisualAge for Jaa. If the Welcome to VisualAge dialog box appears, click Go to the Workbench and click OK. The IDE workbench appears. Step 3B: Create an Executable Class 1. From the Selected menu, click Add > Class. A wizard appears to request all of the necessary information to create a class. Do the following: a. Ensure that the Project field contains your project name, Examples. b. Ensure that the Package field contains your package name, ex01. c. Click Create a new class. d. Enter Ex01Execute in the Class name field. e. Ensure that the Superclass is jaa.lang.object. f. Ensure that the Compose the class isually check box is not checked. g. Click Next to continue to the next window. 2. You need to add import statements to a class that executes an EAB command that uses IMS Connector for Jaa. To include these classes as import statements, click Add Package... A list of aailable packages appears. From the list, select each of the following packages, and click Add to include it in the import statements. Chapter 4. Building a Jaa application to run an IMS transaction 91

98 com.ibm.connector.connectionmanager com.ibm.connector.imstoc com.ibm.connector.infrastructure com.ibm.connector.infrastructure.jaa After adding the final one, click Close. In addition, this example requires the following import statement for the code that parses the command line arguments: import jaa.util.stringtokenizer; You can add this line of code later or select the Add Type... button. As you enter the characters of the type in the Filter field of the Import Statements window (for example, jaa.util.s ), type names and package names will appear. Select the appropriate type, then select the Add button to add the import statement. 3. Ensure that only the following fields on the Attributes SmartGuide are checked: public (in modifiers section) Methods which must be implemented (Recommended) Copy constructors from superclass (Recommended) main(string[]) 4. To generate the class, click Finish. The class appears inside the package that you hae specified. Step 3C: Add Jaa Code to the Class Code must be added to the main() method of the Ex01Execute class to use the EAB command to run the IMS transaction. This code can be copied from the main() method of the Ex01Execute class in package com.ibm.connector.ims.sample.phonebook.command in the Connector IMS Samples project on your Workbench. Replace the alues youruid, yourpwd, and yourgrp with the user ID, password, and group name for your IMS enironment. In addition, the code illustrates three ways in which error or status messages from IMS can be printed. In each case, the appropriate method or property must be promoted to the EAB command interface. This sample code allows you to change to a different host name, port, or datastore name at run time by supplying new alues as command-line arguments. The format of these arguments is illustrated in the comments of this code. Step 4: Testing Your Application within VisualAge for Jaa After you hae successfully compiled your Jaa application (for example, Ex01Execute), you can test the application from within VisualAge for Jaa. Do the following: 1. Select the class of your application and, from the Selected menu, click Properties. The Properties window (for example, Ex01Execute) appears. 2. Ensure that the Program tab is selected and, if required, enter any command-line arguments in the text box under Command line arguments. Each argument is separated with a space. For example, in Writing a Jaa Application to Use the EAB Command, you enter: 92 IMS Connector for Jaa User s Guide and Reference

99 HOSTNAME=yourhost PORT=yourportnumber DATASTORE=yourdatastorename 3. Select the Class Path tab and make sure that the Include. (dot) in class path and Project path: check boxes are checked. 4. Click Compute Now, and click OK when the class path is computed. This updates the VisualAge for Jaa class path to include your Jaa application. 5. Select the main method of your application and from the Selected menu, click Run > Run main... The results of running your application appear in the Console window. Step 5: Running Your Application Outside of VisualAge for Jaa If you want to run your Jaa application on a workstation that does not hae VisualAge for Jaa installed, you must proide access on the workstation to all of the class libraries that the application uses. These class libraries are the same as those that are normally part of VisualAge for Jaa. Do the following: 1. Ensure that JDK or JRE Version or higher is installed. 2. Copy the following class libraries (.zip files) to your workstation: IBM Common Connector Framework File ccf.zip is located in the directory <IBM_Connectors_install_dir>\classes IBM Enterprise Access Builder Library File eablib.zip is located in the directory <install_dir>\eab\runtime30. IBM Jaa Record Library File recjaa.zip is located in the directory <IBM_Connectors_install_dir> \eab\runtime30. IMS Connector for Jaa File imsconn.zip is located in the directory <IBM_Connectors_install_dir>\classes where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. For example, d:\ibm Connectors. In addition, you must create a.jar file from the.class files for your application and copy it to your workstation. Your Jaa application might consist of one or more EAB command beans. Therefore, when you create the.jar file for your application, you must include all of the Jaa beans of which the composite EAB command beans are comprised, as well as any classes that represent the application. 3. Modify (or append to) your workstation s CLASSPATH enironment ariable to point to the aboe.zip and.jar files. 4. Use jaa.exe to run the class that corresponds to your Jaa application. If your application requires input command-line arguments, enter: jaa application_class_name arg1 arg2... where application_class_name is the name of the executable class corresponding to your application and arg1 and arg2 are the command-line arguments. For example, jaa ex01.ex01execute HOSTNAME=MYHOST PORT=9999 DATASTORE=IMSA Chapter 4. Building a Jaa application to run an IMS transaction 93

100 Note: Consider the following if you are haing trouble running your application outside of VisualAge for Jaa: Ensure that all class libraries (.jar and.zip files) are pointed to correctly by the CLASSPATH enironment ariable. A small error in CLASSPATH can result in a class not being found. Remember that a GUI application, such as the IMS Connector for Jaa s IVP, uses classes that may not be part of the JDK or JRE you are using. For example, you may hae to separately deploy the swing classes and point to them with CLASSPATH. Remember that, in some enironments, you may hae to restart the process in which you are running your application, after modifying CLASSPATH. Ensure that you correctly specify the name of your application. Keep in mind case sensitiity and remember to qualify the name of your application by its package name, if applicable. Verify that the JAR file for your application contains all of the necessary classes. Depending on how you hae implemented security for the operating system and Jaa, you might also need to ensure that the appropriate access to the JAR file is allowed. 94 IMS Connector for Jaa User s Guide and Reference

101 Chapter 5. Building a Jaa application to run a naigator This section describes how you can create an EAB Naigator to run multiple IMS transactions. An EAB Naigator is composed of multiple EAB commands that form a more complex interaction (naigation) with a host system. This section also describes how to create and run a Jaa application that uses an EAB Naigator. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at The process of creating and running a Jaa application to run two IMS transactions is described in the following sections: Creating a Naigator Using the Command and Visual Composition Editors Writing a Jaa Application to Use a Naigator Testing the Jaa Application Creating a Naigator Using the Command and Visual Composition Editors This example illustrates how you can create an EAB Naigator command to run multiple IMS transactions. The Naigator command is composed of other commands that form a more complex interaction (naigation) with a host system. You construct the commands contained in the Naigator using the Command Editor and then create the complex interactions in the Naigator by interconnecting these commands using the Naigator s Visual Composition Editor. In this example, we build a Naigator command that runs two IMS transactions sequentially. This Naigator command consists of two commands. Each command corresponds to an IMS transaction. The Naigator command accepts input from the user which it uses as the input to the first command. The first command executes and the output from this command is displayed by the Naigator on its output screen and used as the input for the second command. The Naigator then executes the second command and uses the output of this command to formulate the output which it displays on its output screen. Definition: An Enterprise Access Builder Naigator wraps multiple interactions with a host system into what appears to the user to be a single interaction. From the outside, a Naigator looks like an EAB command. A Naigator consists of both EAB commands and Naigators strung together to form a more complex interaction with the host system. The following procedure assumes that you hae the com.ibm.connector.ims.sample.phonebook.command package on your Workbench. This will be the case if you hae installed the IMS Connector Samples feature (and hae not subsequently deleted the package.) The IMS transactions executed by both of the commands that make up the Naigator command take a single-segment input message and return a single-segment output message. Generally, the steps are as follows: 1. Start the Workbench in the VisualAge for Jaa IDE Copyright IBM Corp. 1998,

102 2. Create a Project and Package for the Application 3. Create a Naigator Bean for Building Complex Commands 4. Set Up the Property Features 5. Create a Command Bean for the First Command 6. Create a Command Bean for the Second Command 7. Set Up the Connection Specification for the Naigator (Optional) 8. Promote Connection and InteractionSpec Property Features (Optional) 9. Sae the Naigator Bean Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Step 1A of Building a Jaa application to run an IMS transaction. Step 2: Create a Project and Package for the Application This step creates a project, called Examples, that contains a package named ex02. For a description of how to create a project and package, see Step 1B of Building a Jaa application to run an IMS transaction. The package used by the sample code in this section is ex02. Step 3: Create a Naigator Bean for Building Complex Commands This step creates the Naigator bean, which is composed of two command beans that correspond to the two IMS transactions. Do the following: 1. With the package ex02 selected, click the Selected menu, then click Add > Class... The Create Class wizard appears. 2. Ensure that the correct names, Examples and ex02, appear in the Project and Package entry fields, respectiely. 3. Click Create a new class and enter a name for the new Naigator command class (for example, Ex02Naigator). 4. To choose the superclass for class Ex02Naigator, click Browse, then select CommunicationNaigator from the TypeNames list. Ensure that the Compose the class isually radio button is selected and click Finish. A new window (titled Ex02Naigator [mm/dd/yy HH:MM:SS AM/PM] in Ex02) appears with the Visual Composition tab selected. When you execute a Naigator, the Naigator proides its input to the commands and Naigators of which it is composed in accordance with the connections that are set up when the Naigator is created. These connections in a Naigator also determine the order of execution of each EAB command or Naigator contained in the Naigator. For a simple Naigator, after the final interaction is carried out, the output of the indiidual commands and Naigators can be used to formulate the output of the Naigator. For more complex Naigators, the output of the Naigator is determined 96 IMS Connector for Jaa User s Guide and Reference

103 by the output of the indiidual commands and Naigators it contains as well as code that can be added to the connections in the Naigator and/or code in the Jaa application that executes the Naigator. Step 4: Set Up the Property Features This step creates new property features for the Naigator command. These property features are linked to the property features of the indiidual commands that make up the Naigator, which allows the input data and output results to be passed between the indiidual commands and the Naigator in accordance with the property-to-property connections set up in the Naigator. This enables the output of one command to be used for the input of a subsequent command and allows the output of a command to be passed to the Naigator where it can be processed if necessary and then in turn, passed on to the application executing the Naigator where it can be further processed if necessary and displayed to the user. Create new property features for the data beans in the command bean by doing the following: 1. Create Input property features: Input for first command: Select the BeanInfo tab of the Ex02Naigator bean window (located at the top of the window that opened in the last step). Click Features > New Property Feature... from the pull-down menu at the top of the screen. The New Property Feature SmartGuide appears. In the New Property Feature SmartGuide, enter a name in the Property name field for one of the promoted properties in the Ex02FirstCommand. For example, enter FIRST_CMD_IN_LL for the IN_LL property of Ex02FirstCommand. In the Property Type field, select the corresponding type for the property (for example, short). Accept the default settings for all of the other selections for this property feature and click Finish. A new property feature of FIRST_CMD_IN_LL appears in the Feature section of the window. Repeat the aboe steps to create the following new features for all of the other input properties of the Ex02FirstCommand bean: The following is Property Type short: - FIRST_CMD_IN_ZZ (for IN_ZZ property of Ex02FirstCommand) The following are Property Type jaa.lang.string: - FIRST_CMD_IN_TRCD (for IN_TRCD property of Ex02FirstCommand) - FIRST_CMD_IN_CMD (for IN_CMD property of Ex02FirstCommand) - IN_NAME1 (for IN_NAME1 property of Ex02FirstCommand) - IN_NAME2 (for IN_NAME2 property of Ex02FirstCommand) - IN_EXTN (for IN_EXTN property of Ex02FirstCommand) - IN_ZIP (for IN_ZIP property of Ex02FirstCommand) Input for second command: Similarly, create the following new features for all of the input properties of the Ex02SecondCommand bean. The following are Property Type short: Chapter 5. Building a Jaa application to run a naigator 97

104 >SECOND_CMD_IN_LL (for IN_LL property of Ex02SecondCommand) >SECOND_CMD_IN_ZZ (for IN_ZZ property of Ex02SecondCommand) The following are Property Type jaa.lang.string: SECOND_CMD_IN_TRCD (for IN_TRCD property of Ex02SecondCommand) SECOND_CMD_IN_CMD (for IN_CMD property of Ex02SecondCommand) 2. Create output property features: This step creates the following new features for all of the output properties. The following are Property Type short: OUT_LL (for OUT_LL property of Ex02SecondCommand bean) OUT_ZZ (for OUT_ZZ property of Ex02SecondCommand bean) The following are Property Type jaa.lang.string: OUT_MSG (for OUT_MSG property of Ex02SecondCommand bean) OUT_CMD (for OUT_CMD property of Ex02SecondCommand bean) OUT_NAME1 (for OUT_NAME1 property of Ex02SecondCommand bean) OUT_NAME2 (for OUT_NAME2 property of Ex02SecondCommand bean) OUT_EXTN (for OUT_EXTN property of Ex02SecondCommand bean) OUT_ZIP (for OUT_ZIP property of Ex02SecondCommand bean) OUT_SEGNO (for OUT_SEGNO property of Ex02SecondCommand bean) Step 5: Create a Command Bean for the First Command This step creates the first command bean, which represents the first IMS transaction for this example. There are multiple ways in which this command bean can be created. In this example we will create the Ex01FirstCommand EAB command bean by reusing the command bean that was created in the ex01 example, see Building a Jaa application to run an IMS transaction (Step 2.) 1. Select the Visual Composition tab of the Ex02Naigator bean window to start the Visual Composition Editor. 2. Click the Choose Bean... icon in the tool palette and ensure that the Class Bean Type is selected. Click the Browse button for the Class name field. In the Pattern field, enter Ex01. A list of class names appears. Select Ex01Command for the Class name from the list of aailable classes and com.ibm.connector.ims.sample.phonebook.command from the package name. Click OK. Enter Ex02FirstCommand in the Name field and click OK. 3. To plant the bean, moe the cursor to a position in the frame window and click the left mouse button. 4. The following connections are needed for communication between the command and the Naigator: a. UnsuccessfulExecution eent connection: These steps create an Eent-to-method connection such that the returnexecutionunsuccessful method of the Naigator is inoked when an executionunsuccessful of the Ex02FirstCommand eent occurs. Select the Ex02FirstCommand icon and click the right mouse button. Choose Connect > Connectable Features... in the resulting pop-up window. 98 IMS Connector for Jaa User s Guide and Reference

105 Click Eent and scroll down the list to choose the executionunsuccessful(com.ibm.ij.eab.command.commandeent) eent and click OK. Moe the cursor to an empty area in the frame window and click the left mouse button. Click Connectable Features... A list in an End connection to [Ex02Naigator] dialog box appears. In the End connection dialog box, ensure that the Method radio button is selected. Choose returnexecutionunsuccessful(com.ibm.ij.eab.command.commandeent) from the scroll-down list and click OK. A new dotted-line connection is created. Select the new connection and click the right mouse button. Select Properties from the pop-up menu, and the Eent-to-method connection properties window appears. Click the Pass eent data box and then click OK. The connection now becomes a solid line. b. StartExecution eent connection: See the description in item 4a of this step to create an Eent-to-method connection between the internalexecutionstarting(com.ibm.ij.eab.command.commandeent) eent of the Naigator and the execute(com.ibm.ij.eab.command.commandeent) of Ex02FirstCommand. The execute method of Ex02FirstCommand is inoked when an internalexecutionstarting of the Naigator method occurs. Note that this step requires you to start the connection by right-clicking on an open area in the Naigator Visual Composition window and then end the connection by clicking on the Ex02FirstCommand icon. Be sure to click the Pass eent data box before clicking OK. The connection now becomes a solid line. c. Input property connections: The following steps create property-to-property connections between the input properties of Ex02FirstCommand and the corresponding input property features of the Naigator. These connections are used to propagate the user input alues from the property features of the Naigator to Ex02FirstCommand. Place the cursor on an empty area in the frame window and click the right mouse button. Select Connect... and a Start connection from [Ex02Naigator] dialog box appears. Click Property. Select the FIRST_CMD_IN_LL property from the scroll-down list and click OK. Place the cursor on the Ex02FirstCommand icon and click the left mouse button. Choose Connectable Features... An End connection to [Ex02FirstCommand] dialog box appears. Click Property. Select the IN_LL property from the scroll-down list and click OK. A new property-to-property connection between the FIRST_CMD_IN_LL property of the Naigator and the IN LL property of the Ex02FirstCommand bean is created. Repeat the aboe steps to associate all of the other features of the Ex02FirstCommand with the Naigator: FIRST_CMD_IN_ZZ > IN ZZ FIRST_CMD_IN_TRCD > IN TRCD Chapter 5. Building a Jaa application to run a naigator 99

106 FIRST_CMD_IN_CMD > IN CMD IN_NAME1 > IN NAME1 IN_NAME2 > IN NAME2 IN_EXTN > IN EXTN IN_ZIP > IN ZIP d. Result property connections. This step connects the output properties of the first command with the Naigator bean so that the results can be accessed and returned to the user. It creates property-to-property connections between the output properties of Ex02FirstCommand and the output property features of the Naigator. These connections are used to propagate the output alues from Ex02FirstCommand to the output property features of the Naigator. Because these are result property connections and the result property alues are not known until after the command has executed, it is necessary to specify that the trigger eent is a change in the alue of source property. This is accomplished by selecting the result property-to-property connection after you hae created it, right-clicking and selecting Properties and then selecting propertychange as the source eent for all result property connections. See the description in Step 5, item 4c, aboe to create property-to-property connections between the following output properties of the Ex02FirstCommand bean and the corresponding output property features of the Naigator. Remember to start the result property connections by right-clicking on the Ex02FirstCommand icon and end them by clicking in an open area of the Naigator Visual Composition window. Be sure to select propertychange for the Source eent in the Property-to-property connection - Properties window. OUT LL > OUT_LL OUT ZZ > OUT_ZZ OUT MSG > OUT_MSG OUT CMD > OUT_CMD OUT NAME1 > OUT_NAME1 OUT NAME2 > OUT_NAME2 OUT EXTN > OUT_EXTN OUT ZIP > OUT_ZIP OUT SEGNO > OUT_SEGNO Sae the Ex02FirstCommand bean by clicking on Bean > Sae Bean. This will sae the Ex02FirstCommand bean and generate the runtime code associated with this bean, some of which will be modified in the next paragraph. On your Workbench, expand the Ex02Naigator class and select the connetom2 (CommandEent) method. In the Source pane, add the following code in the user code {1} block (after the line that reads // user code begin {1}): System.out.println( \nbeginning execution of Ex02FirstCommand... + \n ); This code will cause the aboe line to be displayed on the output screen (the Jaa console) right before Ex02FirstCommand is executed. Sae this change by again clicking on the connetom2(commandeent) method and then click on Yes. 100 IMS Connector for Jaa User s Guide and Reference

107 Step 6: Create a Command Bean for the Second Command This step uses the Visual Composition Editor to create a second EAB command and associate to the Naigator. Do the following: 1. Click Choose Bean... again. This time the Class Bean Type should be already selected and com.ibm.connector.ims.sample.phonebook.command.ex01command should be highlighted as the Class name. If so, enter Ex02SecondCommand in the Name field and click OK. Otherwise, click Browse. InthePattern field enter Ex01Command. A list of class names appears. Choose Ex01Command (in package ex01) for the Class name from the list of aailable classes. Click OK. Enter Ex02SecondCommand in the Name field and click OK. 2. To plant the bean, moe the cursor to a position in the frame window and click the left mouse button. 3. The following connections are needed for communication between this command, Ex02FirstCommand the Naigator: a. UnsuccessfulExecution eent connection: This step creates an Eent-to-method connection such that the returnexecutionunsuccessful method of the Naigator is inoked when an executionunsuccessful eent of Ex02SecondCommand occurs. See the description in Step 5, item 4a to create an Eent-to-method connection between the executionunsuccessful(com.ibm.ij.eab.command.commandeent) eent of Ex02SecondCommand and the returnexecutionunsuccessful(com.ibm.ij.eab.command.commandeent) method of the Naigator. Be sure to click the Pass eent data box before clicking OK in the Eent-to-method connections - Properties window. b. ReturnSuccessfulExecution eent connection: This step creates an Eent-to-method connection such that the returnexecutionsuccessful method of the Naigator is inoked when an executionsuccessful eent of Ex02SecondCommand occurs. See the description in Step 5, item 4a to create an Eent-to-method connection between the executionsuccessful(com.ibm.ij.eab.command.commandeent) eent of Ex02SecondCommand and the returnexecutionsuccessful(com.ibm.ij.eab.command.commandeent) method of the Naigator. Be sure to click the Pass eent data box before clicking OK. c. Execution eent connection: This step creates an Eent-to-method connection to start the execution of the second command when the first command has executed successfully. The execute method of Ex02SecondCommand is inoked when an executionsuccessful eent of the Ex02FirstCommand occurs. Select the Ex02FirstCommand icon and click the right mouse button. Choose Connect > Connectable Features... A Start connection from [Ex02FirstCommand] dialog box appears. Click Eent. Select the executionsuccessful(com.ibm.ij.eab.command.commandeent) eent from the scroll-down the list and click OK. Moe the cursor to Ex02SecondCommand icon and click the left mouse button. Click Connectable Features... An End connection dialog box appears. Chapter 5. Building a Jaa application to run a naigator 101

108 In the End connection to [Ex02SecondCommand] dialog box, click Method. Choose execute(com.ibm.ij.eab.command.commandeent) from the scroll-down list and click OK. A new dotted-line connection is created. Select the new connection and click the right mouse button. Select Properties from the pop-up menu. An Eent-to-method connection properties window appears. Click the Pass eent data box and click OK. The connection is now a solid line. d. Properties connections: This step sets up the input properties for the Ex02SecondCommand bean. In this example, the second command takes input in the form of the SECOND_CMD_IN_TRCD and SECOND_CMD_IN_CMD which are set in the Jaa application that runs the Naigator and also from the output of the first command, in this case the OUT_NAME1 property. Note that the properties of Ex02SecondCommand that are not set do not need to be set in this case only because we hae set up Ex02SecondCommand to execute an IVTNO DISPLAY command. Had we chosen to make Ex02SecondCommand execute another ADD command, we would hae had to set the other input properties accordingly. Otherwise, those fields in the record added to the database used by IVTNO would be blank. 1) Input Properties from first command: This step creates property-to-property connections between the output properties of Ex02FirstCommand and the input properties of Ex02SecondCommand. These connections are used to propagate the output alues from Ex02FirstCommand to Ex02SecondCommand as its input alues. Select the Ex02FirstCommand icon and click the right mouse button. Choose Connect > Connectable Features... Click Property. Select OUT_NAME1 property from the scroll-down the list and click OK. Place the cursor to Ex02SecondCommand icon and click the left mouse button. Click Connectable Features... An End connection to [Ex02SecondCommand] dialog box appears. In the End connection to [Ex02SecondCommand] dialog box, click Property. Select IN_NAME1 property from the scroll-down list and click OK. Right-click the connection just created and select Properties. Select propertychange as the source eent in the resulting Property-to-property connection - Properties window and click OK. A new connection between the OUT_NAME1 property of the Ex02FirstCommand bean and the IN_NAME1 property of the Ex02SecondCommand bean is created. 2) Input properties from the Naigator bean: This step creates property-to-property connections between the input property features of the Naigator and the input properties of Ex02SecondCommand. These connections are used to propagate the input alues from the input property features of the Naigator to Ex02SecondCommand as its input alues. See the description aboe in Step 5, item c to create property-to-property connections between the following input property features of the Naigator and the input properties of the Ex02SecondCommand bean: SECOND_CMD_IN_LL > IN LL SECOND_CMD_IN_ZZ > IN ZZ 102 IMS Connector for Jaa User s Guide and Reference

109 SECOND_CMD_IN_TRCD > IN TRCD SECOND_CMD_IN_CMD > IN CMD e. Result property connections: This step connects the output properties of the second command with the Naigator bean so that the results can be accessed and returned to the user. It creates property-to-property connections between the output property features of the NaigatorEx02SecondCommand and the properties of Ex02SecondCommandoutput property features of the Naigator and the properties of Ex02SecondCommand. These connections are used to propagate the output alues from Ex02SecondCommand to the output property features of the Naigator. See the description in Step 5, item c to create property-to-property connections between the following output properties of the Ex02SecondCommand bean and the output property features of the Naigator: Remember to start the result property connections by right-clicking on the Ex02SecondCommand icon and end them by clicking in an open area of the Naigator Visual Composition window. Be sure to select propertychange for the Source eent in the Property-to-property connection - Properties window. OUT LL > OUT_LL OUT ZZ > OUT_ZZ OUT MSG > OUT_MSG OUT CMD > OUT_CMD OUT NAME1 > OUT_NAME1 OUT NAME2 > OUT_NAME2 OUT EXTN > OUT_EXTN OUT ZIP > OUT_ZIP OUT SEGNO > OUT_SEGNO 4. This step adds the DFS output message method feature of the second command so that the Naigator bean can display the DFS message from the second command. Do the following: a. Select the Ex02SecondCommand icon and click the right mouse button. Choose Promote Bean Features... A new window appears. b. Ensure that the Method radio button is selected and moe the GetDFSMessage() method from the left pane to the Promoted features section by highlighting and clicking the >> button. Click OK. A new ex02secondcommandgetdfsmessage() method is created in the Ex02Naigator bean. Sae the Ex02SecondCommand bean by clicking on Bean > Sae Bean. This will sae the Ex02SecondCommand bean and generate the runtime code associated with this bean, some of which will be modified as described in the next paragraph. On your Workbench, expand the Ex02Naigator class and select the connetom5(commandeent) method. In the Source pane, add the following code in the user code {1} block (after the line that reads // user code begin {1}): System.out.println( The output from Ex02FirstCommand is: + \n + \nll: + getout_ll() + Chapter 5. Building a Jaa application to run a naigator 103

110 \nzz: + getout_zz() + \nmsg: + getout_msg() + \ncmd: + getout_cmd() + \nname1: + getout_name1() + \nname2: + getout_name2() + \nextn: + getout_extn() + \nzip: + getout_zip() + \nsegno: + getout_segno() + \n + \n + \nbeginning execution of Ex02SecondCommand... + \n ); This code will cause the aboe lines to be displayed on the output screen (the Jaa console) after Ex02FirstCommand has executed successfully but before the start of execution of Ex02SecondCommand. Sae this change by again clicking on the connetom5(commandeent) method and then click on Yes. Step 7: Set Up the Connection Specification for the Naigator (Optional) This step sets up a separate connection specification for the Ex02Naigator bean so that all of the EAB commands in the Naigator can use the same connection specification. This is an optional step since each EAB command already has its own connection spec. If you choose to create a connection spec in the Naigator, its attributes and methods will oerride those of all EAB commands that are part of the Naigator. Do the following: 1. In the Visual Composition Editor, click Choose Bean... again and click Browse. In the Pattern field, enter IMSConnectionSpec. A list of class names appears. Choose IMSConnectionSpec (in package com.ibm.connector.imstoc) for the Class name from the list of aailable classes. Click OK on this and the preious window. 2. To plant the bean, moe the cursor to a position in the frame window and click the left mouse button. By default, it is assigned the name IMSConnectionSpec1. 3. To connect the bean to the Naigator, select the IMSConnectionSpec1 icon and click the right mouse button. Choose Connect > this, then moe the cursor to an empty area in the frame window and click the left mouse button. Select ConnectionSpec from the Property list that appears and click OK. 4. Double click the IMSConnectionSpec1 icon to iew the bean properties. Specify the bean properties as follows: beanname Leae as is. Connection timeout If you want to proide additional connection properties, see the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of this property. Host name Enter the TCP/IP host name of the machine running IMS Connect that the Naigator (IMS transaction) will be using. 104 IMS Connector for Jaa User s Guide and Reference

111 Maximum connections If you want to proide additional connection properties, see the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of this property. Minimum connections If you want to proide additional connection properties, see the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of this property. Port Enter the port for IMS Connect that the Naigator (IMS transaction) will be using. Reap time If you want to proide additional connection properties, see the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of this property. Unused timeout If you want to proide additional connection properties, see the interface com.ibm.connector.connectionspecmanagementproperties in package com.ibm.connector of the Enterprise Access Builder for a description of this property. Realm The Realm property defines a unique name for a remote target to which the client Jaa application or serlet is connecting. The Realm property is used by the infrastructure LogonInfo of the component serer for mapping security information. For example, it maps the client information to the user information. The component serer that supports the Realm property proides the appropriate alue. 5. Optionally, promote the Host name and Port property features, as follows: a. In the Visual Composition Editor, select the IMSConnectionSpec1 icon and click the right mouse button. b. Select Promote bean feature... A new window appears. c. Ensure that the Property radio button is selected and moe the Host name and Port properties from the left pane to the Promoted features section by highlighting and clicking the >> button. Then click the OK button. Step 8: Promote InteractionSpec Property Features (Optional) In this step you will promote the datastorename and DFSDATA1 bean features of the IMSInteractionSpec beans used by the EAB commands Ex02FirstCommand and Ex02SecondCommand to the interface of the composite Naigator bean. This is an optional step that you would complete if you want your Jaa application or serlet to be able to dynamically accept alues for and set property features of the IMSInteractionSpec beans used by the EAB commands in your Naigator. Chapter 5. Building a Jaa application to run a naigator 105

112 Promote the datastorename and DFSDATA1 property features of the IMSInteractionSpec for each of the EAB commands in the Naigator as follows: 1. In the Visual Composition Editor, select the Ex02FirstCommand icon and click the right mouse button. 2. Select Promote bean feature... A new window appears. 3. Ensure that the Property radio button is selected and moe the datastorename and DFSDATA1 property features from the left pane to the Promoted features section by highlighting each property feature, and clicking the >> button and then clicking the OK button. 4. Repeat steps a. b. and c. to promote the datastorename and DFSDATA1 properties of the Ex02SecondCommand bean. Step 9: Sae the Naigator Bean Click the Bean menu and click Sae Bean to sae your work. This is the final step in creating the Naigator composite command bean. You can use this bean (Naigator) to run two IMS transactions. Figure 8. The completed naigator bean as shown in the Visual Composition Editor Writing a Jaa Application to Use a Naigator 106 IMS Connector for Jaa User s Guide and Reference

113 The following example illustrates how you can use the EAB Naigator created in Creating a Naigator Using the Command and Visual Composition Editors to create a Jaa application. You can use the Jaa application to run two consecutie IMS transactions. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create an Executable Class 3. Add Jaa Code to the Class Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction (Step 3A) Step 2: Create an Executable Class For the description of how to create a new executable class, see Building a Jaa application to run an IMS transaction (Step 3B). The sample code for this section uses Ex02NaigatorExecute for the name of the executable class. Step 3: Add Jaa Code to the Class Code must be added to the main() method of the Ex02NaigatorExecute class to use the EAB command to run the IMS transaction. This code can be copied from the main() method of the Ex02NaigatorExecute class in package com.ibm.connector.ims.sample.phonebook.naigator in the Connector IMS Samples project on your Workbench. Place the user ID, password, and group name to be sent to IMS in the fields youruid, yourpwd, and yourgrp, respectiely. Testing the Jaa Application To test the Jaa application within VisualAge for Jaa, see Building a Jaa application to run an IMS transaction (Step 4). Running the Jaa Application To run the Jaa application with the Naigator outside of VisualAge for Jaa, see Building a Jaa application to run an IMS transaction (Step 5.) Chapter 5. Building a Jaa application to run a naigator 107

114 108 IMS Connector for Jaa User s Guide and Reference

115 Chapter 6. Building a Jaa application for an IMS transaction with multi-segment output messages This section describes how to build a Jaa application that processes an IMS transaction that has a single-segment input message and an output message with multiple segments. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at This example corresponds to one of the samples included in the IMS Connector Samples feature. The Jaa source relating to this example is contained in the com.ibm.connector.ims.sample.multisegout package of the Connector IMS Samples project which is added to your workspace when the IMS Connector Samples feature is added. See Preparing your VisualAge for Jaa enironment for instructions on installing the IMS Connector Samples feature if you hae not already done so. By following the instructions in this section, you will create an application which is the same as the corresponding sample except that it uses different project and package names than are used in the sample since you can t hae duplicate package or project names within your VisualAge enironment. As a result, you will be able to check your work against the sample, helping you to resole any difficulties you encounter as you progress through the steps that follow. Note: The Jaa application might not be executable, because the corresponding IMS application program might not be aailable in all enironments. The IMS application program used with the sample code in this section is DFSDDLT0. The DFSDDLT0 script for this sample, MSOut.scr is proided in the <IBM_Connectors_install_dir> \imsconn\samples\misc. The following stage 1 source was used in the IMS enironment of this example: APPLCTN PSB=STLDDLT2, PGMTYPE=(,,2) TRANSACT CODE=SKS2, PRTY=(8,8) The PSB and CODE alues can be changed to match your IMS system definition requirements. The PSB requires only an I/O PCB. It does not require alternate PCBs or database PCBs. Related Reading: For information on using DFSDDLT0, see the IMS Application Programming: Design Guide. The processing of a multiple segment output message differs from that of a single segment output message in that the transaction output is represented by a class that implements the IByteBuffer interface of the IBM Jaa Record Library, rather than a transaction output message bean created by the VisualAge for Jaa Enterprise Access Builder. The IMS Connector for Jaa populates the byte array of the output class with the transaction output message. The Jaa application extracts the indiidual segments from the byte array and uses them to set the alues of the output segment objects. The output segment objects are created using the VisualAge for Jaa Enterprise Access Builder from COBOL 01 descriptors of the indiidual message segments. Copyright IBM Corp. 1998,

116 Related Reading: For information on building a Jaa application that processes an IMS transaction that has an input message with multiple segments and a single-segment output message, see Building a Jaa application for an IMS transaction with multi-segment input messages. A method for building a Jaa application for an IMS transaction with multi-segment output messages is coered by the following sections: 1. Creating an EAB Command Using the Command Editor 2. Writing a Jaa Application to Use the EAB Command 3. Testing Your Application within VisualAge for Jaa 4. Running Your Application outside of VisualAge for Jaa Some of the steps in the following sections are not described in detail, since they are coered by earlier sections. Creating an EAB Command Using the Command Editor This section describes how you create an EAB command for an IMS transaction with a multi-segment output message using the Command Editor. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create a Project and Package for the Application 3. Create a COBOL Record Type Class for the IMS Transaction Input Message 4. Create a Transaction Input Message Record Bean 5. Create a Transaction Output Message Class that Implements IByteBuffer 6. Create COBOL Record Type Classes for the Output Message Segments 7. Create Record Beans for the Output Message Segments 8. Create a Command Class for the IMS Transaction 9. Set Up the Interaction Specification for the Command 10. Set Up the Connection Specification for the Command 11. Set Up the Command Input 12. Set Up the Command Output 13. Create the Command Bean Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 1A. Step 2: Create a Project and Package for the Application For a description of this step, see Building a Jaa application to run an IMS transaction: Step 1B. The package used by the sample code for this section is multisegout. 110 IMS Connector for Jaa User s Guide and Reference

117 Step 3: Create a COBOL Record Type Class for the IMS Transaction Input Message For a description of how to create a COBOL Record Type class from the COBOL source for an IMS input message, see Building a Jaa application to run an IMS transaction: Step 1C. The COBOL source for the input message can be found in file MSOut.ccp in <IBM_Connectors_install_dir>\imsconn\samples\misc, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. Step 4: Create a Transaction Input Message Record Bean For a description of how to create a transaction input message record bean from a COBOL Record Type class, see Building a Jaa application to run an IMS transaction: Step 1D. The sample code for this section uses InMsg for the name of the input message record bean. Step 5: Create a Transaction Output Message Class that Implements IByteBuffer This step creates a class that implements the IByteBuffer interface of the package com.ibm.record of the IBM Jaa Record Library. 1. With the package multisegout selected, click the Selected menu, then select Add >Class... The Create Class wizard appears. 2. Ensure that the correct names appear in the Project and Package entry fields. 3. Select the Create a new class radio button. Enter a name for the new class (for example, AllSegs), and ensure that the superclass is jaa.lang.object. 4. Ensure that the Browse the class when finished and the Compose the class isually check boxes are not checked. 5. Select the Next button. The Attributes wizard appears. 6. Enter com.ibm.record.ibytebuffer in the Which interfaces should this class implement? list. 7. Check the public check box and the recommended check boxes under Which method stubs would you like to create?. 8. Select the Finish button to create the class. 9. Modify the code generated for the class by VisualAge for Jaa as follows: a. Add the following priate field to the AllSegs class: priate byte[] bytes; b. Modify the checkbytes method so that it returns true instead of false. return true; c. Modify the getbytes method so that it returns the priate field bytes. return bytes; d. Modify the setbytes method so that it sets the priate field bytes. bytes = arg1; Step 6: Create COBOL Record Type Classes for the Output Message Segments Chapter 6. Building a Jaa application for an IMS transaction with multi-segment output messages 111

118 For a description of how to create a COBOL Record Type class from COBOL source, see Building a Jaa application to run an IMS transaction: Step 1E. Create a COBOL Record Type for each segment of the output message. The COBOL source for the output message segments can be found in file MSOut.ccp in <IBM_Connectors_install_dir>\imsconn\samples\misc, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. Step 7: Create Record Beans for the Output Message Segments For a description of how to create a record bean from a COBOL Record Type class, see Building a Jaa application to run an IMS transaction: Step 1D. Create three record beans, OutSeg1, OutSeg2, and OutSeg3. Step 8: Create a Command Class for the IMS Transaction For a description of how to create a command class, see Building a Jaa application to run an IMS transaction: Step 2A. The command class used by the sample code for this section is MSOutCommand. After completing this step, you will be working in the Command Editor. Step 9: Set Up the Interaction Specification for the Command For a description of how to set up the Interaction Specification for the command, see Building a Jaa application to run an IMS transaction: Step 2E. This includes adding the IMSInteractionSpec bean, connecting it to the EAB command, and promoting the Datastore Name property. Step 10: Set Up the Connection Specification for the Command For a description of how to set up the Connection Specification for the command, see Building a Jaa application to run an IMS transaction: Step 2F. This includes adding the IMSConnectionSpec bean, connecting it to the EAB command, and promoting the Host name and Port properties. Step 11: Set Up the Command Input For a description of how to set up the command input, see Writing a Jaa application to use the EAB command. (page 113) This includes adding the InMsg bean, connecting it to the EAB command, and promoting the LL, ZZ, TRCD, DATA1, and DATA2 properties. Step 12: Set Up the Command Output For a description of how to set up the IMS transaction output, see Building a Jaa application to run an IMS transaction: Step 4) In this case, the class that implements IByteBuffer (AllSegs) is associated with the command output. After adding the AllSegs bean and connecting it to the command, promote the bytes property of the bean. Step 13: Create the Command Bean For a description of how to create the composite EAB command bean, see Building a Jaa application to run an IMS transaction: Step 2G. 112 IMS Connector for Jaa User s Guide and Reference

119 Figure 9. The completed EAB command as shown in the Visual Composition Editor Writing a Jaa Application to Use the EAB Command This section describes how you use the EAB command created in the preious section in a Jaa application. The descriptions that follow are based on the Jaa code in the package com.ibm.connector.ims.sample.multisegout. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create an Executable Class 3. Add Jaa Code to the Class Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 3A. Step 2: Create an Executable Class For a description on how to create an executable class, see Building a Jaa application to run an IMS transaction: Step 3B. The sample code for this section uses ExecuteMSOutCommand for the name of the executable class. In addition, the import statements needed for the sample code are: import jaa.util.stringtokenizer; import jaa.io.*; Step 3: Add Jaa Code to the Class Chapter 6. Building a Jaa application for an IMS transaction with multi-segment output messages 113

120 Code must be added to the main() method of the ExecuteMSOutCommand class to use the EAB command to run the IMS transaction. This code can be copied from the main() method of the ExecuteMSOutCommand class in the package com.ibm.connector.ims.sample.multisegment in the Connector IMS Samples project on your Workbench. Replace the alues youruid, yourpwd, and yourgrp with a user ID, password, and group name, as appropriate for your IMS enironment. The code in the main method, up to and including execution of the EAB command, is similar to the Jaa applications discussed in earlier sections. After running the EAB command, the output of the command is retrieed using the following line: segbytes = cmd.getbytes(); This output can be either the output of the IMS transaction or a DFS message from IMS. The method getallsegsbytes retriees an EBCDIC byte array. The code in the main method passes the EBCDIC byte array to the checkbytes method of the DFSMsg class to determine if the output receied is a DFS message from IMS. If it is, the DFS message is printed; if not, the output is assumed to be from the transaction, and it is also printed. To print the DFS message, the adfsmsg object must first be populated with data by passing the EBCDIC array to the setbytes method: adfsmsg.setbytes( segbytes ); The setbytes method conerts the data from EBCDIC to UNICODE. The code in the main method shows three methods for printing DFS messages from IMS, as follows: 1. The indiidual fields of two of the segments of the message are printed using get methods for the fields (adfsmsg.getdfsll1(), adfsmsg.getdfszz1(), adfsmsg.getdfsdata1(), etc.) 2. Method getdfsmessage returns a string that is a concatenation of the data portion of the segments of the DFS message: System.out.println( \noutput of getdfsmessage is: + adfsmsg.getdfsmessage() ); 3. Method getdfsmessagesegments returns a ector of the data portion of the segments of the DFS message, which can be used with an enumeration to print the indiidual data portion of the segments of the DFS message: en = (adfsmsg.getdfsmessagesegments()).elements(); System.out.println( \ndfs Message Segments are: ); while( en.hasmoreelements() ) { System.out.println( \n + en.nextelement() ); } If the output receied is not a DFS message, it is assumed to be transaction output. The indiidual segment objects are populated by doing the following: 1. Extracting the data for a segment from the buffer containing the command output (segbytes) to a byte array (buff): buff = new byte[ LL ]; System.arraycopy( segbytes, srcpos, buff, dstpos, LL ); 2. Using the resulting byte array as input to the setbytes method of the corresponding segment: OutSeg2 S2 = new OutSeg2(); S2.setBytes( buff ); 114 IMS Connector for Jaa User s Guide and Reference

121 The setbytes method conerts the data from EBCDIC to UNICODE. The code in the main() method also illustrates printing the data fields of the segment and adding the segment objects to a ector. Testing Your Application within VisualAge for Jaa For a description of how to test your application within VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 4. If you choose to execute the application using the DFSDDLT0 script proided, the console output should be as follows: OutSeg1 LL is: 16 OutSeg1 ZZ is: 768 OutSeg1_DATA1 is: *******M1SO1 OutSeg2 LL is: 31 OutSeg2 ZZ is: 768 OutSeg2_DATA1 is: ********M1SO2 OutSeg2_DATA2 is: *********M2SO2 OutSeg3 LL is: 52 OutSeg3 ZZ is: 768 OutSeg3_DATA1 is: **********M1SO3 OutSeg3_DATA2 is: ***********M2SO3 OutSeg3_DATA3 is: ************M3SO3 Running Your Application outside of VisualAge for Jaa For a description on running your application outside of VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 5. Chapter 6. Building a Jaa application for an IMS transaction with multi-segment output messages 115

122 116 IMS Connector for Jaa User s Guide and Reference

123 Chapter 7. Building a Jaa application for an IMS transaction with multi-segment input messages This section describes how to build a Jaa application that processes an IMS transaction that has a multiple-segment input message and a single-segment output message. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at This example corresponds to one of the samples included in the IMS Connector Samples feature. The Jaa source relating to this example is contained in the com.ibm.connector.ims.sample.multisegin package of the Connector IMS Samples project which is added to your workspace when the IMS Connector Samples feature is added. See Preparing your VisualAge for Jaa enironment for instructions on installing the IMS Connector Samples feature if you hae not already done so. By following the instructions in this section, you will create an application which is the same as the corresponding sample except that it uses different project and package names than are used in the sample since you can t hae duplicate package or project names within your VisualAge enironment. As a result, you will be able to check your work against the sample, helping you to resole any difficulties you encounter as you progress through the steps that follow. Note: The Jaa application might not be executable, because the corresponding IMS application program might not be aailable in all enironments. The IMS application program used with the sample code in this section is DFSDDLT0. The DFSDDLT0 script for this sample, MSIn.scr, can be found in <IBM_Connectors_install_dir>\imsconn\ samples\misc The following stage 1 source was used in the IMS enironment of this example: APPLCTN PSB=STLDDLT2, PGMTYPE=(,,2) TRANSACT CODE=SKS2, PRTY=(8,8) The PSB and CODE alues can be changed to match your IMS system definition requirements. The PSB requires only an I/O PCB. It does not require alternate PCBs or database PCBs. Related Reading: For information on using DFSDDLT0, see the IMS Application Programming Guide. The process for processing a multiple-segment input message differs from that of a single-segment input message, in that the transaction input is represented by a class that implements the IByteBuffer interface of the IBM Jaa Record Library, rather than a transaction input message bean created by the VisualAge for Jaa Record Generator. The Jaa application populates indiidual input segment objects, then builds the transaction input buffer. The input segment objects are created using the VisualAge for Jaa Record Generator from COBOL 01 descriptors of the indiidual message segments. A method for building a Jaa application for an IMS transaction with multiple-segment input messages is coered in the following sections: 1. Creating an EAB Command Using the Command Editor 2. Writing a Jaa Application to Use the EAB Command Copyright IBM Corp. 1998,

124 3. Testing Your Application within VisualAge for Jaa 4. Running Your Application outside of VisualAge for Jaa Seeral of the steps in the sections that follow are not described in detail, because they are coered in earlier sections. Creating an EAB Command Using the Command Editor This section describes how you create an EAB command for an IMS transaction with a multi-segment input message using the Command Editor. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create a Project and Package for the Application 3. Create COBOL Record Type Classes for the Input Message Segments 4. Create Record Beans for the Input Message Segments 5. Create a Transaction Input Message Class that Implements IByteBuffer 6. Create a COBOL Record Type Class for the IMS Transaction Output Message 7. Create a Transaction Output Message Record Bean 8. Create a Command Class for the IMS Transaction 9. Promote the IMS Transaction Input Properties 10. Promote the IMS Transaction Output Properties 11. Promote the DFS Message Properties 12. Promote the Interaction Specification Properties 13. Promote the Connection Specification Properties 14. Create the Command Bean Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 1A. Step 2: Create a Project and Package for the Application For a description of this step, see Building a Jaa application to run an IMS transaction: Step 1B. The package used by the sample code for this section is multisegin. Step 3: Create COBOL Record Type Classes for the Input Message Segments For a description of how to create a COBOL Record Type class from the COBOL source for an IMS input message, see Building a Jaa application to run an IMS transaction: Step 1C. Create a COBOL Record Type for each segment of the input message. The COBOL source for the input message segments can be found in file MsIn.cpp, located in <IBM_Connectors_install_dir>\imsconn\samples\misc, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. For example, d:\ibm Connectors. Step 4: Create Record Beans for the Input Message Segments 118 IMS Connector for Jaa User s Guide and Reference

125 For a description of how to create a record bean from a COBOL Record Type class, see Building a Jaa application to run an IMS transaction: Step 1D. Create four record beans: InSeg1, InSeg2, InSeg3, and InSeg4. Step 5: Create a Transaction Input Message Class that Implements IByteBuffer This step creates a class that implements the IByteBuffer interface of the package com.ibm.record of the IBM Jaa Record Library. 1. With the package multisegin selected, click the Selected menu, then select Add > Class... The Create Class wizard appears. 2. Ensure that the correct names appear in the Project and Package entry fields. 3. Select the Create a new class radio button. Enter a name for the new class (for example, AllInSegs), and ensure that the superclass is jaa.lang.object. 4. Ensure that the Browse the class when finished and the Compose the class isually check boxes are not checked. 5. Select the Next button. The Attributes wizard appears. 6. Enter com.ibm.record.ibytebuffer in the Which interfaces should this class implement? list. 7. Check the public check box and the recommended check boxes under Which method stubs would you like to create?. 8. Select the Finish button to create the class. 9. Modify the code generated for the class by VisualAge for Jaa as follows: a. Add the following priate field to the AllInSegs class: priate byte[] bytes; b. Modify the checkbytes method so that it returns true instead of false. return true; c. Modify the getbytes method so that it returns the priate field bytes. return bytes; d. Modify the setbytes method so that it sets the priate field bytes. bytes = arg1; Step 6: Create a COBOL Record Type Class for the IMS Transaction Output Message For a description of how to create a COBOL Record Type class from the COBOL source for an IMS output message, see Building a Jaa application to run an IMS transaction: Step 1E. The COBOL source for the output message can be found in file MsIn.cpp, located in <IBM_Connectors_install_dir>\imsconn\samples\misc, where <IBM_Connectors_install_dir> is the IBM Connectors installation directory. Step 7: Create a Transaction Output Message Record Bean For a description of how to create a transaction output message record bean from a COBOL Record Type class, see Building a Jaa application to run an IMS transaction: Step 1F. The sample code for this section uses OutMsg for the name of the output message record bean. Step 8: Create a Command Class for the IMS Transaction Chapter 7. Building a Jaa application for an IMS transaction with multi-segment input messages 119

126 For a description of how to create a command class, see Building a Jaa application to run an IMS transaction: Step 2A. Briefly, use the Command Editor to create an EAB command with name MSInCommand that includes an interaction specification of IMSInteractionSpec, a connection specification of IMSConnectionSpec, the AllInSegs input record bean, and output record beans of OutMsg and DFSMsg. Step 9: Promote the IMS Transaction Input Properties For a description of how to promote properties of an input record bean, see Building a Jaa application to run an IMS transaction: Step 2B. In this case, promote the bytes property of the AllInSegs Input record bean. Step 10: Promote the IMS Transaction Output Properties For a description of how to promote properties of an output record bean, see Building a Jaa application to run an IMS transaction: Step 2C. In this case, promote the LL, ZZ, and DATA1, properties of the OutMsg Output record bean. Step 11: Promote the DFS Message Properties For a description of how to promote properties of the DFSMsg output record bean, see Building a Jaa application to run an IMS transaction: Step 2D. In this case, promote the methods getdfsmessage and getdfsmessagesegments, as well as the DFSDATA1 property of the DFSMsg output record bean. Step 12: Promote the Interaction Specification Properties For a description of how to promote properties of an interaction specification, see Building a Jaa application to run an IMS transaction: Step 2E. In this case, promote the Datastore Name property of the IMSInteractionSpec record bean. Step 13: Promote the Connection Specification Properties For a description of how to promote properties of an connection specification, see Building a Jaa application to run an IMS transaction: Step 2F. In this case, promote the Host name and Port properties of the IMSConnectionSpec record bean. Step 14: Create the Command Bean For a description of how to sae the command bean, see Building a Jaa application to run an IMS transaction: Step 2G. 120 IMS Connector for Jaa User s Guide and Reference

127 Figure 10. The completed EAB command as shown in the Command Editor Writing a Jaa Application to Use the EAB Command This section describes how you use the EAB command created in the preious section in a Jaa application. The descriptions that follow are based on the Jaa code in the package com.ibm.connector.ims.sample.multisegin. The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create an Executable Class 3. Add Jaa Code to the Class Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 3A. Step 2: Create an Executable Class For a description on how to create an executable class, see Building a Jaa application to run an IMS transaction: Step 3B. The sample code for this section uses MSInCommandExecute for the name of the executable class. In addition, the import statements needed for the sample code are: import jaa.util.stringtokenizer; import jaa.io.*; Step 3: Add Jaa Code to the Class Chapter 7. Building a Jaa application for an IMS transaction with multi-segment input messages 121

128 Code must be added to the main() method of the MSInCommandExecute class to use the EAB command to run the IMS transaction. This code can be copied from the main() method of the MSInCommandExecute class in package com.ibm.connector.ims.sample.multisegin in the Connector IMS Samples project on your Workbench. Replace the alues youruid, yourpwd, and yourgrp with a user ID, password, and group name that is appropriate for your IMS enironment. The code in the main method, up to and including proiding a Connection Manager for the runtime context is similar to the Jaa applications that are discussed in earlier sections. Following execution of set methods for host name, port, and datastore, each segment object is instantiated and populated with transaction input data as follows: multisegin.inseg1 seg1 = (InSeg1)jaa.beans.Beans.instantiate(null, multisegin.inseg1 ); seg1.setin LL( (short)14 ); seg1.setin ZZ( (short)0 ); seg1.setin TRCD( SKS2 ); seg1.setin DATA1( SI1M1 ); A buffer is allocated to hold the data of the indiidual segments, then the getbytes() method is inoked for each segment to obtain the segment data in EBCDIC. The EBCDIC segment data is then placed in the buffer: msginbuff = new byte[seg1.getin LL() + seg2.getin LL() + seg3.getin LL() + seg4.getin LL()]; buff = null; srcpos = 0; dstpos = 0; buff = seg1.getbytes(); totallen = buff.length; System.arraycopy( buff, srcpos, msginbuff, dstpos, totallen ); dstpos = dstpos + totallen; Finally, the buffer containing the data of the indiidual segments is used to populate the AllInSegs object as follows: // // Use buffer to populate input object (AllInSegs). // cmd.setbytes( msginbuff ); The remainder of the main method is similar to Jaa applications discussed earlier and includes execution of the EAB command followed by processing of the IMS transaction output. Testing Your Application within VisualAge for Jaa For a description of how to test your application within VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 4. If you choose to execute the application using the DFSDDLT0 script proided, the console output should be as follows: Output from transaction is... LL: 8 ZZ: 768 DATA1: JI IMS Connector for Jaa User s Guide and Reference

129 Running Your Application outside of VisualAge for Jaa For a description on running your application outside of VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 5. Related Reading: For information on building a Jaa application that processes an IMS transaction that has a single-segment input message and an output message with multiple segments, see Building a Jaa application for an IMS transaction with multi-segment output messages. Chapter 7. Building a Jaa application for an IMS transaction with multi-segment input messages 123

130 124 IMS Connector for Jaa User s Guide and Reference

131 Chapter 8. Building an application to run an IMS transaction with synchronization leel confirm This section discusses two ways in which you can build a Jaa application that runs an IMS transaction with a synchronization leel of Confirm. The instructions in this section demonstrate methods in which two EAB commands are created, in addition to the EAB command that runs the transaction. These two commands are created with InteractionSpec modes of MODE_ACK and MODE_NACK, and are used to send positie and negatie acknowledgements to IMS. This method is used when the coordinator used by the runtime context of the Jaa application is not coordinating; for example, if NullCoordinator is used. The second method is used if the coordinator of the runtime context of the Jaa application is coordinating; for example, if JaaCoordinator is used. In this case, it is recommended that you use the commit() and rollback() methods of the coordinator to send positie and negatie acknowledgements to IMS. Instructions for this method are not included in this section; howeer, the source code is proided in the Ex04ExecuteWithCoordinator class in package com.ibm.connector.ims.sample.phonebook.confirm in the Connector IMS Samples project on your Workbench. For information on the synchronization leel of an interaction of a command and the different scenarios to build a Jaa application that runs an IMS transaction with synchronization leel Confirm, see IMS Connector for Jaa concepts and terms: Synchronization Leel. This example uses the IMS transaction that is described in the IMS INSTALL/IVP sample application, and corresponds to one of the samples included in the IMS Connector Samples feature. The Jaa source relating to this example is contained in the com.ibm.connector.ims.sample.phonebook.confirm package of the Connector IMS Samples project which is added to your workspace when the IMS Connector Samples feature is added. See Preparing your VisualAge for Jaa enironment for instructions on installing the IMS Connector Samples feature if you hae not already done so. By following the instructions in this section, you will create an application which is the same as the corresponding sample, with the exception that your sample uses different project and package names than are used in the sample since you can t hae duplicate package or project names within your VisualAge enironment. As a result, you will be able to check your work against the sample, helping you to resole any difficulties you encounter as you progress through the steps that follow. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at Creating the MODE_ACK and MODE_NACK EAB commands The following steps create commands to run an IMS transaction with Synchronization leel Confirm when using MODE_ACK and MODE_NACK commands to send positie and negatie acknowledgements to IMS: Copyright IBM Corp. 1998,

132 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create a Project and Package for the Application 3. Create a Command to Execute the IMS Transaction 4. Create a Command for the MODE_ACK Interaction 5. Create a Command for the MODE_NACK Interaction Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 1A. Step 2: Create a Project and Package for the Application For a description of this step, see Building a Jaa application to run an IMS transaction: Step 1B. The package used by the sample code for this section is ex04. Step 3: Create a Command to Execute the IMS Transaction This step creates a command for an IMS transaction with a synchronization leel of Confirm. 1. Create an EAB command with the name, for example, Ex04Command. 2. Edit the interaction specification properties of the command. 3. Select SYNC_LEVEL_CONFIRM for the property Synchronization Leel. Related Reading: For information on how to create and set up a command, see Building a Jaa application to run an IMS transaction: Step 2A. Step 4: Create a Command for the MODE_ACK Interaction This step creates a command for the MODE_ACK interaction with IMS. The MODE_ACK command is used to send a positie acknowledgment to IMS. It informs IMS that the output data has been receied and tells IMS to commit the transaction. 1. Create an EAB command with the name, for example, Ex04AckCommand. Since the MODE_ACK command is not a transaction request, it does not contain any user input or output data. As a result, the MODE_ACK command consists only of the IMSInteractionSpec and IMSConnectionSpec objects. The MODE_ACK command does not contain any input or output objects. 2. Edit the interaction specification properties of the command. Select MODE_ACK for the Mode property. Related Reading: For information on how to create a Command class, see Building a Jaa application to run an IMS transaction: Step 2A Step 5: Create a Command for the MODE_NACK Interaction This step creates a command for the MODE_NACK interaction with IMS. The MODE_NACK command is used to send a negatie acknowledgment to IMS. It notifies IMS that the user is not satisfied with the output data, and requests IMS to roll back the transaction. 126 IMS Connector for Jaa User s Guide and Reference

133 1. Create an EAB command with the name, for example, Ex04NackCommand. Since the MODE_NACK command is not a transaction request, it does not contain any user input or output data. As a result, the MODE_NACK command consists only of the IMSInteractionSpec and IMSConnectionSpec objects. The MODE_NACK command does not contain any input or output objects. 2. Edit the interaction specification properties of the command. Select MODE_NACK for the Mode property. Writing a Jaa Application to Run the Transaction Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 3A. Step 2: Create an Executable Class This step creates an executable class for this example. For a description on how to create an Executable Class using the package created in Step 2 aboe, see Building a Jaa application to run an IMS transaction: Step 3B. Specify Ex04Execute as the name of the class, and a new class named Ex04Execute will be created. Step 3: Add Jaa Code to the Class Code must be added to the main() method of the Ex04Execute class to use the EAB commands to run the IMS transaction and to send positie or negatie acknowledgements to IMS. This code can be copied from the main() method of the Ex04Execute class in package com.ibm.connector.ims.sample.phonebook.confirm in the Connector IMS Samples project on your workbench. Replace the alues for user ID, password, and group name, according to your IMS enironment. Testing the Jaa Application To test the Jaa application within VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 4. Running the Jaa Application To run the Jaa application with the Naigator outside of VisualAge for Jaa, see Building a Jaa application to run an IMS transaction: Step 5. Chapter 8. Building an application to run an IMS transaction with synchronization leel confirm 127

134 128 IMS Connector for Jaa User s Guide and Reference

135 Chapter 9. Building the graphical user interface This example illustrates how you can use the EAB command that you created in Creating an EAB Command Using the Command Editor to create a GUI Jaa application. You can use the Jaa application to run an IMS transaction. This example illustrates only basic concepts, and does not include sophisticated GUI input and output processing. This example corresponds to one of the samples included in the IMS Connector Samples feature. The Jaa source relating to this example is contained in the com.ibm.connector.ims.sample.phonebook.gui package of the Connector IMS Samples project which is added to your workspace when the IMS Connector Samples feature is added. See Preparing your VisualAge for Jaa enironment for instructions on installing the IMS Connector Samples feature if you hae not already done so. By following the instructions in this section, you will create an application which is the same as the corresponding sample except for the fact that your application will use different project and package names than those that are used in the sample, since package or project names cannot be duplicated within your VisualAge enironment. As a result, you will be able to check your work against the sample, helping you to resole any difficulties you encounter as you progress through the steps that follow. Note: The examples in this section are for Windows platforms. For information on other platforms, see the IMS Connector for Jaa Web page located in the IMS Web site at The steps include the following: 1. Start the Workbench in the VisualAge for Jaa IDE 2. Create the Main GUI Dialog Class 3. Add the Import Statements 4. Add Connection Manager and Run-Time Context 5. Create the Main GUI Dialog Interface 6. Create a Command to Execute the IMS Transaction 7. Set Up the IMS Command 8. Finish Step 1: Start the Workbench in the VisualAge for Jaa IDE For a description of how to start the Workbench in the VisualAge for Jaa IDE, see Building a Jaa application to run an IMS transaction: Step 1A. The package used by the sample code for this section is ex03. Step 2: Create the Main GUI Dialog Class From the Selected menu, click Add > Class. A wizard appears to request all of the necessary information to create a class: 1. Ensure that the Project field contains your project name, Examples. 2. Ensure that the Package field contains your package name, ex Click Create a new class. 4. Enter Ex03MainDialog in the Class name field. Copyright IBM Corp. 1998,

136 5. To choose the superclass for class Ex03MainDialog, click Browse, then select JDialog from the TypeNames list. 6. Ensure that jaax.swing is selected as the package name and click OK. 7. Ensure that the Compose the class isually radio button is selected. 8. Click Finish. A new window appears with the Visual Composition tab selected. Step 3: Add the Import Statements You need to import a number of classes when running the executable file. Add the following import statements to the Ex03MainDialog class: import com.ibm.connector.infrastructure.*; import com.ibm.connector.infrastructure.jaa.*; import com.ibm.connector.imstoc.*; import com.ibm.connector.connectionmanager.*; Step 4: Add Connection Manager and Run-Time Context This step adds the run-time context and the connection manager, which is used for the GUI application. Add the following statements to the Ex03MainDialog class: ConnectionManager connmgr = new ConnectionManager(); JaaRuntimeContext runtimecontext = null; Step 5: Create the Main GUI Dialog Interface This step builds a GUI dialog for giing the input alues to the command bean that was created, and for displaying the output alues from the command bean. The GUI interface shown below is built using Swing components. Figure 11. Sample GUI dialog for the IMS Phone Book Application 130 IMS Connector for Jaa User s Guide and Reference

137 Step 6: Create a Command to Execute the IMS Transaction This step creates an EAB command to execute an IMS transaction, as described in Building a Jaa application to run an IMS transaction: Step 2A. Name this command class Ex03Command. When creating the Transaction Input/Ouput Record Beans for the command, make sure to do the following: On the Create Record from Record Type wizard, select the Generate Notification check box under Additional Options. This ensures that appropriate notification is generated when the properties of the record bean are updated. This step uses the Visual Composition Editor to associate the appropriate field alues of IMS command created in the preious step, Step 6: Create a Command to Execute the IMS Transaction, with the GUI dialog to get input from the user. 1. In the Visual Composition Editor, click Choose Bean..., located beneath the Swing pull-down menu. 2. Click Browse to look through a list of aailable classes. In the Pattern field, enter Ex03Command. A list of class names appears. 3. Choose Ex03Command (in package ex03),for the Class name from the list of aailable classes. Click OK on this and the preious window. 4. To plant the bean, moe the cursor to a position in an empty space in the Visual Composition Editor frame window and click the left mouse button. By default, it is assigned the name Ex03Command1. 5. The following connections need to be established: a. Set up the run-time context connection corresponding to this GUI thread. This step creates an Eent-to-Code connection, such that the following block of code is executed when the actionperformed eent of the Submit button occurs (in other words, when the user clicks on the Submit button). Click Submit and click the right mouse button. Choose Connect > actionperformed. Moe the cursor to an empty area in the frame window and click the left mouse button. Click Eent-to-Code... and an Eent-to-Code Connection dialog box appears. In the Eent-to-Code connection dialog box, replace the method with the code below. Replace the alues youruid, yourpwd, and yourgrp with the user ID, password, and group name for your IMS enironment. /** * Setup the runtime context and other property alues to prepare * for the execution of an IMS transaction. Proide the user ID, * password and group name that will be supplied to IMS. * */ public oid setup(ex03command cmd) { // // Set up the runtime context for the current thread. // if (runtimecontext == null) { runtimecontext = new JaaRuntimeContext(); JaaRuntimeContext.setCurrent( runtimecontext ); Chapter 9. Building the graphical user interface 131

138 } // // Proide your enironment s alues for user ID, // password, and group name for the runtime context. // IMSLogonInfoItems logon = new IMSLogonInfoItems( runtimecontext.getlogoninfo(), cmd.getconnectionspec() ); logon.setuser( youruid ); logon.setpassword( yourpwd ); logon.setgroup( yourgrp ); // // Set Connection Manager // runtimecontext.setconnectionmanager( connmgr ); // // Set trace leel. // (JaaRASSerice)runtimeContext.getRASSerice()).setTraceLeel( RASSerice.RAS_TRACE_OFF ); return; } Click OK. Click Yes when prompted with Text has been modified-sae changes? dialog box. A new setup(ex03command cmd) method is created. A new connection is also created. This connection requires a cmd input parameter. To proide the cmd parameter and complete the connection, do the following: 1) Select the new connection and click the right mouse button. 2) Select Connect > cmd. 3) Moe the cursor to the Ex03Command1 bean icon and click the left mouse button. Click this. b. Execute Command connection This connection triggers the execution of the command bean when the submit button of the GUI is clicked: Select the new connection setup(ex03command cmd) created in the preious step and click the right mouse button. Select normalresult. Moe the cursor to the Ex03Command1 bean icon, and click the left mouse button. Click Connectable Features... and an End connection dialog box appears. Make sure that the Method radio button is selected. Scroll down the list to choose the execute() method and click OK. A new connection is created. c. Input alues property connections This step associates the input properties of the command bean to the GUI interface to get input from the user. This step creates property-to-property connections between the input text fields of the GUI and the input properties of the Ex03Command1 bean. Select the LL text input field of the Input Section of the GUI and click the right mouse button. Select Connect > text. Moe the cursor to select the Ex03Command1 icon and click the left mouse button. Click Connectable Features... An End connection dialog box appears. Scroll down the list of properties to choose the IN LL and click OK. 132 IMS Connector for Jaa User s Guide and Reference

139 A property-to-property connection with the LL text input field on the GUI and the IN LL property of the Ex03Command1 bean is created. Select the newly created connection and click the right mouse button. Select Properties. In the source eent box, select caretupdate. Click OK. This keeps the alue of the IN LL property of the command updated when the input text is changed. Repeat the steps aboe to associate the following text field alues of the input section of the GUI with the properties of the command bean: ZZ > IN ZZ Tran Code > IN TRCD Command > IN CMD Name1 > IN NAME1 Name2 > IN NAME2 Extension > IN EXTN Zip >IN ZIP In a property-to-property connection, the ordering of the source and target bean affects how the property alues are updated and synchronized. d. Output alues property connections Similarly, this step associates the output property alues of the command bean with the GUI interface to display the output to the user. See the description in Step 5, item d on how to create property-to-property connections between the following output properties of the Ex03Command1 bean and the output text fields in the Output section of the GUI: OUT LL > LL OUT ZZ > ZZ OUT MSG > Message OUT CMD > Command OUT NAME1 > Name1 OUT NAME2 > Name2 OUT EXTN > Extension OUT ZIP > Zip In a property-to-property connection, the ordering of the source and target bean affects how the property alues are updated and synchronized. In this step, ensure that the property-to-property connections are created with Ex03Command1 as the source bean and the GUI output text fields as the target bean. e. DFS message output connection This connection associates the output DFS message from IMS to the GUI interface. The text alue in the GUI for the DFS message is updated when the output bean of the command returned is a DFSMsg object. 1) Select the Ex03Command1 icon and click the right mouse button. Choose Connect > Connectable Features... A Start connection dialog box appears. 2) Make sure that the Property radio button is selected. Scroll down the list to choose the DFSDATA1 property and click OK. Chapter 9. Building the graphical user interface 133

140 3) Moe the cursor to the DFS Message TextField in the GUI and click the left mouse button. Select text. A property-to-property connection with the DFS Message Text field and the DFSDATA1 property of the Ex03Command1 is created. 4) Select the newly created connection and click on the right mouse button. Select Properties. 5) In the Source Eent box, select propertychange. Click OK. This keeps the alue of the DFS Message Text field updated when the DFSDATA1 property is changed (i.e., a DFS message is returned from IMS). f. Close run-time context connection This connection closes the run-time context when the Close button is clicked and the GUI closes. This step creates an Eent-to-Code connection, such that the following block of code is executed when the actionperformed eent of the Close button occurs (in other words, when the user clicks on the Close button): /** * Close the runtime context for the current thread. */ public oid closeruntimecontext() { // // Commit resources and close the runtime context. // if ( runtimecontext!= null ) { ((JaaCoordinator)runtimeContext.getCoordinator()).commit(); runtimecontext.close(); runtimecontext.remoecurrent(); } // // Dispose the window. // dispose(); System.exit(0); } See the description in Step 5, item a on how to create an Eent-to-Code connection between the actionperformed eent of the Close button and the code. The code in this step does not requires any parameter. Related Reading: For more information on property-to-property connections, see the Visual Composition Editor documentation. Step 8: Finish This is the final step in creating the GUI Application. Click the Bean menu and click Sae Bean to sae your work. The workbench shows the new Ex03MainDialog class. You can modify the handleexception(throwable) method of the Ex03MainDialog class to print messages when exceptions occur. All trace information and exceptions are logged to the console. 134 IMS Connector for Jaa User s Guide and Reference

141 Figure 12. The Completed GUI application Testing the GUI Application To test the GUI application within VisualAge for Jaa, do the following: 1. Select class Ex03MainDialog and, from the Selected menu, click Properties. The Properties for Ex03MainDialog window appears. 2. Select the Class Path tab and make sure that the Include. (dot) in class path and Project path: check boxes are checked. 3. Click Compute Now, and click OK when the class path is computed. This updates the VisualAge for Jaa class path to include your Jaa application. Close the Properties for Ex03MainDialog window. 4. Modify method getex03command1() of class Ex03MainDialog as follows: Replace the alue 0 in the setportnumber method with the port number of your enironment. Replace the alue YourHost in the sethostname method with the host name of your enironment. Replace the alue YourDS in the setdatastorename method with the datastore name of your enironment. 5. Modify method setup(ex03command cmd) of class Ex03MainDialog as follows: Replace the alue youruid in the setuser method with the userid of your enironment. Replace the alue yourpwd in the setpassword method with the password of your enironment. Chapter 9. Building the graphical user interface 135