New Advanced Functions in IBM WebSphere Host Publisher V2.2 Accessing Host Applications from Web Devices Invoke Integration Objects from Web browsers and WAP phones Interface with your mainframe applications using XML content Access host applications from Java, Perl, C++ Juan R. Rodriguez Roy Froehlich ibm.com/redbooks
SG24-5964-00 International Technical Support Organization New Advanced Functions in IBM WebSphere Host Publisher V2.2 Accessing Host Applications from Web Devices December 2000
Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix B, Special notices on page 183. First Edition (December 2000) This edition applies to Version 2.2 of IBM WebSphere Host Publisher for use with the Windows NT operating system. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 678 P.O. Box 12195 Research Triangle Park, NC 27709-2195 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. Copyright International Business Machines Corporation 2000. All rights reserved. Note to U.S Government Users Documentation related to restricted rights Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents Preface....vii The team that wrote this redbook.... vii Commentswelcome...viii Chapter 1. Introduction...1 1.1 Overview...1 1.2 XMLGateway...5 1.2.1 HTML Mapper....5 1.3 RemoteIntegrationObjects(RIO)...6 1.3.1 Components.....7 1.4 Hostsimulatortool...8 Chapter 2. Installation...11 2.1 Overview...11 2.2 HostPublisherStudioinstallation...11 2.3 HostPublisherServerinstallation...12 2.3.1 Webbrowserinstallation...15 2.3.2 WebServerinstallation...15 2.3.3 HostPublisherServer2.2installation...19 2.3.4 UninstallingHostPublisher...25 Chapter 3. XML Legacy Gateway....27 3.1 Overview...27 3.1.1 XLGW components.....28 3.2 XMLgatewaylimitations...29 3.3 HTMLtoHostsampleprogram...29 3.4 Sample Scenario.....33 3.5 UsingtheHTML-to-Hostemulator...34 3.6 XMLLegacyGatewayJavaBeaninterface...39 3.6.1 The xmllegacygateway servlet......39 3.6.2 ThexmlAppDataJavaBean...41 3.6.3 HostConnection JavaBean.....45 3.7 SampleXMLdocumenttree...45 3.8 Problemdetermination...46 3.8.1 Logging...46 3.8.2 IntegrationObjecttracing...47 3.8.3 DisplayTerminaltracing...48 3.9 Documentation...50 Chapter 4. Remote Integration Objects (RIO)...53 4.1 Overview...53 Copyright IBM Corp. 2000 iii
4.1.1 RIO Components......53 4.2 RIO XML interface and the XML Legacy Gateway...55 4.3 RIO Studio support....55 4.3.1 Creating RIO support...55 4.3.2 RIO generated files....58 4.4 RIO server side support.....59 4.4.1 RIOServlet...60 4.4.2 RIOServlet input request......61 4.4.3 RIOServletoutput...66 4.5 WebbrowserRIOclients...67 4.5.1 Using XML stylesheets...68 4.5.2 SampleWebbrowserRIOaccess...72 4.6 JavaRIOclients...75 4.6.1 Architectureoverview...75 4.6.2 Securityissues...76 4.6.3 RIOproxyinterface...76 4.6.4 Javasampleprogram...82 4.7 XMLapplications...84 4.7.1 SampleXMLapplicationinJava...85 4.7.2 SampleXMLapplicationinPerl...89 4.8 RIO chaining support...92 4.8.1 Chaining support in Web Browsers clients (thin clients).....92 4.8.2 Chaining support in Java clients......95 4.8.3 Chaining support in XML applications....98 Chapter 5. Transcoding Host Publisher HTML Content...103 5.1 TranscodingHostPublisherHTMLapplications...103 5.2 Scenario: transcoding with WAS filters.....103 5.2.1 SampleHostPublisherapplication...105 5.2.2 Transferapplicationtoserver...109 5.2.3 Deploy application.....110 5.2.4 Definingthetranscodingfilter...111 5.2.5 Invoking transcoded content from a desktop browser...113 5.2.6 Transcoding HTML to WML from JavaServer Pages....116 5.3 Scenario: transcoding using WTP as a network proxy....122 5.3.1 Configuration...123 Chapter 6. Transcoding Host Publisher XML content...127 6.1 WTPinstallationconsiderations...127 6.2 WTP Request Viewer...128 6.3 Registering stylesheets to WTP.....129 6.3.1 XML-to-HTML stylesheet registration...130 6.3.2 XML-to-WML stylesheet registration...133 iv New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
6.4 TranscodingHostPublisherXMLcontent...134 Chapter 7. Using WebSphere Studio with Host Publisher...143 7.1 Overview...143 7.2 Configuration requirements...143 7.3 Using Host Publisher Integration Objects in WebSphere Studio...143 7.3.1 High-leveloverviewforourscenario...144 7.3.2 Detailed steps in our scenario...144 Appendix A. Sample Java program using RIO proxy...165 Appendix B. Special notices...183 Appendix C. Related publications...187 C.1 IBM Redbooks...187 C.2 IBM Redbooks collections.....187 C.3 Otherresources...187 C.4 ReferencedWebsites...188 How to get IBM Redbooks...189 IBM Redbooks fax order form......190 Glossary...191 Index...195 IBM Redbooks review...199 v
vi New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Preface This redbook helps you to understand the new advanced functions included in the IBM WebSphere Host Publisher Version 2.2 release. It focuses on the architectures and technologies implemented in this release, and helps you plan, install, configure and deploy your host access applications (3270, 5250) quickly in a wide variety of environments. In this redbook you will find information on the installation, configuration and customization of these applications using the IBM WebSphere Host Publisher Version 2.2 Studio to create Integration Objects that can be accessed from JavaServer Pages (JSPs), Java applets, Java servlets, Java stand-alone applications, XML applications and desktop Web browsers. You will also find numerous configuration examples and scenarios showing ways to set up the IBM WebSphere Host Publisher Version 2.2 server to access mainframe applications using the new XML gateway. In addition, this redbook provides a good description of the new Remote Integration Object (RIO) support that allows you to access Integration Objects from client devices such as Web browsers, Java and XML applications. Other client devices, such as WAP phones, can also access these Integration Objects using the IBM WebSphere Transcoding Publisher product. A basic knowledge of Java technologies such as servlets, JavaBeans, JavaServer Pages (JSPs) as well as XML applications and the terminology used in Web publishing is assumed. The team that wrote this redbook This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Raleigh Center. Juan R. Rodriguez is a Senior Software Engineer at the IBM ITSO Center, Raleigh. He received his M.S. degree in Computer Science from Iowa State University. He writes extensively and teaches IBM classes worldwide on such topics as networking, Web technologies and data security. Before joining the IBM ITSO, he worked at the IBM laboratory in Research Triangle Park (North Carolina, USA) as a designer and developer of networking products. Roy Froehlich is an IT Architect for IBM Global Services in Toronto, Canada. Roy received his B.S. degree in Computer Science from the University of Copyright IBM Corp. 2000 vii
Western Ontario. He has experience in Internet application architecture and development. His areas of expertise include pervasive computing and development in technologies such as Java servlets, Perl, Lotus Domino, WML, WAP, and XML transcoding. Roy has applied these technologies to various e-commerce integration and client solution projects such as the IBM Finance Portal, numerous Host Publisher applications, and Fortune 500 clients. Thanks to the following people for their invaluable contributions to this project: Kyle Croutwater, Jack Sanders, Marshall Lamb IBM Research Triangle Park, North Carolina, USA Wolfgang Sanyer IBM Americas, Southeast Region Azucena Martinez IBM Ecuador Comments welcome Your comments are important to us! We want our Redbooks to be as helpful as possible. Please send us your comments about this or other Redbooks in one of the following ways: Fax the evaluation form found in IBM Redbooks review on page 199 to the fax number shown on the form. Use the online evaluation form found at ibm.com/redbooks Send your comments in an Internet note to redbook@us.ibm.com viii New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Chapter 1. Introduction IBM WebSphere Host Publisher Version 2.2 provides access to host 3270, 5250, VT and database applications using state-of-the-art technologies such as JavaBeans, JavaServer Pages (JSPs) and XML. In this chapter we provide an overview of the new functionality included in this new release. 1.1 Overview IBM Host Publisher is a key component of IBM's Host Integration software portfolio. Host Publisher Version 2 provides a Web-to-host solution designed to address the unique characteristics of the Internet. It enables Web integration with existing 3270, 5250, VT, JDBC, and Java applications, without requiring any changes to those existing applications and using industry-standard HTML Web pages to support end users running non-java browsers. Figure 1. Integration of existing applications with the World Wide Web Host Publisher offers additional platform support and provides run-time solutions for S/390, AIX, Windows NT, AS/400 and Solaris operating environments. Copyright IBM Corp. 2000 1
As illustrated in Figure 2, there are two major components in IBM Host Publisher: Host Publisher Studio, which provides easy-to-use tools to assist in the creation of Web-to-host integration projects. It is available for Windows 95, Windows 98, Windows NT and Windows 2000. Host Publisher Server, which consists of IBM WebSphere Application Server (WAS) and Host Publisher run-time components. It provides the run-time environment for executing Web applications created with the Host Publisher Studio. Figure 2. IBM WebSphere Host Publisher 2.2 Components IBM Host Publisher allows you to create and use reusable integration objects. Integration Objects created with Host Publisher encapsulate the interaction and data retrieval with host applications. The created Integration Objects can also be reused by other Host Publisher applications as well as Java applications developed outside of Host Publisher. 2 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Figure 3. Host Publisher Component Relationship (Studio and Server) The most important features included in IBM WebSphere Host Publisher are: Load balancing and hot backup are included with Host Publisher. They are provided by IBM Network Dispatcher, which provides enterprise-class load balancing and hot backup of Host Publisher servers. Fully customizable Web pages. It generates fully customizable HTML pages that the application builder can enhance using his or her favorite HTML editor. Back-end data sources. It supports the integration of applications from 3270, 5250, Java, and JDBC-compliant databases. Connection pools. User-defined connection pools are used during runtime to cache connected, logged-on, and ready connections to improve response time. Integration Object chaining enables you to break the application into steps to provide greater flexibility and performance. Chapter 1. Introduction 3
Integration with other IBM connectors enables integration with other IBM connectors such as the one for MQSeries. IBM Host Publisher integrates multiple data sources, including host and database applications, into a single Web page on a client's browser, making host access transparent to the user. UNIX AS/400 CS/390 Web Browser Web Server and Host Publisher Vax SNA / TCPIP Internet Figure 4. Internet host integration with Host Publisher IBM Host Publisher is designed for enterprises that need to deliver host information via HTML to standard Web browsers. It is Java-based and supports AIX, OS/390, Windows NT, AS/400 and Sun Solaris operating systems. Enhancements in Host Publisher include: Support for multiple platforms. Ability to create host Integration Objects that can be reused within Java development tools. Inclusion of a run-time version of IBM WebSphere Standard Edition. Integration with IBM's connector solutions, such as MQSeries, which significantly extends the breadth of existing applications that can be supported. Host Publisher Version 2.2 has included more additional platform support. For example, the server (runtime) now supports NetWare 5.1 (with WebSphere Application Server 3.0.2) and the Studio has included support for Windows 2000. In addition, the server has also included new support for more current versions of WebSphere Application Server (WAS) as follows: 4 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
WAS Version 3.0.2.1 is now supported in the Windows NT, AIX and Sun Solaris platforms. In OS/400, the server can also run with WebSphere Application Server Version 3.0.2. In OS/390 the server now supports WebSphere Application Server Version 1.2 The following important features have been added in this release: XML Legacy Gateway. It makes existing host application data available to customer or Business Partner Java applications in an XML format. It includes a 3270/5250 HTML Mapper that provides a load-and-go entry-level HTML emulator within a Web browser window. Remote Integration Objects (RIO). It allows Integration Objects running on the Host Publisher server to be accessed from Web clients such as Web browsers, Java programs and XML applications written in Java, Perl, C++ and other languages. Additional National Language Support (NLS) Note: The WebSphere Studio Professional Edition 3.5 is also packaged in this release. 1.2 XML Gateway IBM WebSphere Host Publisher Version 2.2 has included an XML gateway that allows you to access your 3270 and 5250 application using XML content. The Host Publisher XML Legacy Gateway (XLGW) communicates with a host application in XML data format. The XML data interface is encapsulated using a JavaBean. The XML data representing the host application windows can be modified and integrated into other Java applications, applets, JavaBeans, or servlets. Interaction with the host program can be manipulated by Java using XML formatting and techniques. See Chapter 3, XML Legacy Gateway on page 27 for an architectural overview of the XML Legacy Gateway feature of Host Publisher. 1.2.1 HTML Mapper It is up to the application to parse the XML content and apply stylesheets if so required. The XML gateway implementation in Host Publisher provides a load-and-go entry-level HTML emulator within a Web browser window. The HTML mapper is provided as a sample program that can be used as a model Chapter 1. Introduction 5
to develop an application using the XML gateway provided interface. Figure 5 illustrates a CICS application access using the provided sample program. Figure 5. Accessing host applications using the XML Legacy Gateway (XLGW) 1.3 Remote Integration Objects (RIO) IBM WebSphere Host Publisher Version 2.2 has included a very important feature that allows you to access your 3270, 5250, VT and database Integration Objects (IOs) from a wide range of client devices. The implementation is via a Host Publisher Server-provided servlet called the RIOServlet. This servlet accepts input types that can be used from different client devices. For example, a desktop browser will typically invoke the servlet using a URL where the input is passed as parameters. Other clients may decide to pass the input request in the form of an XML document as a parameter in a URL. RIO support is included for a specific Integration Object (IO) when the IO is saved with the new RIO option in the Host Publisher Studio. This option is always set by default but it can be easily turned off if RIO support is not required. 6 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
The RIOServlet will always respond with an XML document with results from the execution of the Integration Object. Therefore, a client must either support XML content or some process must take place to transform the XML content into client-supported content (for example, HTML, WML). This can be accomplished with stylesheets or in a more general case transcoding using the IBM WebSphere Transcoding Publisher product. For information on how you can transcode RIOServlet XML content see Chapter 6, Transcoding Host Publisher XML content on page 127. The Host Publisher server-side support and the most common RIO client devices are shown in Figure 6. Remote Integration Object (RIO) access is provided for database (using JDBC interface) and host Integration Objects (3270, 5250 and VT applications). Figure 6. Accessing database and host Integration Objects remotely 1.3.1 Components Host Publisher requires the following components in a RIO environment as illustrated in Figure 6 on page 7: Server side a. RIOServlet (provided by Host Publisher) b. The Host Publisher Integration Objects that you created with the RIO option RIO Clients Chapter 1. Introduction 7
a. Web browsers. They can easily invoke Integration Objects via the RIOServlet. XML support (and stylesheets) or transcoding can be used to properly display the RIO XML content (response). Since invocation is via URL a page form can also be used to get or post the RIOServlet. These clients are called thin clients and they do not require Java support. b. Java programs. These clients invoke the RIOServlet via a RIO proxy. The RIO proxy is automatically generated when you save the Integration Object with the RIO option. The RIO proxy provides a very simple JavaBean interface and therefore the Java program instantiates the RIO proxy and issues setter methods for inputs in the request and getter methods to obtain the Integration Object response. The Java program can be an application, an applet (requires a browser), or a servlet. c. XML applications. These clients use the HTTP interface to communicate with the RIOServlet to access an Integration Object remotely. This interface is generally available for the most important languages and it is not provided by Host Publisher. For example, these client-side applications can be written in Java, C++, Perl and other languages where this interface is available. d. Other client devices such as Palm Pilots, Windows CE, Work Pads, WAP phones and personal digital assistants can access the RIOServlet via transcoding using the IBM WebSphere Transcoding Publisher product. For sample scenarios and more details about how Remote Integration Objects (RIO) can be used in Host Publisher, see Chapter 4, Remote Integration Objects (RIO) on page 53. 1.4 Host simulator tool The host simulator tool is not included in the Host Publisher product but it can be downloaded from the Host Publisher Web site. The host simulator tool resides between your Host Publisher Server or Studio and the host system and records TN3270, TN5250 or VT conversations between Host Publisher and the host, saving the conversation as a trace file. The tool is then able to replay the host's side of the conversation, allowing you to generate Integration Objects and run applications without having to have a live host system. 8 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
You can use the host simulator tool to record an interaction with a live host application once, then simply play back the trace over and over in the simulator, allowing you to: Build portable demonstration and education packages Build Integration Objects and Web applications to test stress and load balancing environments while negating the variables introduced by host systems and their network connections. Record window sequences causing problems in your Host Publisher environment so that IBM Service can reproduce the problem without having direct access to your host. Figure 7. Host simulator tool Chapter 1. Introduction 9
10 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Chapter 2. Installation In this chapter we describe the IBM WebSphere Host Publisher Version 2.2 installation process under Windows NT. It includes the installation of the Studio and the Server. The Host Publisher Server requires the proper installation of a Web server such as the IBM HTTP Server and the WebSphere Application Server. 2.1 Overview There are several tasks you will need to perform before or during the actual installation. In general, the following software is required: A supported Web server. IBM WebSphere Host Publisher Version 2.2 includes IBM HTTP Server Version 1.3.6.2 on the CD-ROM. Java Development Toolkit (JDK) 1.1.8. This is provided with Host Publisher Server Version 2.2. IBM WebSphere Application Server (Standard, Advanced or Enterprise Editions). IBM WebSphere Host Publisher Version 2.2 includes and integrates the standard edition (Version 3.0.2.1). IBM WebSphere Host Publisher Version 2.2 Studio. It runs under Windows only (95, 98, NT or 2000). The Studio installs its own JDK Version 1.2.2. IBM WebSphere Host Publisher Version 2.2 Server. In this chapter we show you the Windows NT installation. Database support such as IBM DB2 Universal Database and databases from Oracle and Sybase (not provided with IBM WebSphere Host Publisher Version 2.2). Note: Database support is only required if you are planning to work with database Integration Objects. 2.2 Host Publisher Studio installation Host Publisher Version 2.2 Studio is a Win32 program and therefore it is available for Windows 95, 98, NT and 2000 operating systems. The installation is very straightforward and requires that you provide a proper directory for the target directory. However, there are no selectable components, and no prerequisites or corequisites are required. Host Publisher Studio can install over itself and requires 70 MB of disk space and 128 MB of memory. Copyright IBM Corp. 2000 11
Note: Host Publisher Studio requires and installs JDK 1.2.2. For example: 1. Run Set up from the Host Publisher Studio CD-ROM. 2. Install Host Publisher Studio in c:\hostpub directory. Figure 8. Host Publisher Studio installation To verify that Host Publisher Studio was correctly installed you may want to start any of the applications listed in the Host Publisher Studio program group and make sure it comes up successfully. You can also bring up the Host Access component and make sure you can access a host system. If are planning to create database Integration Objects, make sure Database Access can access a target database. If not, check the availability of JDBC drivers: They must be installed separately from the database software. They must be in the CLASSPATH environment variable. 2.3 Host Publisher Server installation In AIX, AS/400, Solaris, and Windows NT, Host Publisher Server installation does not install a Web server for you. It also does not support installation of a 12 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Web server after Host Publisher and WebSphere Application Server are installed. Before you install WebSphere Application Server, be sure to install one of the Web servers it supports. If WebSphere Application Server is already installed, ensure that a Web server has been installed and is functioning properly with WebSphere Application Server. Note: If you have a preexisting WAS 2.0.3, make sure it is at level 2.0.3.1, no less and no more. However, if you are using WAS 3.0.2, it can be at the 3.0.2 or 3.0.2.1 or 3.0.2.2 level. The following Web servers are supported in this release: Domino Go Version 4.6.2.5 Domino Version 5.0 Netscape FastTrack Version 3.01 Netscape Enterprise Version 3.01, 3.51, 3.6 Microsoft IIS Version 3.0, 4.0 Apache Version 1.3.2, 1.3.6 IBM HTTP Version 1.3.3.x, 1.3.6.2 Note For unsupported Web servers an option is provided to continue anyway, but part of the automatic WAS install verification is to verify that a plug-in has been successfully installed. In general, to be able to run Host Publisher Server 2.2 including the new XML Gateway and the Remote Integration Object (RIO) support, you will need to install the following software: 1. Web browser. It is required to access the Host Publisher administration servlet. A Web browser is also required by IBM HTTP Server (IHS) and by the IBM WebSphere Application Server (WAS) Version 2.0.3 administration. 2. Web Server. A Web server is a prerequisite for IBM WebSphere Application Server (WAS) since it runs as a plug-in of a Web server. In this chapter we include the installation of the IBM HTTP Web Server 1.3.6.2. 3. JDK 1.1.8. It is included and used with Host Publisher Server 2.2. It gets installed during the Host Publisher installation in the \HostPub\Common\JDK\ directory. Chapter 2. Installation 13
4. WebSphere Application Server. The WebSphere Application Server (WAS) can be installed either with Host Publisher (WAS Standard Edition) or manually (Standard, Advanced or Enterprise editions). Host Publisher Server 2.2 runs on both WAS 2.0.3.1 and WAS 3.0.2.1. Note If Host Publisher Server installation process does not find a supported WAS, it will silently install WAS 3.0.2.1 Standard Edition for you. 5. Host Publisher Server Version 2.2 (runtime and administration). Figure 9. Host Publisher 2.2 server installation environment 14 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Figure 9 on page 14 illustrates the environment required to successfully run Host Publisher server (runtime). You should notice that a Web server is always required as well as WebSphere Application Server. Also notice that the Web Server uses port 80 by default for an unsecure port (HTTP) and port 443 (default) for a secure port (HTTPS). The WAS 3.0.2.1 administration does not require a browser since it uses an administration client Java program using Sockets to the default port 900. 2.3.1 Web browser installation Install your favorite Web browser. In some cases it is a good idea to have both Netscape 4.7x and Internet Explorer 5.x available in your system in case you run into unpredictable problems and need to do problem determination. 2.3.2 Web Server installation In this section we show you how to install the IBM HTTP Web Server Version 1.3.6.2: 1. Run Setup from the Host Publisher Server CD-ROM Windows->HTTPServer directory. Figure 10. IBM HTTP Web Server 1.3.6.2 setup 2. Select typical installation. Chapter 2. Installation 15
3. Select a proper target directory, for example: c:\ibm HTTP Server. Figure 11. IBM HTTP Web Server 1.3.6.2 destination directory 4. Enter a valid user ID and password so the Web server can be installed as a service. Figure 12. IBM HTTP Web Server 1.3.6.2 - user ID and password 16 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Note: The user ID must have administrator s privileges. 5. Finish the installation. Figure 13. IBM HTTP Server installation is complete 6. Reboot the machine and proceed to verify a correct installation. 7. At this time you may want to use Notepad or Wordpad to browse and familiarize yourself with the configuration file httpd.conf in the IBM HTTP Server->conf subdirectory. 8. From the control panel, select Services to make sure the IBM HTTP Web server has been started as a service. See Figure 14 on page 18. If you have problems, select Startup and review the configuration options. Start the service manually or reboot the machine if required. Chapter 2. Installation 17
Figure 14. IBM HTTP Web Server and Administration running as a service 9. If you cannot get IBM HTTP Server started, check the server name of your computer in the configuration file (httpd.conf). See Figure 15. This statement is commented out by default. In some networks, you may need to specify your server name here. If you change the configuration file, you will need to refresh the Web server to pick up the new values. Figure 15. IBM HTTP Server - server name 10.Once the IBM HTTP Server has been started as a service, from your Web browser access the administration panel locally (see Figure 16) by using 18 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
the URL http://127.0.0.1/ or http://localhost/. By default it will use port 80 to access HTTP server administration. Figure 16. IBM HTTP Server - administration panel 2.3.3 Host Publisher Server 2.2 installation In this section we show you the Host Publisher Version 2.2 Server installation in a Windows NT machine. The installation includes the JDK 1.1.8 and the WebSphere Application Server 3.0.2.1 provided in the product CD-ROM. 1. From the CD-ROM, execute setupwin and click Install Product. Note: A common problem during Host Publisher installation is when you have installed Host Publisher but WebSphere Application Server is not properly configured. Generally, this is caused when you run the wrong installation program. Make sure you use the setupwin.exe command in Windows NT (setupaix.sh in AIX, or setupsun.sh in Sun Solaris) from the root directory of the CD and not from the platform subdirectory. Executing \windows\setup.exe is not correct, and nothing will work if this is invoked. Chapter 2. Installation 19
Figure 17. Host Publisher Server installation 2. Enter the default values for the number of licenses and Host Publisher alias. Notice that the alias should contain no blanks. Figure 18. Host Publisher alias (default value) 20 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
3. Click Next to start the installation of Host Publisher Server 2.2 including JDK 1.1.8 and WAS 3.0.2.1. Figure 19. Host Publisher Server Version 2.2 installation including WAS 3.0.2.1 4. Browse the Host Publisher directories to get familiar with them (JDK 1.1.8, Server, WebSphere, documentation, log). Figure 20. Host Publisher Server directories Chapter 2. Installation 21
5. Browse the IBM HTTP Server configuration file (httpd.conf) and at the end of the file find the entries added by the Host Publisher Server and WebSphere installation. The following is a sample of these entries: LoadModule ibm_app_server_module c:/hostpub/websphere/appserver/bin/mod_ibm_app_server.dll Alias /IBMWebAS/samples/ "c:/hostpub/websphere/appserver/samples/" Alias /IBMWebAS/ "c:/hostpub/websphere/appserver/web/" The following is a sample of the entries for Host Publisher Server: Alias /_IBM_HP_doc_/ "c:/hostpub/common/doc/" Alias /_IBM_HP_WebAdmin_/ "c:/hostpub/server/production/documents/" Alias /HostPublisher/ "c:/hostpub/server/production/documents/" Note If the Web server was not configured or if WAS did not correctly install its plug-ins for a Web server, Host Publisher will not configure the Web server for Host Publisher use. 6. It is recommended that for testing purposes you manually start the WAS AdminServer. Make sure WebSphere AdminServer is running. If not running, you may need to re-configure Startup, reboot and try again. Figure 21. IBM WebSphere AdminServer running as a service 7. From the desktop select Programs->IBM WebSphere Host Publisher 2.2, and access WebSphere administration by selecting Programs->IBM WebSphere->Application Server V3.0->Administrator s Console. 22 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
8. Start the WAS Default Server (not required to run Host Publisher) by selecting the server in the Topology tab and click the green button in the tool bar. This will allow you to run the HelloWorldServlet provided by WAS. 9. From a Web browser, run the WAS provided HelloWorldServlet using the following URL: http://<server-name>/servlet/helloworldservlet Figure 22. Executing the HelloWorldServlet 10.In a similar way, start the Host Publisher server and make sure it shows as running (use the green button in the tool bar). Note: WAS must be active in order to run the Host Publisher Server. In some cases WAS does not start successfully, and the XML configuration file fails. To start it manually, use the.bat or.sh file (AIX): HostpubWAS HostPubWASConfig.xml Chapter 2. Installation 23
Figure 23. Starting Host Publisher Server 11.With the Host Publisher Server running, bring up Host Publisher administration. You can either do this from the desktop or using a URL as follows: - From the desktop select Programs -> Host Publisher -> Host Publisher Administration - From a browser invoke Host Publisher administration using the following URL: http://<server-name>/_ibm_hp_webadmin_/hpadmin/main.jsp Note: Access to Host Publisher 2.2 administration servlet requires a browser. 24 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Figure 24. Host Publisher Server Administration window Note: When accessing Host Publisher administration using Internet Explorer on Windows NT, the Host Publisher administration shortcut points to http://localhost/... However, if Internet Explorer has not been configured to bypass the proxy server for a local address, the URL may not be found and you may need to substitute the host name. 2.3.4 Uninstalling Host Publisher Since other products may be using the WebSphere Application Server (WAS), when you uninstall or remove Host Publisher it will not remove WAS. If you also need to uninstall WAS, you will need to do it separately. For the same reason, the JDK will not be removed. Chapter 2. Installation 25
Note: Although all configuration data is removed from WAS at uninstall time, the aliases are not removed from the Web servers. 26 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Chapter 3. XML Legacy Gateway The XML Legacy Gateway (XLGW) is a new feature in Host Publisher 2.2. It allows program access to 3270 and 5250 application data in an XML format. In addition, it also provides an HTML emulator for end-user access to 3270 and 5250 applications. In this chapter we describe this function. Note: VT applications are not supported by the XML Gateway. 3.1 Overview The XLGW provides an XML interface to host programs (3270, 5250) where minimal host emulator programming skills are required to develop application programs that will interface with available host programs. It also provides a common data interface for re-use of programming techniques and tools (for example, XSL processing of XML data) as well as a common interface for exchange of data with other XML data sources. Figure 25. XML Gateway architecture overview In addition, the XLGW includes a sample servlet (HTML to Host emulator) that can be used as a quick, out-of-the-box, Web browser access to many 3270 and 5250 applications. Copyright IBM Corp. 2000 27
The sample servlet includes an administrative application to provide access via a browser, for creating a portal page. The created portal page provides easy access to host systems so that end-user configuration is no longer needed. The Host Publisher XML Legacy Gateway communicates with a host application in XML data format, and optionally in HTML format. The XML data interface is encapsulated using a JavaBean (xmlappdata). The XML data representing the host application windows can be modified and integrated into other Java applications, applets, JavaBeans, or servlets. Interaction with the host program can be manipulated by Java using XML formatting and techniques. Figure 25 on page 27 illustrates the new XML Legacy Gateway feature of Host Publisher. It shows a browser interacting with the xmllegacygateway sample servlet (or a user servlet that you provide). The servlet in turn uses the provided interface to communicate with the host application. 3.1.1 XLGW components The XML Legacy Gateway (XLGW) provides the following resources: 1. An XML-to-Host JavaBean programming interface. 2. An HTML-to-Host TN3270/TN5250 emulation sample program and tools. It consists of the following programs and files: e. hpubportaladmin, an administrative servlet tool that allows you to create and configure host connections. f. hpubportaldata.xml, the XML data file that hpubportaladmin creates. g. hpubportal. The XML Legacy Gateway supplies a portal to the emulator function, which relies on the xmllegacygateway servlet for interaction with the host applications. The portal servlet enables access to host links created through the administrative servlet (hpubportaladmin) h. xmllegacygateway servlet, the Web-based terminal emulator that enables interaction with host terminal applications using XML data formats. 3. Detailed sample/sdk of the above two features. It also shows how XSL processing can be incorporated for flexibility with display formats. 28 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Note The XML Gateway feature is a runtime function only and it does not require you to use the Host Publisher Studio. 3.2 XML gateway limitations The following are known limitations with the XML Legacy Gateway emulator function: When you use the XML Legacy Gateway function, it is strongly recommended that you use one of the following versions of Web browser: - Netscape Communicator 4.7 or above - Microsoft Internet Explorer 5.0.2919 or above If you wish to use more than one XML Legacy Gateway session simultaneously, it is recommended that you use a separate browser window for each session. It is recommended that the browser window be dedicated to the XML Legacy Gateway session. If you open an XML Legacy Gateway session and then use the browser window for other work, it is possible that the XML Legacy Gateway session will be interrupted. When using the XML Legacy Gateway for terminal emulation in Microsoft Internet Explorer Version 5.0, do not open new browser windows using File -> New -> Windows. This causes multiple copies of the emulation session to be split between existing and new browser windows and will result in inaccurate terminal-emulation output. Input fields in the terminal emulation feature of the XML Legacy Gateway default to insert mode. Because of this, cursor input is inhibited when these fields are filled with characters. (Bear in mind that "space" is a valid character.) In this case it is necessary to press the Insert key to toggle the field to "overwrite" mode. With some Web browsers, it is possible that text cut or copied from the XML Legacy Gateway window and pasted into a text file will be misaligned. 3.3 HTML to Host sample program Host Publisher 2.2 provides a sample program that shows you how to use the XML interface to write servlets that can interact with host applications. You Chapter 3. XML Legacy Gateway 29
can modify this sample to create a servlet that manipulates host application XML data-handling techniques. To do this, the sample code uses two Host Publisher-supplied JavaBeans. The first bean is called HostConnection bean, and it allows a program to acquire and release session beans using the Host Publisher Server runtime environment. The second bean is called the xmlappdata Bean, and it provides the XML interface to the host application windows. The sample code uses these two beans and the XSL processor that comes with IBM WebSphere to translate the XML data into HTML format. This transformation can give you insight into how you can use XSL processing to render XML data on devices that have different display criteria. The sample code implements a subset of the functionality that comes with the Host Publisher XML Legacy Gateway feature. This feature allows users to view and interact with host application windows in a Web browser. 3.3.0.1 Sample servlet The sample servlet renders host data windows in an HTML format and posts these windows to a Web browser. This sample is a subset of the servlet which Host Publisher uses to perform that same function as part of the Host Publisher XML Legacy Gateway feature. As such, the sample has been simplified to provide the Java programmer with the essentials for creating an application that can interface to host application windows using an XML interface. The source code is provided in the SDK and is documented throughout with comments so the programmer can understand the necessary steps involved in writing similar servlets. This sample displays every host application windows to the user. A more typical application may want to drive several application windows automatically, and only display to the user a few pieces of data from the host application windows. The user may then input data into the HTML form and then the application can drive more host windows with this input, and so on. The general flow of the servlet processing is as follows: 1. The user first accesses the servlet, causing the xmllegacygwsample servlet to be instantiated and the doget method to be invoked. 2. The servlet receives the host connection parameters via the parameters passed with the URL. 3. The servlet sets up a hashtable to store these values, along with other initial values. This hashtable is stored in a vector, which is then stored in a 30 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
static hashtable. The key value for the vector in the static hashtable is the Web session ID. This allows for multiple instances of the servlet, for the same Web session ID, to be easily manipulated. 4. The doget method will also initialize an IBM Host On-Demand (HOD) properties object, to be used for establishing a connection to the host. 5. An xmllegacyprocesssample object is then instantiated and the first access method of this object is called. 6. The xmllegacyprocesssample object will then use the stored parameters to establish a connection with the host. This is done by instantiating a Host Publisher HostConnection JavaBean, and calling the acquirehostconnection method. This function will return an HOD Session JavaBean. 7. The xmllegacyprocesssample object will then instantiate a Host Publisher xmlappdata JavaBean, and wire this bean to events generated by the HOD Session bean. 8. Then the xmllegacyprocesssample will wire itself to events generated by the xmlappdata bean. In this way the xmllegacyprocesssample bean can communicate with the xmlappdata bean using XML data formats, and the xmlappdata bean communicates with the host using the HOD Session bean. This path yields the desired XML data interface to a host application. A block diagram of the relationship of these components is illustrated in Figure 26 on page 32. Chapter 3. XML Legacy Gateway 31
Figure 26. XML Legacy Gateway architecture When the xmlappdata bean signals that it has received data from the host, the xmllegacyprocesssample object retrieves this data in XML format. It then combines this data with a stylesheet (an XSL file) using a stylesheet processor that is included in IBM's WebSphere product. This process produces HTML output. The HTML output contains JavaScript calls. The JavaScript file is called lxgwfunctions.js, and is included in this sample. The user then is presented with the host window, and is able to fill in the input data fields and select an action to take on the windows (for example, Enter, PF1 function key, PF3, and so on) by clicking one of the buttons presented on the HTML page. When a button is clicked, this causes a dopost command to be sent to the servlet, and the xmllegacygwsample servlet receives this dopost. The dopost does some status and error checking and then instantiates an xmllegacyprocesssample object, and calls the "execute" method of this object. The execute method will then read in the HTML data that represents the host window with the user's input, into an XML data structure. Next the xmllegacyprocesssample will invoke a method of the xmlappdata bean to 32 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
send this new data to the host. The xmllegacyprocesssample will then wait for the xmlappdata bean to send back the new host window in XML format. Then, as stated before, this data is combined with a stylesheet to produce an HTML page at the browser. This process continues until the user disconnects. 3.4 Sample Scenario In this section we illustrate how you will run the provided sample HTML to Host emulator. Before you attempt to run the emulator, make sure that the Host Publisher Server has been started and it is running. This will also make the XML Legacy Gateway (xmllegacygw) available as shown in Figure 27. Figure 27. XML Gateway shown as available (running) Chapter 3. XML Legacy Gateway 33
3.5 Using the HTML-to-Host emulator In this section we show you the steps required to invoke the XML Legacy Gateway (XLGW) HTML-to-Host emulator sample provided as a sample program in the Host Publisher Version 2.2 product: 1. In order to configure your sessions and links, you first need to access the XML Legacy Gateway Administration panel using the following URL: http://<servername>/_ibm_hp_webadmin_/hpubportaladmin where <servername> is the host name of your Host Publisher Server. For example, if the server is in the same machine you have the option to use the computer name, IP address, localhost or the loop-back address 127.0.0.1. This will bring up the XML Legacy Gateway Administration Panel as shown in Figure 28. Note: The XLGW HTML-to-Host emulator is provided as a sample program and its source is also included with Host Publisher. It shows you how a program can interface with the XML gateway to access 3270, 5250 and VT host applications. 2. Next you will click the Create New Session button in the administration panel to create, for example, a 3270 session. Figure 28 illustratess panel. 34 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Figure 28. XML Legacy Gateway Administration Panel 3. When you select the option to create a new session, the administration servlet will bring you to the XML Legacy Transformation panel as shown in Figure 29 on page 36. You will need to configure the following information: a. Session Name: enter any session name that will help you to identify this session. b. Link Name: enter any link name that will help you to identify this link. c. Link Description: enter any description that will help you to describe this link. d. Host Name: enter the host name or IP address of the Telnet 3270 or 5250 server. e. Port: 23 (default value) or whatever port your server is listening. f. Host Type: 3270 or 5250 g. Host Code Page: 037 United States or your required page code. h. Display Size: 24 x 80 (default) or the window size your application requires. Chapter 3. XML Legacy Gateway 35
Figure 29. XML Legacy Gateway Transformation 4. Click the Save button to create or update the XML configuration file. A sample configuration file is shown in Figure 30 on page 37. 36 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
Figure 30. Sample HTML-to-Host configuration file (XML format) 5. Once the configuration file is created using the administration panel, the session with host can be started by clicking the Start button. 6. Alternatively you can invoke the XLGW portal (hpubportal servlet) to select the link that you defined using the Portal Administration (hpubportaladmin). For an example, see Figure 31. Chapter 3. XML Legacy Gateway 37
Figure 31. XML Legacy Gateway Portal page 7. Once the session is started you will be interacting with the 3270 or 5250 session as shown in Figure 32. Figure 32. Accessing mainframe applications using XML Legacy Gateway 38 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2
8. The HTML to Host sample servlet displays the window shown in Figure 33 when the session is terminated. Figure 33. XML Legacy Gateway - session disconnected 3.6 XML Legacy Gateway JavaBean interface The XML Legacy Gateway provides two components that communicate with a host application: The xmllegacygateway servlet The xmlappdata JavaBean Note: In addition, the HostConnection class is provided by Host Publisher. 3.6.1 The xmllegacygateway servlet The xmllegacygateway servlet transforms XML data into HTML format. This servlet enables viewing of a host window in a Web browser. A user can interact with the host window in the browser by typing in the fields on the window or by using the function keys, which are displayed as buttons in the browser. Because the servlet interacts with the host application, most of the data processing takes place at the server. This enables browser access to host applications from a thin client. The servlet uses Extensible Stylesheet Language (XSL) processing to transform XML data to HTML format. This is a powerful example of how to Chapter 3. XML Legacy Gateway 39
transform the host window into XML data and, through the use of a stylesheet, present it to the end user in a different format. By replacing or modifying this servlet, the supplied stylesheet, or both, and by using an XSL processor such as the one included in WebSphere Application Server, the application programmer can easily render host data onto a variety of devices using a single servlet with multiple stylesheets. The source code for the servlet is included with the Host Publisher product. Refer to Figure 26 on page 32 to see how the xmllegacygateway servlet relates to the other components of the XML Legacy Gateway. The xmllegacygateway servlet: 1. Is instantiated with form parameters that describe the desired host session. These parameters describe the telnet name of the host, the terminal format (3270 or 5250) of the session, and so on. 2. Initiates a host session using Host Publisher and IBM Host On-Demand Java objects and properties. 3. Instantiates the xmlappdata JavaBean and makes the JavaBean a listener for Host On-Demand events. 4. Retrieves, after a programmed delay, the current state of the host window as XML data from the xmlappdata JavaBean. 5. Formats the XML data as HTML output using an XSL stylesheet and an XSL processor. This output is returned to the browser. The HTML output returned to the browser shows how the window displays on a traditional terminal. The user can input data directly onto the HTML host window. The user can move the cursor to the input fields using the mouse or the Tab key. The traditional terminal function keys are presented to the user as buttons on the browser window. The user can select the buttons using the mouse or using the Tab key and pressing the Enter key on the keyboard. Two additional buttons are presented on the user's browser page: Refresh and Disconnect. The Refresh button updates the browser's host window to the current state of the host session, ignoring possible input. The Disconnect button terminates the current host session. Disconnection enables an efficient use of Host Publisher resources. The user should disconnect the host session when interaction with the host application is no longer needed. While the servlet is a useful application, it is an example of how to interact with Host Publisher to encapsulate host data in XML format. The servlet 40 New Advanced Functions in IBM WebSphere Host Publisher Version 2.2