IBM System I Application Modernization: Building a New Interface to Legacy Applications September 2006

Front cover

IBM System i Application

Modernization Building a New Interface to Legacy Applications

Comparison of the different ways to access the IBM System i platform

Discussion of JSFs, HATS, Web services, portlets, IBM WebFacing Tool, and rich client

Examples of building different client interfaces

Guenther Hartung Rolf Andre Klaedtke Elena Lowery Estela McCarty Els Motmans Aleksandr Nartovich

ibm.com/redbooks

International Technical Support Organization

IBM System i Application Modernization: Building a New Interface to Legacy Applications September 2006

SG24-6671-00

Note: Before using this information and the product it supports, read the information in “Notices” on page vii.

First Edition (September 2006)

This edition applies to IBM OS/400 V5R3 and IBM i5/OS V5R4.

© Copyright International Business Machines Corporation 2006. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents

Notices ...... vii Trademarks ...... viii

Preface ...... ix The team that wrote this redbook...... ix Become a published author ...... xi Comments welcome...... xi

Part 1. Looking at the alternatives ...... 1

Chapter 1. Why you should consider new application interfaces ...... 3 1.1 Reasons for a change ...... 4 1.2 Up-front considerations and prerequisites ...... 5 1.3 IBM System i Developer Roadmap ...... 5 1.4 How to read this book ...... 6

Chapter 2. Modernizing System i legacy applications: Common business scenarios 7 2.1 Considerations for the scenarios and possible solutions ...... 8 2.2 Overview of the scenarios...... 8 2.2.1 Scenario 1: Add a Web front end to a monolithic iSeries application ...... 8 2.2.2 Scenario 2: Add a portal front end to a monolithic iSeries application ...... 9 2.2.3 Scenario 3: Build a Web front end for a modular RPG application ...... 9 2.2.4 Scenario 4: Build a portal front end for a modular RPG application ...... 10 2.2.5 Scenario 5: Build a rich-client front end for a modular RPG application ...... 10 2.2.6 Scenario 6: Expose modular RPG applications as Web services...... 10 2.3 Overview of basic solutions...... 11 2.3.1 IBM WebFacing Tool ...... 11 2.3.2 Host Access Transformation Services ...... 14 2.4 Overview of advanced solutions ...... 16 2.4.1 JavaServer Faces technology...... 16 2.4.2 Rich client ...... 19 2.4.3 PHP...... 20

Part 2. Using IBM solutions ...... 23

Chapter 3. Host Access Transformation Services ...... 25 3.1 Requirements to prepare for a HATS implementation ...... 26 3.1.1 Hardware and software requirements...... 26 3.1.2 Project implementation requirements ...... 28 3.1.3 Project implementation strategy ...... 30 3.1.4 Typical case studies ...... 32 3.2 IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology...... 34 3.2.1 Benefits to iSeries customers ...... 34 3.2.2 Components in the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology package ...... 35 3.2.3 Additional PTFs to enable IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology ...... 36 3.2.4 Purchasing scenarios ...... 36

© Copyright IBM Corp. 2006. All rights reserved. iii 3.2.5 Purchasing IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology ...... 37 3.3 Installing and configuring HATS ...... 37 3.3.1 Installing HATS ...... 37 3.3.2 Upgrading the HATS Studio with the latest available refresh pack...... 39 3.3.3 Upgrading the HATS Trial Toolkit ...... 44 3.4 New features in HATS V6.0 and the refresh packs...... 45 3.4.1 HATS V6.0 ...... 45 3.4.2 HATS V6.0.1 (refresh pack level 1)...... 47 3.4.3 HATS V6.0.2 (refresh pack level 2)...... 47 3.4.4 HATS V6.0.3 (refresh pack level 3)...... 47 3.4.5 HATS V6.0.4 (IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology V6.0.1) ...... 48 3.5 Sample HATS application using default rules ...... 48 3.5.1 Developing a HATS application ...... 48 3.5.2 Preparing the HATS application for production...... 59 3.6 Deploying the HATS application to the iSeries server ...... 61 3.6.1 Enabling HATS runtime ...... 61 3.6.2 Packaging the HATS application ...... 63 3.6.3 Installing the application on WebSphere Application Server V6.0 ...... 64

Chapter 4. The IBM WebFacing Tool ...... 67 4.1 WebFacing versus screen scrapers ...... 68 4.2 Requriements to prepare for a WebFacing implementation ...... 69 4.2.1 Hardware and software requirements...... 69 4.2.2 Recommended skills...... 73 4.2.3 Project implementation strategy ...... 73 4.3 Installing and configuring WebSphere Development Studio Client V6.0...... 76 4.3.1 Installing WebSphere Development Studio Client V6.0 ...... 77 4.3.2 Upgrading WebSphere Development Studio Client V6.0 with the latest available fix pack ...... 80 4.3.3 Checking for new program temporary fixes ...... 81 4.3.4 New features of the IBM WebFacing Tool ...... 83 4.4 Sample WebFacing application...... 86 4.4.1 iSeries servers that should be started for the IBM WebFacing Tool...... 86 4.4.2 Starting WebSphere Development Studio Client ...... 88 4.4.3 Creating a WebFacing project...... 88 4.4.4 Converting the WebFacing project ...... 95 4.4.5 Deploying the WebFacing application to the iSeries...... 101

Part 3. Designing a new user interface ...... 107

Chapter 5. Before you create a new user interface ...... 109 5.1 Modularizing an existing iSeries application ...... 110 5.1.1 OPM versus ILE RPG ...... 110 5.1.2 Modernizing OPM programs ...... 110 5.1.3 Whether to choose the ILE path: Pros and cons ...... 111 5.2 More modernization: Database access methods ...... 112 5.3 Integrating iSeries applications and Java ...... 112

Chapter 6. Application architecture, design, and implementation ...... 113 6.1 Model view controller ...... 114 6.2 Facade pattern ...... 114 6.3 Application design and implementation...... 115 iv IBM System i Application Modernization: Building a New Interface to Legacy Applications Chapter 7. Designing a Web services interface ...... 119 7.1 From buzzword to reality: What Web services are ...... 120 7.1.1 A non-technical example...... 120 7.1.2 A more technical introduction ...... 121 7.1.3 A short introduction to service-oriented architecture...... 122 7.1.4 Web services technology stack...... 123 7.1.5 Web services invocation model...... 124 7.2 Web service development cycle ...... 125 7.2.1 Web services development approach...... 125 7.2.2 Interface considerations ...... 127 7.2.3 Testing and deployment ...... 127 7.3 Creating a Web service...... 127 7.3.1 Implementing thread safety in an RPG program...... 128 7.3.2 Development steps ...... 128 7.3.3 Web service interface design hints ...... 158 7.4 Consuming or using a Web service ...... 158 7.5 Advantages and disadvantages of Web services ...... 158 7.6 Further reading ...... 159

Chapter 8. Designing a JavaServer Faces-based interface ...... 161 8.1 Overview of JSF technology ...... 162 8.2 The JSF framework...... 162 8.3 The JSF development environment ...... 163 8.3.1 JSF components ...... 163 8.3.2 Properties ...... 163 8.3.3 Events ...... 163 8.3.4 Binding ...... 163 8.4 Why use JSFs ...... 164 8.5 Sample JSF application ...... 164 8.5.1 Using the ProgramCall mechanism...... 165 8.5.2 Invoking a Web service...... 189 8.6 What is next ...... 196

Chapter 9. Designing a portlet client...... 197 9.1 Portal framework ...... 198 9.1.1 More technical definition of a portal server ...... 198 9.2 Business reasons for implementing a portal server ...... 199 9.3 Overview of portal technology...... 200 9.3.1 Portal pages and portlets ...... 201 9.3.2 Basic portal architecture ...... 202 9.3.3 Portlet API - JSR 168 ...... 202 9.4 IBM WebSphere Portal Server ...... 202 9.4.1 IBM WebSphere Portal for iSeries ...... 205 9.4.2 Creating portlets that access iSeries applications and data ...... 207 9.5 Prerequisites for using IBM WebSphere Portal...... 208 9.5.1 Development requirements...... 208 9.5.2 iSeries hardware and software requirements for deployment...... 208 9.5.3 Required skills...... 209 9.6 Portlet example ...... 209 9.6.1 Creating a project ...... 210 9.6.2 Creating the ProgramCall Java beans ...... 216 9.6.3 Modifying the portlet source code ...... 216 9.6.4 Testing the portlet ...... 224 9.6.5 Deploying the portlet ...... 226

Contents v 9.7 Simple example of invoking a Web service...... 227 9.7.1 Generating the portlet project ...... 227 9.7.2 Generating a Web service client ...... 227 9.7.3 Modifying the generated code...... 231 9.8 Links ...... 235 Chapter 10. Designing a rich-client interface ...... 237 10.1 Overview of the rich-client technology ...... 238 10.1.1 Rich client and thin client ...... 238 10.1.2 Advantages and disadvantages of rich-client technology ...... 239 10.1.3 Technology choices for implementing rich-client applications ...... 240 10.2 Example of a rich-client application accessing a Web service ...... 254

Chapter 11. Designing a PHP client...... 267 11.1 Introducing PHP ...... 268 11.1.1 A short look back ...... 268 11.1.2 Why you should use PHP ...... 269 11.1.3 Who is using PHP ...... 269 11.1.4 Technology overview ...... 269 11.2 PHP on the System i platform ...... 274 11.2.1 Zend Core for i5/OS ...... 275 11.2.2 PHP version and availability ...... 275 11.2.3 Accessing DB2 Universal Database and calling RPG and COBOL programs in i5/OS...... 276 11.3 PEAR, the PHP Extension and Application Repository ...... 276 11.3.1 Why PEAR is important...... 276 11.3.2 Installing PEAR packages...... 277 11.3.3 Further information about PEAR...... 277 11.4 Development tools that offer PHP support ...... 277 11.5 Example: Consuming a Web service using PHP ...... 278 11.6 Example: Calling a DB2 Stored Procedure with PHP ...... 280 11.7 PHP and XML ...... 283

Appendix A. Additional material ...... 285 Locating the Web material ...... 285 Using the Web material ...... 285 System requirements for downloading the Web material ...... 285 How to use the Web material ...... 286

Related publications ...... 287 IBM Redbooks ...... 287 Other publications ...... 287 Online resources ...... 287 How to get IBM Redbooks ...... 289 Help from IBM ...... 289

Index ...... 291

vi IBM System i Application Modernization: Building a New Interface to Legacy Applications Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

AS/400® i5/OS® System i5™ Cloudscape™ Language Environment® Tivoli® CICS® Lotus Notes® VisualAge® developerWorks® Lotus® WebSphere® Domino.Doc® Notes® Workplace™ Domino® OS/400® Workplace Client Technology™ DB2 Universal Database™ POWER5™ Workplace Forms™ DB2® pSeries® Workplace Managed Client™ eServer™ QuickPlace® Workplace Web Content Everyplace® Rational® Management™ Integrated Language Environment® Redbooks™ xSeries® IBM® Redbooks (logo) ™ z/OS® iNotes™ Sametime® zSeries® iSeries™ System i™ 1-2-3®

The following terms are trademarks of other companies: Enterprise JavaBeans, Java, JavaBeans, JavaScript, JavaServer, JavaServer Pages, JDBC, JRE, JSP, JVM, J2EE, Sun, Sun Microsystems, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Excel, Internet Explorer, Microsoft, Visual Basic, Visual Studio, Windows Server, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Pentium, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Zend is a trademark of Zend Technologies Ltd. in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.

viii IBM System i Application Modernization: Building a New Interface to Legacy Applications Preface

This IBM® Redbook examines many different alternatives for accessing your IBM System i™ legacy applications. It provides recommendations for selecting different tools and technologies based on your existing environment and the goals that you are trying to achieve. It covers the IBM WebSphere®-based solutions, such as IBM Host Access Transformation Services (HATS) and JavaServer™ Faces (JSF), as well as rich-client and PHP solutions.

The parts of this redbook are designed for company CIOs, architects, and developers. Within these parts, this redbook provides guidance for those who are selecting the most suitable alternative for their existing IT environment. This redbook also demonstrates the process of creating a sample application using a specific technology. For those who are interested in a more detailed information, this redbook points to other publications and online materials.

Note: At the time this redbook was written, IBM was transitioning from the IBM eServer™ iSeries™ server to the release of the IBM System i5™ platform. In this redbook, we use the terms System i platform, System i5 platform, and iSeries server interchangeably. System i5 platform merely refers to the IBM POWER5™ line of servers within the IBM System i product line.

Also, this book was under development when IBM released IBM i5/OS® V5R4. The new release comes with the new names of the system itself and some of the products. For this reason, you might see a mixture of terms that are both pre- and post-i5/OS V5R4.

Important: All examples in this book have been tested with WebSphere Development Studio Client Advanced Edition V6.0.1.

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, Rochester Center.

Guenther Hartung is an independent IT professional and owner of UBHartung IT-Beratung in Berlin, Germany. He is skilled in a variety of products and technologies including DB2®, Java™, RPG, Extensible Markup Language (XML), Java 2 Platform, Enterprise Edition (J2EE™), Web services, Eclipse, and WebSphere products in general. He is an author of technical articles and teaching materials as well as a speaker at technical conferences. Guenther has about 20 years of experience as a programmer and project leader using several programming languages, database management systems, and operating systems. He joined IBM Germany in 1990 as an instructor for IBM eServer iSeries application development with IBM Learning Services. He left IBM Germany in 2002 and continues to teach modern iSeries development for IBM in addition to his own work as a consultant for application modernization. Guenther holds a science degree in mathematics from the university of Jena, Germany. To contact Guenther, send e-mail to [email protected].

Rolf Andre Klaedtke is an independent IT Specialist and owner of RAK Software, Consulting & Publishing in Kreuzlingen, Switzerland. He has a commercial background and accumulated over 20 years of experience in the IT industry initially starting as a software developer using RPG and CL on IBM S/38. He has used a wide array of database management system (DBMS), tools, and languages. In recent years, he concentrated on Web development, mostly using PHP and cascading style sheets (CSS), as well as on C#.NET. He is an author and the

© Copyright IBM Corp. 2006. All rights reserved. ix publisher of PowerTimes and has organized technical conferences and user group meetings in Switzerland. You can contact Rolf by sending e-mail to [email protected].

Elena Lowery is a Technical Consultant in the IBM eServer Solutions Enablement organization at IBM Rochester. She helps IBM Business Partners implement various WebSphere technologies on the iSeries server. Her areas of expertise include WebSphere Application Server, WebSphere Portal Server, Web services, and Java development. You can send e-mail to Elena at [email protected].

Estela McCarty is a Computer Consultant for the EMEA Custom Technology Centre (CTC) located in La Gaude, France. For the past three years, she has been involved with the Web-enabling solutions (HATS, iSeries Access for Web, IBM WebFacing Tool, and WebSphere Portal Server) on the iSeries server. Estela conducts technical workshops for IBM Clients and Business Partners across EMEA. She was an AS/400® RPG application developer and systems analyst for nine years with IBM New Zealand and worked with the telecommunications, manufacturing, insurance, and education industries. Estela is also a Certified IBM Solution Developer for WebSphere Development Studio Client for iSeries. You can reach Estela by sending e-mail to [email protected].

Els Motmans is an advisory IT Specialist for IBM Global Services in Belgium, specializing in Application Management Services. She has 14 years of experience as a System i developer in RPG and COBOL. She joined IBM in 2000 to develop banking sector applications on the iSeries server, from the requirements definition over functional and technical analysis to coding and testing. Her areas of business expertise include accounting, inventory control, purchase management, stock exchange, and travel business. Els invented and improved several source code skeletons for standardization and increased productivity in application development and maintenance. You can contact Els by sending e-mail to [email protected].

Aleksandr Nartovich is a Senior IT Specialist in the IBM ITSO, Rochester Center. He joined the ITSO in January 2001 after working as a developer in the IBM WebSphere Business Components organization. During the first part of his career, Aleksandr was a developer in AS/400 communications. Later, he shifted his focus to business components development on WebSphere. Aleksandr holds two degrees: one in computer science from the University of Missouri-Kansas City and the other in electrical engineering from Minsk Radio Engineering Institute. You can reach Aleksandr by sending e-mail to [email protected].

Thanks to the following people for their contributions to this project:

Warren Acker Marc Fick Linda Hirsch Jeff Lee Carole Miner Nitin V. Raut Michael J. Sandberg IBM Rochester, Minnesota

Roland Barcia IBM Paramus, New Jersey Maha Masri IBM Somers, New York

John H. Douglas April Singer IBM Raleigh, North Carolina x IBM System i Application Modernization: Building a New Interface to Legacy Applications Doug Fulmer IBM Dallas, Texas

Hania Abd-El-Razik IBM Canada

Wilfried Blankertz IBM Germany

Axel Lachman FoxCom, Germany

Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability.

Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our Redbooks™ to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an e-mail to: [email protected] Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400

Preface xi

xii IBM System i Application Modernization: Building a New Interface to Legacy Applications

Part 1

Part 1 Looking at the alternatives

In this part, we discuss several typical scenarios of the current customer environment. We provide a quick look at possible alternatives for building a new interface to existing legacy applications. This part includes the following chapters: Chapter 1, “Why you should consider new application interfaces” on page 3 Chapter 2, “Modernizing System i legacy applications: Common business scenarios” on page 7

2 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 1. Why you should consider new application interfaces

In this chapter, we provide reasons why you should consider providing new user interfaces to modernize your applications. We address some of the implications that you must take into account when doing so. In addition, we point you to possible solutions that are discussed throughout the book.

Every so often, you may wonder whether your house needs a new coat of paint. In deciding whether to repaint your house, you may consider whether it is in fact “good enough”. You may question whether there are other aspects of the house, such as the replacing the roof or upgrading windows, that require your attention more than painting does. You will know it is time to take some action when the wind is howling through the windows and rain enters through the roof. Hopefully you will have made the right decision to avoid such problems.

Assuming that the user interfaces of your software applications are like the walls, roof, or windows of your house, the same concepts apply as to whether you should modernize them by adding a new interface. Here are some reasons why you might want to think about doing this: Your customers do not buy green-screen solutions anymore. If you are selling solutions to the iSeries market, you may already face the requirement by your customers to provide a Microsoft® Windows®- or Web-based interface to your application or applications. Putting a new iSeries application on the market without providing a Windows- or Web-based user interface may not work anymore because of the perception that green-screen applications are old or not modern enough. This idea is independent from the inner workings of the application. Users are accustomed to graphical user interfaces (GUIs). With the high level of distribution of GUIs, either through the Internet or through Windows-based applications, many current and potential new users are already familiar with the behavior of the user interface. Green-screen-type applications are clearly in the minority nowadays, and new employees may need extra training or time to get used to green-screen user interfaces. A new interface can yield better productivity and new possibilities. The saying, “A picture is more than a thousand words” is true here. Providing a GUI allows a wealth of new features. For example, product catalogs can display pictures of the actual product. Human resources applications can display a picture of the employee. In addition, financial applications can display data in a graph, allowing users to immediately compare and understand important information. Furthermore when using a GUI, more data may be displayed on a single screen, although not too much data so that it overloads the interface. Such a change enables you to streamline work processes and eliminate unnecessary downloads. Many iSeries users download data from their system to analyze it by creating charts and graphics in a spreadsheet (such as Lotus® 1-2-3® or Microsoft Excel®). Some have automated this process. Consider accessing your current data directly by using a Web-based application, without needing to download it. That way you do not duplicate data on other systems, and the whole process can be streamlined. Enhancing your software applications can lead to generating support for new clients. If your application provides a Web-based user interface, you may be one step away from supporting mobile or other clients. In certain environments, a handheld computer may provide tremendous productivity gains by allowing the users to collect data regardless of their location, where access to a computer is impossible otherwise.

4 IBM System i Application Modernization: Building a New Interface to Legacy Applications 1.2 Up-front considerations and prerequisites

Obviously you cannot simply apply a new Web- or Windows-based user interface to your application or applications. Otherwise that you would have done that already or perhaps long ago. Also, in certain circumstances applying a new GUI on an application may not be the best choice. For example, in a pure data-entry environment, it might be counter-productive.

In Chapter 2, “Modernizing System i legacy applications: Common business scenarios” on page 7, we introduce common business scenarios that can help you to identify the best solution for your requirements. Let us discuss some points that you must consider when modernizing an application interface: Hardware You should be aware that some of the suggested solutions in this book might require a hardware upgrade. This depends on your current system and the future requirements. Do not spend time and money to implement a new solution if the system cannot handle the possible increase in requirements. Existing software Are your current applications written according to the Original Programming Model (OPM) or the Integrated Language Environment® (ILE)? If the latter is true, have you taken full advantage of ILE concepts? Depending on the architecture of your current applications, you may have to envisage additional modernization steps, such as converting your RPG OPM programs to the ILE architecture. Otherwise it may be impossible to continue using them with some of the solutions that are introduced in this book, such as Web services based upon RPG programs. Available skills Depending on the available skills of your development team, you may need to plan for additional training and education. It is not simple to move from RPG to object-oriented software development, whether you use Java, .Net, or PHP. However, some of your staff members may have acquired some Web development skills in their spare time, for example, while setting up a private or family Web site. Others may have looked at the .Net architecture or other object-oriented technologies. A good first step is to catalog the available skills on your team, regardless of whether they are directly job related. Then you can evaluate the kind of skills that are necessary for the solution that you envisage to implement and start planning the required education accordingly.

1.3 IBM System i Developer Roadmap

IBM System i Developer Roadmap encapsulates IBM’s recommendations for modernizing iSeries applications. The IBM System i Developer Roadmap provides a step-by-step approach for taking an RPG, COBOL, C, C++, or Java application and building the necessary extensions to help iSeries customers adopt and integrate the latest technologies. The roadmap provides independent software vendors (ISVs) and customers the explanation and positioning of these technologies, tools, and products, along with the education learning path to begin to grow their skills.

Building a new user interface to your iSeries applications is one of the steps on this roadmap. You can find more information about the IBM System i Developer Roadmap at the following Web address: http://www.ibm.com/systems/i/roadmap/index.html

Chapter 1. Why you should consider new application interfaces 5 1.4 How to read this book

In Part 1, “Looking at the alternatives” on page 1, we identify the scenarios and provide the necessary input to help you to decide whether you need to consider providing a new user interface to your applications. In some cases, that signifies modernizing your applications and therefore, we explain the term “modernizing” in this context. Respectively requirements must be met so that implementing a new user interface can be reasonably envisaged.

In Part 2, “Using IBM solutions” on page 23, we introduce the IBM solutions, which are: IBM Host Access Transformation Services IBM WebFacing Tool

We only skim over the installation and configuration process of these solutions, because other IBM Redbooks and resources, to which we refer you, explain the steps in detail. Furthermore, we provide details about the up-front requirements for using each product and additional steps to perform when the installation and configuration process is done.

Finally in Part 3, “Designing a new user interface” on page 107, we explain how to build your own user interface to your applications. Because many of the selected technologies require that the business logic and the presentation layer are separated from each other, we discuss the necessary technical foundations and prerequisites.

This part includes a chapter on how to design a Web services interface, which contains some introductory material on Web services. Web services are not a user interface technology, but lead to a wide array of possible client technologies. This part also includes chapters that provide details about how to design user interfaces based on such technologies as JavaServer Faces (JSF) or portlets.

Throughout this book, we use a sample application. To download and install this application, refer to Appendix A, “Additional material” on page 285.

6 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 2. Modernizing System i legacy applications: Common business scenarios

In this chapter, we introduce some common business scenarios in which you may want to modernize your iSeries applications. These scenarios explain current customer situations with regard to the installed hardware, the application development environment, the target market, and the available skills. First we describe each example, and then we provide recommendations for a quick and more advanced solution, if one is available.

The following general considerations apply to all scenarios to a greater or lesser extent: Hardware

Depending on your currently installed hardware and the solution that you choose, a hardware upgrade might be necessary. Application development environment There is a tremendous difference between using the Screen Design Aid (SDA) and Source Edit Utility (SEU) tools and using more modern development tools such as WebSphere Development Studio Client for iSeries, which, among others features, provides a graphical user interface (GUI). Depending on your goals, you may also need to modernize your development environment. Target market The situation for an independent software vendor (ISV) who is in the market to sell applications is different from one where applications are developed for in-house use. Available skills For someone who is developing RPG applications according to the Original Programming Model (OPM) without using Integrated Language Environment (ILE), for example, it is more difficult to acquire the necessary knowledge and implement a full-blown, Java or WebSphere-based application than for someone who already has some Web development experience. Consider the skills that you have available to you and where those involved might require education.

2.2 Overview of the scenarios

In this section, we describe application modernization scenarios. For each scenario, we define the starting point and the end goal. We also explain the skills and investment required to complete the project.

2.2.1 Scenario 1: Add a Web front end to a monolithic iSeries application Company A has several traditional 5250 applications. The company’s application architecture is monolithic; presentation logic is mixed in with business and database logic. The company’s IT manager has decided that all internal applications must be Web-enabled. The manager asked his programming staff to Web-enable one of the traditional RPG applications in three months to evaluate the feasibility of converting the entire portfolio of company’s applications. The company has a staff of RPG developers and a Web master who maintains other internal HTTP-server based Web applications.

Since this project must be completed in a short time, and the company does not have Web application development skills, the best approach is to use a refacing tool. Refacing tools can usually convert an existing 5250 application to a Web application without changes to RPG source code.

IBM provides two refacing tools: IBM WebFacing Tool and IBM Host Access Transformation Services (HATS). In addition, IBM Business Partners provide tools for refacing traditional iSeries applications. See IBM System i Developer Roadmap Tools Web site for a complete list of IBM Business Partner tools: http://www-1.ibm.com/servers/enable/tools/innovation/enhance.html#application

8 IBM System i Application Modernization: Building a New Interface to Legacy Applications To complete a refacing project, the development staff must learn how to use a refacing tool, but they do not have to learn the underlying technology, such as servlets and JavaServer Pages™ (JSPs). Another skill that your staff must acquire is HTTP and application server (for example, WebSphere Application Server) administration.

Refacing projects can usually be completed in a shorter amount of time than building a new user interface (UI) from scratch. Different refacing tools provide various levels of customization for a refaced application. In Chapter 3, “Host Access Transformation Services” on page 25, and Chapter 4, “The IBM WebFacing Tool” on page 67, we describe the features of the IBM refacing tools.

2.2.2 Scenario 2: Add a portal front end to a monolithic iSeries application The starting point of this scenario is similar to scenario 1. In this scenario, a company has traditional monolithic RPG applications, skilled RPG staff, and a short amount of time to complete a project. The end goal of this scenario is to create applications that can be deployed in WebSphere Portal.

The task of portalizing iSeries applications can be achieved with three IBM products: IBM WebFacing Tool IBM Host Access Transformation Services toolkit iSeries Access for Web

As in the previous example, your development team must learn how to use a portlet builder tool, but not the underlying technology, which in this case is portlet programming. This project can be completed in the same amount of time as Web-enabling an application.

2.2.3 Scenario 3: Build a Web front end for a modular RPG application Company B has a suite of monolithic RPG applications. The company’s lead architect evaluated RPG refacing tools and learned that they do not satisfy customer’s requirements. The architect decided to reuse as much RPG code as possible and build a new Web front end.

The company’s developers have strong RPG skills, and a few developers have beginner to intermediate Java skills. The company started the project by choosing a Web technology, JavaServer Faces (JSF). Other choices that the architect considered were JSPs and PHP. This decision was based on the company’s direction to implement new applications in Java and JSF’s features that simplify and speed Web application development.

To complete this project, the company formed two teams: RPG developers to modernize the RPG application JSF developers to build a Web front end

The required skill for RPG developers is understanding the concepts of modular RPG and ILE programming. JSF developers must have beginner Java skills, understand IBM Toolbox for Java application programming interface (API), and learn how to use JSF tooling in WebSphere Studio or IBM Rational® products. IBM Toolbox for Java is an API for accessing iSeries applications, functions, and data from Java applications.

The main advantage of JSF over other technologies is not in the richness or the functionality of the UI, but in the development time and skills required to build the project. See Chapter 8, “Designing a JavaServer Faces-based interface” on page 161, for more information about JSF.

Chapter 2. Modernizing System i legacy applications: Common business scenarios 9 2.2.4 Scenario 4: Build a portal front end for a modular RPG application The end goal of this scenario is to create portal applications that access iSeries applications and data. Similar to scenario 3, a company evaluated refacing tools that convert traditional Web applications to portlets. The company decided that they want to implement custom portlets that fully use features of WebSphere Portal.

This project requires skills in understanding modular RPG and ILE programming concepts and knowledge of IBM Toolbox for Java API and portlet API. In addition, portlets can be developed with the JSF technology described in 2.2.3, “Scenario 3: Build a Web front end for a modular RPG application” on page 9.

From the scope, project length, and skills perspective, portlet development is similar to Web development. Rational tools provide wizards that simplify portlet development.

2.2.5 Scenario 5: Build a rich-client front end for a modular RPG application Company C has a requirement to build a rich-client front end for an existing RPG application. The term rich client usually refers to a desktop application. In the past, a rich client was often called a fat client. Companies choose to implement a rich client to provide a highly interactive event-driven UI.

To accomplish this task, the RPG application must be written in a modular format. The next step is to choose a rich-client technology. Today the most popular choices for rich-client application development are Eclipse Rich Client Platform (Eclipse RCP), Standard Widget Toolkit (SWT), Swing, IBM Workplace™ Managed Client, and Microsoft .Net. All of these rich-client technologies, with the exception of Microsoft .Net, are Java-based technologies.

Rich-client technologies provide the same UI features; the differences are in complexity, tools, integration with iSeries, and product philosophy (Java portability and open standards versus Microsoft proprietary technology). IBM provides tools and technologies for integrating both Java and Microsoft .Net applications with iSeries applications and data.

Company C decided to implement the Eclipse RCP application because of the company’s commitment to Java and open source technologies. The skills required to build an Eclipse RCP application are intermediate Java programming skills and an understanding of Eclipse plug-in development. WebSphere Studio and Rational tools, as well as IBM Business Partner tools, simplify Eclipse RCP application development by providing drag-and-drop development environment and wizards for building rich-client screens.

2.2.6 Scenario 6: Expose modular RPG applications as Web services Company D has a requirement to connect their existing RPG applications to different client applications, including client applications outside of the company’s firewall. The company decided to wrap existing RPG applications as Web services.

Web services are written in the form of an API, which means that they have a well-defined interface with input and output parameters. To create Web services from existing RPG programs, the RPG programs must be modular and stateless. See Chapter 7, “Designing a Web services interface” on page 119, for more information. The skills required to complete this project are understanding modular RPG and ILE programming concepts, knowledge of IBM Toolbox for Java API and Web services concepts.

From the scope, project length, and skills perspective, portlet development is similar to Web development. In many cases, you can develop Web services faster than a Web application

10 IBM System i Application Modernization: Building a New Interface to Legacy Applications because Web services do not have a UI. WebSphere Studio and Rational tools provide wizards that simplify Web services development.

Note: For most of the development tasks that are described in the previous sections, we recommend that you use WebSphere Development Studio Client for iSeries as the most advanced and feature-rich environment for iSeries developers.

2.3 Overview of basic solutions

In this section, we provide an overview of the basic solutions based on the tools that are available from IBM. Basic means that the cost and effort required to implement them are less than with the more advanced solutions that are introduced in the next section.

For each solution, we indicate the prerequisites as outlined in the following list: Hardware Software Skills Time Costs

In general, IBM-provided tools offer a faster development environment, which requires less time, knowledge of the new technologies, and effort. These solutions allow customers quickly move to the Web-based solutions without affecting their existing IT environment. The drawback of these solutions is the limited customization of the GUI and less opportunities to migrate to the more advances solutions in the future.

The advanced solutions, as we call them, require more knowledge and development effort. You can expect to pay a higher price for implementing these solutions. They provide a chance to build the advanced GUIs, integrate them with other applications, and open possibilities to move to the new technologies easier.

2.3.1 IBM WebFacing Tool In this section, we provide an overview of the IBM WebFacing Tool using business criteria.

Investment The IBM WebFacing Tool is part of WebSphere Development Studio Client. For iSeries customers with an existing software license agreement, the WebSphere Development Studio Client V6.0 Standard Edition is free, but you must purchase the Advanced Edition. Some of the more advanced IBM WebFacing Tool functions are available only in the Advanced Edition of WebSphere Development Studio Client.

Software WebFacing applications require an application server software for deployment. We recommend that you use WebSphere Application Server Express because it ships free with V5R3. Another option is to use ASF Tomcat on iSeries, but this servlet engine is not a strategic product, nor has IBM updated it for a few releases.

At runtime, the IBM WebFacing Tool creates the Web pages that should be displayed in Internet Explorer® V5.5 or later. You must consider the required PC hardware configuration as well (refer to the following “Hardware” section).

Chapter 2. Modernizing System i legacy applications: Common business scenarios 11 Hardware To use the IBM WebFacing Tool, you must follow these hardware requirements for development as well as for runtime: Development environment

To develope WebFacing applications, we recommend that you have about 1 GB RAM with 1.2 GHz processor for better response times. You must also have a bare minimum of a 3.5 GB hard disk. At installation time, you need an additional 1 GB of temporary space. If your file system is FAT32, you require more space. For more details, refer to Chapter 4, “The IBM WebFacing Tool” on page 67. Runtime environment Changes in the Licensed Internal Code (LIC) of the new iSeries servers announced on 20 January 2003 have made it possible for RPG and Cobol applications that are modernized using the IBM WebFacing Tool not to require any 5250 interactive capacity. Therefore, they can be run on the less-expensive Standard Edition of OS/400®. The supported iSeries models are the 170, 250, 270, 7xx, 8xx, 520, and 570. Because your WebFacing application must be deployed to a Web application server, you must ensure that your systems meet the minimum hardware requirements for your chosen application server version. For instance, if you plan to use WebSphere Application Server Express V6.0, the minimum available processor CPW required is 300 CPW, with a minimum of 1200 MB free disk space for installation. We recommend that you have 1 GB of physical memory and 2 MB of Level 2 Cache.

Skills You can use the generated pages without modification. In this case, you need only the skills to perform a basic conversion with WebSphere Development Studio Client.

Advanced customization features require skills in HTML, JavaScript™, page designing, and cascading style sheets (CSS) as well as knowing the CODE Designer tool. Integration with other Web applications may require some Java skills and good knowledge of the WebSphere Development Studio Client workbench.

Time Running the conversion is relatively fast, depending on your PC configuration. On a 3.2 GHz PC with 1.5 GB RAM, we estimate that it takes about one hour to create a project with 720 data description specification (DDS) files, assuming that the DDS files have an average of five typical record formats each, such as a header, a subfile control, a subfile body, and a footer. When the display files are converted, you can immediately run your WebFacing application.

However, time must be allotted to review every converted screen to validate the conversion and the behavior. If there are screens that need fixing, customization takes longer, especially if there are several of these erroneously-converted screens. This is because the customization is done on a screen-per-screen basis using the CODE Designer tool (or the Web settings inside the workbench). There are some customization that can be done on a project level, but these are basic changes such as to function keys, fonts and colors, and so on. If most of the screens that need customization follow some kind of pattern or standard, you may be able to globalize the customization by developing your own tool to copy and apply the Web settings done for fields in one display file to similar fields in the other display files.

12 IBM System i Application Modernization: Building a New Interface to Legacy Applications Changes to current business practices IBM WebFacing Tool is not a screen scraper. The host screens are converted to JSPs at development time, not at runtime. Some errors in this conversion process can be caused by product limitations and may necessitate changes in your current business practices: IBM WebFacing Tool uses the DDS to convert the screen record formats to JSPs and uses the DDS keywords to define the attributes of the generated Web pages. Not all keywords are supported, such as MLTCHCFLD, MENUBR, or PSHBTNCHC. Therefore, you may need to change your DDS to find alternatives to the unsupported keywords. The DDS Keyword Survey Tool scans your DDS sources and reports the keywords that are not supported by the IBM WebFacing Tool. You can download the Survey tool from: http://www-1.ibm.com/support/docview.wss?uid=swg24001257 Some operation codes are either not supported or only partially supported, such as INVITE (support is only for a single-device invite). IBM WebFacing Tool also cannot handle called APIs that are Synon-generated. IBM WebFacing Tool now supports the display of system screens, but this support is only in the Advanced version and only for user-interface manager (UIM)-based screens. To find the list of currently-supported system screens, refer to the following Web address: http://www.ibm.com/support/docview.wss?rs=715&context=SSZND2&context=SSBRL&context=SSKJJ P&context=SS2MD7&q1=system+screens&uid=swg21177025&loc=en_US&cs=utf-8&lang=en You may need to change your processing RPG or COBOL programs to accommodate the limitations of the IBM WebFacing Tool. You can use the WebFacing API QqfEnvironment to determine whether your program is being invoked by a 5250 user or by a WebFacing client. You can use this API to redirect the processing logic of the affected program if it is being invoked by a WebFacing client.

Note: WebSphere Development Studio Client V6.0.1 is equivalent to the new IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology has extensions to provide immediate integration of WebFaced applications with system screens and non-WebFaced 5250 applications. It leverages the “on-the-fly conversion” capabilities of HATS to Web-enable these system screens and 5250 applications. The Web pages generated on-the-fly inherit the GUI style of the WebFaced application.

While IBM WebFacing Tool can convert UIM-based Help panels referenced inside the DDS, it may not be capable of converting user-generated display files using UIM panels. Therefore, you may need to redo these screens with proper DDS files. There is no wizard to do incremental deployment of IBM WebFacing Tool if you need to reconvert some files and redeploy them. Therefore, you may need to review the scheduling of your version change control or implementation process for posting the changes, such as not redeploying the WebFaced application every time there is a change to one display file. Reconverting the DDS files regenerates the corresponding JSPs. IBM WebFacing Tool customization changes are stored as comments in these DDS files to accommodate this conversion behavior. If your DDS files are generated by a tool other than the PDM SDA or SEU, it is possible that the source files are scrapped completely by a third-party tool and brand new sources are created by the tool. In this case, you may need to save a copy of the DDS sources of your customized screens (with the customization comments) and manually put them back on the new DDS sources, or you may need to redo the customization again using the new DDS sources.

Chapter 2. Modernizing System i legacy applications: Common business scenarios 13 Because the WebFaced application is now browser-based, you must provide training and possibly create a company-specific user guide, to transition your application users from using the green-screen version to the Web version. You must also train your operations people on knowing which subsystems and jobs are associated with WebFacing clients.

Business scenarios addressed By using the IBM WebFacing Tool, you can address the following business scenarios: Availability of all display file DDS sources Need for quick and easy Web-enablement Not many changes on host display files Standard DDS coding patterns Not a lot of graphical DDS keywords Not a lot of user-generated UIM panels DDS sources not generated by third-party tools Need to integrate with other Web applications

2.3.2 Host Access Transformation Services In this section, we provide an overview of IBM HATS using business criteria.

Investment iSeries customers using WebSphere Development Studio Client get the HATS Toolkit for free, but with a hard limit of two users. To use the full HATS product, you must buy per-user or per-server licenses.

Software HATS applications require an application server software for deployment (similar to the IBM WebFacing Tool). We recommend that you use the WebSphere Application Server Express that ships free with V5R3 or later.

Your client may use one of the HATS-supported browsers, depending on the HATS version that you are using and your client platform. On a Windows platform for instance, HATS V6.0 can use Firefox V0.9 or later, Internet Explorer V6.0 SP1, Mozilla V1.6 or later, Netscape V6.2.3 or later, and Opera V7.0 or later.

Hardware To use HATS, you must meet the following hardware requirements for development and runtime: Development environment On a Windows platform, you need an Intel® Pentium® III minimum of 768 RAM with 500 MHz processor. You need a 2.2 GB hard drive with an additional 700 MB of temporary space during installation. Runtime environment The minimum recommended iSeries server models are the 270 model with processor feature 2252 or the 820 model with processor feature 2395. Runtime requirements for HATS follow those of the version of WebSphere Application Server used. For instance, for simple HATS applications deployed on WebSphere Application Server Express, you must have available at least 300 CPW with 768 MB memory. You may want to go above these minimum resource levels if you have a lot of users or if you require faster response times.

14 IBM System i Application Modernization: Building a New Interface to Legacy Applications Skills HATS is a screen scraper. To generate a working HATS application, you only need to know how to use the HATS project creation wizard. This generates all the required Web application resources without the JSPs because these are generated at runtime.

Advanced customization and transformation features require the same skills as the IBM WebFacing Tool, which include HTML, JavaScript, page designing, and CSS skills. You may also need to be familiar with using the macro feature of HATS. Integration with other applications may require some Java skills to fully use the Business Logic feature, and you must have good knowledge of the advanced macro features and use of integration objects.

Time HATS converts the host screens on-the-fly, that is, at runtime. It does not even take an hour to generate a working HATS application if you accept all of the default settings.

However, after you create your HATS project, you must run your application and visit all your host screens to validate how they are converted to their corresponding Web pages. The screens that are not rendered properly need to be corrected, either by tweaking the project-level recognition and rendering rules or by introducing screen transformations. To perform this validation and correction exercise for say 2500 to 3000 screens, you might want to allocate a minimum of two weeks of full-time work. You then need additional time to perform any other company-specific customization.

Changes to the current business practices HATS does not require any DDS sources to generate JSPs for the host screens. It converts the screens at runtime by “reading” the host screens and trying to recognize components on them. Then it applies predefined rules to render the host components as widgets on the generated Web pages. If the way your host components appear on the screen does not satisfy the predefined rules for recognition, they may not be recognized and may not be rendered the same way as other recognized components in other screens. The effect is an inconsistent look and consequent user behavior across all your screens. It is possible too that a badly-rendered screen will not deliver its function correctly. For example, if two function keys are rendered as one, then you lose the business function that is provided by the normal invocation of the other function key. When this happens, your options are to change the recognition rules or customize the screens. In some cases, especially if there are too many badly-rendered screens and exceptions to your coding standards, then you may prefer to make changes to your DDS sources instead. The choice of whether to accommodate an exception by tweaking the default rules or by doing a screen customization may be based on the possible number of screens having the same irregular patterns. For example, one of the default rules for recognizing function keys is the pattern “Fn=xxx”. If your coding pattern is “CAn=xxx”, then it may be more efficient to change the default recognition rule for function keys to make the change global to your application. If all your application coding practices are so diverse and no standards are followed, changing the default rules may not be an option at all. Introducing screen-per-screen customization is an option, but it may result in degraded performance. In this case, you may want to consider revisiting your coding practices, introduce some standards, and change your display file sources. HATS has a keyboard mapping file KBS.js that defines how the 5250 keyboard strokes are recognized on the browser page. Some of these default mappings may not match your

Chapter 2. Modernizing System i legacy applications: Common business scenarios 15 company-defined keyboard mappings. For example, the Reset function on the 5250 keyboard is the Ctrl key, while the HATS mapping is to a combination of the Ctrl key and the letter R (Ctrl+R). You must review this mapping file to determine the HATS defined mappings. Then you have the option to either change the HATS mappings or change your physical keyboard mappings.

Like all Web applications, the HATS application is now browser-based. Therefore, you must also provide a training session and possibly create a company-specific user guide, to transition your application users from using the green-screen version to the Web version. You also have the option to create a HATS Administration application for your system operators to use. This Web-based application gives them options to manage HATS sessions. If you decide to implement this, you must have a separate user training for your operations staff.

Business scenarios addressed Using the IBM HATS tool addresses the following business scenarios: Availability of display file DDS sources Need for quick and easy Web-enablement Frequent changes to host display files Standard DDS coding patterns Use of a lot of graphical DDS (ENPTUI) keywords Use of a lot of user-generated UIM panels Starting many system screens or functions from application screens In-house development of DDS sources The need to integrate with IBM eServer zSeries®-based applications or other Web applications

2.4 Overview of advanced solutions

In this section, we provide an overview of the advanced solutions based on tools from IBM and from other sources. Advanced in this case refers to the fact that the requirements with regard to the necessary hardware, software, skills, time to implement, and the costs are higher than with the basic solutions.

2.4.1 JavaServer Faces technology In this section, we provide an overview of the JSF technology using business criteria.

Investment IBM first implemented and delivered the JSF standards in WebSphere Development Studio Client V5.1.2. It is available in the Standard Edition of the product, which is free for iSeries customers who already have a software license agreement. Both WebSphere Development Studio Client V5.1.2, with all applicable fix packs, and WebSphere Development Studio Client V6.0 implement the JSF 1.1 standards. WebSphere Development Studio Client V6.0 also implements the JSF 1.4 standards.

Software JSF technology provides a UI framework for rapid Web application development. To create JSF applications, you only need a WebSphere Studio version that provides JSF support. At runtime, your generated JSF application, like any other Web application, requires a Web application server for deployment. You need to have that installed on your server platform. There are no special requirements that apply specifically to JSF applications.

16 IBM System i Application Modernization: Building a New Interface to Legacy Applications Hardware The workstation hardware requirements for developing JSF applications follow the requirements of the WebSphere Studio software version that you use for development: Development environment

There are no special workstation hardware requirements for developing JSF applications. If you want to use WebSphere Development Studio Client V6.0, refer to the following Web site for the workstation system requirements: http://www-306.ibm.com/software/awdtools/wds400/sysreq/index2.html Runtime environment There are also no special server hardware requirements for running JSF applications. It follows the requirements of the WebSphere Application Server version that you use for deployment. If you want to use the WebSphere Application Server V6.0, refer to the following Web site for the system requirements: http://www-306.ibm.com/software/webservers/appserv/was/requirements/

Skills To create a basic JSF Web application, you must have a working knowledge of the following items: Java programming language Java 2 Platform, Enterprise Edition (J2EE) Web application architecture Model-view-controller (MVC) design pattern JSPs or servlets

You must also have previous experience with using the WebSphere Development Studio Client or Rational Application Developer workbench and some of the related features such as the Remote Systems Explorer functions and the iSeries Web development tools.

To fully take advantage of the JSF framework or to debug your JSF application, you may also need solid background knowledge regarding the following topics: Tag libraries Extensible Markup Language (XML, because JSF configuration files are in XML format) Page designing and CSS knowledge Prior experience in Web development

Time Let us assume that you are a beginner to the JSF technology with the following background and requirements: You have a basic knowledge of Java programming. You are familiar with the WebSphere Development Studio Client or Rational Application Developer workbench functions. You need to develop a JSF-based Web application using basic database create, read, update, and delete functions. You want to invoke existing RPG modules using create, read, update, and delete functions for your host application

We estimate that you might be able to develop the functional JSF application in at least one full day. If you were a developer with more advanced knowledge of Java and the JSF framework, it might only take you an hour. Both cases assume there is no page designing done yet.

Chapter 2. Modernizing System i legacy applications: Common business scenarios 17 Changes to the current business practices JSF applications typically access the iSeries resources by using Java ProgramCall beans, by invoking Web services, or by retrieving data directly from application files: If you want to develop a JSF application that retrieves data from some of your database files because you have no existing host application functions that currently do that, then you can use another technology called Service Data Objects (SDO). SDO is basically the encapsulation of data from your files as Java objects and using these Java objects within the JSF framework. With SDO, you are now exposing your data files to direct access from the Web client. You may have to ensure that create, update, and delete access to these files will not result in database discrepancies, especially if you have other host programs that require create, read, update, and delete access to the files but that pass through business validations within the programs. These can imply building validation triggers for the files or revisiting your programs to make the validation procedures more robust. You may prefer to invoke your existing RPG or COBOL programs or modules within the JSF framework by using ProgramCall Java beans or Web services. With ProgramCall Java beans or Web services, all access to your database files passes through the same business validations to ensure minimal database discrepancies. For host application programs to be callable from Java beans or Web services, they must satisfy two basic requirements: – They must be structured in an API format. The program must have input and output parameters if they are not outputting the results of the processing to a database file for further processing. – They must be modular and not monolithic. Handling of the input and output processing as well as the business logic processing and the database access is not being done within one program. If your application programs do not meet these two requirements, you may need to go through the exercise of modernizing your applications as explained in 5.1.2, “Modernizing OPM programs” on page 110. Like all Web applications, the JSF application is also browser based. You must provide the required training or a user guide for your new Web application. If you still need to use your green-screen applications, then you may also need to revisit your application version change-control process to accommodate the handling of changes to the Web version.

Business scenarios addressed Using the JSF technology addresses the following business scenarios: The need for more flexibility in ways of retrieving data from host applications or servers Application programs that are modular and modernized A development team with a solid background in Java programming and J2EE technology The need for quick and easy Web enabling of some business functions not being delivered by the existing host applications Most new functions required for Web-enabling for enquiry purposes only The need to integrate with applications running on various platforms The need to integrate with other company business applications (business to business (B2B))

18 IBM System i Application Modernization: Building a New Interface to Legacy Applications 2.4.2 Rich client The interest in rich-client applications is a comeback from the client-server architecture with a new twist. In the following sections, we provide a high-level look at the existing technologies to implement the rich-client interface, server requirements, and the development platform that you need to master.

Rich-client technologies In this section, we review the business impact of implementing rich-client applications. We focus on four main choices for developing rich-client applications: Standard Widget Toolkit (SWT) Eclipse Rich Client Platform (Eclipse RCP) IBM Workplace Managed Client™ Microsoft .Net

Investment The required investment is different for each rich-client technology because of the following factors: Open source versus proprietary technology The cost of tooling Built-in functionality

SWT and Eclipse RCP are open source technologies. In addition, you can use open source tools (Eclipse IDE) to develop SWT and Eclipse RCP applications.

IBM Workplace Managed Client is a part of the IBM Workplace family of products. While Workplace Managed Client applications are extensions of open source Eclipse RCP applications, they require a server-side component, IBM Workplace Collaboration Services. Workplace Managed Client applications can be developed in WebSphere Development Studio Client with Workplace Managed Client toolkit. SWT, Eclipse RCP, and Workplace Managed Client rich-client applications can run on Windows and Linux®.

Microsoft .Net applications are developed in Microsoft Visual Studio®. Microsoft .Net rich-client applications run only on Windows.

All of the described technologies provide almost equivalent rich-client functionality. IBM Workplace Managed client extends the basic rich-client functionality by providing server-managed installation and maintenance, as well as collaboration functions.

Software Rich-client applications, with the exception of IBM Workplace Managed Client, do not require additional software on the server. However, if your rich-client application accesses a servlet or a Web service, you need an application server to host the Web application or Web services.

Java rich clients require a Java virtual machine (JVM™) on a client system. Microsoft .Net rich-client applications do not have any additional requirements for the client system, although you can run it on Windows only.

Hardware There are no specific hardware recommendations for rich-client applications. In this case, the best way to find the minimal hardware requirements is through testing.

Chapter 2. Modernizing System i legacy applications: Common business scenarios 19 Skills We recommend that you have the following skills for developing rich-client applications: Strong knowledge of the object-oriented architecture GUI design skills Java programming language (for Java rich-client applications) SWT API (for SWT and Eclipse RCP applications) Eclipse plug-in development (for Eclipse RCP applications) Visual Studio for .NET applications

Business scenarios addressed The main business need addressed by rich-client technology is to provide a highly functional “rich” UI. While Web applications offer some rich-client features, there are still cases where a true rich-client implementation is better because it brings a more function-rich-client platform. Other business scenarios are: The need to shift some workload from the server to the client The need for simpler server infrastructure (rich client does not require an HTTP or application server)

Keep in mind that, as with any client-server architecture, you should expect higher costs in maintenance.

2.4.3 PHP Interest in PHP has gown constantly since it first became available, and there are no signs why this should change anytime soon. In this section, we provide information about what you can expect if you want to start working with PHP.

Investment The initial investment to start working with PHP is low. In fact, you can download Zend Core for i5/OS from the following Web site: https://www.zend.com/core/oem_registration.php?access_code=IBMi5OS

Depending on your staff’s skill set, you may want to invest in training classes or in-house training. Furthermore, you may want to invest in a professional development environment that provides better support than just a simple text editor, such as support for debugging.

Software Except for PHP, no additional software is needed. However, you may want to consider such products as Zend Guard, which enables the protection and mass distribution of commercial PHP applications. Zend Guard is comprised of two key components, Zend Guard’s encoder and Zend Guard’s license manager.

Hardware No additional hardware is needed to develop and run PHP applications. PHP can be installed on systems that run i5/OS V5R4.

20 IBM System i Application Modernization: Building a New Interface to Legacy Applications Skills Even though PHP is rather easy to learn and use, we recommend that you learn at least the basics to make the best use of it. We recommend that you have the following skills: Good software design principles Knowledge of object-oriented technology Knowledge of Web technology and the particularities of Web applications compared to “traditional” or host-based applications

Business scenarios addressed PHP is typically used for Web-based applications, which is where it excels. This can be Internet or intranet applications. A possible scenario is to develop an intranet application using PHP to gain some experience. That way you can apply your PHP knowledge and learn about Web-based applications. Such an intranet application can even access resources on the System i platform using Web services.

In the near future, you should be able to access a wide variety of System i resources using the extensions packaged in Zend Core for i5/OS.

Chapter 2. Modernizing System i legacy applications: Common business scenarios 21

22 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Part 2

Part 2 Using IBM solutions

In this part, we discuss the IBM-provided solutions and tools that help customers quickly move to the Web. These solutions are presented in the following chapters: Chapter 3, “Host Access Transformation Services” on page 25 Chapter 4, “The IBM WebFacing Tool” on page 67

24 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 3. Host Access Transformation Services

Host Access Transformation Services (HATS) is one of the IBM solutions for Web-enabling applications running on z/OS® (3270 screens) or on i5/OS (5250 screens). Through a set of predefined screen recognition and screen-to-Web-page rendering rules, HATS makes access to these applications through the most popular Web browsers, converting host screens to the HTML pages.

The macro support of HATS provides the ability to improve the workflow and navigation of host applications as well as the ability to merge information from multiple screens or from multiple applications into a single Web page. Other advanced features include Integration Objects, the use of business logic, and portal support provide integration capabilities with other applications running on the customer environment.

This chapter concentrates on HATS V6 and addresses the following areas: What is required to prepare for a HATS implementation? What is required to have a production-strength HATS application? How do you install and configure HATS? What are the new features provided in HATS V6.0 and the refresh packs? Is there a sample HATS application that uses default rules (refer to Appendix A, “Additional material” on page 285)? How do you deploy the HATS application to the iSeries server?

The following sections describe the system prerequisites for using HATS. More importantly, they attempt to set some customer expectation by discussing the approach to and the requirements for doing a HATS project implementation.

The HATS version that we describe in this redbook is the fully-licensed product that is installed as a plug-in to a WebSphere or Rational Software Development-based studio in your PC. If you already have a studio installed on your PC, the HATS Toolkit is plugged into this existing studio. You must purchase HATS licenses to use this product on a production system. (Refer to 3.2, “IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 34, for the latest information.) However, you can use the HATS Trial Toolkit if you want to evaluate the product first. This HATS Toolkit also requires an Eclipse-based development studio to plug into.

3.1.1 Hardware and software requirements

A HATS application is a typical Web application that runs in a Web application server. As such, it has both development requirements and deployment requirements.

Development requirements

Note: Additional PTFs are required for the latest support of HATS applications. Refer to 3.2.3, “Additional PTFs to enable IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 36, for more information.

HATS applications are developed using the HATS Toolkit, a plug-in to the IBM Eclipse-based development studio. The system requirements for HATS development inherit the system requirements for the Eclipse-based development studio being used. The HATS V6.0 tool requires one of the following development studios: Rational Web Developer V6.0 Rational Application Developer V6.0 Rational Studio Architect V6.0 WebSphere Development Studio Client for iSeries V6.0

In this redbook, we use WebSphere Development Studio Client V6.0 installed on a PC workstation. This includes the HATS Toolkit that provides two connections that can be used for development. The system requirements for installation on your PC follow those of the IBM Rational Developer product on which WebSphere Development Studio Client V6 is based. The disk and memory requirements have considerably increased compared to previous versions. To view these requirements, refer to the Web page at the following address: http://www-306.ibm.com/software/awdtools/developer/application/sysreq/index.html

Note: You can reduce the minimum required disk space if optional features and test environments are not installed.

For the complete system requirements that are specific to WebSphere Development Studio Client V6.0, refer to the following Web page: http://www-306.ibm.com/software/awdtools/wdt400/sysreq/index.html

26 IBM System i Application Modernization: Building a New Interface to Legacy Applications Deployment requirements

HATS applications are deployed to an application server for run-time execution of the applications. Therefore, they inherit the software and system requirements for the Web application server, with the following exceptions: 5250 print support requires IBM iSeries Access for Web Version 5.3 or later, which is available as part of the iSeries Access Family. HATS works with IBM Tivoli® Access Manager to provide support for Web Express Logon. Deploying HATS projects that were created in HATS Studio as portlets requires WebSphere Portal V5.0, V5.0.2, V5.0.2.1, V5.0.2.2, or V5.1.

HATS can be deployed on the iSeries server to one of the following types of IBM WebSphere Application Server: WebSphere Application Server V5.1 for iSeries or later WebSphere Application Server Network Deployment V5.1 for iSeries or later WebSphere Application Server - Express for iSeries V5.1 or later WebSphere Application Server V6.0 for OS/400 or later WebSphere Application Server - Express V6.0 for OS/400 or later WebSphere Application Server Network Deployment V6.0 for OS/400 or later

You can find the full list of supported platforms and WebSphere versions in the WebSphere Information Center at the following address: http://publib.boulder.ibm.com/infocenter/hatsv6/index.jsp?topic=/com.ibm.hats.doc/nl/en/doc /hatshwsw.htm

In this redbook, we use WebSphere Application Server for iSeries V6.0. Your iSeries machine must have a minimum of 1200 MB free disk space for installation.

If you have simple applications, your iSeries server must meet these minimum requirements: One of the following recommended minimum server models: – Model 270 with processor feature 2252 – Model 820, processor feature 2395 300 CPW 768 MB memory

Note: These requirements are based on a single WebSphere Application Server profile and represent the recommended minimum requirements. Additional profiles running concurrently require additional resources. Applications that must support many users or require shorter response times require additional resources.

Chapter 3. Host Access Transformation Services 27 If your applications contain enterprise beans, your iSeries server must meet these minimum requirements: Recommended minimum server models: – Model 170 with processor feature 2385 – Model 720 with processor feature 2062 – Model 270 with processor feature 2252 – Model 800 with processor feature 2464 – Model 820 with one of these processor features 2395, 2396, 2427, or 2458 – Models 520, 570, 810, 825, 830, 840, 870, or 890 450 CPW 2 MB Level 2 cache 1 GB memory in addition to memory required for any other applications running on your iSeries server

Note: Each HATS application that you deploy requires additional disk space. The minimum disk space required for each HATS application is approximately 30 MB.

For the complete software, hardware, and PTF prerequisites for WebSphere Application Server, refer to the following Web page: http://www-03.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/

When you reach this Web page, click your version or edition of the product and then, on the next page, select a link for specific prerequisite information.

3.1.2 Project implementation requirements

For a more complete overview about the HATS V6.0 product, refer to the Software Announcement from 08 February 2005 at the following Web address: ftp://ftp.software.ibm.com/software/webserver/hostintegration/library/ENUS205-022.pdf

HATS is primarily a screen-scraper tool that converts host screens into HTML pages by using a rules engine. Screen recognition rules are used to identify host screen components, and rendering rules are used to transform the host components into Web page widgets. As the tool is developed to be a generic tool, the default HATS rules may not work well with your application coding standards. Thus, while you can Web-enable your application by using the default HATS conversion, the resulting look and feel may not be enough depending on your company requirements. Therefore, you might be required to use the HATS screen customization and transformation features.

HATS is not just a screen converter. It has powerful advanced features to handle more complex requirements such as integration with other applications or platforms, security and advanced screen flow, and navigation changes. Therefore, if you prefer to design your own Web pages and control the information that is being displayed in these pages, you can do so. Then you only use HATS for its integration capabilities. These advanced features require you to have an in-depth knowledge of the tool and may require some knowledge of Java, HTML, and JavaScript.

28 IBM System i Application Modernization: Building a New Interface to Legacy Applications HATS project scoping It is important that you define your business and Web page requirements before scoping out a HATS project implementation. These requirements may involve the following considerations among others: Number and complexity of screens involved Integration with third-party applications Back-end systems to be converted Requirements for look and feel (default or customized) Security requirements Requirements for changes to screen flow and navigation Special data formatting requirements Team skills Price tag

Possible hardware and software upgrade If you do not yet have an application server for deploying your HATS application, you must investigate the server hardware and software prerequisites before you buy your HATS licenses. Depending on the version of the Web application server that you have or plan to use, there may or may not be a need to upgrade your server configuration. You must ensure that your server meets the minimum requirements specified in 3.1.1, “Hardware and software requirements” on page 26.

For the complete hardware and software requirements for using HATS V6.0, refer to WebSphere Information Center at the following address: http://publib.boulder.ibm.com/infocenter/hatsv6/index.jsp

Skills requirement We recommend that you have the following composition of knowledge and skills for a HATS project implementation: HATS product knowledge, especially customization and integration Host application knowledge, preferably by application analysts, experts, or developers, who can identify screen recognition patterns and validate the customization requirements Application use knowledge, which is typically of the actual users of the application Their normal application usage will serve as the functional testing to flush out screens with errant conversions. Page designing skills to design and implement the final HATS template and the Web page design Some of the skills needed are in the areas of CSS, HTML, and JavaScript. Java skills to support any third-party integration requirement Third-party application knowledge to provide the information or development required for the integration. Project management to provide the required decision about the possible alternatives or workarounds to adopt in case of unsupported functions due to possible HATS product limitations

Chapter 3. Host Access Transformation Services 29 3.1.3 Project implementation strategy Every HATS implementation strategy varies from customer to customer depending on the

following customer implementation factors: Business requirements Web page look-and-feel requirements Screen flow and navigation change requirements Total number of screens Third-party or back-end applications integration requirements Development or implementation team skills Type of users

Regardless of your requirements are, there is a basic implementation strategy that is generic enough that you can use it as the basis to make an estimate of how long your implementation might take. We attempt to outline that strategy in the following sections.

Recommended implementation phases The duration of some of the activities listed in a phase may continue on to the next phase, depending on how complex the activity is.

Phase 1: Project initiation and problem identification This phase involves creating your first HATS application using the shipped default conversion and rendering rules and validating the resulting behavior of your application. Development of your integration requirements may also be started in parallel: 1. Identify all of your requirements including the application that is to be HATS-enabled (refer to “HATS project scoping” on page 29). 2. Assemble the right skills for your implementation team (refer to “Skills requirement” on page 29). 3. Create a default HATS project using your targeted application. At this point, you should already have introduced changes in the default HATS rendering rules to accommodate your company-defined look-and-feel requirements. Typical examples are: – Whether function keys should be rendered as buttons or as links on the generated Web pages – Whether menus should be rendered as radio buttons or links 4. Perform the following actions in parallel: – Validate the default conversion of all the application screens that you consider to be critical and important for the project. You do this by invoking the screens using the HATS application: • Identify screens that are not rendered properly or that do not behave as expected and mark these host screens as errant screens. • Identify common screen recognition patterns among these screens. – Start developing your company-specific template and Web page look and feel. – Start developing your integration requirements, if you have any.

30 IBM System i Application Modernization: Building a New Interface to Legacy Applications Phase 2: Unit and function testing and problem resolution You must perform the steps in this phase in iteration until all of your application screens are rendered correctly and all of your added customized functions are working properly. 1. Start resolving the errant screens by completing either of the following actions (listed in the order of recommended preference): a. Change the default rendering rules. This makes the resolution global; that is, the change is propagated to all the application screens because it is at project level. b. Introduce global rules to resolve problems involving input fields. This also makes the resolution global. c. Introduce screen customizations or transformations. As much as possible, try to use the identified common screen recognition patterns to make the customizations as global as possible. The aim is to limit the number of screen-by-screen customizations as best you can for performance considerations and development time. 2. Define and configure the deployment environment, and put in place a change control strategy for the application deployment. 3. Validate the default conversion of the rest of the application screens. The best way to do this might be to deploy a test version of your HATS application to your server and make it available to a function test team composed of your application analysts, experts, or developers. They know how to run the applications to flush out all other errant screens because they know the application coding standards. They can identify the common host screen patterns required to globalize the resolution of the errant screens.

Phase 3: User testing and problem resolution This phase involves deploying your HATS application to your production environment and making your test HATS application available to a pilot testing team that is composed of selected actual users of your application. The HATS application runs in parallel to the production green-screen application.

At this time, you have already built in your other integration requirements and have a HATS project that is close to production-strength level. This exercise not only flushes out more incorrectly-converted screens, but it might also dictate more changes to correct possible problems in the behavior and usability of the generated Web pages from a user perspective.

This pilot user testing exercise also gives you an initial idea of the HATS performance so you can identify an acceptable level of response times.

Phase 4: User training and project documentation This phase involves training the users on the use of the new HATS application as well as developing customer-specific user guides or manuals. This training phase should include developing the HATS administration project and training the system administrators.

You may only be able to start this phase when there is a nearly stable base version of the HATS application to work with, probably in parallel with Phase 3.

Phase 5: Go live At this stage, you deploy the customized HATS application on the production server.

Chapter 3. Host Access Transformation Services 31 3.1.4 Typical case studies In this section, we discuss typical customer scenarios and provide estimates on the

implementation time frames.

Case study 1: Full implementation This scenario involves implementing to production a HATS application based on the customer requirements outlined in Table 3-1.

Table 3-1 Customer scenario: Full implementation Implementation factors Customer situation

Business requirements To Web-enable RPG-based host applications running on the iSeries server only

Web page look-and-feel To use a company-defined template and default browser requirements behavior, with the Web pages as close as possible to green-screen look because of conservative users

Screen flow and navigation change None requirements

Total number of screens 2500 to 3000 screens

Third-party or back-end applications Requires the customer to receive input information from a integration requirements PC-based application and use this information to determine the initial Web page and contents to display

Development or implementation Resource group of 20 people with the following skills or roles: team skills HATS knowledge RPG development Application knowledge Function testers Page designer Java developer Third-party application developer Actual users

Type of users No power users (users who do a lot of type-ahead data entry)

Based on an actual customer with almost identical requirements, the implementation effort estimates are outlined per phase in Table 3-2.

Table 3-2 Ballpark estimates: Full implementation Implementation phase Estimated effort

Phase 1: Project initiation and problem identification One to two weeks

Phase 2: Unit and function testing and problem resolution Two months

Phase 3: User testing and problem resolution Two months

Phase 4: User training and project documentation One month

Phase 5: Go live

32 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Restriction: These estimates are not meant to replace the requirement of scoping your HATS implementation based on properly-defined business, function, and user

requirements.

Case study 2: Proof of concept This is an example of a typical proof of concept in which only one of the major functions of a company’s main application is implemented.

Business requirements Allow clients to access one function of the main application, but limit their view to only certain screens of the function; that is, restrict the viewing of screens that contain company internal information such as product price tables.

Proof of concept shows the required final Web page flow and navigation as outlined in “Proof-of-concept requirements” on page 33. The implementation also serves as on-the-job HATS training to the customer’s application analysts.

Customer situation The implementation team consists of one HATS implementor working with two or three customer application analysts or users.

Proof-of-concept requirements The purpose of proof of concept is to develop a Web version of the application function with the following requirements: Display the input prompts from three consecutive host screens in the Web page that correspond to the first of these screens (combine screens into one). Change the function navigation by skipping the display of four to five screens in the Web version. Hide navigation paths and skip any intermediate screens that may be invoked programmatically based on information displayed on these screens. Do not display certain information from host screens in the Web version. Introduce drop-down selection lists to certain input fields in some screens.

There are no requirements for templates and Web page look and feel yet.

Proof-of-concept ballpark estimate This proof of concept involves the macros, skip screens, and combined screens features of HATS. It can become quite complex to implement especially if the screens to be combined have dynamic data as well as input fields. An exercise like this can take a minimum of one to two weeks depending on the number of hidden navigation paths to be accommodated.

Chapter 3. Host Access Transformation Services 33 3.2 IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology

IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology is a runtime enabler that allows the IBM WebFacing Tool and HATS technologies to work together in an integrated fashion. Both the IBM WebFacing Tool and HATS Toolkit customers can work seamlessly with their existing projects, while taking advantage of the new capabilities when combined with i5/OS V5R4.

Note: The HATS hardware and software prerequisites are the same as described in 3.1.1, “Hardware and software requirements” on page 26.

For more information, read the announcement letter at the following Web page: http://www-306.ibm.com/fcgi-bin/common/ssi/ssialias?infotype=an&subtype=ca&appname=Demonstr ation&htmlfid=897/ENUS206-023

The IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology home page is at the following Web address: http://www.ibm.com/software/awdtools/wdht/

3.2.1 Benefits to iSeries customers

V5R4 customers can take advantage of IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. This product integrates the strengths of HATS and the IBM WebFacing Tool in a single offering. It removes the confusion that has existed before regarding which tool to use.

For HATS customers, it means no more online transaction processing (OLTP) capacity requirements if they run their host applications on V5R4. For IBM WebFacing Tool customers, it means seamless support of the system screens and non-WebFaced applications on the System i platform. In the following sections, we provide mode details about each tool: HATS and IBM WebFacing Tool.

IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology for HATS customers As of 14 April 2006, all part numbers for WebSphere HATS for iSeries and WebSphere HATS for IBM eServer i5 520 have been withdrawn. They are being replaced by IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology.

The new HATS customers with V5R4 systems must purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology and enable HATS applications with the enablement key. The enablement is done at development time by using the Enable HATS Runtime option in the HATS perspective. For more information about this, see 3.5.1, “Developing a HATS application” on page 48.

Note: HATS applications are limited to two user connections without the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology enablement option.

34 IBM System i Application Modernization: Building a New Interface to Legacy Applications IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology for IBM WebFacing Tool customers IBM WebFacing Tool customers have two ways to run the WebFaced applications: Like before, convert the System i applications that have data description specification (DDS) source and run them. There is no need to purchase the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology product.

Important: In the next version of WebSphere Development Studio Client, customers are required to purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology for all WebFaced applications.

Develop and run 5250 applications that include: – WebFaced applications – Non-WebFaced applications (with or without the DDS source) – System screens You must purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology to enable this support. The support for non-WebFaced applications and system screens is enabled with HATS technology; the conversion is performed on the fly.

Note: There is limited support for two user connections without purchasing IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. This is acceptable for testing only.

3.2.2 Components in the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology package

The WebFacing Deployment Tool with HATS Technology V6.0.1 product includes the following components: Required: The runtime license enablement file for deploying HATS and WebFaced applications is included. These WebFaced applications interact with non-WebFaced 5250 applications and system screens. This product is only available via Passport Advantage. It is not available in as a shrink-wrapped product. Optional: HATS Toolkit 6.0.4 is included for convenience. This has been the latest HATS fix level at the time when IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology was released. Optional: WebSphere Application Server Express for Multiplatforms is included for non-tier-based license entitlement.

Items listed as optional are additional workstation products. Install them only if you are doing development tasks that require them. For the purpose of this chapter, you want to install HATS Toolkit v6.0.4 to develop a HATS project.

Chapter 3. Host Access Transformation Services 35 3.2.3 Additional PTFs to enable IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology

To support the new product on iSeries, you must verify that your system has the latest IBM WebFacing Tool PTFs. For the current list of PTFs, refer to the following Web site:

http://www-1.ibm.com/support/docview.wss?rs=255&uid=swg27002213

At the time of writing this book, the following PTFs are required: SI21733 Enable WebFacing server for V5R4 SI21736 OSP WSFM SUPPORT FOR NON-WEBFACED DSPF SI21738 OSP WSFM SUPPORT FOR NON-WEBFACED DSPF

3.2.4 Purchasing scenarios

After announcing IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology, we present several scenarios to help clarify what you should receive for using HATS and how.

Important: All HATS for iSeries and HATS for eServer i5 520 accounts have been migrated to IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. In the event that a migration has not been successfully completed, contact your IBM representative.

Scenario 1: Existing HATS customer on a pre-V5R4 system For customers who bought HATS for iSeries before April 2006, these are the conditions for using HATS: You can continue to use their current HATS Toolkit and enablement file. You can continue to download fixes to the current version of their HATS Toolkit, as long as it is in service. At the time of maintenance renewal, you will renew IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology maintenance in place of the HATS for iSeries maintenance.

Scenario 2: Existing HATS customer on a V5R4 system For existing HATS customers who are running a V5R4 system, these are the conditions for using HATS: You can continue to use your current HATS Toolkit and enablement file. You can continue to download fixes to the current version of your HATS Toolkit, as long as it is in service. If you want to take advantage of the new features of the latest HATS Toolkit, including the elimination of the OLTP requirement, you can upgrade your HATS Toolkit to the latest version. At the time of maintenance renewal, you will renew IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology maintenance in place of HATS for iSeries maintenance.

36 IBM System i Application Modernization: Building a New Interface to Legacy Applications Scenario 3: New HATS customer on a V5R4 system For new HATS customers on a V5R4 system, there is one condition for using HATS. If you are interested in using the HATS technology, you should purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology.

3.2.5 Purchasing IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology

You must purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. It acts as the runtime enablement key for applications that are created with the HATS Toolkit. There are three purchase options for IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology (product number 5724-N52). The following list shows the purchasing options as of April 2006: Authorized user A per-user license fee is per user that accesses the HATS application through a browser. Per processor (on IBM eServer xSeries® or pSeries®) IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology is also available for non-System i5 family systems. Per processor per tier (for iSeries deployment on P05, P10, P20, or P30-60)

HATS runtime will no longer require i5/OS Enterprise Edition.

3.3 Installing and configuring HATS

The installation of the HATS V6.0 product requires that you have installed any of the following products: Rational Web Developer V6.0 Rational Application Developer V6.0 Rational Studio Architect V6.0 WebSphere Development Studio Client for iSeries V6.0

Most iSeries customers have the WebSphere Development Studio license. It includes WebSphere Development Studio Client for iSeries CDs. For this reason, we use WebSphere Development Studio Client for all our examples.

3.3.1 Installing HATS

Before we explain how to install HATS, you must first understand the difference between HATS Toolkit and IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. HATS Toolkit is a development tool that plugs into the Eclipse platform. You use it to build a HATS application.

IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology is the runtime enabler. As such, you need IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology only when you deploy your HATS application to a production system for stress testing your application for performance.

HATS Toolkit without IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology license gives you two user connections for testing.

Chapter 3. Host Access Transformation Services 37 Thus, the installation of HATS Toolkit is the same with or without IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. However, when you are ready to deploy your HATS application to a production system, you must use IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology. See 3.5.2, “Preparing the HATS application for production” on page 59.

The HATS Toolkit is available in two different ways: WebSphere Development Studio Client customers already have the HATS CD, which is included in the WebSphere Development Studio Client package. It is at version 6.0. New HATS customers, who have purchased IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology, have the HATS CD included with the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology package. You may have the electronic image of this CD. It is at version 6.0.4.

The following sections provide detailed instructions for installing HATS, the runtime enablement option, and the latest fix pack. The first section outlines the steps for installing the HATS Toolkit. All steps are performed on a workstation running Windows XP Professional with SP1.

Installing HATS Toolkit To install HATS Toolkit: 1. Insert the CD or locate the electronic CD image of HATS in the file system. Customers who have IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology should have a CD or electronic image that has HATS V6.0.4, which includes fix pack 4. 2. Double-click setup.exe.

38 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3. In the Welcome to IBM HATS launchpad (Figure 3-1), click Installation Prerequisites.

Figure 3-1 Welcome to IBM HATS launchpad

4. In the browser window that opens, complete these actions: a. Read the prerequisites. Ensure that you meet all of them. If you do not have all the prerequisites, the installation might fail. Even if the installation succeeds, while you can still create a HATS application, the runtime behavior may have problems. b. Find the Installing HATS Studio section and print the information from this section. Use the instructions that you printed to install HATS. 5. Back in the Welcome to IBM HATS launchpad window, click Install. 6. The InstallShield wizard opens in which you follow the printed instructions (see step 4) to install HATS. 7. After the installation finishes, verify that IBM WebSphere HATS 6.0 is displayed in the list of programs; click Start → All Programs → IBM WebSphere HATS 6.0.

3.3.2 Upgrading the HATS Studio with the latest available refresh pack

Because the way to install a HATS refresh pack for V6.0 has changed drastically from the way it is done for HATS V5.0, we outline the complete steps here, illustrating with the use of HATS

refresh pack V6.0.2: 1. Check for the latest refresh or service pack that is available for HATS from the following Web address: https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=hatssvc

Chapter 3. Host Access Transformation Services 39

Note: IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology V6.0.1 includes HATS technology at fix pack level 6.0.4. This is

the latest fix pack level of HATS as of April 2006.

a. Click the Sign in link and sign in with your IBM user ID. b. Select WebSphere Host Access Transformation Services Refresh pack Version 6.0. c. Click Continue. d. Read the license agreement. If you agree select I agree and click Confirm. e. Download both the release notes and the HATS RefreshPack. 2. Install the refresh pack. a. Open the HATS Studio and select Help → Software Updates → Find and Install. b. On the Feature Updates page, select Search for new features to install and click Next. c. The HATS refresh pack comes as a zip file. In the Update sites to visit panel (Figure 3-2), click New Archived Site to locate the refresh pack zip file that you downloaded.

Figure 3-2 Update sites to visit panel

40 IBM System i Application Modernization: Building a New Interface to Legacy Applications d. Navigate to the directory where you downloaded the HATS_6.0.2.zip file (in our case) to select it. The Update sites to visit panel (Figure 3-3), in the search results section, now includes this file. i. Select the file along with other updates that may have been found during the search. ii. Select Ignore features not applicable to this environment and click Next.

Figure 3-3 Update sites to visit panel with search results

Chapter 3. Host Access Transformation Services 41 e. The Search Results panel (Figure 3-4) shows the selected features to install. Click Select All and select Filter features included in other features on the list. If the Next button is unavailable, click Error Details to determine which features do not apply to your environment so you can deselect these options. Click Next.

Figure 3-4 Search Results panel showing the features to install

f. Follow the wizard instructions to complete the installation. You may ignore the warning messages about installing unsigned features. g. When the install finishes, the wizard asks you to restart the workbench. Click OK. 3. Verify the refresh pack installation. Select Help → Software Updates → Manage Configuration.

42 IBM System i Application Modernization: Building a New Interface to Legacy Applications You should see the new version of HATS as shown in Figure 3-5.

Figure 3-5 HATS upgrade check

Fixing a loss of HATS perspective

Important: As of the time of writing of this redbook, there is a situation where you can lose your HATS perspective. This situation typically occurs as a result of the following actions: 1. Install HATS 6.0.0. 2. Apply HATS 6.0.2. 3. Uninstall HATS using InstallShield. 4. Install HATS 6.0.0. 5. HATS 6.0.0 is not available (perspective not available).

If the HATS perspective disappears from your workbench after you reinstall HATS, you can correct the situation by using these steps: 1. Restart Rational Studio with the -clean option to clean the loaded plug-in cache and ensures that the correct plug-ins are loaded. You only need to use the -clean option once to correct this problem. From a command prompt, enter the following commands: cd C:\Program Files\IBM\Rational\SDP\6.0 rationalsdp.exe -clean 2. In Rational Studio, complete these steps: a. Select Help → Software Updates → Manage Configuration. b. Click the Show Disabled Features icon (third icon from the left on the main toolbar). c. Expand C:\Program Files\IBM\HATSV6\eclipse. d. From the list, select Host Access Transformation Services 6.0.0. e. You should see that HATS 6.0.0 is disabled, and an Enable option is not available in the right frame. Select Disable in the right frame, even though it is already disabled. f. Select Yes when prompted to restart Rational Studio.

Chapter 3. Host Access Transformation Services 43 3. After Rational Studio restarts, follow these steps: a. Select Help → Software Updates → Manage Configuration. b. Select Host Access Transformation Services 6.0.0 and click Enable. c. When prompted to restart Rational Studio, select Yes.

After Rational Studio restarts, HATS 6.0.x (the refresh pack) should now be enabled, and HATS 6.0.0 should be displayed as disabled because it has been replaced by the newer level.

3.3.3 Upgrading the HATS Trial Toolkit

If you have been evaluating the trial version and have now bought HATS licenses, you do not have to re-install HATS to upgrade your HATS projects: 1. Insert the HATS product CD into your CD drive. Do not run setup.exe. 2. Start HATS Studio. 3. On the main toolbar, select HATS → Enable HATS runtime as shown in Figure 3-6.

Figure 3-6 Choosing Enable HATS Runtime

4. In the panel that appears, click Browse and browse from the root CD drive to the \Upgrade directory. Select the runtimeenablement.jar file and click Open.

Note: If your HATS Toolkit has been upgraded before, a window opens showing a message that the HATS project in your workspace is already enabled.

5. Enter your number of licenses. You must know how many HATS licenses you purchased. All your current projects are updated with your new HATS license information, and all future projects are created with the correct license information. 6. Upgrade the HATS version. Refer to 3.3.2, “Upgrading the HATS Studio with the latest available refresh pack” on page 39.

44 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3.4 New features in HATS V6.0 and the refresh packs

In the following sections, we introduce the new features that are available in HATS V6.0 and in the Refresh pack levels 1 to 4. We discuss them in the following context (where applicable): The product function that they enhance Previous product limitations that they address The benefits that they introduce

Note: This section is of value to those customers who have had previous experience with HATS.

3.4.1 HATS V6.0

The latest version of HATS, HATS V6.0, provides the new features presented in the following sections. For the details of these features and how to use them, refer to the Host Access Transformation Services Information Center at: http://publib.boulder.ibm.com/infocenter/hatsv6/index.jsp

Enhancements to existing features These improvements were made to features in previous versions of HATS. The focus of these enhancements is usability, making it easier to use the product to develop your Web applications.

Transformations These enhancements make it easier to work with customized pages called HATS transformations: Drag and drop HATS components from the Palette view Two new wizards to help in developing your own components and widget Side-by-side preview of host screens and HATS customizations Pre-population of transformations with default rendering Free layout mode in Page Designer for easier page designing Modification of components, widgets, and text replacement using the Properties view Use of the Design view to apply and adjust templates

Macros The enhanced macro support with macro stepping feature introduces a “step-through” capability to debug macros.

Components and widgets These enhancements allow more flexibility in defining how the screen components are displayed on the Web pages by improving existing wizards or introducing new wizards, which also make the task easier: Improved 5250 subfile recognition, rendering, and customization Two new wizards for customizing components and widgets Item selection component and widget Support for (ENPTUI) 5250

Chapter 3. Host Access Transformation Services 45 Recognition of 5250 display data stream extensions (support for the following subset of graphical DDS keywords): – PSHBUTTON: Push buttons – MLTCHCFLD: Check boxes – SNGCHCFLD: Radio buttons – SFLSNGCHC: Single-selection list box – SFLMLTCHC: Multiple-selection list box – WINDOW: Popup window – MNUBAR: Menu bar – PULLDOWN: Pull-down menus Support for 5250 HTML DDS keywords Support for highlighting hidden fields Use of alternate rendering sets JavaServer Faces (JSF) support and Integration Objects for easier Web page design CICS® Basic Mapping Support (BMS) and map importer for offline editing

Text, image, and HTML replacements These enhancements improve the ways to manipulate text and data on the screens: Default rendering and component tag-level text replacement Regular expression support for text replacement Inserting a button or link via text replacement

New capabilities HATS V6.0 supports the following new features and functions: Macros: A capability to identify potential next screens for a given recognized screen to improve macro performance 3270 support: A capability to import CICS BMS) source, thereby providing the ability to do screen customizations and transformations remotely Note that a terminal connection is still required to test the application. Integration objects: The capability to use the JSF pages support Display of the Operator Information Area (OIA) in the HATS projects Debugging: Option to display the host terminal on “Run server” Capability to rename global variables Screen customization: Capability to specify the execution of a host key Asynchronous update applet: Enhanced for improved reliability and error handling Keyboard support: Option to enable support when one host key is inserted Blank screens: Three possible ways for handling Problem determination: New wizard to collect contents of projects, maintenance levels, and log files

46 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3.4.2 HATS V6.0.1 (refresh pack level 1) The first service pack provides the following enhancements:

Alternate tag rendering New Function Key component setting New Text Input, Calendar, and Pop-up widgets setting New subfile component setting New setting for Global Rules imported from HATS V5 Adds server support for the HP/UX 11i operating system for WebSphere Application Server Versions 5.1 and 6 Adds server support for WebSphere Application Server V6 for the OS/400 Adds the capability to create 5.1 portlets Extends support for HATS portlets to run on IBM WebSphere Portal Server and IBM WebSphere Portal Express Version 5.1

For more details about each item, refer to the Release Notes. For the instructions to download the refresh pack, see 3.3.2, “Upgrading the HATS Studio with the latest available refresh pack” on page 39.

3.4.3 HATS V6.0.2 (refresh pack level 2)

This refresh pack provides the following major capabilities: Support for 3270 Lightpen applications HTTP compression now provided by HATS Automatically delete host field data Support for 3270/5250 numeric

For more details about each item, refer to the Release Notes.

3.4.4 HATS V6.0.3 (refresh pack level 3)

This refresh pack provides the following major capabilities: New suppressUnchangedData project level setting Additional bi-directional support for integration objects Support added for 937 Macau code page New option to follow transformation order instead of green-screen order if autoAdvance =true Allow additional Host On-Demand print session properties for HATS 3270 print Support provided for Eclipse resource decorator Quick access to related actions and perspectives Debug and Profile on the server in the HATS Project view Detection of corrupted or missing licenseHardLimit values in runtime.properties

For more details about each item, refer to the Release Notes.

Chapter 3. Host Access Transformation Services 47 3.4.5 HATS V6.0.4 (IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology V6.0.1)

This latest refresh pack level ships in the new IBM WebFacing Deployment Tool with HATS Technology V6.0.1 product starting 14 April 2006 (see 3.2, “IBM WebFacing Deployment Tool

for WebSphere Development Studio V6.0.1 with HATS Technology” on page 34). This refresh pack provides the following capabilities: Support for the WebFacing TCP/IP server: Connection to the WebFacing server does not require OLTP capacity. This significantly reduces the overall cost of a HATS application on iSeries. New widget for creating list boxes: The widget is similar in function to the drop-down widget and can be populated from a global variable, a string, or from a hint (when using the input field with hints component). Java 2 security: This feature provides a policy-based access control mechanism that checks for permission before allowing an application access to certain protected system resources, such as file I/O, sockets, and environment properties. New connection management API: This API enables you to acquire an existing transformation connection in a servlet context in anticipation of executing a middle-in-chain Integration Object against that transformation connection to provide better integration between HATS applications and other non-HATS Web applications. Support for Eclipse team feature: Team functions can now be accessed from the HATS Project view context menu. Licensing options and runtime enablement: There are now three licensing options: user-based, processor-based, and one based on your iSeries tier. Other enhancements: These enhancements include the capability to override CSS style settings, dynamic widget previews, and enhancements to the calendar widget.

3.5 Sample HATS application using default rules

The host application that we use in this section as a sample is the Flight Reservation System application. If you want to use this sample, download the savefile to restore the library on your iSeries. Refer to Appendix A, “Additional material” on page 285, for details about how to use the sample.

3.5.1 Developing a HATS application

In this section, we discuss the important things to watch for when creating HATS applications. For the detailed steps to create your HATS project using the shipped default screen recognition and rendering rules, refer to the Getting Started for iSeries manual from the HATS Library on your PC. You can find this manual by clicking Start → All Programs → IBM WebSphere HATS 6.0 → Library → Getting Started for iSeries.

48 IBM System i Application Modernization: Building a New Interface to Legacy Applications Perform the instructions described in the guide and pay attention to the following actions: Create a Project When you enter your project details on the Create a Project panel (Figure 3-7), you now have the option to specify the version of WebSphere Application Server in the Target server field. We recommend that you give your Enterprise Application project name the same name as your project name, with the suffix EAR6, unless you intend to package other HATS projects into the same EAR file: a. Deselect Use default Enterprise Application project. b. Type the new name in the field. Select the Add administration console support option only if you think there may be a need to access the administration functions of HATS while you are testing. Refer to the User’s and Administrator’s Guide for details on the HATS administration console. Be sure to deselect this support at the time that you package your HATS application for deployment. At production stage, HATS is administered by using a separately-deployed HATS Administration Project.

Figure 3-7 Project details

Chapter 3. Host Access Transformation Services 49 Connection Settings The Connection Settings panel (Figure 3-8) is where you specify that you want to use the ENPTUI support. Refer to “Enhancements to existing features” on page 45 for a description of this feature enhancement. You still have the capability to add connections to other iSeries machines or to a zSeries machine as secondary connections.

Note: The HATS Toolkit V6.0.4 is shipped in IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology V6.0.1. HATS Toolkit V6.0.4 is required to eliminate OLTP requirements for i5/OS V5R4.

To leverage this new feature of HATS, a new Connection Type 5250W can be used for HATS main connection. This connection type uses the same TCP/IP server (the *WEBFACING server) that is used by WebFaced applications. All HATS secondary connections however still use the 5250 Telnet type of connection.

In the Type field, select 5250W.

Figure 3-8 Connection details

50 IBM System i Application Modernization: Building a New Interface to Legacy Applications The Confirm Requirements window (Figure 3-9) opens. It informs you about additional requirements to support this new connection type. You must install additional PTFs on the server (see 3.2.3, “Additional PTFs to enable IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 36). Click OK.

Figure 3-9 Warning window

Select a Default Template Now 23 sample templates are shipped with HATS V6.0 as shown in Figure 3-10.

Figure 3-10 Shipped sample templates

Chapter 3. Host Access Transformation Services 51 To use your own template, we recommend that you use one of the following options: – Copy an existing template and make changes to that copy. – If you have a company Web site that you want to follow the template of, use the existing HATS capability of creating a new template and prefilling it with your chosen Web site (see Figure 3-11). However, this feature cannot copy Web sites that have been developed using the HTML frames.

Figure 3-11 Using the existing Web page as the template

52 IBM System i Application Modernization: Building a New Interface to Legacy Applications If you use this option, you must cut out an area of your template page to accommodate the transformation of your host application area. If your Web page uses a lot of JavaScript, it might get truncated in the process. Ensure that you receive a clean working page by previewing the template page as shown in Figure 3-12.

Figure 3-12 Previewing a new template

Chapter 3. Host Access Transformation Services 53 Figure 3-13 shows a sample of the HATS application using the customized template. Any original links, such as Home, Products, Services & Solutions, Support & downloads, and My account, will still work.

Figure 3-13 Sample using a customized template

54 IBM System i Application Modernization: Building a New Interface to Legacy Applications Rendering rules in the project settings After you create your project, you can change the rendering rules. If your host application uses a lot of pop-up windows (set up with the WINDOW keyword on your DDS), we recommend that you let HATS transform these windows: a. Expand your created HATS project folder in the workbench and double-click Project Settings. b. In the right panel, click the Rendering tab of the project settings menu bar. c. On the Rendering page (Figure 3-14), select Transform dialogs and press Ctrl+S to save your changes.

Figure 3-14 Project settings Rendering page

Chapter 3. Host Access Transformation Services 55 Testing your HATS application We recommend that you test your HATS application on your workbench first before you deploy it to your iSeries. Test your HATS application by right-clicking your project and selecting Run on Server. The application takes some time to run because the embedded WebSphere Application Server will be started. The Display Terminal window (Figure 3-15) opens and gives you the option to run your test in debug mode.

Figure 3-15 Option to run testing in debug mode

56 IBM System i Application Modernization: Building a New Interface to Legacy Applications When testing in debug mode, a small host terminal window opens that shows the green-screen application screens while you are running its HATS version. Figure 3-16 shows this dual display (notice that we also cleaned up the template).

Figure 3-16 Testing in debug mode

To call our Flight Reservation sample application, sign on to the iSeries. Then on the command line, enter the following two commands: ADDLIBLE FLGHT400 GO FRSMAIN

Chapter 3. Host Access Transformation Services 57 The Flight Reservation System main menu opens as shown in Figure 3-17. If you choose not to display in debug mode, you do not see the small black host terminal shown in the display.

Figure 3-17 Flight Reservation main menu

To use any menu item, you are asked to log in using the agent name and password. To test this application, you can use: User ID: Bill Password: mercury

58 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3.5.2 Preparing the HATS application for production The HATS Web application that you created mostly using just the shipped default rules can

already be deployed to an application server for use. In most cases, however, the resulting Web application may not be ready for production.

Because HATS is a generic tool, the HATS default rules for recognizing host components for conversion to Web page widgets may not be capable of rendering all your screens properly. This happens most often when your company does not adhere strictly to coding standards for displaying, such as function keys or selection lists.

Because of these variations of coding practices, HATS is not expected to render properly all of your screens. Therefore, after creating your default HATS application, it is important that you validate the rendering of all your host screens by running as much of your application functions as possible.

To resolve these improperly-rendered screens, we recommend that you work with the default rendering rules first (refer to Figure 3-18).

Figure 3-18 HATS rendering rules

Chapter 3. Host Access Transformation Services 59 This exercise involves setting the correct combination of rules for component recognition as well as for the rendering widgets to find the set of rules that will properly render as much of your application host screens as possible. The key for doing this is to determine as many common screen recognition factors as possible among all the errant screens. The aim is to reduce the number of individual screen customizations as to reduce the impact on

performance.

In “Case study 1: Full implementation” on page 32, which involves about 2500 to 3000 screens, this activity may take a minimum of three months to resolve by just working with the default rendering rules with a minimum number of screen customizations or transformations. Then it may take at least another month of actual user testing to completely flush out and resolve improperly-rendered screens.

If working with the rendering rules is not sufficient, then the next option is to use the HATS screen customizations and transformations (refer to Figure 3-19). These features work off a set of screen recognition criteria. Therefore, this exercise implies that you know your application host screens well enough to define precise screen recognition criteria to use. Failure to do so may result in looping screen flows, screen freeze, or an application abort where the HATS runtime engine does not know what to do to continue processing your requests.

Figure 3-19 HATS screen customization and transformation feature

The version of the HATS application that you deploy to production typically has a stable set of defined rules for screen recognition and rendering. It also has defined rules for other customizations that you may require, such as changing the flow or navigation of some screens, skipping screens and combining information from several screens into one Web

60 IBM System i Application Modernization: Building a New Interface to Legacy Applications page, or integrating calls to third-party applications, or running applications to retrieve data from other iSeries or zSeries systems. It can also include page transformations, such as introducing drop-down selection lists to some entry fields, presenting data in a graph format, or splitting the screen information into separate tabbed folders. Customizations such as these add to the duration of the development period of your HATS application.

3.6 Deploying the HATS application to the iSeries server

The HATS application developed in WebSphere Development Studio Client for iSeries workbench is a typical Web application. It is then packaged into an Enterprise Archive (EAR) file for installing on the WebSphere Application Server. Refer to 3.3, “Installing and configuring HATS” on page 37, for the supported application server versions.

We recommend that you test your HATS application first in the application server test environment inside your workbench until you obtain a version that is stable. Deploy it to the iSeries server only when it does not require any additional functional changes or customizations.

3.6.1 Enabling HATS runtime

With introduction of IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology (see 3.2, “IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 34), HATS customers can run the HATS applications without using the OLTP capacity on the server. This support is available with V5R4.

To enable this feature, add the “enablement key” to your HATS environment. From that moment onward, all of your existing and new projects will be enabled for running on a production server.

To enable the runtime support, follow these instructions: 1. Insert the CD that comes with IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology or make sure that you have the electronic image of the CD. 2. Open your HATS development platform (Rational or WebSphere Development Studio Client).

Chapter 3. Host Access Transformation Services 61 3. Select HATS → Enable HATS Runtime as shown in Figure 3-20.

Figure 3-20 Enabling HATS runtime

4. In the Enable HATS Runtime window that opens, click Browse. 5. In the Open window (Figure 3-21), navigate to the CD or CD image and select runtimeenablement.jar. Click Open.

Figure 3-21 Navigating to the enablement key file

62 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the Enable HATS Runtime window (Figure 3-22), select the proper license option and click Finish.

Figure 3-22 Selecting license option

7. A new window opens and indicates successful enablement. Click OK.

Important: If the Build automatically option is turned off, you must manually rebuild your project or projects to enable the runtime support.

3.6.2 Packaging the HATS application

You must package the HATS application resources on the WebSphere Development Studio Client workbench for deployment: 1. Right-click your HATS project in the workbench and select Assemble HATS Project. 2. In the EAR Export window (Figure 3-23), complete these actions: a. click Browse and go to the folder where you want to store the EAR file. You can place it in a local PC directory or directly in the iSeries integrated file system directory that is mapped to a local drive. Consider the following observations regarding this step: • We recommend that you place the EAR file first in a local file system on a PC. Then you can transfer the file to the integrated file system (using File Transfer Protocol (FTP), iSeries Navigator, and so on). This can save you time, especially with the large EAR files. • If you transfer the EAR file directly to the iSeries integrated file system, then for WebSphere Application Server V6.0, the recommended integrated file system directory is /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/profile_name /installableApps.

Chapter 3. Host Access Transformation Services 63 b. Select the Export source files and Include project build paths and meta-data files options if you want to save the HATS project specific settings and source code. In this case, you can import this file into another installation of WebSphere Development Studio Client. c. Click Finish.

Figure 3-23 Exporting an EAR file

3. If necessary, send the resulted EAR file by using FTP to the integrated file system of your iSeries server.

3.6.3 Installing the application on WebSphere Application Server V6.0

As with any other Web application, the HATS EAR file is installed on the application server. You must have already configured a WebSphere Application Server V6.0 instance to install your HATS application.

For instructions on how to configure the application server, refer to the WebSphere Application Server for OS/400 V6.0 Installation book available from the following Web site: http://publib.boulder.ibm.com/infocenter/wsdoc400/topic/com.ibm.websphere.iseries.doc/info/ ae/ae/install.pdf

To install your HATS application: 1. Open the IBM Web Administration wizard using the following URL: http://iSeries_hostname:2001/HTTPAdmin 2. Log in. 3. Click the Manage tab and then the Application Servers subtab. 4. From the Server list, select your application server. 5. In the navigation area on the left, click the Install New Application task.

64 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the Specify Application Location panel, click Browse to pick up your HATS EAR file from the iSeries integrated file system directory /QIBM/UserData/WebSphere/AppServer /V6/Base/profiles/profile_name/installableApps and click Next. 7. In the Perform Install Options panel, you have the option to choose Pre-compile JSPs and click Next to improve runtime performance. Choosing this option may introduce an increase in the install time. 8. In the Virtual Host Mapping panel, accept the default value and click Next. 9. Review the summary page and click Finish to complete the installation. 10.When the installation is completed, from the Applications task on the left navigation area, click Manage Installed Applications. 11.In the Manage Installed Application panel (Figure 3-24), select your installed HATS application name, click Start.

Figure 3-24 Starting the HATS application in WebSphere Application Server

12.After the application is started, invoke it from the browser by using the following URL: http://iSeries_host:http_port/hats_contextroot In this URL, hats_contextroot is the name that you assigned to your HATS project.

Chapter 3. Host Access Transformation Services 65

66 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 4. The IBM WebFacing Tool

The IBM WebFacing Tool is one of the IBM solutions for Web-enabling applications running on an iSeries (5250 screens) server. Through easy-to-use wizards, the IBM WebFacing Tool converts the data definition specification (DDS) sources for OS/400 display files to standard Web-based graphical user interfaces (GUIs). With little or no modification, your original iSeries applications can be made available from anywhere where users have access to a browser, thereby allowing you to leverage the immeasurable business potential of the Internet.

Anything that can be added to a Web page can also be included in a WebFacing page. The Web settings support of the IBM WebFacing Tool provides the ability to insert predefined customizations to DDS fields and add any HTML, JavaScript, or scriptlets to your Web pages. This allows you to customize any page by modifying the look and feel and adding Web programming to improve the usability of your application. In addition, the look and feel of the entire WebFacing application can be modified by editing the style properties. Advanced features, such as Portal, support provide integration capabilities with other applications running on the customer environment.

This chapter concentrates on the latest version of the IBM WebFacing Tool V6 and provides overview discussions to address the following areas: What makes the IBM WebFacing Tool different from screen scrapers? What is required to prepare for a WebFacing implementation? What is the development effort involved to have a production-strength WebFacing application? How do you install and configure WebFacing? What are the new features provided in WebFacing V6.0? Is there a sample WebFacing application (refer to Appendix A, “Additional material” on

page 285)? How do you deploy the WebFacing application to the iSeries server?

Various product solutions are available that enable customers to bring their host applications to the Web quickly without requiring changes to the host application code. In most cases, these products can do a quick host-screen-to-Web-page conversion because they wait for the display file object to be created and then “scrape” data from the displayed screens. The data is then transformed into Web page widgets based on predefined rules. The transformation is done on-the-fly.

The IBM WebFacing Tool is not a screen scraper. The transformation of the screens is done prior to execution of the application, that is, during development. At runtime, rather than sending the program data to the screen and then sending the screen data to the application server, IBM WebFacing Tool intercepts the program data directly and sends it to the Web application server for consequent delivery to a browser client. Therefore, there may be a performance advantage introduced because the screen data is not created any more and there is no runtime conversion occurring.

The IBM WebFacing Tool converts the host screens primarily by looking at the DDS keywords and generating the Java resources for page attributes and behavior based on these keywords. The resulting HTML Web page attributes tend to be more precise and have a more “Web-like” look and feel than screen-scraped pages.

Figure 4-1 shows the full architecture flow of WebFacing applications. This flow is explained in the paragraph that follows.

4 3

5 2

Figure 4-1 WebFacing architecture

68 IBM System i Application Modernization: Building a New Interface to Legacy Applications First the application display files are converted (1). This creates JSPs as well as Java beans for each record format in the display files. Next, a user invokes a converted program through a Web browser interface (2). When the program performs a READ on a record format, control and application data are sent to the Workstation Data Manager (3). Because the job was started by the WebFacing Runtime Server, Workstation Data Manager knows this is a

WebFacing request and passes the data and control to the WebFacing Runtime Server, which runs on the iSeries server (4). Control returns to the WebFacing Runtime Servlet that runs in WebSphere Application Server (5). The WebFacing Runtime Servlet locates the appropriate JavaServer Pages (JSPs) and Java beans. The WebFacing Runtime Servlet tells WebSphere Application Server to return the JSP™ back to the browser. The JSP is processed, and the resulting HTML is returned to the browser. Note that no 5250 datastream is generated in this flow.

4.2 Requriements to prepare for a WebFacing implementation

In this section, we describe the system prerequisites for using the IBM WebFacing Tool, which is a plug-in tool in the WebSphere Development Studio Client.

4.2.1 Hardware and software requirements The IBM WebFacing Tool generates a typical Web application that is served by a Web application server. As such, it has development requirements as well as deployment requirements.

Development requirements Before you install any software, you must first check whether your iSeries and workstations are capable of running the WebSphere Development Studio Client software.

IBM WebSphere Development Studio Client for iSeries V6.0 delivers an integrated development environment (IDE) with tools for developing Java, Web, Web services, client/server, and iSeries server applications. These iSeries server applications can be in such languages as RPG and COBOL. The iSeries enhancements to WebSphere Development Studio Client V6.0 make it easy to create, test, deploy, and maintain sophisticated applications for On Demand Business with little Java, Web, or Web-service programming.

Table 4-1 describes the hardware that you need for the iSeries and for the workstation. Table 4-2 describes the software that you need on your PC and System i platform. Both tables compare WebSphere Development Studio Client Standard Edition V6.0 and WebSphere Development Studio Client Advanced Edition V6.0.

Chapter 4. The IBM WebFacing Tool 69 Table 4-1 Hardware specifications Type WebSphere Development WebSphere Development Studio Client Standard Edition Studio Client Advanced Edition V6.0 - specification V6.0 - specifications

Server iSeries models 170, 250, 270, 7xx, 8xx, 520 or 570

Workstation minimum

For server Intel Pentium II processor Intel Pentium III processor development 512 MB RAM or better 768 MB RAM

For Java, Web, Intel Pentium III processor Intel Pentium III processor or WebFacing 800 MHz recommended 1.2 GHz recommended development 1 GB RAM recommended 2 GB RAM recommended

For classical Intel Pentium II processor tools only 256 MB RAM or better

Hard disk space required

2200 MB 3.5 GB Additional space required for your Additional space required for your development resources development resources

Additional 1 GB of temporary Additional 1 GB of temporary space required during installation space required during installation

More space is required on FAT32 than NTFS file systems

For classic tools 700 MB 700 MB only

Video required Windows VGA graphics card (1024 x 768 or higher, 256 colors)

Media device CD-ROM or DVD drive

Input devices Keyboard, mouse or pointing device

70 IBM System i Application Modernization: Building a New Interface to Legacy Applications Table 4-2 Software specifications Type WebSphere Development WebSphere Development Studio Client Standard Studio Client Advanced Edition V6.0 - specification Edition V6.0 - specifications

Server

For server-related OS/400 V5R1 or later OS/400 V5R1 or later development Additional program temporary fixes (PTFs) required

Licensed programs 57722SS1 OS/400 - Host Servers

57722TC1 OS/400 - TCP/IP Utilities

5722DG1 IBM HTTP Server

Workstation

Windows 2000 Professional, SP3 or SP4

Windows XP Professional, SP1 or higher

Windows 2000 Server and Advanced Server, SP3 or SP4

Windows Server® 2003 Standard and Enterprise

Microsoft Internet Explorer 5.5, SP1 or higher

For profiling JRE™ 1.4.0 or higher TCP/IP installed and configured applications for profiling applications JRE 1.4.0 or higher

Run-time support for WebSphere Application Server WebFacing and Web 5.1, or 6.0 or Express 5.0, 5.1, Tools applications or 6.0

Note: You can reduce the minimum required disk space if optional features and runtimes are not installed.

For the complete system requirements of WebSphere Development Studio Client V6.0, refer to the following Web site: http://www-306.ibm.com/software/awdtools/wdt400/sysreq/index2.html

Deployment requirements After you create and convert a WebFacing project with the IBM WebFacing Tool, you must deploy it as an enterprise archive (EAR) or Web archive (WAR) file to an application server. Users can then run the application from their Web browser. The IBM WebFacing Tool supports deployment to IBM WebSphere Application Server Base 5.1 or 6.0 or Express 5.0, 5.1, or 6.0 and IBM WebSphere Portal Server Version 5.0 and later.

Chapter 4. The IBM WebFacing Tool 71 To learn more about WebSphere Application Server and WebSphere Portal Server on iSeries, see the following Web sites: WebSphere Application Server for i5/OS http://www.ibm.com/servers/eserver/iseries/software/websphere/wsappserver

WebSphere Portal on iSeries http://www.ibm.com/servers/eserver/iseries/software/websphere/portal

In this redbook, we use WebSphere Application Server for iSeries V6.0. Your iSeries machine must have a minimum of 1200 MB free disk space for installation.

To run applications on a WebSphere Application Server V6.0, your iSeries must meet these minimum requirements: Either of the following recommended minimum server models: – Model 270 with processor feature 2252 – Model 820 with processor feature 2395 300 CPW 768 MB memory

Note: These requirements are based on a single WebSphere Application Server profile and represent the recommended minimum requirements. Additional profiles that are running concurrently require additional resources. Deployments that must support many users or require shorter response times might require additional resources.

If your applications contain Enterprise JavaBeans™ (EJBs), your iSeries must meet these minimum requirements: Either of the following recommended minimum server models: – Model 170 with processor feature 2385 – Model 720 with processor feature 2062 – Model 270 with processor feature 2252 – Model 800 with processor feature 2464 – Model 820 with one of these processor features 2395, 2396, 2427, 2458 – Models 520, 570, 810, 825, 830, 840, 870, 890 450 CPW 2 MB Level 2 cache 1 GB memory in addition to memory required for any other applications running on your iSeries server

Note: Each application that you deploy requires additional disk space.

For a technical overview of the WebSphere Application Server V6.0, see WebSphere Application Server V6 Technical Overview, REDP-3918.

For the complete software and hardware prerequisites of WebSphere Application Server V6.0 for iSeries, refer to the WebSphere Information Center at the following address: http://publib.boulder.ibm.com/infocenter/wsdoc400/index.jsp?topic=/com.ibm.websphere.iserie s.doc/info/ae/ae/prqsvr.htm

72 IBM System i Application Modernization: Building a New Interface to Legacy Applications For the list of PTF requirements for WebSphere Application Server V6.0 for i5/OS V5R3, refer to the WebSphere Application Server for i5/OS Web site at the following address: http://www-1.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/services/servic ews60_V5R3.html

For the software and hardware prerequisites of the different versions of WebSphere Application Server, refer to the WebSphere Application Server detailed system requirements on the Web at the following address: http://www-306.ibm.com/software/webservers/appserv/doc/latest/prereq.html

4.2.2 Recommended skills The recommended composition of skill resources for a WebFacing project implementation includes: WebSphere Development Studio Client product knowledge, especially the WebFacing perspective Host application knowledge, preferably by application analysts, experts, and developers These people can identify DDS source files that they want to enhance with customizations or DDS source files that may require customization. Application use knowledge, typically the actual users of the application The users’ normal job execution will serve as the function testing to flush out screens that are not behaving as expected. Page designing skills to redesign a WebFacing style or a Web page look and feel Some helpful skills are in the areas of cascading style sheets (CSS), HTML, JSP, and JavaScript. Project management to provide the required decision on the possible alternatives or workaround to adopt in case of unsupported functions due to possible WebFacing product limitations Third-party application knowledge to provide the information or development required for the integration requirements when using WebFacing portlet projects

4.2.3 Project implementation strategy A WebFacing implementation strategy depends on various implementation factors, including: Business requirements Web page look-and-feel requirements Different application functions to Web enable Degree of integration between existing application functions Third party or other Web applications integration requirements Development or implementation team skills Type of users Stability of current applications

Recommended implementation phases These are the typical stages of activity that a WebFacing project implementation might take. The assumption here is that you have at least one person in your company who has a fairly solid background in using the IBM WebFacing Tool.

Chapter 4. The IBM WebFacing Tool 73 Phase 1: Project initiation and problem identification This initial phase begins when you start creating your first WebFacing application by using the default project settings and one of the default style sheets: 1. Identify all requirements especially the applications or application functions to be Web-enabled. You might have several existing business applications, or you may only have one company application with tightly-integrated business functions for your different business areas. The following considerations can help you decide whether you should develop one WebFacing project or several projects in parallel: – When you create your WebFacing project, you must specify how your applications are going to be invoked. You must determine beforehand whether you intend to provide a single access point to your host applications or multiple access points. – You might have to ensure that the business applications of your different business areas can operate independently of each other. For instance, you may not want your online ordering system to be brought down when you must stop your payroll system for maintenance. – You might have a business application that goes through frequent design or code changes of the screens due to constantly-changing business requirements. Or you might have a business application that is not quite stable in its development. – You may have several business applications that are highly integrated; that is, program functions and business logic and function screens are shared across the entire application. 2. Assemble the right skills for your implementation team. Refer to 4.2.2, “Recommended skills” on page 73. 3. Prepare your iSeries environment for development and testing of your WebFacing application: – Ensure that all the DDS sources of your targeted application are available. The IBM WebFacing Tool requires these to generate the corresponding JSPs. – The display file objects must not have a Coded Character Set ID (CCSID) of zero. Your conversion will succeed, but your application will not run. To check this, use the Display File Description (DSPFD) command. – Your system value for automatic configuration of virtual devices (QAUTOVRT) must not be zero because WebFacing clients access the iSeries using virtual terminal devices. – Set up a development user profile that has the correct library list and the correct required authorities to compile the DDS sources of your chosen application and to run the application during the development period. • If your existing developer user profiles are able to do that, then you can use the same profiles to do the WebFacing conversion task. Otherwise, you may need to create a job description that specifies your development and runtime libraries in the initial library list. Then you need to associate this job description to your developer user profile. • The user profiles must have Limit capabilities set to *NO (LMTCPB(*NO)). • The WebFacing runtime engine does not use the Initial Program to Call (INLPGM) and the Initial Menu (INLMNU) settings assigned to the user profiles. If you are using these to set your application environment, then you might need to introduce a small CL program to set the environment correctly.

74 IBM System i Application Modernization: Building a New Interface to Legacy Applications – Ensure that the iSeries Net server is started by entering the following command: STRTCPSVR *NETSVR This allows you to map the iSeries integrated file system to your local PC directory for easier exporting of your project EAR file to the integrated file system.

– Ensure that the WebFacing server is started by entering the following command: STRTCPSVR *WEBFACING This TCP/IP server listens for requests from the WebFacing application on port 4004 (default port number). 4. Perform a first round of conversion using the DDS sources of your targeted application. 5. You can perform the following activities in parallel after you complete the first round of conversion: – Validate the default conversion by testing your WebFacing application using the Studio application server test environment. Identify whether any screens are not rendered properly or are not behaving as expected. Mark these screens for investigation. Typical problems might be misalignment of fields, unreadable displays due to faulty rendering of overlapping screens, function keys not delivering expected behavior, or subfiles not being rendered consistently. You can find good Tips-and-Techniques and Trouble Shooting documents for debugging your WebFacing applications. One example is available at the following address: http://www-306.ibm.com/software/awdtools/wdt400/library/hottips.html – Create your own company-specific style sheet if required. – Start developing any other customer-specific customizations using the Web settings view. Note that we recommend that you do no implement your customizations by changing the generated JSPs for the display files. If you change your DDS sources and have to reconvert them, the JSPs are regenerated, and you will lose your customizations. – Develop your integration requirements, if any. You may want to investigate the option of defining Command Key Actions or using the Web Settings hyperlinks option or even developing a WebFacing portlet for integration into a Portal environment.

Phase 2: Unit and function testing and problem resolution Because the IBM WebFacing Tool uses DDS keywords to generate the corresponding JSPs, the resulting Web pages tend to have minimal rendering errors. Most of the rendering errors are due to a combination of unsupported keywords and developer inexperience with the most effective way of working with the tool capabilities probably due to lack of or limited exposure to business requirements. Refer to Tips and Tricks documents that have been published or Troubleshooting Web sites that provide good pointers on how to fully use the customization options of the tool. One such Web site is available at the following Web address: http://www-306.ibm.com/software/awdtools/wdt400/library/hottips.html

You can also find problem resolution guidelines in the Help Contents of the WebSphere Development Studio Client workbench. To access these guidelines, click Help → Help Contents → Troubleshooting and support → Troubleshooting checklists → iSeries WebFacing applications.

Also, as expected from any refacing tool that attempts to be as generic as possible, there are always product limitations. Fortunately, regular internal product testing and customer

Chapter 4. The IBM WebFacing Tool 75 implementation experiences have singled out most of these limitations. Some alternative ways to work around them are documented in Troubleshooting documents available from Internet sites. Another one of these sites is WebFacing Troubleshooting Tips at the following Web address: http://www-1.ibm.com/support/docview.wss?rs=715&context=SSZND2&context=SSKJJP&context=SSBRL P&context=SS2MD7&q1=webfacing+troubleshooting+tips&uid=swg27005905&loc=en_US&cs=utf-8&lang= en

Phase 3: User testing and problem resolution In this phase, you may want to deploy your WebFacing application EAR file to an application server on a central test server and subject it to end-to-end function testing. This is done better by a subset of your actual users because they are familiar with the applications and can test the application with real data. They should write down Web pages with faulty functional behavior; that is, the Web version of the page does not provide the functions provided by its green-screen counterpart.

You might also want to use this phase to monitor and analyze the performance and response times of your WebFaced application. WebFacing performance guidelines that you can use as a basis for your analysis are available a the following Web sites: Aiming for Zero Interactive on iSeries http://www-1.ibm.com/support/docview.wss?uid=swg27004617&aid=1 IBM WebFacing Tool Performance Update http://www-1.ibm.com/servers/enable/site/education/abstracts/webappv5_abs.html V5R4 Performance Capabilities Reference http://www-03.ibm.com/servers/eserver/iseries/perfmgmt/resource.html

Phase 4: User training and project documentation This phase involves developing the customer-specific user manuals that explain how to use the WebFacing application, train the users of the WebFaced application, and educate the operations people on the system resources that are used by a WebFacing application at runtime so that they can better manage the environment. The best time to start this phase is when you have almost finished all customizations required so that the resulting Web pages are now stable and will most likely no longer undergo anymore visual changes.

Phase 5: Go live At this stage, your customized WebFacing application is deployed on your production application server. WebFaced versions of your application can run alongside the green-screen versions if you still have users who need to use the latter.

4.3 Installing and configuring WebSphere Development Studio Client V6.0

If you have the software license agreement for the WebSphere Development Studio (5722-WDS), you are entitled to have the WebSphere Development Studio Client Standard Edition. The Advanced Edition is now a stand-alone product (since March 2004) and must be purchased through Passport Advantage.

If you purchased the Advanced Edition before March 2004 and still have an active iSeries Software Maintenance or Software Subscription contract since its initial purchase, you are entitled to upgrades until the iSeries Software Maintenance or Software Subscription contract expires.

76 IBM System i Application Modernization: Building a New Interface to Legacy Applications If you already have the Standard or the Advanced contract with a current iSeries Software Maintenance or Software Subscription contract, you are entitled to receive the upgrades with no additional charge. For more detailed information, refer to the document at the following Web address: http://w3-3.ibm.com/sales/ssi/rep_ca/0/897/ENUS205-160/ENUS205-160.PDF

4.3.1 Installing WebSphere Development Studio Client V6.0 The core required components for a WebSphere Development Studio Client V6.0 install are on seven CDs or one DVD. CODE400 and VisualAge® RPG, which used to be part of the core installation, are now optional tools and come on a separate CD.

WebSphere Development Studio Client V6.0 is now based on the Rational Software Development (RSD) Platform. When you insert disk 1 into your CD drive to start the installation, you are presented with the RSD platform.

It is important that you have at least 500 MB free disk space on your installation directory. You must also ensure that your TEMP or TMP environment variable points to a temporary directory with at least 500 MB free space. Click Start → Control Panel → System and click the Advanced tab and select Environment Variables.

In the following steps, we explain how to perform the installation using the Rational Application Developer Launchpad after is starts (if autostart is enabled): 1. Click Install IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0 (see Figure 4-2).

Figure 4-2 Installation startup page

2. The Install Shield wizard displays the Welcome panel; click Next.

Chapter 4. The IBM WebFacing Tool 77 3. In the Software License Agreement panel, read the license agreement and then select I accept the terms in the license agreement and click Next. 4. In the next panel to select the directory to install WebSphere Development Studio Client Advanced Edition V6.0, accept the suggested default and click Next. 5. In the next panel (Figure 4-3), select the optional features of WebSphere Development Studio Client that you want to install and then click Next.

Note: If you deselect Language Pack, the workbench will always be in English. Otherwise WebSphere Development Studio Client checks your Regional Settings in Windows at run time. It shows the appropriate national language version. If you select Language Pack, you can select a different language every time, before you start WebSphere Development Studio Client, simply by changing the regional settings in Windows.

Figure 4-3 Selecting the features of the installation

6. On the summary information panel, click Next.

78 IBM System i Application Modernization: Building a New Interface to Legacy Applications 7. The installation starts. This can take a while. When it finishes, the summary panel shown in Figure 4-4 is displayed. Click Next.

Figure 4-4 Summary of the installation

8. After the WebSphere Development Studio Client installation, you can also install the Agent Controller by selecting Launch Agent Controller install (see Figure 4-5). You need this if you want to use the profiling, runtime analysis, and logging features of WebSphere Development Studio Client Advanced Edition V6.0. Then click Next.

Figure 4-5 Selecting the option to install the Agent Controller

Chapter 4. The IBM WebFacing Tool 79 9. On the Install Shield wizard for IBM Rational Agent Controller, click Next. 10.Make sure the WebSphere Development Studio Client workbench is not running and click Next. 11.In the next panel, you see how to start WebSphere Development Studio Client Advanced Edition V6.0. We strongly recommend that you obtain the updates for the installed features as explained in 4.3.2, “Upgrading WebSphere Development Studio Client V6.0 with the latest available fix pack” on page 80. Click Finish.

For the complete installation guidelines for WebSphere Development Studio Client Standard Edition V6.0, go to the following Web address: ftp://ftp.software.ibm.com/as400/products/ad/wdt400/v60/manuals/install.html

For WebSphere Development Studio Client Advanced Edition V6.0, go to this Web address: ftp://ftp.software.ibm.com/as400/products/ad/wdt400/v60/manuals/install_adv.html

4.3.2 Upgrading WebSphere Development Studio Client V6.0 with the latest available fix pack You are required to update your WebSphere Development Studio Client installation with the latest fixes from the Web. To do this upgrade with the latest available refresh packs and single fixes, follow these steps: 1. From the Windows desktop, select Start → All Programs → IBM Rational → Rational Product Updater. 2. In the IBM Rational Product Updater panel, select Find Updates. You must be connected to the Internet because this step accesses IBM Web sites to search for the fix packs that are applicable to your installed version. This download might take a while. If fix packs are found that are required for your installed version, you see a list like the example in Figure 4-6. Select all fix packs and click Install updates.

Figure 4-6 Clicking the Install Updates button

80 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3. Some features may have license agreements that you need to accept before you proceed. If this is the case, read the agreement, select I accept the terms in the license agreement, and click OK.

Important: The process of downloading and installing the latest fixes takes several hours. Plan this step accordingly.

4. After the required updates are installed, click the Optional Features tab. The Update Manager automatically searches for new updates. 5. The Update Manager presents the available updates. Review the updates and deselect the ones that you do not need. Click Install Features. 6. Depending on the selected features, you may see the license information window. Review the license agreement. If you agree, select I accept the terms in the license agreement and click OK.

Depending on the selected features, the installation process may take up to several hours.

4.3.3 Checking for new program temporary fixes Apart from making sure that your WebSphere Development Studio Client installation is upgraded with the latest fix packs, you must also ensure that your server or iSeries platform has the correct level of PTFs for the host component of the WebSphere Development Studio program license product (5722-WDS), of which WebSphere Development Studio Client is the client component. Three ways are available to do this as explained in the following sections.

List of PTFs from the IBM Web site Make sure that your iSeries server has all the required licensed program products (LPP) and the required CUM PTF and the WebSphere Development Studio PTF levels. You can access the PTF information for the iSeries from the IBM WebFacing Tool PTFs site at: PTF information for WebSphere Development Studio for iSeries http://www-1.ibm.com/support/docview.wss?uid=swg21044473 WebFacing Tool PTFs http://www-1.ibm.com/support/docview.wss?rs=0&uid=swg27002213

You must also ensure that your WebSphere Application Server has the latest PTFs. See the WebSphere Application Server product support site at the following address: http://www-306.ibm.com/software/webservers/appserv/was/support/

Verifying the connection from Remote Systems Explorer To verify the connection: 1. From inside your workbench, open the Remote Systems Explorer (RSE) perspective. 2. Create a new iSeries connection to your server. Expand the connection and highlight the subsystem iSeries Objects. Right-click and select Verify Connection.

Chapter 4. The IBM WebFacing Tool 81 3. The Verify Connection window opens. This process not only verifies that RSE can connect to your iSeries, but it also verifies that you have a valid user profile and password to connect to your server, as well as whether you have the prerequisite products and product options installed and started. WebSphere Development Studio Client also connects to the Internet, retrieves the latest PTF numbers, and verifies if they are installed on your iSeries.

See Figure 4-7. When the verification is complete, click OK.

Figure 4-7 Verifying the connection to check PTFs

Note: To allow WebSphere Development Studio Client to access the Internet using a proxy server, you must define its name in WebSphere Development Studio Client workbench. In the workbench, select Window → Preferences → Install/Update as well as Window → Preferences → Internet → Proxy settings.

The Check PTF option from CODE With the installation CDs for WebSphere Development Studio Client, you receive another CD with the label CoOperative Development Environment and VisualAge RPG V6.0 (previously known as CODE400 and VisualAge RPG). This is now a separate installation for WebSphere Development Studio Client V6.0 as opposed to how it was delivered in the previous version of WebSphere Development Studio Client. Previously, CODE400 was installed when you installed WebSphere Development Studio Client.

If you installed IBM CODE and VisualAge RPG on your PC, then when select Start → All Programs → IBM Code and VisualAge RPG 6.0, you see the Check PTF option. When you select this option, the Check PTF window (Figure 4-8) opens, where you enter the server that to check for PTFs. If you have the required prerequisites, then a smaller window opens stating “You have the required LFP and PTFs.”

82 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Figure 4-8 Checking the PTFs from CODE

4.3.4 New features of the IBM WebFacing Tool The IBM WebFacing Tool is delivered as part of WebSphere Development Studio Client. V6.0, which is the latest version, is now based on the Rational Software Development Platform, and the IBM WebFacing Tool is still accessed by opening the WebFacing Perspective.

In this section, we give an overview of the major changes to the IBM WebFacing Tool. For detailed descriptions on how to use these features, refer to the iSeries Application Development Tools Information Center at the following address: http://publib.boulder.ibm.com/infocenter/iadthelp/v6r0/index.jsp?topic=/com.ibm.etools.iser ies.webfacing.doc/concepts/cwfov.htm

Some of the features described here were added after the last major release, which was V5.1.2, and are included in V6.0: Web Settings view: This enhanced feature is available in both the Standard and Advanced Editions. The former Web Settings option within CODE Designer is now part of the WebFacing perspective. This enhancement provides the user with an integrated Eclipse version of the former Web Settings tool. This means that introducing customizations with Web settings can now be done without leaving the workbench.

Chapter 4. The IBM WebFacing Tool 83 To use the Web Settings feature, you open the DDS with the Remote Systems LPEX Editor. See Figure 4-9.

Figure 4-9 Web Settings now part of the workbench

The transfer of the Web Settings option from CODE Designer into the workbench implies that you do not have to install CODE Designer when you install WebSphere Development Studio Client V6.0. It is now a separately installed option. This is important if you do not have enough workstation capacity to include all the optional features of WebSphere Development Studio Client. Cascading Style Sheets - Positioning (CSS-P): This feature is available only in the Advanced Edition and is delivered as a fix pack. You must upgrade your WebSphere Development Studio Client to V6.0.0.2. CSS-P provides the capability to do pixel-based repositioning of 5250 fields on a Web page. The user can now associate a new pair of row and column coordinates to a 5250

field. The IBM WebFacing Tool maps row and column coordinates to pixel-based coordinates for CSS-P. Native portlet support: This enhanced feature was originally introduced in fix pack V5.1.2.1 and is available only in the Advanced Edition. Portal support allows IBM WebFacing Tool to participate in the integration strategy for Web applications as well as third-party applications. The portal project creation process is the

84 IBM System i Application Modernization: Building a New Interface to Legacy Applications same as a WebFacing Web project. Figure 4-10 shows an example of a WebFacing portlet integrated in the Portal environment.

Figure 4-10 WebFacing Portlet sample

Single sign-on (SSO) support: This enhanced feature was originally introduced in fix pack V5.1.2. 1 and is available only in the Advanced Edition. SSO removes the need for user ID and password setup on the CL command that is defined in your WebFacing project properties. The user credential challenge is now done by the secured server or the Portal environment. System screens support: This enhanced feature is available only in the Advanced Edition originally introduced in fix pack V5.1.2.1.

Note: Additional system screen support is available with IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with Host Access Transformation Services (HATS) Technology. See 3.2, “IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 34.

This feature provides the option to handle screens that have command keys or logic that invokes system commands. It also gives you the capability to integrate with system functions provided by invoking their respective screens. System screens support is only for user interface manager (UIM)-based system screens and does not yet encompass the whole set. The supported system screens are those invoked by the following system commands: –WRKACTJOB –WRKJOB –WRKJOBQ –WRKJRN –WRKLIB –WRKMNU –WRKMSG –WRKMSGD

Chapter 4. The IBM WebFacing Tool 85 –WRKMSGQ –WRKOBJ – WRKOBJLCK –WRKOUTQ –WRKOUTQD

– WRKPRTSTS –WRKSBMJOB – WRKSYSSTS – WRKUSRJOB – WRKUSRPRF –WRKWTR

New support for Web services in Version 6.0.1 The Web services wizard now supports the creation of a Web service directly from ILE RPG and COBOL source in either the RSE perspective or from projects in your workspace. Similar to other Web Service types, a context menu item (Web Services → Create Web Service) is available for RPG, COBOL, and PCML source files. The context menu item is available from within RSE as well as when right-clicking the files in the workspace.

4.4 Sample WebFacing application

In the following sections, we show a sample application to demonstrate what you need to do to reface your iSeries Application using the IBM WebFacing Tool. The sample application is described in Appendix A, “Additional material” on page 285.

In our example, we used WebSphere Development Studio Client Advanced Edition V6.0 installed on a PC workstation to reface the display files of the sample application.

4.4.1 iSeries servers that should be started for the IBM WebFacing Tool To make things run smoothly, start the following iSeries servers on your iSeries to support using the IBM WebFacing Tool and to run the WebFaced applications: Host servers: Allow you to add DDS or UIM source files to your WebFacing project WebFacing server: Allows you to run the application in a Web browser IBM WebSphere Application Server: Allows you to deploy your WebFacing application to an iSeries server, after you finish testing your application using the test environment

Starting the host servers When you create a WebFacing project, WebSphere Development Studio Client for iSeries uses the RSE communications server to access the iSeries server. The RSE communication server requires the OS/400 host servers to be started. If the host servers are not started, you may see the error message shown in the lower half of Figure 4-11 at the time connection is made to the iSeries when you add DDS or UIM source files to your WebFacing project.

86 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Figure 4-11 Connection could not be established

In advance, you can set up a connection to your iSeries and verify that connection. The Verify connection utility also checks that certain host servers are active. This is new with WebSphere Development Studio Client V6. Also, when RSE has a working connection, you can check certain host servers from within the RSE view and, if necessary, start or stop them. Expand your connection, and then right-click iSeries Objects and select Remote Servers. In the submenu, you can either start or stop any of the following items: Agent Controller Debug WebFacing DDM Data queue File host servers

You can also start all host servers on the iSeries by running the following command from the 5250 command line: STRHOSTSVR *ALL

This command is used only to enable client applications to communicate with any of the host servers using sockets communication support.

Starting the WebFacing server After you create the WebFacing application on your workstation, ensure that the WebFacing server is started before you run your application in a Web browser. This is required for testing the application in the WebSphere Development Studio Client test environment or when running in the Web application server.

The WebSphere Application Server server must be able to communicate with OS/400 or i5/OS where the application runs. WebSphere Application Server can be on the same iSeries as your RPG/Cobol application or on a remote system.

This communication is TCP/IP-based. Therefore, on the iSeries, you must start the TCP/IP server that allows the system to communicate with the WebSphere Application Server. This TCP/IP server is called the WebFacing server. This WebFacing server communicates with the WebSphere Application Server server (where your Web application is) and the Workstation Data Manager (where your iSeries application data is) as shown in Figure 4-1 on page 68.

You can start the WebFacing server from the workbench. See “Starting the host servers” on page 86 to start this server from RSE.

Chapter 4. The IBM WebFacing Tool 87 Another option is to run the following command from the OS/400 command line on your iSeries server: STRTCPSVR SERVER(*WEBFACING)

Alternatively you may use iSeries Navigator to start the WebFacing server. In iSeries Navigator, click your server → Network → Server → TCP/IP. In the right panel, right-click WebFacing and select Start.

You can use the iSeries Navigator to check the status of the WebFacing server. Or you can check the status by entering the following command from the OS/400 command line: WRKACTJOB SBS(QSYSWRK)

The WebFacing server is represented by two jobs: QQFWFSVR (the WebFacing run-time server) QQFVTSVR (the WebFacing virtual server)

To set up IBM WebSphere Application Server V6.0, refer to the WebSphere Application Server Information Center on the Web at: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp

4.4.2 Starting WebSphere Development Studio Client To start WebSphere Development Studio Client: 1. Start the WebSphere Development Studio Client Advanced Edition for iSeries 6.0. From the Windows desktop, click Start → All Programs → IBM Rational → IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0 → WebSphere Development Studio Client Advanced Edition for iSeries. 2. Specify the directory for your workspace (where all your projects will be stored). If you are not sure which directory to select, you may use the default directory and click OK. 3. Either close the Welcome tab or press the arrow in the upper right corner of the Welcome tab (go to Workbench) to go to the workbench. 4. In the workbench, select the WebFacing perspective to work with the IBM WebFacing Tool: a. From your workbench, click Window → Open Perspective → Other. b. From the Select Perspective window, select WebFacing and click OK.

4.4.3 Creating a WebFacing project To convert a 5250 application, you must create a WebFacing project. Part of creating the WebFacing project requires using a wizard, which prepares all the required components for the conversion process.

Tip: You can see up front if all DDS keywords that are used in your display source members are supported by the IBM WebFacing Tool. The DDS Keyword Survey Tool is available to check your DDS source files on unsupported keywords; you can download this

tool from the following site: http://www.ibm.com/software/awdtools/wdt400/support/

Then search for DDS and sort by Rank order.

88 IBM System i Application Modernization: Building a New Interface to Legacy Applications Starting the wizard to create a WebFacing project From your workbench, start the wizard: 1. Click File → New → WebFacing Web project.

2. In the WebFacing Web Project panel, enter the name of the WebFacing Project like the example shown in Figure 4-12 and click Next.

Tip: When naming your project, avoid using blank spaces within the name. If you use blank spaces in the name, you may experience unpredictable results when testing or deploying your application, although you do not see any error message immediately.

Figure 4-12 Creating a new WebFacing Web project

Chapter 4. The IBM WebFacing Tool 89 3. For Advanced Edition users: In the WebFacing Features panel, you may select Use single signon (see Figure 4-13), but you need an EIM infrastructure configured to support this option. Click Next.

Figure 4-13 Advanced edition selections

4. In the Select Display File Source Members to Convert panel (Figure 4-14), you can access the iSeries system on which your DDS sources are located. If you do not have a connection yet, click New to create one. You must provide information about your system host name, user ID, and password.

90 IBM System i Application Modernization: Building a New Interface to Legacy Applications After you establish the connection to your iSeries, select the display file source members to convert (see Figure 4-14): a. In the Library field, type the library name that contains the display file source and click Refresh DDS list. If you just created the connection, you should see a sign-on window. Sign on to your system. b. Expand your library and the source file. This can be DSPF or MNUDDS. c. Select the members by clicking their names. If you need to convert all members from the file, click the file name. d. Click the >> button to copy the selected members on the left to the list of the members to be converted on the right. e. For FLGHT400, select QDDSSRCD and QMNUSRC. f. Click Next.

Figure 4-14 Selecting the DDS source members to convert

Chapter 4. The IBM WebFacing Tool 91 5. In the Select UIM Source Members to Convert panel (Figure 4-15), you can select the UIM source members if they are available. In this example, no UIM files are available, so click Next.

Note: This panel applies only to UIM HELP panels. Other UIM panels are only converted (real time) if you select system screen support in WebSphere Development Studio Client AE or use IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology.

Figure 4-15 Selecting the UIM source members to convert

92 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the Specify CL Commands panel (Figure 4-16), you can specify the CL Commands to invoke the application. You can specify the command label, which is the text shown on the site where the application is invoked: a. In the CL command field, type the command GO MENU(FLGHT400/FRSMAIN). b. For Command label, type Flight 400 Reservation System. c. Click Add, and your CL command is listed in the table at the bottom. d. Click Next.

Figure 4-16 Command to invoke the application

Chapter 4. The IBM WebFacing Tool 93 7. In the Choose a Web Style panel (Figure 4-17), you can choose a classic WebFacing style or indicate that you want to enable Web Site Designer to create your own style. In this example, we select Select classic WebFacing style and specify the textbuttons style. Click Next.

Figure 4-17 Choosing a Web style

8. In the next panel, you complete the WebFacing project by choosing to create your project with or without converting it. In this example, we create only the project without the conversion. Therefore, we select No, I only want to create the project now and click Finish. We convert the display files after the project is created.

Tip: To speed up conversion, deselect the Build Automatically option before you do the conversion and then select it again after the conversion has completed. To access this option, from the menu bar, select Project → Build Automatically.

After your project is created, the Flight400 project appears in the workbench as shown in the example in Figure 4-18.

Figure 4-18 After creating the Flight400 project

94 IBM System i Application Modernization: Building a New Interface to Legacy Applications 4.4.4 Converting the WebFacing project To start converting the selected display and menu files, you must be in the WebFacing view as in the example in Figure 4-19. To open this view, click Window → Open Perspective → WebFacing.

Figure 4-19 WebFacing perspective - WebFacing Projects

To convert the Flight400 WebFacing project: 1. Right-click your project name (Flight400 in this example) and select Convert (see Figure 4-20).

Figure 4-20 Starting the conversion

In this example, 31 files are converted. Depending on the configuration of your workstation, it can take one or more minutes to convert these files.

Chapter 4. The IBM WebFacing Tool 95 2. After the conversion, the DSPF Conversion Log (Figure 4-21) is displayed in the editor panel of your workbench.

Tip: You can click any of the display files shown in Figure 4-21 to see all the records in the converted file. To see all messages for a specific record, click that record. You should see the messages in the Errors sections.

Severe errors are indicated by the presence of a red X sign in front of the record format. If you have such errors, check the error, correct it, and run the conversion again until no errors are remain.

Figure 4-21 WF perspective - DSPF Conversion Log

Testing your WebFacing application We recommend that you test your WebFacing application first on your workbench before you deploy it to your WebSphere Application Server. When you install WebSphere Development Studio Client V6.0, a default WebSphere profile is created. We also recommend that you use this profile for testing.

Before you start the testing, check the following conditions: The user profile or profiles that you use to invoke this application should have the application library listed in either the user profile as the default library or in the job description for this user profile.

Your WebFacing server is started; see “Starting the WebFacing server” on page 87. No firewall blocks access to your server. The default WebFacing server port is 4004. You must add the FLGHT400 library to the library list of a user profile that you use for testing. You can do this at the job description level for that user profile or at the system level (QUSRLIBL).

96 IBM System i Application Modernization: Building a New Interface to Legacy Applications To test your WebFacing application: 1. Right-click your project in the WebFacing Project view and select Run → Run on Server. 2. In the Define a New Server window (Figure 4-22), select the existing WebSphere Application Server V6.0 server and click Finish.

Figure 4-22 Selecting the server

The application takes some time to start and deploy your application. In WebSphere Development Studio Client, this is referred to as publish the application. When the embedded WebSphere Application Server test environment has started, the status on the Servers tab changes to Started (Figure 4-23).

Figure 4-23 Server is started

Chapter 4. The IBM WebFacing Tool 97 3. On the Web Browser page that opens (Figure 4-24), click Launch.

Figure 4-24 Launching the application

98 IBM System i Application Modernization: Building a New Interface to Legacy Applications 4. In the next Web page (Figure 4-25), log on using your iSeries user profile and password.

Figure 4-25 Signon screen

Chapter 4. The IBM WebFacing Tool 99 5. You should see the main application menu (see Figure 4-26). If you click 1, it starts the new reservation process. It requires you to enter an agent ID (for example Bill) and password (for example mercury).

Figure 4-26 Testing the WebFacing application on the test server

100 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. After successful application login, you see the main page for creating a new reservation (see Figure 4-27). Use the buttons to prompt a specific data entry.

Figure 4-27 Adding a flight reservation

Customizing your application To customize the default look and feel, you can apply several customization techniques. For more information about these techniques, read Mastering the IBM WebFacing Tool, SG24-6331.

4.4.5 Deploying the WebFacing application to the iSeries The WebFacing application developed in WebSphere Development Studio Client workbench is a typical Web application. Being thus, it is then packaged as an EAR file for installing on the WebSphere Application Server.

We recommend that you test your WebFacing application first in the Web application server test environment of your workbench until you obtain a version that is stable. Then deploy it to the IBM WebSphere Application Server only when it does not require any functional changes or customizations.

Chapter 4. The IBM WebFacing Tool 101 Support for system screens and non-WebFaced applications If your WebFaced application accesses a non-WebFaced application or system screens, you must enable runtime support. This support comes with IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology (see 3.2, “IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology” on page 34).

Note: If your application has DDS source and does not access either non-WebFaced applications or system screens, you do not need to purchase IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology and enable the runtime. However, be aware that, in the next release of WebSphere Development Studio Client, all WebFacing applications will require the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology license.

To enable runtime support: 1. Insert the IBM WebFacing Deployment Tool for WebSphere Development Studio V6.0.1 with HATS Technology CD or open a directory with an electronic CD image and click launchpad.exe. The launchpad opens a panel with a single link. 2. Click the View Readme file for 6.0.1 link. This opens a default Web browser and displays a readme file. This file contains the installation instructions. 3. Start WebSphere Development Studio Client for iSeries: – To start WebSphere Development Studio Client for iSeries, click Start → All Programs → IBM Rational → IBM WebSphere Development Studio Client for iSeries V6.0 → WebSphere Development Studio Client for iSeries. – To start WebSphere Development Studio Client for iSeries Advanced Edition, click Start → All Programs → IBM Rational → IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0 → WebSphere Development Studio Client Advanced Edition for iSeries. 4. In the window that opens, select the location of your workspace and click OK. 5. When the workbench window opens, switch to the WebFacing perspective by selecting Window → Open Perspective → WebFacing (see Figure 4-28).

Figure 4-28 Switching to the WebFacing perspective

102 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the WebFacing perspective, right-click anywhere in the WebFacing Projects view and select Enable WebFacing Run Time (Figure 4-29).

Figure 4-29 Enabling the WebFacing run time

Chapter 4. The IBM WebFacing Tool 103 7. In the Enable WebFacing Run Time window, follow these steps: a. Click Browse. b. In the Open window, navigate to the location of the enablement JAR file cd-rom drive\runtimeenablement.jar. For first-time installations, specify the WebFacing Deployment Tool CD as the location. Click Open. c. Back in the Enable WebFacing Run Time window (Figure 4-30), select the license option. In this example, we select Processor. Then click Finish.

Figure 4-30 Selecting the license option

8. If everything is correct, a window opens with the message about successful enablement. Click OK.

The wizard enables all existing and newly created projects from now on.

Important: If the Build automatically option is unavailable, you must manually rebuild your existing project or projects to enable runtime support. There is a bug fix planned for the next release. If you apply a fix pack to your WebSphere Development Studio Client installation, the existing projects remain enabled. However to enable your newly created projects, you must reapply the JAR file.

104 IBM System i Application Modernization: Building a New Interface to Legacy Applications Packaging the WebFacing application The WebFacing application resources on the WebSphere Development Studio Client workbench must be packaged for deployment. You must export your WebFacing application EAR file to the iSeries server: 1. Click File → Export. 2. Select the EAR file and click Next. 3. In the next window, select your EAR project (Flght400EAR) and select the destination folder. The destination can be either a temporary local PC directory or the iSeries integrated file system directory that is mapped to a local drive. If you transfer the EAR file directly to the iSeries integrated file system, then, for WebSphere Application Server V6.0, the recommended integrated file system directory is /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/profile_name/installableApps.

Tip: We recommend that you transfer the EAR file first to a local PC directory and then move it (using FTP) to the iSeries integrated file system directory. You may also use iSeries Navigator to transfer the EAR file.

Installing the application on WebSphere Application Server V6.0

Note: You must always have the latest PFTs installed on your iSeries server (see 4.4, “Sample WebFacing application” on page 86) and have the latest Rational Product updates (see 4.3.2, “Upgrading WebSphere Development Studio Client V6.0 with the latest available fix pack” on page 80).

After the EAR file are on your iSeries server, start the WebSphere profile to install and run your WebFacing application. To install your WebFacing application: 1. Open the IBM Web Administration for i5/OS with this URL and log in: http://iSeries_hostname:2001/HTTPAdmin 2. Click the Manage tab and Application Servers subtab. From the Server list, select your WebSphere profile. 3. Under WebSphere Application Server Wizards in the left navigation area, click Install New Application. 4. In the Specify Application Location panel on the right, complete these actions: a. Click Browse to pick up your WebFacing EAR file from the iSeries integrated file system directory /QIBM/UserData/WebSphere/AppServer/V6/Base/profiles/ profile_name/installableApps. b. Select the EAR file and click OK. c. Click Next. 5. In the Perform Install Options panel, you have the option to choose Pre-compile JSPs, which improves runtime performance for accessing JSPs. Choosing this option may introduce an increase in the installation time. Click Next. 6. In the virtual host mapping panel, accept the default value and click Next. 7. Review the summary panel and click Finish to complete the installation.

Chapter 4. The IBM WebFacing Tool 105 8. When the installation is completed, under Applications in the left navigation area, click Manage Installed Applications (Figure 4-31).

Figure 4-31 Starting the WebFacing application in WebSphere Application Server

9. In the Manage Installed Applications panel, select your installed WebFacing application on the right, and then click Start. 10.After the application is started, run it from the browser using the following URL, where the WebFacing_contextroot is the name you assigned to your WebFacing project: http://iSeries_host:http_port/WebFacing_contextroot

106 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Part 3

Part 3 Designing a new user interface

The IBM products that we describe in Part 2, “Using IBM solutions” on page 23, have some limitations. Customers who seek a more advanced approach in modernizing their existing legacy applications should invest in developing a different set of skills.

This part provides a technical look at several alternatives that you may consider for your solutions, including: Web services JavaServer Faces (JSF) Portlets Rich-client interface PHP applications

The following chapters are included in this part and discuss these alternatives in detail: Chapter 5, “Before you create a new user interface” on page 109 Chapter 6, “Application architecture, design, and implementation” on page 113 Chapter 7, “Designing a Web services interface” on page 119 Chapter 8, “Designing a JavaServer Faces-based interface” on page 161 Chapter 9, “Designing a portlet client” on page 197 Chapter 10, “Designing a rich-client interface” on page 237 Chapter 11, “Designing a PHP client” on page 267

108 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 5. Before you create a new user interface

Before you create a new user interface for your applications, you may have to modernize the inner workings of the applications themselves. In this chapter, we provide information about what you may need to do and how to do it.

We start by contrasting Original Programming Model (OPM) and Integrated Language Environment (ILE) and then introduce possibilities on how to move from OPM to ILE-based applications. We also discuss reasons why you may or may not want to take that path. Furthermore, we provide information about a related topic, namely the modernization of the database access methods.

Similar to the changes in hardware over time, there have been changes in software development techniques and programming models. While in the beginning (and still today) RPG programs were developed according to the OPM, the ILE represents a newer model that, while more complex, also has its advantages.

5.1.1 OPM versus ILE RPG In this section, we show some differences between OPM and ILE. We point out why a modernization of OPM programs may be necessary, in order to continue using their functionality with new graphical user interfaces (GUIs). Modernizing in this case means to transform OPM programs to ILE. This is more complex than it sounds, because it is not primarily a syntax change, but rather a modularization of your applications.

In fact, while OPM programs often include file access, business logic, and display or print functionality in one single program (partly because of the performance hit of each dynamic CALL of an external program represented in earlier versions), ILE programs are more modularized. Functionality is broken apart in modules and service programs. Instead of compiling a single source member into an executable program object, ILE programs typically consist of more than one source file that was first compiled into modules and then bound together to form an executable program. These modules can be written using different programming languages. Therefore, an executable program can consist of modules written in RPG, COBOL, or any other supported language.

Tip: In a C-based programming environment, the process of binding modules (often files with an .OBJ extension) to an executable program is called linking.

5.1.2 Modernizing OPM programs Let us look at a typical OPM program to further illustrate the concept from the previous section. The following actions allows the user to maintain customer data. Changes are registered in a log file that is printed at the end of the program: 1. Open the necessary files (database, display, printer). If necessary, the files may be conditionally opened when needed. Files may be externally or internally described. For example, in this case the printer file description may be contained in the program source. 2. Display an entry screen, where the user may enter a customer number to select that customer. 3. If the user does not know the customer number and presses F4 while the cursor is in the customer key entry field, fill a subfile that contains customer numbers and allows selection of a customer number and then display it. 4. Display the customer details, allowing the user to change certain values. 5. If the user changes any values and confirms the change by pressing the Enter key, the data is validated. If there are no errors, print a line in the log file indicating that the customer has been changed.

6. Display the customer number entry screen again. 7. If the user ends the program by pressing the F3 key, print the log file, close all open files, and end the program, returning control to the calling program.

110 IBM System i Application Modernization: Building a New Interface to Legacy Applications If this application must be made available to employees working from home through the Internet, providing a GUI in the same time, you can either choose to rewrite the whole application or to modularize the application using ILE RPG. To use our simple example, the functionality to display a subfile showing a selection of customers can be detached from the program’s source code and packed into a separate module. Doing this allows its use in other programs, where that same functionality might be needed. The program simply calls the module, receiving a customer number as a parameter in return.

Another example is to create a module that receives a customer number as an input parameter and displays the corresponding customer information.

By breaking apart your OPM programs into modules and creating ILE-based applications, you open the door to more than just increasing the potential to reuse certain functionality inside other RPG applications. In fact, when this step is done, you can create Web services from your modules, allowing them to be used from a wide array of possible client technologies.

Refer to Chapter 7, “Designing a Web services interface” on page 119, for more information on Web services. The ultimate goal when modernizing your OPM programs is to separate the business from the display logic.

The following Web site contains the list of tools that you can use to modernize your host applications: http://www-304.ibm.com/jct09002c/partnerworld/vic/hardware/portal/iii_pages/iii_tools_innov _roadmap?gcLang=en

5.1.3 Whether to choose the ILE path: Pros and cons There is no doubt that transforming your OPM into ILE RPG programs is a complex task. Tools are available that can transform your existing source code to ILE compliant source code, but that is merely a cosmetic change. The program logic is not modified using such a tool.

The goal in our case is to modularize existing applications, that is to separate the business logic from the display logic conforming to the model-view-controller (MVC) architecture. For more information and a definition of the MVC architecture, refer to the following Web site: http://en.wikipedia.org/wiki/Model-view-controller

The question about whether to undertake this endeavour is not generally answerable. However, the following list provides some points to consider that ideally will help you to choose the right decision: Changing the architecture signifies that there is not only the syntax of a new language to learn, but that education in ILE concepts should not be neglected. If the application is not functionally adequate, it is not worth modularizing. In such a case you may better rewrite it. ILE RPG provides additional enhancements such as longer field names, source level debugging, free-format editing, built-in functions, additional data types and support for date and time fields and calculations. Breaking apart and modularizing huge and complex applications may represent a major, time-consuming task. However, it allows you to use your existing skills and build upon your earlier investments into RPG.

Chapter 5. Before you create a new user interface 111 At least parts of existing code may be reused and know-how, respectively business rules, that may be hidden in the applications can be extracted and grouped together in specific modules. The bottom line is that if you consider building a new Web interface to your existing host applications, then having them in a monolithic form (display and business logic are implemented in the same program) limits your choice to one of the refacing tools.

5.2 More modernization: Database access methods

When talking about OPM RPG, we cannot ignore that along with these applications there many database files were also created. Most of them used data description specifications (DDS) to define the database physical files (PF) and logical files (LF), including the base tables, views, and indexes.

With the arrival of OS/400 on the IBM AS/400 (announced in 1988), IBM offered Structured Query Language (SQL) as an alternative to DDS for creating databases. In addition, SQL Data Manipulation Language (DML) statements were made available as an ad hoc query language tool. These statements can also be embedded and compiled within high level language (HLL) programs. SQL Data Definition Language (DDL) has become the industry standard for defining relational database management system (RDMS) databases.

If you start the process of modernizing your OPM RPG applications, we recommend that you look at the database access methods as well. For more information, refer to the IBM Redbook Modernizing IBM eServer iSeries Application Data Access - A Roadmap Cornerstone, SG24-6393.

This IBM Redbook will help you understand how to reverse engineer a DDS-created database and provides tips and techniques for modernizing applications to use SQL as the database access method.

5.3 Integrating iSeries applications and Java

Earlier in this chapter, we mentioned that most applications implemented with the latest user interface (UI) technologies are implemented in Java. The Java layer allows us to integrate with iSeries programs, functions, and data. IBM Toolbox for Java or JTOpen (the open source version of the product) is the set of application programming interfaces (APIs) for integrating iSeries components with Java. IBM Toolbox for Java provides APIs for calling an iSeries program, invoking a non-interactive command, and accessing iSeries data queues, integrated file system, spool files, and many other iSeries components. For more information about IBM Toolbox for Java, refer to the following Web site: http://www.ibm.com/servers/eserver/iseries/toolbox/

112 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 6. Application architecture, design, and implementation

In this chapter, we provide a high level overview of several application design alternatives. Understanding materials should make your decision on selecting the type of user interface (UI) easier.

When creating a new UI for a traditional iSeries application, you may need to modify or create a new application architecture. Application architecture usually consists of a logical representation of all application components, such as business logic, user interface, data access, file access, and so on, and the relationship between the components.

Over the years, IT industry professionals have come up with software architectures that can be reused to implement different types of applications. These architectures are often called design patterns. Model view controller (MVC) is one of the most popular design patterns for implementing applications that have a graphical user interface (GUI). The main concept of the MVC design pattern is to separate business and presentation logic. Separating business and presentation logic results in better code reuse and maintainability. Let us look closer at each layer of the MVC architecture implementation: Model: This layer of the application encapsulates business logic. Business logic can be implemented in a programming language that runs natively on iSeries (RPG, COBOL, C/C++) or in Java (JavaBeans, Enterprise JavaBeans (EJBs)). View: This layer contains the UI part of the application. All UI technologies described in this redbook are implemented using the Java programming language. Web and portal interfaces are implemented using JavaServer Pages (JSPs), and a rich-client interface is implemented using JavaBeans with a Java GUI API. The “view” layer can be implemented in programming languages other than Java, such as PHP or Microsoft .Net. Controller: This software component or a set of components controls interactions between the view and the model. In a Web environment, the controller layer is implemented in a servlet. A servlet receives requests from a JSP and invokes business logic implemented in JavaBeans, EJBs or iSeries applications. Portlets are controllers in portal applications. They perform similar functions to servlets in a Web application. A controller in a rich-client application is usually implemented in a JavaBean.

One key point to remember is that MVC is a logical architecture, not a physical or deployment architecture. Having an MVC model implementation does not mean that each application layer is packaged and deployed separately.

The MVC application architecture is used for applications that have a UI, and it is not applicable to a Web service application architecture. In a Web service implementation, we can use another design patterns known as the facade pattern.

6.2 Facade pattern

The facade pattern creates an additional layer or a “facade” in front of a component that implements business logic. In this case, the facade component becomes a Web service. The role of the facade component is to separate core business logic from additional tasks that must be performed before the logic is executed. As in the case with MVC, the main benefit of this design pattern is code reuse and better maintainability. In a Java 2 Platform, Enterprise Edition (J2EE), Web services implementation, the facade layer is usually implemented in a JavaBean. The following sample functions can be implemented in a facade component: Create a program interface for better interoperability The facade component method can have a different type of input or output parameters than the Web service implementation. For example, an input or output parameter of type array provides better interoperability than a java.lang.Vector input or output parameter in a Web services implementation. The core business component can keep java.lang.Vector as a parameter, and the facade component converts an array to java.lang.Vector. Maintain application state Web services implementation is usually stateless. An application that uses Web services has to maintain its state. Application state is information that needs to be stored during the period that a user is interacting with an application. For example, an online shopping

114 IBM System i Application Modernization: Building a New Interface to Legacy Applications application must keep track of items selected by the user prior to check-out. In an application that uses Web services, state can be maintained on a server side or in a client application. If you choose to maintain state on a server-side, the recommended approach is to keep Web services stateless and to implement state management in a separate component.

Validation Facade components can implement some preliminary validation that is not required for executing core business logic, but is required for the application. For example, core business logic does not need to check if a user has logged on to the system, but the application needs to validate user credentials before letting the user execute business functions.

Figure 6-1 demonstrates the facade design pattern in an application that uses Web services.

Figure 6-1 Facade design pattern architecture

6.3 Application design and implementation

During the design and implementation phase, developers apply the selected architecture to create an application. In this section, we review design and implementation approaches for each of the technologies described in this redbook.

There is a fundamental difference in design between refacing technologies (IBM WebFacing Tool and Host Access Transformation Services (HATS)) and technologies that allow you to create a new user or programming interface for a traditional iSeries application (JavaServer Faces (JSF), portal, rich client, and Web services). Refacing technologies do not require restructuring of an iSeries application. After refacing an application, developers only need to apply the changes to the generated UI layer.

The second group of technologies gives much more flexibility in extending application functions and the user interface. However, to achieve this flexibility, developers must first restructure the traditional iSeries application (see Chapter 5, “Before you create a new user interface” on page 109).

There are several design approaches that you can take to develop a new GUI. If you want to truly revamp your new application to take advantage of all of the latest GUI technology features, you can put together a team of UI designers. UI designers are responsible for creating a new user interface based on use cases put together by users or business analysts. Parallel to the UI development, your programming staff needs to work on designing and implementing business logic. The business logic development team should use the same use

Chapter 6. Application architecture, design, and implementation 115 cases as the UI team for developing the new API. After the UI and business logic have been implemented, they must be tied together by implementing the “controller” component.

There are several benefits to this design and development approach: User-friendly and user-oriented GUI Improved developer productivity GUI development can be jointly developed by business analysts and UI designers. Meanwhile, programmers can concentrate on more sophisticated business logic. Improved testing GUI and business logic are tested before they are integrated. Flexible architecture By completely separating UI and business logic, we create business logic that can be reused for different types of applications, such as Web, Portal, rich client, and Web services. Flexible integration of UI and business logic By having a separate controller component, we can implement different kinds of communication between the UI and business components (synchronous or asynchronous).

Another design approach for the host applications is a compromise between the first design approach and refacing tools. You may not have time or resources to create use cases in order to completely redesign the UI. In this case, you can take existing 5250 screens and modify them to take advantage of the new UI features. Here are some examples of the small changes that you can make to improve the UI: Place more fields on a single screen. There is more space to work with in a Web or rich-client application than on a 5250 emulator. Replace prompting with combo drop-down lists where it makes sense. Add radio buttons or check boxes for selection. Organize screens by using tab controls. Implement intuitive navigation between screens using “Next” and “Previous” buttons. Use tool tips to improve the user experience.

Let us take a closer look at design and implementation strategies for each of the technologies that we cover in this redbook.

WebFacing The end result of creating a WebFacing application is a Web application that implements the MVC architecture. As a developer, you do not need to worry about the overall application design and architecture. It is generated by the IBM WebFacing Tool. You can extend and customize a WebFacing application with JavaScript and calls to custom-implemented servlets.

A useful design approach for customizing a WebFacing application is to keep all HTML style pages in cascading style sheets (CSS). By using CSS, you can reuse your customization in both Web and portal WebFacing applications.

116 IBM System i Application Modernization: Building a New Interface to Legacy Applications HATS HATS converts traditional iSeries applications to Web applications at run time (versus development time conversion with the IBM WebFacing Tool). There are no special design considerations for HATS applications. iSeries Access for Web iSeries Access for Web is not used to build new applications, but rather to configure iSeries access for Web components (servlets or portlets) to perform a function specific to your environment. There are no special design considerations.

Web applications with JavaServer Faces JSF is a framework that implements the MVC architecture. However, you can still write code that is difficult to maintain and reuse if you do not understand how to plug-in your custom developed components into the JSF framework. Figure 6-2 shows the high-level architecture of a JSF application.

Figure 6-2 JSF application architecture

The FacesServlet is the controller layer of the JSF application. FacesServlet is included in the JSF framework and does not need to be implemented or customized. Developers must implement business logic (JavaBeans, EJBs, Web services, and so on) and the presentation layer (JSF JSPs). The JSF framework handles most interactions between the presentation layer and business logic.

Unlike IBM WebFacing Tool and HATS, where traditional iSeries application code remains unchanged, building a JSF front end requires restructuring the existing iSeries application.

Portlet applications Portlets are applications that run in WebSphere Portal. Portlets usually implement more granular functions than Web applications. For example, in an order entry application, you can have one portlet to place an order and another portlet to display accounts. In a Web application, these two business functions are implemented as different pages of the same Web application. Multiple portlets can be combined into an application.

Business logic implementation in a portal application is the same as in a JSF application; it can be implemented with JavaBeans, EJBs, and Web services, and it should not communicate directly with the presentation layer. The presentation layer in a portlet application consists of JSPs. A portlet is a controller component that ties the presentation and business logic together.

Chapter 6. Application architecture, design, and implementation 117 Figure 6-3 shows the high-level architecture of a portlet application.

Figure 6-3 Portlet application architecture

Rich-client applications Rich-client applications are non-browser applications that are deployed on a desktop. The term “rich” comes from the “richer”, more functional GUI that is provided by a desktop application compared to a thin client (browser) application.

Rich-client applications should be implemented using the MVC architecture. The presentation layer in a Java rich-client application can be implemented using the Standard Widget Toolkit (SWT)/JFace, Eclipse RCP, or Swing API. The business logic layer consists of JavaBeans, EJBs, or Web services. There are two different approaches for implementing the controller layer. Unlike Web and Portal technologies, rich-client applications run on the user’s PC. A rich-client application can be designed to run business logic implemented in Java on the desktop or the server. Running business logic on the desktop requires more resources on the client system, but does not require special server deployment. Running business logic on the server requires an application server, but creates a thinner rich-client application and allows resource reuse on the server. Figure 6-4 shows the rich-client application architecture.

Figure 6-4 Rich-client application architecture

Another design consideration for a rich client is the type of communication between the presentation layer and business logic. While most tasks are probably implemented using synchronous communication, asynchronous communication is a better fit for tasks that take some time to complete.

118 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 7. Designing a Web services interface

In this chapter, we provide an introduction to Web services concepts with references to more thorough discussions and detailed examples. We then show how to create a Web service based on an RPG program. In later chapters in this book, we show how you can consume (or call) these Web services from other applications based on technologies such as JavaServer Faces (JSF), PHP, or Portals.

A search on Google for the keyword “Web services” returns over 930,000,000 documents. We do not know on how many of them you can find an explanation of what Web services is. Explaining technical concepts to an unknown audience is challenging, especially if the background of the audience varies from complete beginner to expert.

Therefore we begin with a non-technical example to introduce you to the topic of Web services. Then we follow this example with more technical information about Web services.

7.1.1 A non-technical example Let us assume that you are the owner of a general store in town where you sell all kinds of goods. One of your main suppliers is located out of town. Both of you are well equipped with phone lines, Internet access, and computers for your business administration. While you are using a Windows-based application, your supplier is running business software on an iSeries with applications written in RPG, because the supplier is serving many customers all over the country.

To place an order for new goods with your supplier, you can usually send him a fax or an e-mail or call him on the phone. All of these means require an employee of your supplier to enter the order into their system. This is not only a time-consuming process, but it is also a source for possible errors due to wrong entries or typos.

Now, if your supplier has a Web site with an order form, you may place that order yourself directly into that system. Assuming that the Web server is running on an iSeries server, the supplier still must integrate the Web site front end, possibly written in a combination of HTML and PHP or using JSF, with the backend software written in RPG.

Back on your side of the business, suppose that your business software allows you to enter all your sales and keeps your stock information up-to-date, allowing you to order new products when stock is decreasing below a certain level. However, you still must check your stock figures and place that order.

As soon as the stock for a certain product goes below a certain level, it would be helpful if your software could contact your supplier’s system directly to order a specific quantity. That would eliminate the need for you to constantly monitor your stock and place an order when needed. On the supplier’s side, it would eliminate the time-consuming need to enter that order into their system.

Web services offers the possibility to make this happen. In short, a Web service is a function in an application that can be called from a program or a system somewhere else using the Internet, similar to a Remote Procedure Call (RPC). Instead of a human interacting with a machine through a Web interface, applications interact directly together with the help of Web services.

In this chapter, we provide detailed information about the technology behind this and show a concrete example on how to create a Web service based on an RPG program.

If instead of Windows, you had a Linux-based system, the same technology would still work. In fact, all big players in the IT industry, such as IBM, Microsoft, and Sun™, have joined forces to support a common standard. This makes it possible to integrate systems based on different technologies using Web services.

120 IBM System i Application Modernization: Building a New Interface to Legacy Applications 7.1.2 A more technical introduction During the past decade, Web applications evolved from static HTML-based sites to dynamic Web applications. The main purpose of static sites is to display information, where dynamic Web applications implement business functions. This includes such sites as online stores, airline reservation systems, and other applications that act upon a user’s request. Dynamic Web applications are implemented using Servlets, JavaServer Pages (JSP), PHP, ASP.NET, and other Internet technologies. Often dynamic Web applications run in a dedicated application server, such as WebSphere Application Server, but they do not have to. The diagram in Figure 7-1 shows the evolution of static (document-centric) to dynamic (application-centric) Web sites in the recent past.

Static Web Applications

Dynamic Web Applications

Web Services Portlet Applications

Figure 7-1 Evolution of the Web from static to dynamic to service-centric

Web services and portal applications are different types of dynamic Web applications. Portal applications are geared toward customizing Web application contents for a user. Unlike other types of Web applications, Web services do no have a user interface. The main goal of Web services is to provide programmatic access to business functions.

Web services are base on the concept of a service-oriented architecture (SOA). See 7.1.3, “A short introduction to service-oriented architecture” on page 122.

A Web service is an application that can be invoked over the Web. In this context, the terms requestor, broker, and provider are often used and are further described in 7.1.3, “A short introduction to service-oriented architecture” on page 122. For now think of the requestor as an application that is asking for a service, and think of the provider as the one who provides the service. In most cases, that means executing a program and sending data back to the requestor. The broker is seen as the “middle man” who helps the requestor and the provider to find each other, such as a telephone directory for businesses.

Web services have the following characteristics: Self-contained: No additional software is required on the client side to invoke a Web service. Self-describing: Web services have a well-defined interface. The definition of the message (from service providers to requesters and vice versa) travels with the message. Published, found, and invoked over the Web: The Internet is the communication media that Web services participants (requestors, brokers, and providers) use to send messages.

Chapter 7. Designing a Web services interface 121 Platform and language independent: Web services can be implemented on different platforms in a variety of programming languages. One of the key requirements for the implementation of Web services is Extensible Markup Language (XML) parsing. Both Web services and traditional Web applications use the Internet as a transport mechanism, but their purpose and implementation are different. Traditional Web applications return HTML that can be displayed in a browser but cannot be passed to other applications.

Web services return XML messages that can either be transformed to be displayed in a browser or passed to other applications. Web applications are human-centric, and Web services are application-centric.

7.1.3 A short introduction to service-oriented architecture SOA is a methodology and a specification that can be used in software development. Because the concept of an “object” is central to an object-oriented architecture, SOA is based on the concept of a “service”. In SOA, a service is an application that can be invoked by other applications.

The concept of a service in software is similar to a concept of a service in real life. For example, if you want to relocate, you look up available services in the telephone directory. Then you can contact the relocation company directly and determine the details of the move. The same scenario can apply to a software interaction. A company can have software that handles relocation procedures. The software can search a public service registry for relocation services. Based on some selection criteria (price, delivery time), the relocation application can choose one of the relocation providers and work with them directly to schedule the move and arrange payment.

The described services scenario involves the following participants and is illustrated in Figure 7-2: Service Requestor: An application with a business need Service Broker: A registry of all available services Service Provider: An application that implements a business function

Broker

2 1

Look up WSDL Publish WSDL

Requestor Provider 3

Use WSDL to bind/invoke

Figure 7-2 SOA interactions using Web services Description Language

122 IBM System i Application Modernization: Building a New Interface to Legacy Applications A service provider implements a service and publishes it to the Service Broker. A service requestor searches the registry to find a service of interest. Upon finding a service, the service requestor binds to the service provider and invokes the service with the help of an XML file that describes the Web services interface. The file uses the Web services Description Language, which is further described in the following section.

7.1.4 Web services technology stack The Web services specification consists of several technologies. The layers as shown in Table 7-1 correspond to interactions among the service requestor, the broker, and the service provider.

Table 7-1 Web services technology stack Service or mechanism Technology

Discovery UDDI, Web Services Invocation Language (WSIL)

Description WSDL

XML Messaging SOAP

Transport HTTP, JMS, FTP, SMTP

The Web services technology stack is based upon the following key technologies: Universal Discovery, Description and Integration (UDDI) UDDI is the technology that fulfills the service broker role (see the introduction to SOA in 7.1.3, “A short introduction to service-oriented architecture” on page 122). At this time, UDDI is mostly used for test purposes. The majority of Web services transactions are performed directly between a Web service client and a Web service without UDDI lookup. Web services Description Language (WSDL) WSDL is an XML vocabulary for describing a Web services interface. A WSDL file usually contains definitions of Web service methods and information about how to invoke the Web service. The Web services wizard in WebSphere Development Studio Client generates a WSDL document based on the Web services implementation. Most Web services tools, including the Web services wizard, use the WSDL document to generate the Web service client proxy code that invokes a Web service. Example 7-1 shows an extract of a sample WSDL document, with the most interesting parts in highlighted in bold.

Example 7-1 Sample WSDL document ...

Chapter 7. Designing a Web services interface 123 ...

In the code in Example 7-1, “sayHello” is the name of a Web service method. A Web service may have multiple methods. The WSDL document describes the input and output parameters for each method. Also notice that the Web service location is specified in the form of a URL. SOAP SOAP is a technology used to create Web services messages that travel between a Web service and a Web service client. SOAP messages are XML messages that contain a RPC or any XML document. SOAP is an open source specification, not a software product, and is the backbone of the Web services technology stack. SOAP Transport Layer Most Web services today are invoked over the Internet. HTTP is the protocol that is used for Internet transport. It is currently the most popular choice for Web services transport because it has been widely used for other Internet applications, and most companies have the infrastructure to support it. One of the most important advantages of HTTP over other protocols is that it can travel through most companies’ firewalls (if companies already have a Web presence and have opened ports for Internet access).

7.1.5 Web services invocation model As introduced earlier in this chapter, a broker or a registry is a component that contains information about Web services. A broker is implemented using the UDDI specification. You may find that the terms broker, registry and UDDI are used interchangeably. Web service providers publish information about their services to UDDI. Web service requestors search UDDI to find a service of interest. This is called the dynamic Web services invocation model and is shown in Figure 7-3.

Broker Lists all services

Provider Requestor

Implements a service Requests a service Figure 7-3 Dynamic Web services invocation model

124 IBM System i Application Modernization: Building a New Interface to Legacy Applications A registry can be public or private. A private UDDI exists within company firewalls and is accessible only by internal applications. A public UDDI is accessible to any application on the Internet. Several major companies, including IBM and Microsoft, maintain public and test registries. Similar to SOAP and WSDL, UDDI is not a product, but a specification, and it has three main components: Yellow pages: Listing of companies and services based on a classification White pages: Contain general information about a specific company including the business name, description, and contact information Green pages: Technical information about Web services

Although UDDI is a part of the Web services architecture, Web services are not required to use UDDI in the interaction between a service requestor and a service provider. If a service requestor knows the location and interface of a service provider at design time, there is no need to go through UDDI. This model is known as a static invocation model and is illustrated in Figure 7-4.

Web Service Client Web Service (Requestor) (Provider)

Figure 7-4 Static Web services invocation model

The static invocation model is easier to use and implement because: The Web service interface is known at design time. There are less security issues.

The differences between the static and dynamic invocation models are similar to the differences between the Intranet and the Internet. In the intranet, the client is known, and there are less security exposures.

7.2 Web service development cycle

In this section, we provide an overview of the Web services development approaches followed by some considerations on interface design and on testing and deployment.

7.2.1 Web services development approach Traditional software development approaches are: Top down Bottom up Meet in the middle All of these approaches can be used for Web services development. The approaches differ in the development order of a Web service interface and implementation and are shortly introduced hereafter.

Chapter 7. Designing a Web services interface 125 Top-down approach The top-down approach works best when you are creating a Web service from scratch. Start with designing an interface using the WSDL. The WSDL file can then be used to generate Web service JavaBeans and Web service client code in WebSphere Developer Studio Client. For a short description of WSDL, refer to 7.1.4, “Web services technology stack” on page 123.

Bottom-up approach If you want to convert an existing application to a Web service, we recommend that you use the bottom-up development strategy. First, evaluate the existing application. Important architectural issues to consider are: Separation of business and presentation logic Web services do not support the presentation layer. Self-contained A Web service does not depend on other applications. Stateless versus stateful Stateful applications may have complex control flow and require greater effort to convert to a Web service.

Applications written in any programming language can be converted to a Web service as long as they support SOAP. Some examples are: JavaBeans Session EJBs Stored procedures RPG programs (with a Java Web services wrapper) C programs C++ programs

After evaluating the application that contains business logic and making the required changes, create a Web service wrapper and a Web service interface. In 7.3, “Creating a Web service” on page 127, we show how to create a Web service based upon an RPG program, including the Java Web services wrapper.

Meet-in-the-middle approach The meet-in-the-middle development approach is the combination of the two previous strategies. First, you have a new Web service interface, and second, you have an existing application. Somehow you need to make them work together. This may require changes to an existing application or to the Web service interface. For example, if you want to create a Web service that will be used by external applications, you may have to add additional parameters to the application that are not required when the Web service is invoked internally.

126 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Stateless versus stateful tip: Each message that the Web service requestor sends to a provider has to contain the necessary information so that the provider can process it.

Adhering to this rule makes it possible to scale the service, as there is no need to store state information between requests.

As an example for a stateless transaction, you may think of a common Web page. You must enter a URL that, in general, contains all the necessary information to display the requested information. For that kind of operation, no additional information or knowledge about earlier requests is needed.

When accessing an File Transfer Protocol (FTP) server to download a file, there can be an interactive session that relies on the fact that the user was authenticated first and that some parameters, such as the working directory, were set. Other examples include e-commerce sites that use shopping carts to store items that a user is interested in purchasing. While browsing the site and going from one page to the next, the information is stored and linked to that particular site visitor; customers would not be happy to suddenly find items from other site visitors in their shopping cart.

7.2.2 Interface considerations When designing a Web service interface, we recommend that you consider the following principles: Choose data types that are supported by SOAP encoding; otherwise you must provide your own implementation. Choose data types that are supported by the majority of programming languages. Service provider and service requestor may be implemented in different languages, and it is important that parameter types are converted correctly between them. For example, java.util.Vector type may not be supported in .Net. Therefore, a Java array is a better choice. For stateless versus stateful Web services, if a service requestor has to make several calls to the service provider, the service provider may have to store some requestor-specific information.

7.2.3 Testing and deployment The WebSphere Development Studio Client Web services wizard generates sample code, such as sample test pages, for easy testing of the Web services that you create.

In addition, a Web service can be published for testing to the IBM Test UDDI. Web services must be registered with a SOAP server, but the WebSphere Development Studio Client Web services wizard does this automatically during the Web service creation. When a Web service is developed and tested in WebSphere Development Studio Client, it can be exported in an enterprise archive (EAR) file and installed in WebSphere Application Server.

7.3 Creating a Web service In this section, we explain how to create a Web service based upon an RPG program. In 7.4, “Consuming or using a Web service” on page 158, we provide the links to the chapters about several client interface technologies that show how to use a Web service.

RPG programs can be converted to Web services by building a Java Web service wrapper around them, either automatically or manually. Before that step, you must ensure that the

Chapter 7. Designing a Web services interface 127 RPG program implementation is suitable for a Web service. We assume that the following two main requirements are met: Separation of business logic and presentation logic: The RPG program must be a callable program that does not contain any display logic. Thread safety: By default, RPG programs are not thread safe. If two or more Java threads call the same RPG program at the same time, you may get unexpected results. Thread safety is discussed in more detail in the next section.

7.3.1 Implementing thread safety in an RPG program Programs or routines need to be thread-safe in order to avoid the risk that one thread interferes or even modifies data elements used by another thread. In a Web service context that can be the same RPG program that is being called from two or more different processes, where each process generates a thread calling the same RPG program. It can be fatal if this program modifies some global data or the heap.

RPG IV has a thread safety option that can be specified on the H spec: THREAD(*SERIALIZE). When the program is compiled with this option, only one thread is active in one module at one point in time. However, you must still ensure that shared storage, such as IMPORT/EXPORT fields, is handled in a thread-safe way. The RPG IV runtime is thread-safe; RPG II and RPG III are not thread-safe.

It is not possible to have thread-scoped files using RPG file support. If the file is left open, the next thread gets the old file state. It is possible to have some of the storage thread-scoped by using allocated storage or user spaces. The program is required know which thread is active (via a parameter from the caller) to know which basing pointer or userspace to use.

Use C runtime I/O functions to do thread-scoped I/O, if necessary.

We highly recommend that you read the text about thread-safety on Wikipedia, because it provides basic, but important definitions. It also outlines ways to achieve thread-safety in programs. There are also links to articles on how to write thread-safe programs:

http://en.wikipedia.org/wiki/Thread_safety

7.3.2 Development steps We begin with a general overview of the development process, specifically about the requirements and assumptions. Then we go into details about the steps to create and test a Web service.

This development entails the following requirements and assumptions: The application has been written in an application programming interface (API) format. It contains no presentation logic, is thread-safe and stateless, and has input and output parameters. We use IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0 for all development tasks in this example. The code sample is based upon the modularized Flight400 library (FLGHT400M) that is used throughout this redbook. See Appendix A, “Additional material” on page 285, for download instructions.

On the following pages, we guide you step-by-step in creating a ProgramCall JavaBean that calls an RPG program. We then explain step-by-step how to create a Web service based upon the ProgramCall JavaBean that will be consumable by a wide array of products.

128 IBM System i Application Modernization: Building a New Interface to Legacy Applications The end result of these steps is shown as a graphical representation in Figure 7-5. The RPG program is called by the ProgramCall Bean, which is generated in WebSphere Development Studio Client. Then we create a Web service using the Web services wizard in WebSphere Development Studio Client.

Web Service Generated by WebSphere Development Studio Client Program Call Bean Generated by WebSphere Development Studio Client RPG Program Implemented by programmers

Figure 7-5 Development steps to create a Web service based on an RPG program

Creating the ProgramCall JavaBean To create a ProgramCall JavaBean: 1. Open IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0. 2. When prompted for a workspace directory, enter C:\IBM Flight400 or a directory of your choice. Click OK. 3. In WebSphere Development Studio Client, open the Remote System Explorer perspective. Select Window → Open Perspective → Remote System Explorer. 4. Click the plus sign next to iSeries to create a new connection to the iSeries server. 5. In the window that opens, enter a profile name and click Next.

Chapter 7. Designing a Web services interface 129 6. In the Remote iSeries System Connection window (Figure 7-6), enter the Connection name, Host name, and Description. Then click Finish.

Figure 7-6 Remote iSeries System Connection panel

130 IBM System i Application Modernization: Building a New Interface to Legacy Applications 7. Review the program. a. In the Remote System pane, click the plus icon next to Work with libraries. b. In the Library Filter panel, for Library name, type FLGHT400M. Then click Next. Figure 7-7 illustrates these two steps.

Figure 7-7 Selecting Work with libraries comes up with the Library filter panel

8. In the next Library Filter panel (Figure 7-8), enter a name for the new filter, FL400 in this example, and click Finish.

Figure 7-8 Entering a new filter name

Chapter 7. Designing a Web services interface 131 9. In the Enter Password panel, enter your user ID and password. For ease of development, you can select the Save user ID and Save password check boxes.

Note: When you are ready to export your application, you may need to consider removing the user ID and password values from the exported application.

Click OK. 10.Expand FL400 → FLGHT400M → QRPGLESRC. Double-click NFS404.rpgle (see Figure 7-9). The source code is then displayed in the source editor window.

Figure 7-9 QRPGLESRC expanded

11.Review the program code. NFS404 contains three procedures: – FindFlightsDoW – FindFlights – GetFlightInfo The procedure that we are interested in is FindFlights. This procedure returns a list of flights based on search criteria, for example, originating city, destination city, departure date, and so on. The procedure GetFlightInfo provides detailed information for a flight but is not discussed further.

132 IBM System i Application Modernization: Building a New Interface to Legacy Applications 12.Create a Dynamic Web Project, if you have not done so yet. This project is used to store the generated code. a. Click File → New → Project. b. Select Dynamic Web Project and click Next. c. In the Dynamic Web Project panel (Figure 7-10), enter a name; we used WebSvc in our example. Click Next.

Figure 7-10 Creating a Dynamic Web Project

Chapter 7. Designing a Web services interface 133 d. In the Features panel (Figure 7-10), accept the default features and click Next.

Figure 7-11 Selecting the features of the Dynamic Web Project

134 IBM System i Application Modernization: Building a New Interface to Legacy Applications e. In the Select a Template for the Web Site panel (Figure 7-12), select Use a default Page Template for the Web site and choose any template (we chose A_blue.htpl). Click Finish. The project is being created.

Figure 7-12 Selecting a page template for the Web site

f. When you see the Confirm Perspective Switch window, click No.

Chapter 7. Designing a Web services interface 135 13.Modify the library list. a. Under your connection in the Remote Systems view, right-click Library list and select Add Library List Entry (see Figure 7-13).

Figure 7-13 Adding the libraries to the list

b. In the Add Library List Entry window (Figure 7-14), in the Additional library field, type FLGHT400M and click OK.

Figure 7-14 Adding a library to the list

c. Add the FLGHT400 library in the same way.

136 IBM System i Application Modernization: Building a New Interface to Legacy Applications 14.Generate the Program Call Markup Language (PCML) file. A tremendous benefit of PCML is that it allows you to write less code. Ordinarily, extra code is needed to connect, retrieve, and translate data between a server and IBM Toolbox for Java objects. However, by using PCML, your calls to the server with the IBM Toolbox for Java classes are automatically handled. PCML class objects are generated from the PCML tags and help minimize the

amount of code you need to write in order to call server programs from your application. We must create a directory that holds the PCML file that we are going to generate in the next steps. Open the Windows Explorer and select Z:\ where Z:\ is a drive mapped to your iSeries server. You may use another drive letter, depending on your preferences. Create a new folder. In our example it is Z:\Book\addmat\RAK.

Note: With WebSphere Development Studio Client V6.0.1, the Web services wizard now supports creation of a Web service directly from the ILE RPG and COBOL source, without separately creating a JavaBean from the PCML file. Similar to other Web Service types, a context menu item (Web Services → Create Web Service) is available for the RPG, COBOL, and PCML source files. The context menu item is available from within RSE and when right-clicking the files in the workspace. Figure 7-15 shows an example.

Figure 7-15 One step Web services wizard

Chapter 7. Designing a Web services interface 137 15.In the Remote Systems view, select NFS404.rpgle, right-click it, and select Compile (Prompt) → CRTRPGMOD (see Figure 7-16).

Figure 7-16 Creating the PCML file

138 IBM System i Application Modernization: Building a New Interface to Legacy Applications 16.In the Create RPG Module window, select the Advanced check box (in the bottom left corner), and several options are added to the window. a. Scroll down. b. For Generate program interface, select *PCML.

c. In the Program interface stream file field, specify the location for the PCML file output followed by the PCML file name to be generated. The file path is /Book/addmat/RAK/nfs404.pcml in our example (see Figure 7-17). d. Click OK.

Figure 7-17 PCML file generation options (lower part of the window)

17.The iSeries Error List view opens. Figure 7-17 shows the lower part of the Create RPG Module window with the values filled in as explained previously. Notice that the corresponding CL command is dynamically constructed on the bottom of the window as you select options and type in values. The command is submitted as a batch job to the system. You may ignore the warning and informational messages, such as the ones shown in Figure 7-18.

Figure 7-18 Warning and information messages displayed when generating the PCML file

If you see error messages indicating that PTFs are missing on the host, check whether the latest PTFs are installed on the server. Under your connection, right-click iSeries Object and select Verify Connection. This checks the system for the latest PTFs. When the job is finished, the generated PCML file is displayed in the indicated directory.

Chapter 7. Designing a Web services interface 139 18.Create a ProgramCall Bean. a. Select File → New → Other. b. In the Select a wizard panel (Figure 7-19), expand iSeries → Java. Select Program Call Bean. Click Next.

Figure 7-19 Creating a ProgramCall Bean

c. In the ProgramCall Wizard, click Import (located in the lower left corner as shown in Figure 7-20).

Figure 7-20 Importing the previously generated PCML file

140 IBM System i Application Modernization: Building a New Interface to Legacy Applications d. In the Import PCML window (Figure 7-21), select Remote/Local File System.

Figure 7-21 Import the PCML file from the file system.

e. In the Browse For File window (Figure 7-22), expand FLGHT400M → / → Book → addmat → RAK and click nfs404.pcml (assuming you have used the same folder as we did for storing the PCML file). Click OK.

Figure 7-22 Navigating to and selecting the generated (and modified) PCML file

Chapter 7. Designing a Web services interface 141 f. In the Import PCML window (Figure 7-23), select the FINDFLIGHTS and GETFLIGHTINFO check box. Click OK.

Figure 7-23 Selecting the programs or structures to import

142 IBM System i Application Modernization: Building a New Interface to Legacy Applications g. In the Program Call definitions panel (Figure 7-24), select GETFLIGHTINFO. Then click Browse next to the Program object field.

Figure 7-24 Browsing for a program object

Chapter 7. Designing a Web services interface 143 h. In the Browse For Object window (Figure 7-25), expand FLGHT400M → *LIB → FLGHT400M and select NFS400.*srvpgm.rpgle. Click OK.

Figure 7-25 Selecting the program object

i. In the Edit Program panel, click OK. j. Select the FINDFLIGHTS node and change the Program object settings in the same way as you did for the GETFLIGHTINFO node.

144 IBM System i Application Modernization: Building a New Interface to Legacy Applications k. Adjust the parameters usage for each function: i. In the Edit Parameter panel, expand the GETFLIGHTINFO node and select FLIGHT(FLIGHTINFO). For the Usage parameter, change the setting from input & output to output (see Figure 7-26). click OK.

Figure 7-26 Changing the usage parameter

ii. Expand FINDFLIGHTS and change the Usage parameter for FLIGHTCOUNT and FLIGHTS(FLIGHTINFO) to output (do not forget to click OK in the Edit Parameter panel). l. In the ProgramCall Wizard, click Next. m. In the next panel, assuming that you created a Dynamic Web Project earlier, select the JavaSource folder of the project and click OK. In our example, this is WebSvc/JavaSource (use the Browse button). n. In the Create iSeries Program Call Java bean and PCML file panel, under Package, enter a package name. In our example, we enter com.ibm.flight400.beans (see Figure 7-27). Click Next.

Figure 7-27 Entering the package name in the ProgramCall Java Wizard

Chapter 7. Designing a Web services interface 145 o. In the Configure Authentication panel (Figure 7-28), complete these actions: i. On the Authentication tab, enter the iSeries Connection information, including your user ID and password. ii. Click the Library List tab (see Figure 7-28). In the Library field, type FLGHT400M and click Add. Then type FLGHT400 in the same field and click Add. You should now have two libraries in the list. iii. Click Finish.

Figure 7-28 Providing the connection information

19.Review the generated code: a. Click Window → Open Perspective → Other. b. Select Java and click OK. c. Expand WebSvc → JavaSource → com.ibm.flight400.beans. d. Double-click any file to open it and look at its source. You may see some errors (shown as a red mark). This is because WebSphere Development Studio Client performs compilation in the background, and it takes some time. To remove these red marks, right-click your project and select Refresh.

You are now done with the first part of creating a ProgramCall JavaBean.

146 IBM System i Application Modernization: Building a New Interface to Legacy Applications Creating the Web service from the ProgramCall JavaBean In this part, we explain how to use the Web services wizard to create a Web service from the ProgramCall JavaBean that we just created. In the following steps, we presume that you are at the Java perspective. 1. In the Package Explorer view, expand the project created in the previous section. In our example, this is WebSvc → JavaSource → com.ibm.flight400.beans. 2. Select the Java class that ends with ‘..Services.java’. In our example, this is FINDFLIGHTSServices.java, but it can be GETFLIGHTINFOServices.java.

Figure 7-29 Selecting com.ibm.flight400.beans.FINDFLIGHTSServices.java

3. In the Select a wizard panel (Figure 7-30), select File → New → Other → Web Service. Click Next.

Figure 7-30 Selecting the Web Service wizard

Chapter 7. Designing a Web services interface 147 4. If the Confirm Enablement window (Figure 7-31) opens, asking you to enable Web services Development, click OK.

Figure 7-31 Confirm Web services Development enablement dialog

5. In the Web Services panel (Figure 7-32), select the following options: – For Web service type: Java bean Web Service – Start Web service in Web project – Generate a proxy, and Java proxy in the Client proxy type – Test the Web service – Create folders when necessary Then click Next.

Figure 7-32 Selecting the Web service creation options

148 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the Object Selection Page panel (Figure 7-33), verify that com.ibm.flight400.beans.FINDFLIGHTSServices (or GETFLIGHTINFOService in your case) is selected. If it is not, browse to the specified JavaBean and select it. Click Next.

Figure 7-33 Selecting the JavaBean

Chapter 7. Designing a Web services interface 149 7. In the Service Deployment Configuration panel (Figure 7-34), accept the default values. Note that they should reflect your project name. Click Next.

Important: If you see an error message at this point, indicating that the server cannot be started (possibly IWAB0213E: Error in starting server), you might have to upgrade your software. Select Help → Software Updates → IBM Rational Product Updater. Check for the latest updates to the installed features. See 4.3.2, “Upgrading WebSphere Development Studio Client V6.0 with the latest available fix pack” on page 80.

Figure 7-34 Service Deployment Configuration panel

The wizard performs some actions. Be patient.

150 IBM System i Application Modernization: Building a New Interface to Legacy Applications 8. In the Service Endpoint Interface Selection panel (Figure 7-35), verify that com.ibm.flight400.beans.FINDFLIGHTSServices is displayed. Click Next.

Figure 7-35 Service Endpoint Interface Selection panel

9. Review the settings on the Web Service JavaBean Identity page (Figure 7-36): – Web service URI: The location of the Web service The Web service client uses this URI to access the Web service. Notice that by default the service URI points to localhost:9080. This setting is saved in a WSDL file and should be changed prior to deployment on a remote (not WebSphere Development Studio Client Test Environment) server. – WSDL Folder and File: The location and name of the WSDL file – Methods: All public methods in the selected JavaBean – Style and Use: Message style can be document (any XML document) or RPC (an XML document that contains a remote procedure call). A message can contain literal XML (an XML document) or encoded parameters (parameter type and encoding is specified in the SOAP message). The choices of style and use are reflected in the generated WSDL document only, not in the generated Java code. The Document/Literal combination is the best choice for interoperability between Web services and Web service clients. – Security Configuration: The security options available through the wizard (XML Signature and XML Encryption) are for test purposes only. Implementing security settings is a configuration task that has to be completed in WebSphere Application Server after Web services deployment.

Chapter 7. Designing a Web services interface 151 Deselect all methods with the exception of findflights(...) and findflights_XML(...) because these are the only methods that we want to expose through the Web service. Leave the default values for all other fields. Click Next.

Figure 7-36 Selecting the methods

10.In the Web Service Test Page panel (Figure 7-37), click Next.

Figure 7-37 Web Service Test Page

152 IBM System i Application Modernization: Building a New Interface to Legacy Applications 11.The Web Service Proxy Page panel (Figure 7-38) opens. A proxy is a Java class that encapsulates a SOAP call. Web services test JSPs using the generated proxy to invoke the Web service. In addition, we can use the generated proxy class when we create Web service clients. In this panel, click Next.

Figure 7-38 Web Service Proxy Page panel

12.If you see a warning message (Figure 7-39), indicating that the web.xml cannot be created because automatic file overwriting has not been enabled, click Yes.

Figure 7-39 Overwrite file warning message

Chapter 7. Designing a Web services interface 153 13.In the Web Service Client Test panel (Figure 7-40), click Finish.

Figure 7-40 Web Service Client Test panel

154 IBM System i Application Modernization: Building a New Interface to Legacy Applications 14.The wizard generates Web services code, starts the WebSphere test environment, and displays the test JSP, as shown in Figure 7-41. This takes time, so be patient.

Figure 7-41 The WebSphere test environment displaying the test JSP

15.Test the Web service by clicking findflights_XML(...) and providing the following input for the parameters indicated (see Figure 7-42): –tOCITY: Chicago –fLIGHTDATE: 20061206 –fROMCITY: Orlando Then click Invoke.

Figure 7-42 Input the test data to test the Web service

16.The results are displayed in the results pane. Notice that some records in the XML string are empty. This happens because of the way in which the RPG program is implemented. We do not want to change the RPG program because it will break other interfaces that use the RPG program, but we can fix the problem in the ProgramCall Bean code.

Chapter 7. Designing a Web services interface 155 17.Optional step: Modify the code to remove blank XML records. In FINDFLIGHTSServices.java, locate the process_FINDFLIGHTS_Output_XML() method. Make the following changes: a. Add two lines of code after int[] idx = null (see Example 7-2). Here we create a variable and assign it the number of records retrieved: // Code to remove blank XML records Integer numOfRecordsInt = new Integer(getflightinfo.getData( "FINDFLIGHTS.FLIGHTCOUNT", ProgramCallBean.INTEGER, idx)); int numRec = numOfRecordsInt.intValue(); b. Change the loop condition in the For loop to take the value of the variable numOfRecords into consideration. Look for the following line: iFINDFLIGHTS_FLIGHTS < 50 Change the line to: iFINDFLIGHTS_FLIGHTS < numRec;

Example 7-2 Modifying the generated code int[] idx = null;

// Code to remove blank XML records Integer numOfRecordsInt = new Integer(getflightinfo.getData( "FINDFLIGHTS.FLIGHTCOUNT", ProgramCallBean.INTEGER, idx)); int numRec = numOfRecordsInt.intValue();

strResult.append("\n"); strResult.append("\n"); strResult.append(" " + getflightinfo.getData("FINDFLIGHTS.FLIGHTCOUNT", ProgramCallBean.INTEGER, idx) + "\n"); for (int iFINDFLIGHTS_FLIGHTS = 0; iFINDFLIGHTS_FLIGHTS < numRec; iFINDFLIGHTS_FLIGHTS++) { idx = addidx(idx, iFINDFLIGHTS_FLIGHTS);

c. After you make these changes, save the file, restart the WebSphere Test Environment and test the findflights_XML(...) method by providing the following input parameters: •tOCITY: Chicago •fLIGHTDATE: 20061206 •fROMCITY: Orlando You should not see any empty XML elements.

Restarting the WebSphere test environment After you modify the Java code, retest your Web service: 1. In WebSphere Development Studio Client, open the Project Explorer view. 2. Expand the WebSvcClient (used in our example; your Web service may have a different name) → WebContent → sampleFINDFLIGHTSServicesProxy (this may have a different name on your system). Right-click TestClient.jsp (see Figure 7-43).

156 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Figure 7-43 Search for the automatically generated TestClient.jsp

3. Select Run → Run on Server. 4. In the Define a New Server panel (Figure 7-44), click Finish.

Figure 7-44 Selecting the server for testing the Web service

The WebSphere Application Server restarts. Then you see the browser window from which you can retest the Web service methods (see Figure 7-41 on page 155).

Chapter 7. Designing a Web services interface 157 After you complete the previous steps, the Web service based on the RPG program is ready to be consumed from a wide range of applications. If necessary, you can modify the code to fit your specific needs. From here, you can deploy the Web service in WebSphere Application Server for OS/400. In 7.4, “Consuming or using a Web service” on page 158, we point you to the sections in this book that introduce the various products and technologies and

demonstrate how to invoke a Web service.

7.3.3 Web service interface design hints We collected some Web service interface design hints that you may find helpful. Avoid parameter types that are unique to the implementation language. Remember that a Web service client and a Web service may be written in different languages. Primitive types, such as String, Integer, Long, and so on are supported by most programming languages. They are a good choice for input/output (I/O) parameters for Web services methods. Most applications need to return more than just primitive values. You can build complex objects with primitive values. In Java, we encapsulate related fields in an Object, in other languages, such as RPG, it may be called a Structure. For example, customer information can be represented as a Customer object that contains multiple fields, such as customer id (long), customer name (String), telephone number (String), and so on. Notice that the Customer object contains fields of primitive types (String, long), which means that it will easily integrate with other programming languages. Keep in mind that in Web services parameters are passed by value. Some programming languages use the concept of passing by reference. Using objects that are passed by reference is not possible in a Web services implementation.

7.4 Consuming or using a Web service

After a Web service is created, it can be consumed by several means. Instead of providing a detailed description of how to use a Web service in this section, we provide the links to the sections that deal with a certain technology: JSF client: See 8.5.2, “Invoking a Web service” on page 189. Rich client: See 10.2, “Example of a rich-client application accessing a Web service” on page 254. PHP client: See 11.5, “Example: Consuming a Web service using PHP” on page 278. Portlet client: See 9.7, “Simple example of invoking a Web service” on page 227.

In these sections, we also show you how to use a Web service.

7.5 Advantages and disadvantages of Web services

If you have read this chapter from the beginning, you know some of the advantages already. Let us summarize the most important ones here: Web services allow data and information sharing between applications even on different platforms, potentially making these applications more efficient, effective, and usable. They are widely supported. All the big players in the IT industry support the same standard. Web services are based on known, proven technologies.

158 IBM System i Application Modernization: Building a New Interface to Legacy Applications Web services are platform and language independent, which is not the case for other interoperability technologies, such as OMG Common Object Request Broker Architecture (CORBA) and Microsoft Distributed Component Object Model (DCOM), and therefore easier and cheaper to implement. Web services allow you to leverage existing applications, for example by continuing usage of existing business rules embedded in RPG programs, therefore protecting investments. Web services offer a wide choice of possible user interfaces. Web services can be invoked by multiple client technologies, such as Web, mobile, and desktop applications.

Are Web services the technology, the solution to all our problems, the step into a better future? The latter may be true, but they are certainly not the solution to all our problems. While Web services are certainly useful, some issues must be considered, first of which are security-related issues.

Let us review some disadvantages of Web services: Transactions are not well defined. There is a performance gap compared to other distributed computing approaches such as CORBA, DCOM or Remote Method Invocation (RMI). Using HTTP, Web services can circumvent existing firewall measures that are in place to block or audit communications between programs on either side of the firewall.

Regarding the second point of poor performance, writing a Web services-based application takes much less time than doing the same with CORBA, which is a much more complex technology.

7.6 Further reading

For more information about Web services, refer to the SOA and Web services Web site from IBM developerWorks® at: http://www-130.ibm.com/developerworks/webservices

IBM developerWorks site features many technical articles and tutorials.

You can also read more on Wikipedia. Wikipedia is a free online encyclopedia that contains many articles and information in several languages, not only IT-related. For Web services http://en.wikipedia.org/wiki/Web_service For SOA http://en.wikipedia.org/wiki/Service-oriented_architecture

Chapter 7. Designing a Web services interface 159

160 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 8. Designing a JavaServer Faces-based interface

JavaServer Faces (JSF) is the advanced framework for building the rich user interface (UI). Unlike the refacing tools, the JSF-based applications require more development knowledge and effort. However, the JSF framework gives you more advanced user interface capabilities and a standard approach for building a presentation layer for the Web applications.

In this chapter, we help you to understand the basic principle in building a JSF application and the advantages offered by this framework. To better realize the JSF development process, we provide instructions for building a simple JSF interface to the sample application.

JSF is a new server-side technology that allows developing Web applications with rich UIs. It provides a UI framework that consists of ready-to-use UI components. In addition, it provides a runtime framework for rendering these components, managing the life cycle of the page, and handling the interaction between the UI and your host applications.

The ultimate goal of the JSF technology is rapid application development. The framework provides support for easy page navigation, session and object management, validations and internalization requirements. Application development is made more efficient by the capabilities for rapid prototyping, early, iterative functional testing of designs, reusing of standard software components, and using visual design tools.

For a more extensive description of the technology, read the IBM Redbook WebSphere Studio 5.1.2 JavaServer Faces and Service Data Objects, SG24-6361. For additional considerations about using JSF, refer to 2.4.1, “JavaServer Faces technology” on page 16.

8.2 The JSF framework

A typical JSF-based application architecture follows the model-view-controller (MVC) architecture where business logic is separated from presentation, as illustrated in Figure 8-1. (For more details about the MVC design pattern, refer to Chapter 6, “Application architecture, design, and implementation” on page 113.) In this design architecture, the model or the business logic may consist of Java beans or Enterprise JavaBeans (EJBs) or Web services accessing the host database and applications. The view or the UI consists of the Web pages that are using JSF components. The controller is implemented by the JSF framework.

Figure 8-1 JSF framework in the MVC design

JSF provides a UI framework that simplifies the development of the view. JSF also provides the runtime framework; thus, there is no code development required for the Controller. The development effort therefore can be concentrated on the development of the Model (also known as business logic).

162 IBM System i Application Modernization: Building a New Interface to Legacy Applications 8.3 The JSF development environment

While JSF provides the UI framework, it does not provide the tools for the actual UI development. These are typically provided by the different tool vendors. The IBM development tools WebSphere Development Studio Client V5.1.2 and V6.0, for instance, provide support and functionality for JSF code generation.

In the following sections, we present an overview of the JSF development features and discuss the advantage of using this technology. We do not go into the details about how to use these features. There is a step-by-step tutorial you can follow from the Tutorials Gallery inside your WebSphere Development Studio Client Studio. Click Help → Tutorials Gallery → Do and Learn and select any of the JSF tutorials. You can also use the tutorials in WebSphere Studio 5.1.2 JavaServer Faces and Service Data Objects, SG24-6361.

8.3.1 JSF components JSF components are available under the Palette View within the WebSphere Development Studio Client. From the Faces Components drawer, you can drag and drop JSF components, such as input boxes, output fields, buttons, combo boxes or radio buttons, into your Web pages. There is also a Data drawer from where you can generate new or reference existing Java beans for Web services or database queries.

Unlike the HTML components, these JSF components have properties, respond to events, have predefined behavior, and can be bound to business logic. Because all of these can be done just by configuration, it makes page development quicker and simpler.

8.3.2 Properties Properties are attributes than you can associate with the JSF components. Examples of properties include the component ID, value, style and size, as well as the format, any navigation and validation rules. Based on these properties, JSF provides automatic validation.

In a typical HTML-based development, you must code JavaScripts to provide these validations.

8.3.3 Events JSF supports not only the request and response model of typical Web applications, but also the event model. For example, such an action as clicking a Submit button or clicking a hyperlink or navigating from page to page is tied to a JSF component.

In a typical Web application development, implementing these actions requires intermediate Java knowledge on request handling.

8.3.4 Binding JSF simplifies the capturing of input data for processing and displaying data returned from the execution of business logic by introducing the capability of associating a value to a JSF component in the Value property.

In a typical Web application development, you must code this data handling and processing yourself.

Chapter 8. Designing a JavaServer Faces-based interface 163 8.4 Why use JSFs

While Java 2 Platform, Enterprise Edition (J2EE), provides strong patterns and frameworks for the server side of Java applications, little detail is provided about development of the presentation layer. Most Web applications are developed using JavaServer Pages (JSPs) with HTML user interface components; it is up to the programmer to create the necessary code. The resulting Web pages, however, do not have rich UIs and have limited functionality. Also creating custom components requires time and coding expertise.

The main reason why JSF has been developed is to facilitate the development of the presentation layer. Let us look at the list of advantages for choosing this technology: JSF provides a much more structured and reusable framework. It saves a lot of time for the developer. There is no need to spend time for each new project in determining how to handle such presentation issues as navigation, validation, scrolling through data sets, and managing the life cycle of business objects used in the presentation. Because JSF is based on a standard that has been developed by all the major tool vendors, including IBM, Borland, Oracle and Sun, you have a choice of multiple tools from many different vendors. Because the JSF provides a rich-component UI framework, the presentation is now made in a standard way with well known classes, commands, and tags. This means that the tool vendors can create a graphical development environment that makes the construction of the project much easier by using wizards and drag-drop property sheets to make the development process much more user friendly and efficient. JSF development follows the Rational Application Developer style. Because JSF has a pluggable rendering capability, its UI components can render different data types, such as HTML, XML, Wireless Markup Language (WML), or binary data, depending on the viewing client. You can direct your output data to different viewing clients such as HTML browsers, personal digital assistants (PDAs), or wireless devices. Because JSF provides a runtime framework with a Faces servlet, there is no need to code the handling of the interactions between the client and the application.

With all these great features, there is a price to pay. First, JSF framework does not generate a complete code for the presentation layer. It provides the library of the available GUI components, but you need to apply a development effort to arrange these visual components on the page and tie them to the business components running on a middle ware.

Second, as with any new technology, there is a learning curve that you need to account for in your project plan. Finally, information and documentation about the technology is not yet as extensive as those available for the Servlet and JSP-based framework. Also, some of the tools for JSF support in your chosen integrated development environment (IDEs) may not be robust yet.

8.5 Sample JSF application

In this section, we provide an example of the JSF development process. We help you to understand better the JSF framework and tooling available in WebSphere Development Studio Client V6.0. We demonstrate two approaches for using JSF: Using the IBM Toolbox for Java ProgramCall mechanism Invoking a Web service

164 IBM System i Application Modernization: Building a New Interface to Legacy Applications 8.5.1 Using the ProgramCall mechanism For this sample, we invoke the Flight Reservation RPG function NFS404 to retrieve the list of available flights given an originating city, a destination city, and a departure date. This application and other required resources are available with the downloadable sample application material described in Appendix A, “Additional material” on page 285.

A prerequisite for this exercise is generating the Program Call Markup Language (PCML) file that describes your RPG functions and then using the information from this file to create the Java programs or Java beans to wrap the RPG functions. We then use these Java beans to create a JSF-based application to prompt for the required input parameters and return the list of available flights.

For details about how to generate the PCML and create the Java beans, refer to 7.3.2, “Development steps” on page 128.

To build the JSF application, we use these steps, each of which is explained further: 1. Create the PCML file to describe the functions available in the RPG module NFS404. 2. Create the Dynamic Web Project to hold the JSF application. 3. Generate the ProgramCall Java beans for the program interfaces and services. 4. Create the input JSF to display the input parameters. 5. Create the output JSF to display the results. 6. Add the Java beans to the input/output JSF pages. 7. Bind the Java beans to the JSF pages.

Creating the PCML file for the RPG module Create the required nfs404.pcml file for the NFS404 RPG program and place it either in the integrated file system directory of your iSeries or on your local file system. For instructions on how to do this, refer to “Creating the ProgramCall JavaBean” on page 129.

Creating the Dynamic Web Project to hold the JSF application Here we create a Dynamic Web Project as a holder for our JSF application resources: 1. Open the Web perspective in your WebSphere Development Studio Client workbench. Select Window → Open Perspective → Other → Web. Click OK. 2. Create a new Dynamic Web Project by selecting File → New → Dynamic Web Project. 3. In the New Dynamic Web Project panel, enter a name for your project. For our sample, the project name is JSFRpg. Then accept all the other defaults and click Finish.

Chapter 8. Designing a JavaServer Faces-based interface 165 Creating the ProgramCall Java beans We now make the NFS404 functions available to our JSF application by wrapping them with Java code: 1. Create the required Java beans based on this PCML file. Right-click your project and select New → Other. 2. In the Select a wizard panel (Figure 8-2), expand iSeries → Java and select ProgramCall Bean. Then click Next.

Figure 8-2 Program Call wizard

3. In the Program Call wizard, click Import.

166 IBM System i Application Modernization: Building a New Interface to Legacy Applications 4. In the Import PCML window (Figure 8-4), select Remote/Local File System. In the Browse For File window (Figure 8-3), navigate to the PCML file. Select the nfs404.pcml file and click OK.

Figure 8-3 Importing the PCML file

Chapter 8. Designing a JavaServer Faces-based interface 167 5. Back in the Import PCML window (Figure 8-4), the list of programs or structures shows four programs described by the nfs404.pcml file. Select FINDFLIGHTS and click OK.

Figure 8-4 Program selection from PCML

6. In the Program Call Wizard (Figure 8-5), the resulting list under ProgramCall definitions shows two definitions, FLIGHTINFO and FINDFLIGHTS. a. Under Program call definitions, select FINDFLIGHTS. b. In the Edit Program section, click Browse next to the Program object field (see Figure 8-5). c. In the Browse For Object window, expand FLGHT400M → *LIB → FLGHT400M and select NFS400.*srvpgm.rpgle (see Figure 7-25 on page 144). Then click OK.

Note: These steps presume that you have completed the exercises in the previous chapters. If not, you may need to add FLGHT400 and FLGHT400M to the library list for your System i connection in Remote Systems Explorer (RSE).

168 IBM System i Application Modernization: Building a New Interface to Legacy Applications d. Back in the Program Call Wizard window, under Edit Program, click OK. e. Adjust the parameter usage for each function: i. Expand the FINDFLIGHTS node and select FLIGHT(FLIGHTINFO). ii. In the Edit Parameter section, change the Usage parameter from input & output to output. Then click OK. See Figure 7-26 on page 145. iii. Select FLIGHTCOUNT. iv. In the Edit Parameter section, change the Usage parameter to output, and click OK. f. Click Next.

Figure 8-5 Program definitions

Chapter 8. Designing a JavaServer Faces-based interface 169 7. In the Create iSeries Program Call Java bean and PCML file (Figure 8-6), complete the following actions: a. Enter the following values: •Folder: projectName/JavaSource, where projectName is your project name

This field should be prefilled correctly. •Package: com.ibm.flight400.beans • PCML file name: FINDFLIGHTS This field should be prefilled correctly. b. Select the Services check box. c. Click Next.

Figure 8-6 Creating services

170 IBM System i Application Modernization: Building a New Interface to Legacy Applications 8. In the Configure Authentication panel (Figure 8-7), complete the following actions: a. On the Authentication tab, enter your iSeries host name, your iSeries user profile, and your password. b. Click the Library List tab (see Figure 8-7).

i. In the Library field, type FLGHT400M and click Add. ii. In the Library field, type FLGHT400 and click Add. You should have two libraries in the list. c. Click Next.

Figure 8-7 iSeries authentication

Chapter 8. Designing a JavaServer Faces-based interface 171 9. In the Summary panel (Figure 8-8), you see a summary of the generated files. Click Finish.

Figure 8-8 Summary of generated files

172 IBM System i Application Modernization: Building a New Interface to Legacy Applications After you successfully create the Java beans, expand the Java Resources folder of your project. Then you should see the Java classes created within the JavaSource folder as shown in Figure 8-9. We are interested in three of these Java beans: FINDFLIGHTSInput.Java for the search parameters FINDFLIGHTSResult.Java for the resulting list of flights FINDFLIGHTSServices.Java for invoking our RPG module NFS404

Figure 8-9 Java resources

Chapter 8. Designing a JavaServer Faces-based interface 173 Creating input and output JSF pages The input JSF is for displaying the search criteria for searching for available flights. The criteria are the departure date, the originating city, and the destination city. To create the JSF files: 1. In the Project Explorer panel, select your project, right-click, and select New → Faces JSP file. 2. In the New Faces JSP File window (Figure 8-10), in the File Name field, type RPGIn. For Options, select Create from page template, accept the other defaults and click Next.

Figure 8-10 New Faces JSP File window

3. In the Page Template File Selection window, click the Sample Page Template radio button and select one from the displayed template thumbnails. For our sample, use A_blue.htpl. Click Finish.

174 IBM System i Application Modernization: Building a New Interface to Legacy Applications 4. The new input JSP file opens in the Page designer editor (Figure 8-11). a. Click the Design tab in the editor. b. Click the Properties tab in the lower portion of the window. c. Under the Properties tab, click Text to see the properties.

Figure 8-11 Created input JSF page

d. Highlight the Place your page content here text and change the text to Search Flights.

Chapter 8. Designing a JavaServer Faces-based interface 175 e. Highlight the text and change the color to red under the Properties tab (see Figure 8-12). f. Move the cursor to the end of the text and press Enter two or three times to create some blank lines after the heading.

Figure 8-12 Changing input page headings and color

g. Leave your cursor positioned at the start of one of these blank lines. h. Press Ctrl+S to save the input JSF. i. Repeat steps 1 and 3 to create another Faces JSP as an output JSP. In this sample, we create a JSP named RPGOut.jsp.

176 IBM System i Application Modernization: Building a New Interface to Legacy Applications 5. Review the generated JSF pages in your Project Explorer view. Expand the WebContent folder to see the new JSP files (RPGIn.jsp and RPGOut.jsp) as shown in Figure 8-13.

Figure 8-13 Project Explorer view of new JSF pages

Chapter 8. Designing a JavaServer Faces-based interface 177 Adding the Java beans to the JSF pages We add the Java beans to our JSF pages so we can use the services they provide. We need to use the following Java beans: FINDFLIGHTSInput.Java for the search parameters FINDFLIGHTSResult.Java for the resulting list of flights FINDFLIGHTSServices.Java for invoking our RPG module NFS404

Follow these steps: 1. From the Project Explorer tab, open RPGIn.jsp. If it is open, switch to the tab with RPGIn.jsp. 2. Click the Page Data tab in the lower left corner of your workbench where you see Scripting Variables. Right-click the white space in the Page Data view and select New → JavaBean as shown in Figure 8-14.

Figure 8-14 Adding a new JavaBean

178 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3. In the Add JavaBean window (Figure 8-15), add the Java bean to handle the input parameters for our search program: a. Select Add new JavaBean. b. For Name, type searchBean.

c. For Class, click the Browse button on the right. Start typing FINDFLIGHTSInput. You should see all classes that match your partial string. As soon as you see FINDFLIGHTSInput, select it and click OK. Alternatively, you can type com.ibm.flight400.beans.FINDFLIGHTSInput for Class without browsing. d. Select Make this JavaBean reusable (Make this JavaBean a JSF ManagedBean). e. For Scope, select application. f. Click Finish.

Figure 8-15 Adding a new JavaBean

4. Add another JavaBean to receive the list of flights returned: a. Click Add new JavaBean. b. For Name, type resultBean. c. For Class, click the Browse button on the right.

Start typing FINDFLIGHTSResult. You should see all classes that match your partial string. As soon as you see FINDFLIGHTSResult, select it and click OK. Alternatively, you can type com.ibm.flight400.beans.FINDFLIGHTSResult for Class without browsing.

Chapter 8. Designing a JavaServer Faces-based interface 179 d. Select Make this JavaBean reusable (Make this JavaBean a JSF ManagedBean). e. For Scope, select application. f. Click Finish. 5. Add another JavaBean to handle the ProgramCall processing: a. Click Add new JavaBean. b. For Name, type serviceBean. c. For Class, click the Browse button on the right. Start typing FINDFLIGHTSServices. You should see all classes that match your partial string. As soon as you see FINDFLIGHTSServices, select it and click OK. Alternatively, you can type com.ibm.flight400.beans.FINDFLIGHTSServices for Class without browsing. d. Select Make this JavaBean reusable (Make this JavaBean a JSF ManagedBean). e. For Scope, select application. f. Click Finish. 6. In the Page Data view in the lower left corner of your workbench, you should now have three Java beans (under Faces Managed Beans) as shown in Figure 8-16. Press Ctrl+S to save the file.

Figure 8-16 Added managed JavaBeans

Binding the Java beans to the JSF pages In the following sections, we use the drag-and-drop capability of the JSF framework to generate the processing controls for our JSF pages.

Generating controls for the input JSF Our input JSF needs to display the search parameters for looking up a list of flights. The RPG module that we have chosen requires three input parameters, which are the departure date, originating city, and destination city. Processing controls for these parameters are handled by the managed bean, searchBean, that we added to our RPGIn.jsp. 1. Open the RPGIn.jsp file if it is not open. 2. Position the cursor at the end of the text box (after the two blank lines that you added to this file in step f on page 176).

180 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3. Go to the Page Data view and expand searchBean. 4. You should see the word Introspecting.... while its processing. When it finishes, the panel shows the bean properties that represent the input parameters that are required to call the RPG program to retrieve a list of flights (Figure 8-17). Highlight the three parameters (FLIGHTDATE, FROMCITY, and TOCITY). Drag and drop them onto the open area of RPGIn.jsp.

Figure 8-17 SearchBean properties

5. In the Configure Data Controls window (Figure 8-18) that opens, select the Inputting data radio button, accept the selected parameters, and click Finish.

Figure 8-18 Inserting JavaBean controls

Your input JSF should now look like the display in Figure 8-19.

Note: You may also modify the labels for your input fields to make them more readable.

6. Click the Submit button to highlight it.

Chapter 8. Designing a JavaServer Faces-based interface 181 7. Click the Properties tab in the lower panel. Change the Id value from button1 to search. 8. Enter the code for the processing that needs to be done when the Submit button is pressed. a. Select the Quick Edit tab and select the Command item.

Figure 8-19 Input JSF with searchBean

b. You see the line Insert a code snippet or write your script here in the right portion of the panel. Click this line, and you see the following lines: // Type Java code that runs when the component is clicked

// TODO: Return outcome that corresponds to a navigation rule return ""; Replace the lines with the following code: // Type Java code that runs when the component is clicked FINDFLIGHTSResult res = getServiceBean().findflights(getSearchBean()); getResultBean().setFLIGHTCOUNT(res.getFLIGHTCOUNT()); getResultBean().setFLIGHTS(res.getFLIGHTS()); // TODO: Return outcome that corresponds to a navigation rule return "search";

182 IBM System i Application Modernization: Building a New Interface to Legacy Applications Figure 8-20 shows the result of the changes.

Figure 8-20 Code to process the Submit action

9. Select the Properties tab again, scroll the display to the right, and click the Add Rule tab (see Figure 8-21). You use this tab to define the flow of your pages by providing navigation rules.

Figure 8-21 Add Rule tab for page navigation

Chapter 8. Designing a JavaServer Faces-based interface 183 10.In the Add Navigation Rule window (Figure 8-22), complete these actions: a. From the Page list, select RPGOut.jsp. b. Select The outcome named and type search. c. Accept all other defaults. d. Click OK.

Figure 8-22 Adding a navigation rule

11.Press Ctrl+S to save your file.

Generating controls for the output JSF The output JSF needs to display the list of flights that satisfy the search criteria entered from our output JSF. Processing controls for these parameters are handled by the managed bean, resultBean, that we added to our RPGOut.jsp. To complete coding this JSF: 1. Open the output JSF RPGOut.jsp file. 2. Change the heading to List of Available Flights and create two blank lines after this heading by pressing Enter twice. 3. Go to the Page Data view and expand resultBean. You should see the word Introspecting.... while its processing. When it finishes, the panel shows the bean properties that represent the flight information data. 4. Highlight the FLIGHTS property and drag and drop it onto the open area of the output JSP.

184 IBM System i Application Modernization: Building a New Interface to Legacy Applications 5. In the Configure Data Controls window, rearrange the properties in the order that you want them to display. Use the Up and Down arrow keys as shown in Figure 8-23. You may also modify the labels for your output fields to make them more readable. Click Finish.

Figure 8-23 Data controls for output JSF

Chapter 8. Designing a JavaServer Faces-based interface 185 Your output JSP should now show the flight details in columns as shown in Figure 8-24.

Figure 8-24 Output JSF with resultBean properties

186 IBM System i Application Modernization: Building a New Interface to Legacy Applications 6. In the right side of your workbench, you see a palette of components (Figure 8-25). a. Under the Faces Components drawer, drag the Command - Button component to the area under the table of data on your page. b. You see a button labelled “Submit”. Click the Submit button.

c. Select the Properties tab in the lower panel. i. Change the Id value to back. ii. Near the right side of the panel, click the small down arrow on the right side of the folder icon. Then select Show All Attributes as shown in Figure 8-25.

Figure 8-25 Showing all attributes for a component

7. Scroll down to the bottom of the Attributes window. a. Change value from Submit to Back. b. Click Show All Attributes again to close the window. 8. Scroll towards the right and click the Add Rule button. 9. In the Add Navigation Rule window, complete these actions: a. For Page, select RPGIn.jsp from the list.

b. Select The outcome named and type back. c. Accept all other defaults. d. Click OK.

Chapter 8. Designing a JavaServer Faces-based interface 187 10.Replace the code for the processing that needs to be done when the Back button is pressed. a. Select the Quick Edit tab and select the Command item. b. You see the line Insert a code snippet or write your script here in the right portion of the panel. Click this line and you see the following lines: // Type Java code that runs when the component is clicked

// TODO: Return outcome that corresponds to a navigation rule return ""; Replace these lines with the following code: // Type Java code that runs when the component is clicked

// TODO: Return outcome that corresponds to a navigation rule return "back"; 11.Press Ctrl+S to save your output page.

Testing your JSF application using a ProgramCall Before you test your application, make sure that it has been rebuilt to apply all the changes that you have done. On the menu bar of your workbench, click Project and see if the Build Automatically option is selected. If it is not chosen, select it to activate the automatic rebuilding of projects in your workbench.

To force a rebuild of your JSF project, highlight the project in the Project Explorer view (in our sample this is JSFRpg). Click Project again and select Build Project.

You can now test your JSF application: 1. Expand JSPRpg → WebContent. 2. Right-click your input JSF (our sample is RPGIn.jsp) and select Run → Run on Server. 3. Accept the default WebSphere v6.0 Server and click Finish. 4. Your input JSF should now show the prompts for the search criteria for retrieving available flights (see Figure 8-26). Enter the following test search criteria and click Submit. – Fromcity: Atlanta – Tocity: Albany – Flightdate: A time in the future in the form of MMDDYYYY

Figure 8-26 Flight search criteria

188 IBM System i Application Modernization: Building a New Interface to Legacy Applications The output JSP should now display the results of your search request (Figure 8-27).

Figure 8-27 List of available flights

8.5.2 Invoking a Web service Web services are becoming a popular technology. Fortunately, you can easily access a Web service using JSF. In this section, we show how to invoke a Web service using JSF. For details about how to create a Web service, refer to Chapter 7, “Designing a Web services interface” on page 119.

For this sample, we invoke the Flight 400 Web service, FINDFLIGHTServices. This Web service retrieves available flights between two cities for a given date. In this section, we assume that the Web service has been already built and deployed to the WebSphere Application Server.

Here is the outline of the steps to build a JSF application. 1. Search for the Web service using the Web Services Explorer, a tool that is integrated in WebSphere Development Studio Client. 2. Create a proxy for the selected Web service. 3. Drag and drop the Web service proxy onto JSP using JSF components.

Chapter 8. Designing a JavaServer Faces-based interface 189 To create the sample JSF application: 1. Open the Web perspective in your WebSphere Development Studio Client workbench by selecting Window → Open Perspective → Other → Web. 2. Click OK.

3. Before doing any development steps, start the WebSphere Test Environment in WebSphere Development Studio Client: a. In the lower right corner of the workbench, click the Servers tab. b. You see one entry in the list (bottom of Figure 8-28; considering that you followed the instructions for building a Web service in Chapter 7, “Designing a Web services interface” on page 119). Right-click this server and select Start. Starting WebSphere Application Server activates the Web service.

Figure 8-28 Starting the server

4. Create a new Dynamic Web Project by selecting File → New → Dynamic Web Project. 5. In the New Dynamic Web Project panel, enter a name for your project, accept all the other defaults, and click Finish. 6. When your project is created, select it in the Project Explorer panel, right-click, and select New → Faces JSP File. 7. In the New Faces JSP panel, enter a name for your page and click Next. 8. In the next panel, select the sample page template by clicking one of the template thumbnails. Click Finish. 9. You should now see the newly-created JSP. Replace the Place your page content here text on the page with Available Flights.

190 IBM System i Application Modernization: Building a New Interface to Legacy Applications 10.Verify that the Palette View is open (select Window → Show View → Palette). In the lower section of the Palette under Data (Figure 8-29), select Web service and drag it onto the JSF page.

Figure 8-29 Data portion of the Palette view

11.When the Web services wizard is displayed, click Web Services from your workspace to see the Web Service Discovery Dialog as shown in Figure 8-30.

Note: This step assumes that you have completed the example in Chapter 7, “Designing a Web services interface” on page 119. If you have not, point to the URL for the existing Web service.

Figure 8-30 Web services search

Chapter 8. Designing a JavaServer Faces-based interface 191 Click the URL.

Note: In a more realistic scenario, you must select the Web Services from known URL option and provide a URL for the Web service WSDL file. This URL is similar to the one in Figure 8-30. Be sure to point to a remote server and not localhost.

12.In the Warning window, click Add to Project and click Yes to All. 13.In the Web Service panel (Figure 8-31), in the Select a method field, ensure that the following method is displayed: findFlights(com.ibm.flight400.beans.FINDFLIGHTSInput) Click Next.

Figure 8-31 Adding a Web service

14.In the Input Form panel, accept all default selections and click Next.

192 IBM System i Application Modernization: Building a New Interface to Legacy Applications 15.In the Results Form panel (Figure 8-32), click the ... button next to the Multi-Column Data Tab field.

Figure 8-32 Reviewing the output parameters

Chapter 8. Designing a JavaServer Faces-based interface 193 16.In the Insert JavaBean window (Figure 8-33), you may rearrange the sequence of fields by clicking the up and down arrows. You may also modify the label for each field to make it more readable. Click Finish.

Figure 8-33 Output fields

194 IBM System i Application Modernization: Building a New Interface to Legacy Applications 17.Back in the Results Form panel, click Finish. Figure 8-34 shows how your new page should look.

Figure 8-34 Generated JSF page

18.Press Ctrl+S to save the generated JSF page. 19.Test the JSF. a. In the Project Explorer panel, expand your JSF project → WebContent folder. b. Right-click the generated JSF page and select Run → Run on Server. c. Accept the default WebSphere v6.0 Server and click Finish. d. When the JSF page is displayed in the browser, test it by using the following sample parameter values: • From City: Albany • To City: Atlanta • Departure Date: 05162005

Chapter 8. Designing a JavaServer Faces-based interface 195 The browser should now display a page similar to the example in Figure 8-35.

Figure 8-35 Testing the JSF page in a browser

8.6 What is next

In this chapter, we have only just begun showing you what the JSF framework offers. While the JSF framework offers much more, it is not the purpose of this book to demonstrate each technology in depth.

If you think that the JSF framework is a good fit for your IT environment, allocate some time to gain the required level of skills. IBM offers many ways for you to learn this technology: WebSphere Development Studio Client online help IBM Redbooks Workshops Online courses Articles, tips, and other technical resources on the Web

In addition to the IBM Redbook, WebSphere Studio 5.1.2 JavaServer Faces and Service Data Objects, SG24-6361, which we have recommended throughout this chapter, review the available technical resources (by searching for JSF) on the developerWorks Web site at: http://www-128.ibm.com/developerworks/java

196 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 9. Designing a portlet client

In this chapter, we provide an overview of the portal server, its technology, and business benefits of enabling portal framework in your company. We illustrate the portal application development process by using a simple example.

Think about all the applications that you need to launch to get started every morning. You have many user IDs and passwords to remember, and you look at all the various places to obtain the data that you need. For example, you have to check your e-mail, review the day’s agenda to check for your appointments, review the sales figures of your sales personnel, read the company news to see if there were any major changes, look at how the stock market is doing, and so one. Think about the valuable time you lose by opening every single application separately to obtain all that information.

It would be nice to have all that information on one screen when you start your computer. You can have all different kinds of applications and information integrated on one screen, all with the same common presentation artifacts and only one user ID and password, even when all these different applications and data are located on different systems. You can create such a framework on your own, but to build a sound framework, you must spend a lot of time and money. A much better solution is to deploy a portal server with its rich set of functions, extended customization, and support for the industry standards.

9.1.1 More technical definition of a portal server To fully understand the benefits of a portal server, we describe a list of qualities that each portal server should demonstrate. By definition, a portal should provide the following features: Single sign-on (SSO) SSO allows authorized individuals to log on to multiple portal applications at one time without the need to remember multiple IDs and passwords and to sign on to each application individually. Common presentation This feature enables the same look and feel for all different applications integrated into a portal environment. Application and information integration The main task of a portal is to aggregate different applications into a single user interface with a common look and feel for the portal user. Collaborative capabilities A portal should provide access to the applications such as e-mail, calendar, instance messaging, Web Conferencing, team documents, and so on. Personalization and customization A portal should support sophisticated personalization features that allow users to customize the layout of the page, its content, and the look and feel that appeals to a user. A framework for Web services Web services provide interoperability between various software applications running on multiple platforms. A portal should provide support for consuming Web services. For more information about Web services, see Chapter 7, “Designing a Web services interface” on page 119.

Support for pervasive devices A further business-driven requirement of portals is to support not only the workstation-based user interface, but also the array of pervasive devices such as personal digital assistants (PDAs), mobile phones, and others.

198 IBM System i Application Modernization: Building a New Interface to Legacy Applications Document Management This feature allows portal users to store, view, edit and share documents with others. It enables them to implement a workflow process, which facilitates the management of the team’s document exchange. The workflow process also enables a structured method for document approval. In short, a portal is a single point of personalized interaction with applications, content, processes and people. It integrates and unifies access to a company’s data, applications, and content repositories.

9.2 Business reasons for implementing a portal server

By implementing a portal server in your environment, your company can achieve the following business benefits: Increase employee productivity By providing the most essential business data and applications in a single user interface, you enable your employees to access important information quicker and easier. This also leads to the next benefit. Quicker response to customer inquiries As a vivid example of the portal benefits, consider the click-to-action feature. By using this feature, you connect two or more applications (portlets) inside your portal environment. A change in the state of one application results in a corresponding change in another application. For example, you deploy a portal application with one of the pages that contains customer lookup, customer information, customer orders, and order information portlets, all on a single page. Then a support specialist receives a phone call from a customer with an enquiry about one of the orders. During the customer call, the support person looks up this customer by the name. When the lookup portlet returns the result, all other portlets on the same page are updated with the relevant information about this customer, including the customer profile and customer orders. Therefore, your support person is able to answer most of the customer’s enquiries without loading and using other applications. Increased efficiency through automation By integrating multiple relevant applications and data in a single portal environment, you can explore the portal’s capability to develop workflow solutions that reduce the human-related delays and mistakes, while allowing you to automate the parts of your (or the entire) company’s business processes. This factor has been chosen by companies’ CIOs as one of the key differentiators for implementing portal. Improve decision making Good decision making is based on getting the right information at the right time. This is where the portal server excels.

As the result of these benefits, your company will gain a competitive advantage by increasing customer satisfaction and lowering operating cost.

Chapter 9. Designing a portlet client 199 9.3 Overview of portal technology

Portals are Web sites that serve as a starting point to information and applications on the Internet or from an intranet. Early Internet portals, such as Yahoo, Excite, and Lycos, categorized Web content and provided search facilities. Over the years, portals have evolved to provide aggregation of content from diverse sources, such as rich text, video, or XML, and personalized services, such as user customization of layout and content.

To accommodate the aggregation and display of such diverse content, a portal server must provide a framework that breaks the different portal components into portlets. Each portlet is responsible for accessing content from its source (for example, a Web site, database, or E-mail server) and transforming the content so that it can be rendered to the client. In addition, a portlet might be responsible for providing application logic or storing information associated with a particular user. The portal server provides a framework of services to make the task of writing and managing portlets easier.

From user’s perspective, a portlet is a window in the portal that provides a specific service or information, such as a calender or news feed. From an application development perspective, portlets are pluggable modules that are designed to run inside a portlet container of a portal server.

The portlet container provides a runtime environment on which portlets are instantiated, used, and finally destroyed. Portlets rely on the portal infrastructure to access user profile information, participate in window and action events, communicate with other portlets, access remote content, look up credentials, and store persistent data. The Portlet application programming interface (API) provides standard interfaces for these functions. This portlet container is not a stand-alone container like the servlet container. Instead, it is implemented as a thin layer on top of the servlet container and reuses the functionality provided by the servlet container.

As with any other Web design, the portlet design principle is also based on the model-view-controller (MVC) pattern. For a detailed description about MVC, see 6.1, “Model view controller” on page 114.

200 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9.3.1 Portal pages and portlets Figure 9-1 shows the basic portal page components. The portal page represents a complete markup document and aggregates several portlet windows; that is, it combines different application user interfaces into one unified presentation. The portal page lets the user authenticate to the portal through the login dialog to access a personalized portal view. Most portal pages include some navigation mechanism to enable the user to navigate to other portal pages. A portlet window consists of the following components: Title bar, with the title of the portlet Decorations, including buttons to change the window state of the portlet (such as maximize or minimize the portlet) and buttons to change the mode of a portlet (such as show help or edit the predefined portlet settings) Content produced by the portlet, which is also called a markup fragment The markup fragment produced by the portlet is not restricted to HTML, but can be any markup.

Navigation Sign in portlet

Portlets

Figure 9-1 Portal page

Chapter 9. Designing a portlet client 201 9.3.2 Basic portal architecture Figure 9-2 illustrates the basic architecture of portals, such as a portal that is served by WebSphere Portal. A client request is processed by the portal Web application, which retrieves the portlets on the current page for the current user. The portal Web application then calls the portlet container for each portlet to retrieve its content through the Container Invoker API. The portlet container calls the portlets through the Portlet API. The Container Provider Service Provider Interface (SPI) enables the portlet container to retrieve information from the portal.

The portlet container runs the portlets, provides them with the required runtime environment, and manages their life cycle. It provides persistent storage for portlet preferences, which enables the portlet to produce customized output for different users.

Figure 9-2 Basic portal architecture

9.3.3 Portlet API - JSR 168 Java Standardization Request 168 (JSR 168) is the industry standard for developing portlets. The JSR 168 defines a portlet specification, including a contract between the portlet container and the portlet. It is defined by the Java Community Process (JCP).

The JSR 168 was co-led by IBM and Sun and had a large Expert Group that helped to create the final version, which is now available. This Expert Group consisted of Apache Software Foundation, Art Technology Group (ATG) Inc., BEA, Boeing, Borland, Citrix Systems, Fujitsu, Hitachi, IBM, Novell, Oracle, SAP, SAS Institute, Sun, Sybase, Tibco, and Vignette. You can find more details about this JSR on the Web at: http://jcp.org/en/jsr/detail?id=168

9.4 IBM WebSphere Portal Server

IBM WebSphere Portal is a middleware platform that provides a single point of interaction with dynamic information, applications, processes and people to help build business-to-employee (B2E), business-to-business (B2B), and business-to-customer (B2C) portals. It supports a wide variety of pervasive devices that enable them to interact with portal anytime, anywhere, using any device, wired or wireless.

202 IBM System i Application Modernization: Building a New Interface to Legacy Applications IBM WebSphere is used to build and deploy a portal. Through the portal, you can provide business applications, content, workflow, and people awareness to your customers, employees, business partners, trading partners, and suppliers. You can customize or personalize the interface to fit each audience segment or individual users. You can make this portal an effective, collaborative work area for all your users.

You can use its many services, tools, and add-ons to continually extend the functionality of your portal. For example, you can integrate content from other Web sites and enterprise applications, using portlets that are included with the initial product installation (called “out-of-the-box portlets”). You can publish portlets as remote Web services and integrate remote portlets into your portal. Having such a comprehensive, manageable work environment can reduce your overall costs and give your business a competitive edge. For example, if you enter a city name in a local news portlet to retrieve the highlight of the local news, another portlet can use the same city name to display the local weather information.

IBM sells several editions of the WebSphere Portal Server that target different customer segments. All editions provide the same core features, but differ in the support of the advanced features.

Portlet developers create portlets, which comprise the various sections of portal pages. These developers use Rational Tools and Portal Toolkit to develop the portlets. They can also download hundreds of portlets from the WebSphere Portal and Lotus Workplace Catalog. For more information, see “Out-of-the-box portlets” on page 204.

Figure 9-3 shows a high level view of the WebSphere Portal architecture. Technically, WebSphere Portal Server is a set of Web applications that run in WebSphere Application Server. If you have WebSphere Application Server expertise, it reduces the learning curve for WebSphere Portal Server. As shown in Figure 9-3, WebSphere Application Server provides a solid foundation for deploying WebSphere Portal Server.

Figure 9-3 WebSphere Portal provides many services of all types of portals

Chapter 9. Designing a portlet client 203 For more information about IBM WebSphere Portal, see the following Web site: http://www-128.ibm.com/developerworks/websphere/zones/portal/

Out-of-the-box portlets Out-of -the-box portlets are ready-to-use portlets that come with WebSphere Portal. These portlets are included with the initial product installation, so you can integrate content from other Web sites and enterprise applications. Here is an overview of some of the out-of-the-box portlets: Preconfigured, compelling portlet content, ready to use – Administrative: Reminders, bookmarks – Collaboration: People finder, QuickPlaces, e-meeting, mail – Finances: Financial calculators, currency converters, company tracker – Newsroom: Financial times, Pinnacor – Productivity: WorldClock, IBM Internet mail, MS Netmeeting, MS Exchange client, ToDo list – Portlet Catalog http://catalog.lotus.com/wps/portal/portal Document management, approval and versioning – Portal Document Manager (PDM) Lightweight editors for presentations, spreadsheets, rich text documents – Productivity Components Portal-based collaboration – Collaboration Center Basic content publishing – Web clipping – Document viewer – iSeries Access for Web portlets Integration of back-end data sources and applications – JDBC™ Builder and Domino® Builder – HATS portlet (comes as part of iSeries Access for Web portlets) – WebFacing portlet IBM Lotus Notes/Domino and extended product portlets – Domino Web Access (formerly iNotes™) – Domino applications – Lotus Domino – Lotus Domino Document Manager (formerly Lotus Domino.Doc®) – Lotus Notes® Discussion – Lotus Notes Mail – Lotus Notes Teamroom – Lotus Notes View – Lotus Sametime® – Lotus QuickPlace® – My Lotus Notes To Do – People Finder – Sample pages

204 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9.4.1 IBM WebSphere Portal for iSeries IBM WebSphere Portal allows people to interact with the on demand world in a personalized way. They can automatically obtain the dynamic information they need. They can quickly execute business processes across critical applications. They can collaborate with portal users inside and outside your On Demand Business. By providing these industry-leading portal solutions for your On Demand Business, IBM helps you improve employee productivity, cut costs, and strengthen relationships with your customers and trading partners.

WebSphere Portal Express and Express Plus offer IBM eServer iSeries clients a great way to integrate existing, as well as new applications, into a robust, reliable, and scalable portal environment on the iSeries server. Clients who implement WebSphere Portal Express can provide a single, personalized interface for employees (B2E), suppliers (B2B), and consumers (B2C).

Using iSeries Access for Web, iSeries clients can take the first step with their portal integration plans by portal-enabling 5250 applications. Over time, clients will be able to improve end-user satisfaction and productivity, increase revenue, and reduce the complexities of integrating multiple solutions from IBM and IBM Business Partners.

The latest offering from IBM is WebSphere Portal Version 6.0.

WebSphere Portal Version 6.0 WebSphere Portal Version 6.0 is an enterprise portal solution for organizations that are seeking to improve the effectiveness of their operations. WebSphere Portal is the industry’s leading portal platform because it delivers a complete set of portal platform services with the dependability and scalability demanded by top global companies. New features and improvements can help you to quickly deploy powerful portal applications that can be customized to meet changing business requirements.

WebSphere Portal Version 6.0 consists of three offerings: WebSphere Portal Server WebSphere Portal Enable WebSphere Portal Extend

WebSphere Portal rationalizes and simplifies IT infrastructure by delivering a complete set of portal platform services: Framework services Integration services Content services Collaboration services

These services can be leveraged by WebSphere Portlet Factory Designer to build role-based, portal applications that can help improve the effectiveness of your organization. Because WebSphere Portal uses a service-oriented architecture (SOA), these applications can use existing assets and can be modified quickly to meet changing roles and business conditions.

Chapter 9. Designing a portlet client 205 To meet your requirements, WebSphere Portal Version 6.0 is available in three offerings with the following features: WebSphere Portal Server – Core portal services aggregates applications and content from across your organization and delivers role-based applications for your employees, partners, or customers. – Search services crawl an index portal and Web site content so that users can easily find the information they need via simple queries. New search capabilities in V6.0 include the ability to run multiple search services, an improved search portlet interface, and better search ability from external search engines. – Personalization delivers information to users based on the role in the organization or specific business rules. Therefore, you see information that changes dynamically based on business data. In Version 6.0, the personalization rules can be used to control the portlets that are shown on a page or the navigation of the portal pages. – Security features provide basic SSO capability and fine grained access to control to all portal resources and enterprise assets surfaced by WebSphere Portal. – You can use hundreds of portlets from IBM and IBM Business Partners to access applications, databases, e-mail systems, and more. These portlets are either included with the package or are available for download from the WebSphere Portal Catalog on the Web at: http://catalog.lotus.com/wps/portal/portal/ – WebSphere Portlet Factory and WebSphere Portlet Factory Designer, which are included with a restricted license, provide the ability to quickly build and deploy powerful portlets from your existing applications and information. These portlets become components that can be reused in multiple composite applications, which can help your IT staff save time and deliver new capabilities faster. – Application templates allow composite portal applications to be deployed to different communities, which can then modify aspects of the application to suit their specific needs. WebSphere Portal Enable Includes all the features of WebSphere Portal Server plus: – Document Manager is enhanced so that your users can easily share, view, and organize files of all types ranging from documents to spreadsheets within the portal community. It provides category subscription services, simple approval processes for file contribution, versioning so that you can track the evolution of a piece of content, and access control for managing viewing privileges of different content items. New in V6.0 is the ability to access the portal document repository directly from Microsoft Windows Internet Explorer and Microsoft Office applications. – IBM Workplace Web Content Management™, which is included with a restricted license for portal use, helps to reduce implementation time and costs by placing content creation and management firmly in the hands of content experts for “author once, publish everywhere” control. The end result is that you can keep content on your portal more accurate and can update it more frequently.

– Portal workflow helps you present the tasks that are necessary to complete as well as the right information you need to make accurate decisions quickly. Portal applications can use the workflow services to present information in the context of a given task so you can be more productive.

206 IBM System i Application Modernization: Building a New Interface to Legacy Applications WebSphere Portal Extend This feature includes all the same features of WebSphere Portal Server and WebSphere Enable plus: – Workplace Forms™, with a restricted license for portal use, allows your employees, customers, and partners to store, view, and complete electronic forms from the portal interface. – Lotus Sametime, with a restricted license for portal use, provides portal users with the ability to start instant messaging in the context of a business process. By clicking a user’s name in a portlet, they can tap into knowledge of their associates or ask a question of a customer services representative. – Lotus QuickPlace, with a restricted license for portal users, lets you create security-rich workspaces within your portal site, providing them with a “place” to coordinate, collaborate, and communicate on any project or ad hoc initiative.

For more information about the latest release of WebSphere Portal Server, go to the following Web address: http://www.ibm.com/software/genservers/portalserver/

9.4.2 Creating portlets that access iSeries applications and data In the following sections, we describe three options for creating portlets that access iSeries applications and data: Developing portlets with iSeries Tools Creating portlets using portlet builder tools Writing custom portlets

Developing portlets with iSeries Tools IBM WebFacing Tool, Host Access Transformation Services (HATS), and iSeries Access for Web are three IBM products that can be used to create iSeries-specific portlets without Java programming.

IBM WebFacing Tool converts existing 5250 interfaces to Web applications. In IBM WebFacing Tool, the wizard takes you through the process to create a portlet project. The only required input for the WebFacing wizard is the selection of the data description specifications (DDS) sources. After the conversion, you can modify the WebFacing portlets, like you can customize any other regular WebFacing application. The WebFacing portlets can be configured to provide SSO capability. Therefore, when the user has logged into a portal, they do not have to log in to their iSeries applications displayed in the WebFacing portlet. The IBM WebFacing Tool is a part of the WebSphere Studio Development Client for iSeries. For more information, see “The IBM WebFacing Tool” on page 67.

HATS is a Web-to-host transformation engine. It performs a real-time conversion of the iSeries green-screen application to a Web application. When you are developing HATS applications, you can select if you want to create a portal application. You can use the default settings of the wizard for creating your portlet, or you can create a portlet with a high level of customization. With the high level customization, you can combine several green screens on one page or include improved navigation.

HATS also provides an SSO feature, as WebFacing portlets do. However, with HATS, you can also implement Click-to-Action features of the portlet API. It gives you the ability to send information from one portlet to another. HATS Toolkit is a plug-in to the Rational development tools. For more information, see “Host Access Transformation Services” on page 25.

Chapter 9. Designing a portlet client 207 The iSeries Access for Web product provides portlets for using in the WebSphere Portal Server on iSeries. Most functions that are available in the product are also available in iSeries Access for Web portlets, such as the 5250 portlet, commands portlet, database tables, SQL portlets, integrated file system portlets, and printer portlets.

Portlet builders The portlet builder wizards are provided to build your portlets without Java programming. You have IBM portlet builders such as JDBC Portlet Builder that are a part of WebSphere Application Portlet Builder. The JDBC Portlet Builder provides a template for dynamically building portlets that access iSeries data. Other WebSphere Application Portlet Builder portlet builders are PeopleSoft Portlet Builder, Sieble Portlet Builder, SAP Portlet Builder, Portlet Builder for Domino, and WPCP Portlet Builder. You can also find solutions from independent software vendors (ISV).

Writing custom portlets To develop a portlet “from scratch” requires the programming knowledge of Portlet API and several other specifications. Customizing the portlet is similar to JavaServer Pages (JSP) or Servlets development. A portal is a type of a Web application, so it also uses the MVC design pattern. For more info on MVC design pattern, see 6.1, “Model view controller” on page 114.

The Rational platform is the best development tool for programming a portal interface. WebSphere Development Studio Client includes the Portal Toolkit that enables iSeries developers to start programming the portlets.

9.5 Prerequisites for using IBM WebSphere Portal

WebSphere Portal Server is the advanced deployment environment that requires a significant investment into the hardware and development skills. In this section, we demonstrate some of the hardware requirements and point to the online documentations where you get up-to-date information about hardware and software prerequisites.

9.5.1 Development requirements During the development phase, you must use the appropriate tools to develop your portlets. You need the Portal Development Environment. The Portal Development Environment is integrated in WebSphere Development Studio Client Advanced Edition V5.1.2 and in V6.0. For the hardware and software requirements for WebSphere Development Studio Client V6.0, see “Development requirements” on page 69.

9.5.2 iSeries hardware and software requirements for deployment To deploy your portlets, you need WebSphere Portal Server. A portal server comes with WebSphere Portal for iSeries.

You can use the IBM Systems Workload Estimator for help with sizing all system configurations. You can find the Workload Estimator on the Web at:

http://www-912.ibm.com/supporthome.nsf/document/16533356

Note: Systems that do not meet the recommended minimums can be used in environments that support a limited number of users and where longer server initialization times can be tolerated. However, we do not recommend this.

208 IBM System i Application Modernization: Building a New Interface to Legacy Applications In general, your system should have the following requirements at a minimum: Processor: You need a processor with at least 750 CPW. Production environments should consider servers with a higher CPW rating. Physical memory: You need at least 2 GB of physical memory per server instance, although production environments require more memory. Disk space: You need 3.5 GB free disk space and 750 MB for temporary space. These values are required if you use the installation program to install WebSphere Application Server, extensions and fixes, and WebSphere Portal. These values do not account for any other products or components that can be installed on the WebSphere Portal machine.

For current information about System i hardware requirements, refer to the following Web site: http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html

When you reach this site, select the corresponding tab for your version of WebSphere Portal Server and click the Hardware and software requirements link.

9.5.3 Required skills The following skills and knowledge are required when developing portlets: Knowledge of the WebSphere Development Studio Client development environment Java programming skills Web development skills including HTML and XML A basic understanding of Java 2 Platform, Enterprise Edition (J2EE) technology Web application server and WebSphere Portal skills

9.6 Portlet example

In this section, we demonstrate the development steps for creating and testing a sample portlet. The sample portlet uses under the cover the program call to invoke an RPG application. We use the FLGHT400 RPG application in this example. For the complete set of instructions about developing portlets and using the development tool, refer to the IBM Redbook IBM Rational Application Developer V6 Portlet Application Development and Portal Tools, SG24-6681.

Chapter 9. Designing a portlet client 209 The sample application user interface prompts the user to input origination city, destination city, and a flight date. The portlet returns the list of matched flights as shown in Figure 9-4.

Figure 9-4 Result view

This example demonstrates the following steps: 1. Creating your project 2. Creating the ProgramCall JavaBean 3. Modifying the session bean, JSP, and portlet 4. Testing your portlet

Important: Make sure that you have installed the WebSphere Portal v5.0 Unit Test Environment (UTE), which is included on a separate CD in your WebSphere Development Studio Client media bundle. Verify that you have installed the latest updates and features from the IBM Rational Product Updater.

9.6.1 Creating a project To create a project that holds all application components: 1. Start the WebSphere Development Studio Client Advanced Edition for iSeries 6.0. From the Windows desktop, click Start → All Programs → IBM Rational → IBM WebSphere Development Studio Client Advanced Edition for iSeries V6.0 → WebSphere Development Studio Client Advanced Edition for iSeries. 2. In the window that opens, specify the directory for your workspace. This is where all your work will be stored. We recommend that you specify a new directory on the C: driver, for example C:\PortalProject. Then click OK. 3. If this is the first time you access this workspace, you see the Welcome page. Click the X button on the Welcome tab to close this Welcome page. 4. Select Window → Open Perspective → Other to open the Web perspective.

210 IBM System i Application Modernization: Building a New Interface to Legacy Applications 5. Select Web and click OK. 6. In the Project Explorer view (Figure 9-5), right-click Dynamic Web Project and select New → Project.

Figure 9-5 Creating a new Dynamic Web Project

7. In the Select a wizard panel (Figure 9-6), select Portlet Project (JSR 168) and click Next.

Figure 9-6 Selecting the Portlet Project (JSR 168)

Chapter 9. Designing a portlet client 211

Note: When creating portlet applications with the Portal Toolkit, you have the option to create either JSR 168 or IBM Portlet API portlets. JSR 168 is the industry standard for

developing portlets. We recommend that you develop new portlets in JSR 168.

8. If the Confirm Enablement window (Figure 9-7) opens, click OK.

Figure 9-7 Confirm Enablement window

212 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9. In the Portlet Project (JSR 168) panel (Figure 9-8), complete the following actions: a. For name, type PortletProject. b. For WebSphere Portal version, select 5.0.

Note: We select WebSphere Portal Version 5.0 because we test our application for WebSphere Portal version 5.0. If your application runs in WebSphere Portal Version 5.1, keep the default value.

c. Click Next.

Figure 9-8 Entering the portlet project name

10.In the next panel, for Portlet type, verify that Basic portlet is selected and click Next. 11.In the next panel, for the features, keep the default values and click Next.

Chapter 9. Designing a portlet client 213 12.In the Portlet Settings panel (Figure 9-9), complete the following actions: a. For Portlet name, type PortletProject. b. For Display name, type Flight Lookup. c. Select the Change code generation options check box and enter the following values: i. For Package prefix, type com.ibm.flight400.portlets. ii. For Class prefix, type Flight400Portlet. d. Click Next.

Figure 9-9 General settings of the project

214 IBM System i Application Modernization: Building a New Interface to Legacy Applications 13.In the Action and Preferences panel (Figure 9-10), select the Add action request handler and Add form sample check boxes. Then click Next.

Figure 9-10 Action and Preferences panel for action handling

14.In the Miscellaneous panel, click Finish.

After your project is created, PortletProject appears under Dynamic Web Projects, and the Flight400PortletView.jsp is displayed as shown in Figure 9-11.

Figure 9-11 After creation of the project

Chapter 9. Designing a portlet client 215 9.6.2 Creating the ProgramCall Java beans The next step is to create a JavaBean that wraps the RPG program call, which we have already explained. Go to “Creating the ProgramCall JavaBean” on page 129 and perform all the steps in that section with a few modifications:

Use the workspace that you created for PortletProject; do not create a new workspace. Skip step 12 on page 133 because you have already created a Web project. Replace the WebSvc project name with PortletProject.

By this end of this exercise, you should have a JavaBean that calls the RPG service program.

9.6.3 Modifying the portlet source code You have created a portlet Web project using the steps in 9.6.1, “Creating a project” on page 210. Two Java packages and several files have been generated by the wizard. We are interested in three of them, which are highlighted in Figure 9-12.

Figure 9-12 Generated files

We need to modify these files so that we are able to: Capture the input information from a user (such as date and to and from city) Invoke the ProgramCall JavaBean that, in turn, invokes the RPG service program Display returned results

216 IBM System i Application Modernization: Building a New Interface to Legacy Applications SessionBean We modify the source code for the Flight400PortletSessionBean.java. This bean is used by Flight400PortletView.jsp to pass input/output parameters to and from the Flight400Portlet class: 1. Open the Web perspective. Select Window → Open Perspective → Other → Web. Then click OK. 2. Expand Dynamic Web Projects → PortletProject → JavaSource → com.ibm.flight400.portlets as shown in Figure 9-12. 3. Double-click Flight400PortletSessionBean.java. 4. Delete all code in the Flight400PortletSessionBean.java file. 5. Type or copy and paste the code shown in Example 9-1.

Example 9-1 Source code for the session bean class package com.ibm.flight400.portlets;

/** * * A sample Java bean that stores portlet instance data in portlet session. * */ import com.ibm.flight400.beans.*;

public class Flight400PortletSessionBean {

//Input parameters private String fromCity = ""; private String toCity = ""; private String date = "";

//Outpu parameter private FINDFLIGHTSResult results = null; }

6. Press Ctrl+S to save the file. 7. Right-click somewhere in the code and select Source → Generate Getters and Setters. 8. In the window that opens, click Select All and click OK.

Now the file contains the source code shown in Example 9-2.

Example 9-2 Flight400PortletSessionBean.java package com.ibm.flight400.portlets;

/** * * A sample Java bean that stores portlet instance data in portlet session. * */ import com.ibm.flight400.beans.*; public class Flight400PortletSessionBean {

//Input parameters private String fromCity = ""; private String toCity = "";

Chapter 9. Designing a portlet client 217 private String date = ""; //Outpu parameter private FINDFLIGHTSResult results = null;

/** * @return Returns the date. */ public String getDate() { return date; } /** * @param date The date to set. */ public void setDate(String date) { this.date = date; } /** * @return Returns the fromCity. */ public String getFromCity() { return fromCity; } /** * @param fromCity The fromCity to set. */ public void setFromCity(String fromCity) { this.fromCity = fromCity; } /** * @return Returns the results. */ public FINDFLIGHTSResult getResults() { return results; } /** * @param results The results to set. */ public void setResults(FINDFLIGHTSResult results) { this.results = results; } /** * @return Returns the toCity. */ public String getToCity() { return toCity; } /** * @param toCity The toCity to set. */ public void setToCity(String toCity) { this.toCity = toCity; } }

218 IBM System i Application Modernization: Building a New Interface to Legacy Applications Modifying the JSP Update the JSP so the user can enter the input parameters and see the results: 1. Expand Dynamic Web Projects → PortletProject → WebContent → com_ibm_flight400_portlets → jsp → html.

2. Double-click Flight400PortletView.jsp (see Figure 9-12 on page 216). 3. In the editor view, click the Source tab. 4. Change your source to look like the file in Example 9-3. The code that you must modify is in bold.

Example 9-3 JSP file <%@ page session="false" contentType="text/html" import="java.util.*,javax.portlet.*,com.ibm.flight400.portlets.*,com.ibm.flight400.beans.*" %> <%@taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

<% Flight400PortletSessionBean sessionBean = (Flight400PortletSessionBean)renderRequest.getPortletSession().getAttribute(Flight400Portlet.SESSION_BEAN); %>

Flight Lookup

<% /******** End of sample code *********/ %>

5. Click the Preview tab. Your JSP should look like the example in Figure 9-13. You should see several errors in the JSP file. We will fix them after we modify the portlet class.

Figure 9-13 Preview of Flight400PortletView.jsp

220 IBM System i Application Modernization: Building a New Interface to Legacy Applications Invoking the ProgramCall bean Update the portlet to invoke the RPG JavaBean and save the results in the session bean: 1. Expand Dynamic Web Projects → PortletProject → JavaSource → com.ibm.flight400.portlets as shown in Figure 9-12 on page 216.

2. Double-click Flight400Portlet.java. 3. Replace the code in the source code with the one shown in Example 9-4. The updates are shown in bold. These are the explanations for the highlighted code segments: 1 Add three imports for the additional classes that we use in the portlet. 2 Define three String constants for the input field names. 3 Add the code to invoke the ProgramCall JavaBean passing the input parameters from the session bean. The results are saved in the session bean.

Example 9-4 The portlet class source code package com.ibm.flight400.portlets; import java.io.*; import javax.portlet.*; import com.ibm.flight400.beans.FINDFLIGHTSInput; import com.ibm.flight400.beans.FINDFLIGHTSResult; kkkkkkkkkkkkkkkkkkkkkkkkkkkkk1 import com.ibm.flight400.beans.GETFLIGHTINFOServices;

/** * * A sample portlet based on GenericPortlet * */ public class Flight400Portlet extends GenericPortlet {

public static final String JSP_FOLDER = "/com_ibm_flight400_portlets/jsp/"; // JSP folder name

public static final String VIEW_JSP = "Flight400PortletView"; // JSP file name to be rendered on the view mode

public static final String SESSION_BEAN = "Flight400PortletSessionBean"; // Bean name for the portlet session

public static final String FORM_SUBMIT = "Flight400PortletFormSubmit"; // Action name for submit form public static final String FORM_TEXT = "Flight400PortletFormText"; // Parameter name for the text input

public static final String TEXT_FROMCITY = "FromCity"; public static final String TEXT_TOCITY = "ToCity"; ccccccccccccccccccccccccccccc2 public static final String TEXT_FLIGHTDATE = "FlightDate";

/** * @see javax.portlet.Portlet#init(javax.portlet.PortletConfig) */ public void init(PortletConfig config) throws PortletException{ super.init(config); }

/**

Chapter 9. Designing a portlet client 221 * Serve up the view mode. * * @see javax.portlet.GenericPortlet#doView(javax.portlet.RenderRequest, javax.portlet.RenderResponse) */ public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException { // Set the MIME type for the render response response.setContentType(request.getResponseContentType());

// Check if portlet session exists Flight400PortletSessionBean sessionBean = getSessionBean(request); if( sessionBean==null ) { response.getWriter().println("NO PORTLET SESSION YET"); return; }

// Invoke the JSP to render PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(getJspFilePath(request, VIEW_JSP)); rd.include(request,response); }

/** * Process an action request. * * @see javax.portlet.Portlet#processAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse) */ public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException { if( request.getParameter(FORM_SUBMIT) != null ) { // Invoke RPG program and save results

// Instantiate the ProgramCall bean GETFLIGHTINFOServices lookupService = new GETFLIGHTINFOServices();ccccccccccccccc3

// Create input object FINDFLIGHTSInput searchInput = new FINDFLIGHTSInput(); searchInput.setFROMCITY(request.getParameter(TEXT_FROMCITY)); searchInput.setTOCITY(request.getParameter(TEXT_TOCITY)); searchInput.setFLIGHTDATE(request.getParameter(TEXT_FLIGHTDATE));

// Invoke the program FINDFLIGHTSResult searchResult = lookupService.findflights(searchInput);

// set form text in the session bean getSessionBean(request).setResults(searchResult); } }

/** * Get SessionBean. * * @param request PortletRequest * @return BasicPortletSessionBean */ private static Flight400PortletSessionBean getSessionBean(PortletRequest request) { PortletSession session = request.getPortletSession(); if( session == null ) return null;

222 IBM System i Application Modernization: Building a New Interface to Legacy Applications Flight400PortletSessionBean sessionBean = (Flight400PortletSessionBean)session.getAttribute(SESSION_BEAN); if( sessionBean == null ) { sessionBean = new Flight400PortletSessionBean(); session.setAttribute(SESSION_BEAN,sessionBean); } return sessionBean; }

/** * Returns JSP file path. * * @param request Render request * @param jspFile JSP file name * @return JSP file path */ private static String getJspFilePath(RenderRequest request, String jspFile) { String markup = request.getProperty("wps.markup"); if( markup == null ) markup = getMarkup(request.getResponseContentType()); return JSP_FOLDER+markup+"/"+jspFile+"."+getJspExtension(markup); }

/** * Convert MIME type to markup name. * * @param contentType MIME type * @return Markup name */ private static String getMarkup(String contentType) { if( "text/vnd.wap.wml".equals(contentType) ) return "wml"; return "html"; }

/** * Returns the file extension for the JSP file * * @param markupName Markup name * @return JSP extension */ private static String getJspExtension(String markupName) { return "jsp"; }

}

Chapter 9. Designing a portlet client 223 9.6.4 Testing the portlet Before you deploy your portlet to the WebSphere Portal Server, you can test it in the WebSphere Portal Test Environment.

Note: Make sure that you installed the WebSphere Portal Unit Test Environment (UTE), which is included on a separate CD in your WebSphere Development Studio Client media bundle. Verify that you have installed the latest updates and features from the IBM Rational Product Updater.

1. Right-click your project name. In our example, this is PortletProject. Then select Run → Run on server. 2. In the Define a New Server panel (Figure 9-14), complete these actions: a. Select Manually define a server. b. Look for the WebSphere Portal Test Environment under Select the server type. We select the WebSphere Portal v5.0 Test Environment because this is the version we run on a production server. c. Click Finish.

Figure 9-14 Selecting your server to test the portlet on

224 IBM System i Application Modernization: Building a New Interface to Legacy Applications 3. When the test environment is started, your portlet application looks like the example in Figure 9-15. Complete the following input parameters as indicated: – From City: Atlanta – To City: Chicago – Flight Date: A date in the future (in format MMDDYYYY), for example 12122006 Click Submit.

Figure 9-15 Result after the test environment is started

Chapter 9. Designing a portlet client 225 The result should look like the example in Figure 9-16.

Figure 9-16 Result of your portlet

9.6.5 Deploying the portlet After you test your portlet application, deploy the WAR file of your portlet project to the WebSphere Portal server. Such an exercise is outside of the scope of this redbook. Therefore, we point you to the resources where you can find more information to deploy your application on a WebSphere Portal for Multiplatforms: V5.1.x http://publib.boulder.ibm.com/infocenter/wpdoc/v510/index.jsp?topic=/com.ibm.wp.ent.doc/ wpf/welcome.html V5.0.2 http://publib.boulder.ibm.com/pvc/wp/502/ent/en/InfoCenter/index.html V5.0 http://publib.boulder.ibm.com/pvc/wp/500/ent/en/InfoCenter/index.html

226 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9.7 Simple example of invoking a Web service

In this section, we explain how you can build a portlet that invokes a Web service. In general, this process is a combination of two tasks that we demonstrated in the previous sections: Generating a portlet application skeleton, as described in 9.6.1, “Creating a project” on page 210 Generating the Web service client Modifying generated code, similar to what we did in 9.6.3, “Modifying the portlet source code” on page 216

The basic idea in this process is to let WebSphere Development Studio Client generate as much code as it can. Then we modify the portlet’s source code using an intelligent copy-and-paste technique. We say intelligent because you need to apply basic Java programming skills to do that.

9.7.1 Generating the portlet project See 9.6.1, “Creating a project” on page 210, for the instructions to create such a project.

9.7.2 Generating a Web service client WebSphere Development Studio Client has a wizard that allows you to generate working code for invoking a Web service that runs on a remote system. Follow these steps: 1. Start WebSphere Development Studio Client and open the Web perspective. 2. Select File → New → Other. 3. Expand Web Services and select Web Service Client. Click Next (see Figure 9-17).

Figure 9-17 Starting the Web service client wizard

Chapter 9. Designing a portlet client 227

Note: If you are doing Web services development for the first time, you should not see the Web Service Client option. To enable Web services development, select the Web

Service option (at the top of the list) instead and click Next. The Confirm Enablement window (Figure 9-18) opens with a message asking if you want to enable Web Services development. Click OK.

After this, cancel the wizard and start it again. Now you should see the Web Service Client option.

Figure 9-18 Enabling Web service development

4. In the Web Services panel (Figure 9-19), select Test the Web service and click Next.

Figure 9-19 Selecting to generate the test code

228 IBM System i Application Modernization: Building a New Interface to Legacy Applications 5. In the next panel, enter the URL for the Web services Description Language (WSDL) file on the server. In our example, we point to the sample application that we built and deployed as part of the example in Chapter 7, “Designing a Web services interface” on page 119: http://rchas10:9080/WebSvc/wsdl/com/ibm/flight400/beans/GETFLIGHTINFOServices.wsdl Click Next. 6. In the Client Environment Configuration panel, complete these actions: a. Click the Edit button. We plan to deploy this code in the same test environment as our portlet. The J2EE level of WebSphere Portal V5.0 is V1.3. b. In the Client Environment Configuration window (Figure 9-20), for J2EE version, select 1.3, and for Server, select WebSphere Portal 5.0 Test Environment. Then click OK.

Figure 9-20 Selecting the proper J2EE level

Chapter 9. Designing a portlet client 229 c. Back in the Client Environment Configuration panel (Figure 9-21), select the existing project for the Client project field. d. Click Next.

Figure 9-21 Selecting the existing project

7. If you see a Warning message like the example in Figure 9-22, click Yes to All.

Figure 9-22 Warning message

8. Click Next again. 9. In the Web Service Client Test panel, click Finish. 10.The test client is generated and started in the WebSphere Portal V5.0 Test Environment. Close the Web browser and stop the server. We must make modifications to the code.

230 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9.7.3 Modifying the generated code Now we have generated most of the code. The first file that we modify is Flight400PortletView.jsp. The source code is shown in Example 9-3 on page 219.

Before we begin, we open the Result.jsp file under PortletProject → WebContent → sampleGETFLIGHTINFOServicesProxy. This file has been generated as part of the Web service client code. This file contains the code to invoke a Web service: 1. Find case 18 in the code. You may have a different number if you modified the list of available methods in the Web service. This is the part of the code that invokes the findflights function (see Example 9-5).

Example 9-5 Generated Web service client code ...... case 18: gotMethod = true; String tOCITY_3id= request.getParameter("tOCITY27"); java.lang.String tOCITY_3idTemp = tOCITY_3id; String fLIGHTDATE_4id= request.getParameter("fLIGHTDATE29"); java.lang.String fLIGHTDATE_4idTemp = fLIGHTDATE_4id; String fROMCITY_5id= request.getParameter("fROMCITY31"); java.lang.String fROMCITY_5idTemp = fROMCITY_5id; %> <% com1ibm1flight4001beans1FINDFLIGHTSInput_2id.setTOCITY(tOCITY_3idTemp); com1ibm1flight4001beans1FINDFLIGHTSInput_2id.setFLIGHTDATE(fLIGHTDATE_4idTemp); com1ibm1flight4001beans1FINDFLIGHTSInput_2id.setFROMCITY(fROMCITY_5idTemp); com.ibm.flight400.beans.FINDFLIGHTSResult findflights18mtemp = sampleGETFLIGHTINFOServicesProxyid.findflights(com1ibm1flight4001beans1FINDFLIGHTSInput_2id); if(findflights18mtemp == null){ %> <%=findflights18mtemp %> <% }else{ %> ......

2. Copy the source code from case 18 to the next if statement. We need this code to invoke the Web service. 3. Paste this code into the Flight400Portlet.java class under the processAction method and slightly modify it. This is where you need basic Java programming skills. Example 9-6 shows the modified source code, with the modified portions highlighted in bold.

Example 9-6 Flight400Portlet.java package com.ibm.flight400.portlets; import java.io.*; import javax.portlet.*;

/** * * A sample portlet based on GenericPortlet * */

Chapter 9. Designing a portlet client 231 public class Flight400Portlet extends GenericPortlet { public static final String JSP_FOLDER = "/com_ibm_flight400_portlets/jsp/"; // JSP

// folder // name

public static final String VIEW_JSP = "Flight400PortletView"; // JSP file

// name to be // rendered on // the view // mode

public static final String SESSION_BEAN = "Flight400PortletSessionBean"; // Bean

// name // for // the // portlet // session

public static final String FORM_SUBMIT = "Flight400PortletFormSubmit"; // Action

// name // for // submit // form

public static final String FORM_TEXT = "Flight400PortletFormText"; // Parameter

// name // for // the // text // input public static final String TEXT_FROMCITY = "FromCity";

public static final String TEXT_TOCITY = "ToCity";

public static final String TEXT_FLIGHTDATE = "FlightDate";

/** * @see javax.portlet.Portlet#init(javax.portlet.PortletConfig) */ public void init(PortletConfig config) throws PortletException { super.init(config); }

/** * Serve up the view mode. * * @see javax.portlet.GenericPortlet#doView(javax.portlet.RenderRequest, * javax.portlet.RenderResponse) */ public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException { // Set the MIME type for the render response response.setContentType(request.getResponseContentType());

232 IBM System i Application Modernization: Building a New Interface to Legacy Applications

// Check if portlet session exists Flight400PortletSessionBean sessionBean = getSessionBean(request); if (sessionBean == null) { response.getWriter().println("NO PORTLET SESSION YET"); return; }

// Invoke the JSP to render PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher( getJspFilePath(request, VIEW_JSP)); rd.include(request, response); }

/** * Process an action request. * * @see javax.portlet.Portlet#processAction(javax.portlet.ActionRequest, * javax.portlet.ActionResponse) */ public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException { if (request.getParameter(FORM_SUBMIT) != null) { com.ibm.flight400.beans.GETFLIGHTINFOServicesProxy sampleGETFLIGHTINFOServicesProxyid = new com.ibm.flight400.beans.GETFLIGHTINFOServicesProxy(); com.ibm.flight400.beans.FINDFLIGHTSInput com1ibm1flight4001beans1FINDFLIGHTSInput_2id = new com.ibm.flight400.beans.FINDFLIGHTSInput();

String tOCITY_3id = request.getParameter(TEXT_TOCITY); java.lang.String tOCITY_3idTemp = tOCITY_3id; String fLIGHTDATE_4id = request.getParameter(TEXT_FLIGHTDATE); java.lang.String fLIGHTDATE_4idTemp = fLIGHTDATE_4id; String fROMCITY_5id = request.getParameter(TEXT_FROMCITY); java.lang.String fROMCITY_5idTemp = fROMCITY_5id;

com1ibm1flight4001beans1FINDFLIGHTSInput_2id .setTOCITY(tOCITY_3idTemp); com1ibm1flight4001beans1FINDFLIGHTSInput_2id .setFLIGHTDATE(fLIGHTDATE_4idTemp); com1ibm1flight4001beans1FINDFLIGHTSInput_2id .setFROMCITY(fROMCITY_5idTemp); com.ibm.flight400.beans.FINDFLIGHTSResult findflights18mtemp = sampleGETFLIGHTINFOServicesProxyid .findflights(com1ibm1flight4001beans1FINDFLIGHTSInput_2id);

getSessionBean(request).setResults(findflights18mtemp);

} }

/** * Get SessionBean. * * @param request * PortletRequest * @return BasicPortletSessionBean */ private static Flight400PortletSessionBean getSessionBean( PortletRequest request) { PortletSession session = request.getPortletSession();

Chapter 9. Designing a portlet client 233 if (session == null) return null; Flight400PortletSessionBean sessionBean = (Flight400PortletSessionBean) session .getAttribute(SESSION_BEAN); if (sessionBean == null) { sessionBean = new Flight400PortletSessionBean(); session.setAttribute(SESSION_BEAN, sessionBean); } return sessionBean; }

/** * Returns JSP file path. * * @param request * Render request * @param jspFile * JSP file name * @return JSP file path */ private static String getJspFilePath(RenderRequest request, String jspFile) { String markup = request.getProperty("wps.markup"); if (markup == null) markup = getMarkup(request.getResponseContentType()); return JSP_FOLDER + markup + "/" + jspFile + "." + getJspExtension(markup); }

/** * Convert MIME type to markup name. * * @param contentType * MIME type * @return Markup name */ private static String getMarkup(String contentType) { if ("text/vnd.wap.wml".equals(contentType)) return "wml"; return "html"; }

/** * Returns the file extension for the JSP file * * @param markupName * Markup name * @return JSP extension */ private static String getJspExtension(String markupName) { return "jsp"; }

}

Most of the copied code stays as is. We only used the String constants for the input field names.

234 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Important: You can see some ugly variable names in the highlighted code. These are tool generated. As such, you may see different generated names in your environment

than the ones shown here.

4. Modify the Flight400PortletSessionBean.java in the same way we did in “SessionBean” on page 217. 5. Test your portlet as described in 9.6.4, “Testing the portlet” on page 224.

9.8 Links

The following links provide additional information about WebSphere Portal Server and portlet development: New to WebSphere Portal http://www-128.ibm.com/developerworks/websphere/zones/portal/newto/ Portlet Development Best Practices and Coding Guidelines http://www3.software.ibm.com/ibmdl/pub/software/dw/wes/pdf/PortletCodingGuidelines.pdf Portlet Development Guide ftp://ftp.software.ibm.com/software/webserver/portal/V41PortletDevelopmentGuide.pdf Comparing the JSR 168 Java Portlet Specification with the IBM Portlet API http://www-128.ibm.com/developerworks/websphere/library/techarticles/0312_hepper/ hepper.html WebSphere Portal Server documentation (all supported versions) http://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html

See also IBM WebSphere Portal Primer - Second Edition, ISBN 1-931182-23-X.

Chapter 9. Designing a portlet client 235

236 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 10. Designing a rich-client interface

A Web interface may not be suitable for all types of business applications. In this chapter, we discuss different rich-client technologies and explain how to build rich-client applications with Standard Widget Toolkit (SWT) and Eclipse Rich Client platform (Eclipse RCP).

Rich-client applications can serve as a user interface (UI) for modular RPG and COBOL applications and iSeries DB2 data. We explain design approaches and implementation design patterns that can be used for building such applications.

Rich client is a new term for fat client or “desktop” applications. The term fat client is used in contrast with thin client, which usually refers to browser-based applications. The new term, rich client, describes better, “richer” UI functionality of desktop applications compared to HTML-based applications that run in a browser. Rich-client applications can be written in several programming languages. Examples include Java, Microsoft Visual Basic® .Net, and Delphi.

One of the first decisions that you must make prior to creating a new user interface is the type of interface for the new application: rich client or browser. The following section describes the benefits and shortcomings of each UI type.

10.1.1 Rich client and thin client As shown in Figure 10-1, the main difference between rich-client and Web applications is physical application architecture. Both rich-client and browser-based applications have several logical application layers (presentation layer, business logic, database logic, and so on). In rich-client applications, the majority of application layers are deployed to the client system, while browser-based applications run on a server.

Figure 10-1 Rich-client and thin client application architecture

In most cases, the only difference between a rich-client and a browser-based application is the presentation layer. In browser-based applications, the presentation layer must be written in a technology that renders HTML (JavaServer Pages (JSPs), JavaServer Faces (JSFs), PHP, Active Server Page (ASP), and so on). The UI layer of a Web application consists of several Web pages. Rich-client applications consist of “forms” or “windows”. Rich-client technologies must render UI components directly to the operating system on which they are running

Business and database access logic can be implemented in a way that makes it usable from both rich-client and browser-based applications. The service-oriented architecture (SOA) is

238 IBM System i Application Modernization: Building a New Interface to Legacy Applications an example of an architecture for implementing business logic that can be used by different types of programs.

10.1.2 Advantages and disadvantages of rich-client technology

Migration of business applications to the Web was one of the key technology trends in the late 90s. The Web provided lower distribution and maintenance cost compared to rich-client applications, as well as lower client hardware requirements. However, the IT industry soon realized that the Web could not completely replace rich-client applications. In early 2000, several companies started working on rich-client technologies that would solve traditional shortcomings of rich-client applications. For example, IBM created WebSphere Everyplace® Deployment and Workplace Managed Client, products that have the functionality of a rich-client application and provide deployment and maintenance that is equivalent to Web applications.

Let us look at some advantages and shortcomings of Web and rich-client applications.

Rich-client applications offer the following main advantages over Web applications: “Richer” functionality – Browser-based applications are limited by HTML standards and components. – There are more components to choose from (grids, calendars, built-in editors). Better user experience – Menus, icons, more choices for application navigation – Ability to run multiple tasks at the same time (versus request and response implementation of Web applications) Better interoperability with other desktop applications Less workload on the server Better response time for some tasks

Rich-client applications have the following main disadvantages over Web applications: There are greater client system requirements than for Web applications. Depending on the technology chosen for rich-client application development, deployment and maintenance costs may be higher than for Web applications. Collecting and debugging user problems is more difficult in a rich-client application versus a Web application that runs on a server.

User requirements should be the deciding factor for a UI type. In most cases, users do not tell you which UI type they want, but they make statements that can help you make a decision, for example: I want to access my application from any PC (Web, portal). I need to give access to my application to users outside of my company (Web, portal). We need to have tight integration with office desktop applications (rich client). We need to provide wizards to assist with the application (rich client). We need to have a large number of input fields on one page (rich client).

Chapter 10. Designing a rich-client interface 239 10.1.3 Technology choices for implementing rich-client applications There are several technology and product choices for implementing rich-client applications. Most technologies offer similar functionality, but some of them will be a better fit for your application than others. When evaluating a rich-client technology, prepare a list of requirements and evaluate each technology according to each one of your requirements. The following is a sample list of requirements: Cost (development environment and runtime) Learning curve Open source versus proprietary Industry trends Maturity and stability Functionality Look and feel Ease of integration with iSeries applications and data Client system hardware requirements Ease of deployment Ease of maintenance

Java rich-client development options Java programmers have a choice of two graphical user interface (GUI) application programming interfaces (APIs) for developing rich-client applications: Swing and Standard Widget Toolkit. While some developers argue that Swing is a more comprehensive API, the majority of rich-client developers agree that both APIs provide equivalent functionality. Why do we need two APIs that do the same thing? The answer is simply in timing.

In early 2000, Swing, an API owned and developed by Sun Microsystems™, did not satisfy the needs of some developers in the Java community. Problems traditionally associated with early releases of Swing were look and feel and performance. Object Technology International, Inc. (OTI) developed its own GUI API, which they called Standard Widget Toolkit. OTI’s goal was to create an easy-to-use Java GUI API that would solve the shortcomings of Swing. OTI was acquired by IBM, and IBM donated SWT to open source. IBM needed SWT to build a new generation of development tools, which was named “Eclipse”. Today Eclipse is an open source project that serves as a foundation to IBM integrated development environments (IDEs), including Rational and WebSphere Studio tooling.

IBM has two Java GUI APIs today because Swing was ineffective when developers needed it. Sun Microsystems recently introduced a new release of Swing in Java 5.0. The new release of Swing solves many problems that prevented the success of earlier releases of Swing.

Swing and SWT have different implementation models. SWT relies on the operating system to perform GUI functions such as rendering of widgets and processing events. In the future, we will most likely see less and less visual and performance differences between Swing and SWT. We must look at factors beyond the implementation model to help you make a choice between the two APIs. Proprietary versus open source Swing is developed and owned by Sun Microsystems. SWT is an open source project. Both proprietary and open source technologies have advantages. Your decision should be made on your corporate technology strategy. Learning curve SWT is an easier API to learn for a novice Java programmer.

240 IBM System i Application Modernization: Building a New Interface to Legacy Applications Extending applications SWT is used to build Eclipse plug-ins and Eclipse RCP applications, which we cover later in this chapter. Eclipse RCP applications have several benefits over Swing applications, such as a better user interface, easier maintenance, and the ability to dynamically integrate new functionality via plug-ins.

The best way to decide which Java API is the right choice for your business applications is to have a prototype. With visual development tools, you can build a sample Swing or SWT application.

A closer look at SWT The main tasks of the application presentation layer are: Display windows that contain widgets Event handling (Events are keyboard and mouse actions generated by the user.) Application navigation

SWT is an API for implementing the presentation layer tasks. A window in SWT is called a shell. A stand-alone SWT application usually consists of a primary shell and several other modal or non-modal shells that can be opened from the main shell. SWT does not support Multiple Document Interface (MDI), but you can be creative in designing your SWT application to have the same functionality as MDI. A UI that supports MDI has a container window that displays a menu, a toolbar, and all other windows in an application.

Widgets are different controls that we interact with in a rich-client application. They include buttons, check boxes, radio buttons, text fields, lists, and so on. Several widgets can be combined together in a composite. An example of composite is a Group widget, which is an outlined box with a title that is used to display a group of related widgets. You can develop custom composites and reuse them across different SWT shells. Figure 10-2 shows sample SWT shells with widgets.

Figure 10-2 Sample SWT shells and widgets

Widgets have properties that you can set either at run time or design time. Properties such as text (caption) for a label or a button are most likely set at design time. At run time, you may want to modify such properties as “editable”, “visible”, and “items” (content of combo boxes and lists).

Chapter 10. Designing a rich-client interface 241 Shells and widgets can listen to one of more events. The most common events are different types of mouse clicks: single click, double click, right-click. You will find that there is no mouse click event in STW, simply because SWT uses different terminology. For most clickable widgets, widgetSelected is the event that is generated when a user clicks a widget. Other events that you may find useful in GUI application programming are:

Keyboard events: For example, you can capture keyboard strokes to add support for the Function (F) keys or to prevent users from typing alpha characters in a numeric-only field. Focus events: You can verify content of an input field on a lostFocus event or refresh the view when returning from a modal shell on the focusGained event.

Users navigate through a rich-client application by using menus, pop-up menus, tree controls, and events supported in different widgets. For example, if you have an SWT shell that displays a summary of records in a table, you can open a shell that displays record details with one of the following actions: Select a main menu item Select a pop-up menu item Double-click a row in the table of records

Development platform Eclipse IDE, an open source Java development tool, contains a sample SWT application. We recommend that you use the latest version of Eclipse IDE to run this sample, which is V3.1.2 at the time of writing. This sample is not shipped with WebSphere Development Studio Client.

You can download Eclipse IDE from the Web at the following address: http://www.eclipse.org

To run the application: 1. Open Eclipse IDE. 2. In the Welcome window, click Samples as shown in Figure 10-3. If the Welcome window is not displayed, you can open it by selecting Help → Welcome.

Figure 10-3 Eclipse Welcome window

3. In the next window, click the red round button under SWT as shown in Figure 10-4.

Figure 10-4 SWT Samples

242 IBM System i Application Modernization: Building a New Interface to Legacy Applications 4. In the Project names panel (Figure 10-5), click Finish.

Figure 10-5 Eclipse Samples wizard

5. Verify that you are in the Java development perspective. If not, switch to the Java development perspective by selecting Window → Open Perspective → Java. 6. In Package Explorer, select org.eclipse.swt.examples. Right-click and select Run as → SWT Application. 7. In the Run Type window, select ControlExample. Click OK.

Chapter 10. Designing a rich-client interface 243 Sample SWT application is displayed like the example in Figure 10-6. This application shows different types of SWT controls, their properties and events. Try setting different properties for SWT controls and observe the change in their visual appearance. On the tabs that have Select Listeners button, observe how user actions generate events.

Figure 10-6 Sample SWT application in Eclipse IDE

Developing SWT applications To develop SWT applications, you must perform the following steps: 1. Create SWT shells. 2. Place widgets and composites on SWT shells. 3. Configure design-time widget properties. 4. Implement event handling. Some events invoke business logic, such as calls to IBM Toolbox for Java classes or calls to Web services. 5. Implement application navigation.

While you can write SWT code from scratch, you can save time and shorten the learning curve by using GUI builder tools. Eclipse and WebSphere Development Studio Client are shipped with Visual Editor (VE), an open source editor for building Java GUI applications.

If you are looking for ease of use in building Java rich-client application traditionally associated with Microsoft Visual Basic development, try SWT Designer, a tool created by Instantiations, Inc. SWT Designer is an Eclipse plug-in and can be installed in any version of WebSphere Development Studio Client or Eclipse. You may find other useful GUI builder tools at the following Web site: http://www.eclipseplugincentral.com/

244 IBM System i Application Modernization: Building a New Interface to Legacy Applications Eclipse RCP Most of you are already familiar with Eclipse IDE, which is an open source IDE for developing different types of applications. Eclipse is the base component of IBM development tools, including WebSphere Development Studio Client. An IDE itself is a rich-client application. A few years ago, the open source development community started working on Eclipse RCP, which is a framework for building Java rich-client applications. Eclipse RCP is a cut-down version of Eclipse IDE, because a rich-client application does not need all the functionality required for an IDE.

Figure 10-7 shows a window of Eclipse IDE. The IDE’s outer window is called a workbench. An Eclipse IDE has a menu bar, a toolbar or a coolbar (customizable toolbar), and a perspective bar. When using an Eclipse IDE, we spend most of our time working with views and editors. A view is a container for SWT widgets, and an editor is a tool for modifying different types of resources.

Figure 10-7 Eclipse IDE

Eclipse RCP applications mostly consist of views, because source code editing is not a typical task in a business application. Views that are used to perform a related set of tasks can be grouped into perspectives. In WebSphere Development Studio Client, we have Web and Remote Systems Explorer (RSE) perspectives. In a business application, we can have “New Customer” or “New Order” perspectives.

Chapter 10. Designing a rich-client interface 245 Figure 10-8 shows a sample Eclipse RCP application.

Figure 10-8 Sample RCP application

You can find a comprehensive overview of Eclipse RCP on the Eclipse project Web site at: http://wiki.eclipse.org/index.php/Rich_Client_Platform

Developing Eclipse RCP applications Eclipse RCP applications consist of Eclipse run time and plug-ins that provide application functionality. The first step in creating an Eclipse RCP application is to create a plug-in project. A plug-in project can be created with the plug-in development wizard in WebSphere Development Studio Client. A plug-in project sets up the necessary infrastructure for developing and running plug-ins. One of the most important components of an Eclipse RCP application is the plug-in manifest file, called plugin.xml. The plug-in manifest file contains basic information about the plug-in (name, plug-in Java class, and so on), dependencies, and extension points. A plug-in manifest can be viewed and edited with the plug-in manifest editor provided in Eclipse IDE.

The next step is to create views. Views contain various SWT components such as input fields, buttons, check boxes, tables, tab controls, tree views, and so on. After placing SWT components on a view, you must implement event processing. Overall, developing Eclipse views is exactly the same as developing SWT shells. The only difference is the “container” (view in Eclipse and shell in SWT applications). Views can then be combined into perspectives.

Navigation in Eclipse RCP is implemented both in code and in the plug-in manifest file. Menus can be created by using Eclipse and SWT API or by configuring them in the plug-in manifest. Views and perspectives must be registered in the plug-in manifest. When registered, views and perspectives can be opened using the standard navigation provided by Eclipse. In addition, views can be opened programmatically from SWT widget events.

246 IBM System i Application Modernization: Building a New Interface to Legacy Applications As in stand-alone SWT application development, you can use Visual Editor or SWT Designer to develop Eclipse RCP applications.

Let us go through the steps to create a simple Eclipse RCP application in Eclipse 3.1:

Note: We use the Eclipse 3.1 IDE because it introduced improved functionality for the Eclipse RCP application development. At the time of writing, WebSphere Development Studio Client V6.0 is based on Eclipse 3.0. You can download the latest version of Eclipse IDE from the Eclipse project Web site at the following address: http://www.eclipse.org

1. Open Eclipse 3.1. 2. In the window that opens, in the Workspace field, type ITSO Lab, and click OK. 3. Close the Welcome page if it is displayed. 4. Select Window → Open Perspective → Other → Plug-in Development to switch to the Plug-in Development perspective (see Figure 10-9).

Figure 10-9 Plug-in Development Perspective

5. Create a new Plug-in project. Select File → New → Other → Plug-in Development → Plug-in Project. Click Next.

Chapter 10. Designing a rich-client interface 247 6. The Plug-in Content panel (Figure 10-10) opens. This panel describes code generation options for the plug-in. In most cases, you do not need to change the default values. The same wizard is used to build a regular plug-in and Eclipse RCP applications. The option to create a rich-client application is not available in Eclipse 3.0, and therefore not in WebSphere Development Studio Client V6.0 and Rational V6.0 tooling. Complete the following actions: a. For Plug-in ID, type Flight400RCP. b. In the Rich Client Application section, select Yes. c. For Class Name, type com.ibm.flight400.rcp.Flight400Plugin. d. Click Next.

Figure 10-10 Plug-in content

248 IBM System i Application Modernization: Building a New Interface to Legacy Applications 7. The plug-in project wizard provides several samples that help you get started with Eclipse RCP application development. In our case, RCP application with a view is the best example for building the Flight400 RCP application. In the Templates panel (Figure 10-11), select RCP application with a view and click Next.

Figure 10-11 Plug-in templates

Chapter 10. Designing a rich-client interface 249 8. In the Single View RCP application panel (Figure 10-12), complete the following actions: a. For Application window title, type Flight400 Reservations System. b. For Application ID, type flight400. c. For Java package name, type com.ibm.flight400.rcp. d. Click Finish.

Figure 10-12 Plug-in code generation options

250 IBM System i Application Modernization: Building a New Interface to Legacy Applications 9. In the Package Explorer view, select the Flight400RCP project. Right-click and select Run As → Eclipse Application as shown in Figure 10-13.

Figure 10-13 Launching a plug-in project

The Flight400RCP application is displayed as shown in Figure 10-14. The sample application has one Perspective, which contains one View. When we launch the application, the Workbench (application container or window) displays the default perspective.

Figure 10-14 Generated Eclipse RCP application

Several code artifacts were generated by the plug-in development wizard. In the following steps, we review some of the important components of an Eclipse RCP application.

Chapter 10. Designing a rich-client interface 251 10.When the Plug-in Project wizard finishes generating code, the plug-in manifest file is displayed in the editor. To open the plug-in manifest file, in Package Explorer, under the Flight400RCP project, double-click plugin.xml. The plug-in manifest file contains plug-in configuration information. 11.In Package Explorer, expand the Flight400RCP\src folder. At first glance, this may seem like a lot of code to display a simple application. It is typical in an application development process that uses a framework (Eclipse, in this case) to create a significant amount of code in the beginning of the project. This pays off when you add new functionality to the application; it takes only a fraction of time compared to applications that do not use frameworks. Look at the following classes: – Application.java: Creates and manages the menu bar; is required by the Eclipse frameworkApplicationActionBarAdvisor.java – ApplicationWorkbenchAdvisor.java: Manages workbench perspectives – ApplicationWorkbenchWindowAdvisor.java: Creates and manages the workbench window – Flight400RCPPlugin.java: Is required by the Eclipse framework – Perspective.java: Creates and manages the perspective – View.java: Creates and manages the sample view

To extend this application, add views that are specific to your business applications and integrate them with System i5 applications and data using IBM Toolbox for Java or Web services.

Eclipse RCP applications and IBM Workplace Managed Client IBM Workplace Managed Client enhances Eclipse RCP applications by providing collaboration components, server provisioning, and the ability to work in disconnected mode. Workplace Managed Client is a part of the IBM Workplace family of products.

Figure 10-15 shows a sample IBM Workplace Managed Client application. Since Workplace Managed client is an RCP applications, you can see familiar Eclipse components in this GUI: workbench, a perspective, and several views.

252 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Figure 10-15 Sample Workplace Managed Client application

There are two approaches for developing a Workplace Managed Client application: Create an Eclipse RCP application with plug-in development tools in Eclipse IDE and package it for deployment in Workplace Managed Client. Build a Workplace Managed Client application using Workplace tooling.

You can find additional information about Workplace Managed Client in the following IBM Redpapers: IBM Workplace Client Technology (Rich Client Edition) Technology Overview, REDP-3884 Building a Component for IBM Workplace, REDP-3952

Other rich-client technologies Rich-client applications can be developed with Microsoft .Net. Functionality provided by Java and Microsoft .Net GUI applications is similar. The difference is in the flexibility of the platform and level of integration with iSeries. Eclipse RCP is an open source extensible framework that encourages development of new features by independent developers. Eclipse development community is one of the fastest growing open source comminutes that creates useful tools, utilities, and code samples on a daily basis. Microsoft .Net is a proprietary platform, and new enhancements are introduced only when Microsoft releases version of the framework.

Java provides a better level of integration with the System i5 platform because it has a complete API, IBM Toolbox for Java for integrating with System i5 applications, data, as well as many other System i5 features (integrated file system, print, data queues, and so on). iSeries Client Access ADO .Net provider simplifies integration of Microsoft .Net applications

Chapter 10. Designing a rich-client interface 253 with iSeries DB2 data and stored procedures. However, there is no equivalent to Toolbox for Java in Microsoft. Net.

10.2 Example of a rich-client application accessing a Web service

In this section, we explain how to create an SWT rich-client application that accesses a Web service. The application performs a search based on a search string specified in the input field and displays search results. The Web service is implemented in RPG with the ProgramCall bean Java wrapper (see Chapter 7, “Designing a Web services interface” on page 119).

We complete the following steps to create a rich-client application: 1. Create a Java project in WebSphere Development Studio Client. 2. Create an SWT shell and add SWT widgets. 3. Create a Web service proxy Web service. 4. Implement event handling.

Figure 10-16 shows the sample rich-client application architecture.

Figure 10-16 Sample rich-client application architecture

Important: Prior to running this example, you should have a Web service installed on a remote or local (as a project in WebSphere Development Studio Client) server. See Chapter 7, “Designing a Web services interface” on page 119.

1. Open WebSphere Development Studio Client. Close the Welcome window if it is displayed. 2. Create a Java project: a. Switch to the Java perspective by selecting Window → Open Perspective → Java. b. Select File → New → Project to create a new Java project. c. In the New Project window, expand the Java node and select Java Project. Click Next.

254 IBM System i Application Modernization: Building a New Interface to Legacy Applications d. In the Create a Java project panel (Figure 10-17), enter your project name, which in this example is ITSOSampleRichClient, and then click Finish.

Figure 10-17 Creating a new Java project

3. Import FINDFLIGHTSServices.wsdl into the ITSOSampleRichClient project root. This file is located in your Web services project in the folder WebContent → wsdl (see 7.3, “Creating a Web service” on page 127).

Note: If you deployed the Web service on a server, modify the location property (replace localhost and port) in the WSDL file prior to generating proxy code. This is a sample line in the file that you must change:

4. Create the Web service Java proxy with the Web service Client wizard. The Web service proxy encapsulates a Web service call: a. In Package Explorer, right-click ITSOSampleRichClient and select New → Other... → Web services → Web Services Client. b. Click Next.

Chapter 10. Designing a rich-client interface 255 c. In the Web Services panel (Figure 10-18), click Next.

Figure 10-18 Web Services Client wizard

d. In the Web Services Selection Page panel (Figure 10-19), browse to FINDFLIGHTSServices.wsdl in the ITSOSampleRichClient project. Click Finish.

Figure 10-19 WSDL file selection

256 IBM System i Application Modernization: Building a New Interface to Legacy Applications 5. Review the generated code, which you can find under ITSOSampleRichClient project as shown in Figure 10-20. We integrate the following classes with the rich-client application: – FINDFLIGHTSServices as the Java interface, which guaranties the call interface – FINDFLIGHTSServicesProxy as the client representation of the Web service functions – FINDFLIGHTSServicesServiceLocator containing the identification and addresses – FINDFLIGHTSInput, FINDFLIGHTSResult, and FLIGHTINFO for the data description The rest of the generated classes are helper classes that we do not directly integrate with the rich-client application.

Figure 10-20 Generated classes for the Web service proxy

Chapter 10. Designing a rich-client interface 257 6. Create an SWT shell: a. In Packages Explorer, right-click the ITSOSampleRichClient project and select New → Visual Class. b. In the Java Class panel (Figure 10-21), complete the following actions:

i. Verify that Source folder is ITSOSampleRichClient. ii. For Package, type com.ibm.flight400. iii. For Name, type MyApplication. iv. Verify that Style is SWT Shell for getting an application frame with a title bar. v. Select public static void main (String[] args). vi. Click Finish.

Figure 10-21 New Java Visual Class wizard

258 IBM System i Application Modernization: Building a New Interface to Legacy Applications 7. The Visual Editor is displayed (see Figure 10-22). The main components of Visual Editor are visual and source code editors, the Palette, and the Properties view. Visual and source code editors are synchronized. You can work on the same Java class in either one of the editors, and code is reflected in the other one. The Palette contains SWT components that you can drop onto the Visual Editor design pane. Component properties can be changed

in the Properties view. Change the title of the window. In the Properties view change the text property to ITSO Rich Client Sample.

Figure 10-22 Visual Editor

8. Save MyApplication.java.

Chapter 10. Designing a rich-client interface 259 9. Test the application: a. In Package Explorer, right-click MyApplication.java and select Run → Run.... b. The Run wizard opens as shown in Figure 10-23.

Figure 10-23 Run wizard

c. Click the Arguments tab.

260 IBM System i Application Modernization: Building a New Interface to Legacy Applications d. As shown in Figure 10-24, specify the -Djava.library.path VM argument to point to swt-win32-3064.dll SWT DLL. In a default WebSphere Development Studio Client v6.0.1 installation, the DLL is located in C:\Program Files\IBM\Rational\SDP\6.0\ eclipse\plugins\org.eclipse.swt.win32_3.0.2.2\os\win32\x86. On your system, the DLL may be located in a different directory.

Note: If you are getting “DLL not Found” error messages, try to copy the DLL into a directory with a shorter path.

Click Run.

Figure 10-24 VM arguments in the Run wizard

Chapter 10. Designing a rich-client interface 261 e. You should see an SWT shell similar to the example in Figure 10-25. If the window is not displayed, check for error messages in the Console view. Close the SWT shell. When we create a runtime configuration, we can test the application by clicking the Run icon or selecting Run → Run from the context menu.

Figure 10-25 Basic SWT shell

10.Add SWT components to the SWT shell: a. Add the following SWT widgets to the SWT shell by dragging them from the Palette (widgets are located under SWT Controls): • Three Label widgets • Three Text widgets • One Button widget • One table widget •Five TableColumn widgets b. Change the text and field name properties as shown in Table 10-1. Table 10-1 Default name conversion Widget Text Field name

Label From City default value

Label To City default value

Label Departure Date default value

Text default value txtFromCity

Text default value txtToCity

Text default value txtDeptDate

Table default value tblFlights

TableColumn Airline default value

TableColumn Flight default value

TableColumn Departure default value

TableColumn Arrival default value

TableColumn Price default value

Button Search default value

262 IBM System i Application Modernization: Building a New Interface to Legacy Applications c. Save changes and run the application. Your SWT shell should look similar to the example in Figure 10-26.

Figure 10-26 SWT shell with widgets

Table columns are not yet displayed on the shell, but they are listed in the JavaBeans view as shown in Figure 10-27.

Figure 10-27 JavaBeans view

Chapter 10. Designing a rich-client interface 263 11.Add the Web services proxy JavaBean to the shell: a. Select Choose Bean from the Palette. b. In the Choose a Bean window (Figure 10-28), for Choose a JavaBean, type FindFlights and select FINDFLIGHTSServiceProxy. For Bean variable name, type proxy, and click OK.

Figure 10-28 Choose a Bean window

c. Drop the loaded mouse cursor onto the white design area of the Visual Editor as shown in Figure 10-29. This creates a getter method for getting a reference to the proxy.

Figure 10-29 Non-visual Java Bean

264 IBM System i Application Modernization: Building a New Interface to Legacy Applications 12.Add event handling to invoke business logic: a. Switch to the source code view in the Visual Editor and add the getFlight() method to the MyApplication.java file. This method, shown in Figure 10-30, calls the Web service proxy to retrieve flights based on the specified search criteria.

private void getFlights(){

try { // Remove all rows from the table if exist tblFlights.removeAll();

//Build the input parameter for the proxy FINDFLIGHTSInput input = new FINDFLIGHTSInput(); input.setFROMCITY(txtFromCity.getText()); input.setTOCITY(txtToCity.getText()); input.setFLIGHTDATE(txtDeptDate.getText());

// Declare the variable for the return value FINDFLIGHTSResult result = null;

// Call the Web service over its proxy result = getProxy().findflights(input);

// Extract the data as a whole and general information FLIGHTINFO[] flightinfos = result.getFLIGHTS(); int flightCount = flightinfos.length;

// Declare the table cells final TableItem[] items = new TableItem[flightCount];

//Fill all the table items line-by-line for (int i = 0; i < items.length; i++) { FLIGHTINFO flightinfo = flightinfos[i]; items[i] = new TableItem(tblFlights, SWT.NONE); items[i].setText(new String[] { flightinfo.getAIRLINE(), flightinfo.getFLIGHT(), flightinfo.getDEPARTTIME(), flightinfo.getARRIVETIME(), flightinfo.getPRICE() }); }

// Command displaying the table header and lines tblFlights.setHeaderVisible(true); tblFlights.setLinesVisible(true);

} catch (RemoteException e) { // TODO Auto-generated catch block e.printStackTrace(); } }

Figure 10-30 The getFlights() method

b. Fix the compile errors by adding import statements.

Note: Use Eclipse’s auto error fix by clicking the error icon on the left side bar and selecting the import statement.

Chapter 10. Designing a rich-client interface 265 c. In the Visual Editor, right-click the Search button and select Events → widgetSelect as shown in Figure 10-31.

Figure 10-31 Adding a widgetSelected event

d. Switch to the source code view and replace the generated code for event handling with getFlights() as shown in Figure 10-32.

button.setBounds(new org.eclipse.swt.graphics.Rectangle(473, 2, 65,23)); button.setText("Search"); aShell.setSize(new org.eclipse.swt.graphics.Point(554.293)); button.addSectionListener(new org.eclipse.swt.events.SelectionListener() { public void widgetSelected(org.eclipse.swt.events.SelectionEvent e) { getFlights(); } });

Figure 10-32 Invoking getFlights() from the widgetSelected() event

e. Save your changes to MyApplication.java. f. Prior to running the application, verify that the Web service is started (either in your local environment or on a server). g. Enter one of the following combinations of from and to cities: • From Chicago, To Orlando • From Atlanta, To Denver • From Miami, To Seattle h. Specify a future date in the form of MMDDYYYY.

You have finished developing a sample SWT application.

266 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Chapter 11. Designing a PHP client

In this chapter, we provide an introduction to the scripting language PHP. We look at the history of PHP and provide a technology overview. We also introduce Zend Core for IBM as well as some development tools that are available on the market.

Later we continue with the sample application used throughout this book and show you how to consume a Web service in PHP. Throughout this chapter, we use code samples that are not related to the sample application, but that illustrate the concepts and ideas that are discussed.

Some of you may wonder why PHP is covered in a book in which the basic idea is to show how to provide new graphical user interfaces (GUIs) to traditional green-screen applications on the iSeries server to modernize the look of these applications. PHP, as a server-side scripting language, is not even a typical front-end development technique. In fact, a Web application user does not even see PHP, but HTML code rendered by the browser. Even when viewing the source code, no PHP is visible, unless something has gone wrong.

As mentioned before, PHP is a server-side scripting language. At runtime, it is executed on the server, and the result is generally returned as HTML code to the browser. Actually, this is not entirely true; PHP can also be used as a stand-alone development language, but this is a topic we do not cover in the context of this book. In 11.1.4, “Technology overview” on page 269, you can see how that works in a more detail. However, the question still remains: why cover PHP in this book?

Well, it simply makes sense. In fact, as you may have seen in this book, modernizing your applications is not only about creating a new GUI. Depending on the current state of your applications, you may have to modularize your code and switch to ILE RPG. Based on that process and your needs, you may decide to create Web services, opening the door to a host of new possibilities. Among them is PHP. That, and the fact that PHP is immensely popular and widely used is a good-enough reason for us to include it here.

11.1.1 A short look back In 2005, the PHP community celebrated the tenth anniversary of PHP. Originally, PHP was written by Rasmus Lerdorf from Denmark and named Personal Home Page/Form Interpreter (PHP/FI), because it was born to automate the handling of certain parts of a Web site, such as forms.

Before PHP, developers used mainly PERL, another open source scripting language. While PERL, which stands for Practical Extraction and Reporting Language, is useful, it proved more cumbersome to write and handle code. Over the years, many discussions have taken place between PHP and PERL adepts, trying to determine which is the better language. We do not want to enter this discussion because we think there is no better language as such, but it is a fact that some tools and languages are better suited for the task. The famous comparison cites a hammer that can be used to put a screw into a wall, when a screwdriver is the better choice to use.

After a rewrite of the open source PHP/FI tools in 1997 by Rasmus Lerdorf, a programmer working for an Internet Service Provider in Israel, Zeev Suraski, and one of his students, Andi Gutmans, decided to completely rewrite the scripting language and the parser of PHP/FI. Together with Rasmus Lerdorf, they released what was called PHP 3 in June 1998.

In 1998, there were about 50,000 Internet domains using PHP, but it did not take long before this number reached the barrier of a million domains. But Suraski and Gutmans were not yet satisfied, and three and a half years later, in May 2002, PHP 4 became available. At the same time, they created a new engine called Zend. This is the name of the company that stands behind PHP. It would be unfair to name only Rasmus Lerdorf, Zeev Suraski, and Andi Gutmans as the creators of PHP. In fact, as with most open source projects, PHP unifies the efforts of many people. They are probably too numerous to name here, but as users of PHP, we are thankful for their efforts.

268 IBM System i Application Modernization: Building a New Interface to Legacy Applications PHP 5 represented another rewrite of the Zend engine and was announced in July 2004. The number of Web sites using PHP has reached 22 millions and is still growing. Zend estimates that there are about 2.5 million PHP developers.

11.1.2 Why you should use PHP The short answer to the question of why you should use PHP may be because it is in use on several millions of Web sites by hundreds of thousands or even millions of people. They range from amateurs to Web professionals who are using it for their family Web site as well as for creating full-blown commercial sites. There must be a reason to this.

PHP was designed for Web development. It allows you to write dynamically generated Web pages quickly and easily, to read and write files, to access and process form data, to send e-mails, to read and write cookies and maintain session variables, and much more. One major strength is that it has integrated access to database records, including reading and writing of records from all major databases. Because doing all this with PHP is rather easy, especially compared to some other development languages, it can safely be called a rapid programming language for Web developers.

Furthermore, the PHP community has created an impressive amount of additional functionality through: Freely available code samples – HotScripts.com which has over 12,000 PHP scripts http://www.hotscripts.com – PHP classes http://www.phpclasses.org PHP extensions http://pear.php.net Documentation

Add to this that PHP does not use a lot of system resources while offering speed of execution, stability, and extensibility. In addition, you know some of the reasons why PHP is so successful and still growing in popularity.

11.1.3 Who is using PHP There are many Web sites that use PHP, as mentioned in the previous section. Some of the major businesses who have adopted PHP are Yahoo, Lufthansa for its e-ticketing system, Electronic Arts for Sim City Online, Boeing for a payload measure system, and Orange for its WAP portal. For more information, see Making the Case for PHP at Yahoo! on the Web at: http://public.yahoo.com/~radwin/talks/yahoo-phpcon2002.htm

11.1.4 Technology overview In this section, we first have a look at how PHP works in a typical environment to provide a

general idea about how the different components of a Web server work together. Then, based on the traditional “Hello, World” sample, we show you how PHP can be used. With these short samples, we hope to demonstrate PHP’s strength of flexibility.

Chapter 11. Designing a PHP client 269 How PHP works Figure 11-1 shows a simple diagram of how PHP works in a Web environment. The process flow is explained as follows. Note that the following numbers correspond to those in the figure: 1. A site visitor requests a URL in the browser, which transmits the request over the Internet to the Web server. 2. The server parses the document. If there are PHP instructions (either embedded in HTML or in a pure PHP file), the code is transmitted to the PHP module. The PHP module processes the PHP functions. 3. In this sample, PHP accesses a database to read some data. 4. The data is returned from the database to PHP, which formats it and... 5. ...returns it to the Web server as simple HTML output. The server embeds the result received in the document requested. 6. The requested document is sent back to the Web site visitor.

Figure 11-1 How PHP works

Of course, database access is not necessary in every case. Therefore steps 3 and 4 in Figure 11-1 may not be necessary.

What is needed to use PHP There are not many requirements to start working with PHP as a Web development language. In fact, since PHP is a server-side scripting language, you only need a PHP-enabled server. PHP probably works with all Web server software, such as Apache or the Microsoft Internet Information Server (IIS). The PHP parser engine is the same on all operating systems, so there are no changes required to run it on different platforms.

If you are interested in trying PHP for yourself on a smaller system than your iSeries server, without spending too much time on installation and configuration tasks, search for the terms LAMP (Linux-Apache- mSQL-PHP) or WAMP (Windows-Apache-mySQL-PHP) using your favorite Internet search engine. Sometimes the P stands for PERL or Python, but these scripting languages are not the topic of this chapter. In a Mac environment, the terms may be DAMP or MAMP (Darwin or Macintosh, respectively). Some Web sites offer combinations of these software packages for download.

270 IBM System i Application Modernization: Building a New Interface to Legacy Applications We recommend that you refer to the XAMPP site, which is easy to install and quickly available to start working: http://www.apachefriends.org/en/xampp.html

Alternatively, you can download the appropriate version of PHP from the following Web site and install it yourself. Since PHP is open source software, you may even download the source code and compile it yourself on the system of your choice. http://www.php.net

There is more than one way to say “Hello, World” Often, there is more than one way to do something, especially when it comes to programming. The sample of five programmers implementing five completely different programs to solve the same problem has been cited often enough. PHP is no different. There probably is not a best or a worst solution. Depending on the context, one solution may be better than the other. Here we show some approaches to say “Hello” to the world.

We assume that you have seen an HTML page before, and for the sake of clarity, we only show the relevant code, leaving off everything that is not necessary, such as DOCTYPEs. Therefore, the pages will not look nice when displayed in a browser, but they should contain everything for you to see the differences. Purists may argue that this is enough for a Web page.

All of the following code samples should do nothing else than display a title and the text “Hello, World” underneath. The remarks may state the obvious, but it is our goal to show the various possibilities of how PHP can be used in a Web-based environment. The code is not sophisticated, but all samples have been tested and should work as is.

Just plain HTML To be complete, in Example 11-1, we show you a page using static HTML.

Example 11-1 Static HTML IBM Redbook: Hello World

Plain HTML

Hello, World

Chapter 11. Designing a PHP client 271 HTML with embedded PHP In Example 11-2, you see PHP code that is embedded in the HTML page. It appears obvious that it would be impossible to reuse the PHP code in another page unless it is copied and pasted. However, this approach is certainly valid for smaller Web sites.

Example 11-2 HTML with embedded PHP IBM Redbook: Hello World

PHP embedded in HTML

HTML with embedded PHP, calling a self-written function Example 11-3 shows an HTML document that contains embedded PHP. The PHP function is defined in an external PHP file (see Example 11-4). Note that the PHP file that contains the function needs to be referenced using the include_once statement.

This approach allows you to reuse the same function in many documents. If the function contains an error or needs to be modified, the change is done in one place, and all documents using the function are immediately updated.

Example 11-3 HTML with embedded PHP function call IBM Redbook: Hello World

HTML calling an externally defined PHP function

The phpfunctions.php file (Example 11-4) can contain more than one function. In this example, we included a second function called Hello10, which displays the text “Hello, World” 10 times and then outputs the text “Done”. Note that the functions printf and echo are used to output the text.

Furthermore, the text “Hello, World” is followed by the HTML code for a break line
. This shows that you can perfectly use PHP to output HTML code that is interpreted correctly by the browser. In fact, you can create a basic HTML page that only calls one PHP function, which then outputs massive amounts of HTML. The function is not used in the previous HTML file, but you can easily exchange the name of the function to call it.

272 IBM System i Application Modernization: Building a New Interface to Legacy Applications Example 11-4 The PHP function definition (file phpfunctions.php) "); } echo "Done."; } ?>

PHP using HTML templates The last example aims to show how to separate display from application logic by using PHP with an HTML template. In Example 11-5, we define the template file that we named Template.tpl.

Example 11-5 HTML template file <?php echo $template->doctitle ?> contentTitle; ?> content; ?>

The next step consists in creating a class template with the appropriate functions (see Example 11-6). Our main method, show($doc), receives the name of a document to be displayed as an argument. It sets the path, which is empty in our example, and then executes the template by using the PHP function include().

After that, it calls the function showFooter(), which prints a line with the current date and the current working directory.

Example 11-6 Definition of class Template (TemplateClass.php)

public $template_dir;

function show($doc) { $template = $this; include($this->template_dir.$doc); $this->showFooter(); }

Chapter 11. Designing a PHP client 273 function showFooter() { printf("

Today's date: %s | Current directory: %s", date('d. M Y'), getcwd()); } } ?>

Now, all that is needed is the main document, which first includes the template class file. Then it creates a new instance of the class Template and assigns values to the class attributes. Finally the function show(‘Template.tpl’) displays the template file, parsing and replacing the values according to what is set in the file. See Example 11-7.

Example 11-7 TemplateMain.php, our main file

$template = new Template; $template->doctitle = 'PHP using an HTML template'; $template->template_dir = ''; $template->contentTitle = '

PHP using an HTML template

'; $template->content = 'Hello, World'; $template->show('Template.tpl'); ?>

Using the techniques in this last sample, you get cleaner code and more agile applications, since display and application logic are separated. This allows you to change either the application logic or the look and feel of the application without affecting the other. As always, using templates may not be the best solution for everyone. As you can see with these simple examples, a template-based solution contains more code than one without templates. We do not use templates to write less code, but to keep the display and application logic separate.

If you are interested in templates, but do not want to write a solution yourself, dozens of free template solutions are available. One of the better known template solutions is Smarty, which you can find on the Web at the following address. We recommend that you read the documentation available online. http://smarty.php.net

Sitepoint is a publishing company in Australia that provides information for Web developers. The following Web address points to a thread in a discussion forum where site visitors have started building up a list with all PHP template engines. At last count, over 70 solutions were in the list. http://www.sitepoint.com/forums/showthread.php?threadid=123769

11.2 PHP on the System i platform

Some time ago, IBM and Zend announced a multi-year agreement to deliver selected Zend PHP products and solutions for i5/OS. IBM and Zend are working together to enable Zend Core and Zend Platform for i5/OS for production environments using PHP. Both of these products run in the i5/OS PASE environment.

For development, Zend Studio provides an integrated development environment (IDE) for building and debugging PHP applications. Zend Guard provides code protection and license management tools for independent software vendors (ISVs).

274 IBM System i Application Modernization: Building a New Interface to Legacy Applications Refer to the following Web site for information about PHP on the System i platform: To port PHP applications to System i platform http://www-304.ibm.com/jct09002c/partnerworld/vic/hardware/portal/develop/roadmap?roadMa pId=LfgV1uQMHfrPyHATrdm

To develop PHP applications http://www-304.ibm.com/jct09002c/partnerworld/vic/hardware/portal/develop/roadmap?roadMa pId=RIW6yvQTmgsPyHATrdm PHP forums http://www.zend.com/forums/

11.2.1 Zend Core for i5/OS Zend Core is a fully tested and enhanced version of the open source PHP. It provides the PHP runtime and is packaged to make the software installation easier and faster with instant PHP setup.

Zend Core for IBM is enhanced to take advantage of i5/OS specific resources and capabilities. It provides a seamless, ready-to-use PHP development and production environment product supported by Zend and offers tight integration with DB2 and the IBM Cloudscape™ database server. The product includes native support for XML and Web Services in support of increased adoption of service-oriented architectures (SOA).

Zend Core for IBM delivers a rapid development and deployment foundation for database-driven applications. It offers an upgrade path from the easy-to-use, lightweight Cloudscape database to the important DB2 database, by providing a consistent API between the two databases.

For more information about Zend Core for i5/OS, refer to the following site: http://www.zend.com/products/zend_core/zend_for_i5_os

In addition to the software, you can find additional information such as data sheets and white papers on Zend Core for IBM. For developers, it is worth looking at the Developer Zone at the following Web address, which features tutorials, documentation, discussion forums, and much more: http://www.zend.com/developers.php

11.2.2 PHP version and availability Zend Core for i5/OS supports PHP 5.1 on i5/OS V5R4. It was released on 31 July 2006. Zend Studio Professional is available today for i5/OS customers to start developing PHP applications. You can download a 30-day trial of Zend Studio from the following Web site: http://www.zend.com/products/zend_studio

Required i5/OS release Zend Core is supported on i5/OS V5R4.

Chapter 11. Designing a PHP client 275 11.2.3 Accessing DB2 Universal Database and calling RPG and COBOL programs in i5/OS Zend Core and Zend Studio for i5/OS integrate support for accessing DB2 Universal Database™ for iSeries and other resource in i5/OS. These functions are supported in DB2 extension and PHP Toolkit for i5/OS respectively. Both of these tool are included in Zend Core for i5/OS.

For more information, see the announcement letter at the following Web address: http://www-306.ibm.com/common/ssi/OIX.wss?DocURL=http://d03xhttpcl001g.boulder.ibm.com/comm on/ssi/rep_ca/1/897/ENUS206-161/index.html&InfoType=AN&InfoSubType=CA&InfoDesc=Announcement +Letters&panelurl=&paneltext=

11.3 PEAR, the PHP Extension and Application Repository

The PHP Extension and Application Repository (PEAR) is a community-driven collection of open source classes that can be used to generate HTML code; make SOAP requests; create, validate, and process HTML forms; send MIME mail; and much more. It was founded by Stig S. Bakken in 1999; since then, many people have joined the project.

The PEAR Web site supports the open source comunity for developing additional functions for PHP in a form of PHP extensions. In addition, the PEAR Web site is a mirror server for distributing PHP runtimes and source code. You can find the PEAR Web site at the following address: http://pear.php.net/index.php

11.3.1 Why PEAR is important PHP and Zend Core for i5/OS provide many features, but you may find yourself in a situation where the needed functionality is not part of the core system. In general, that is the time when you start developing the missing features yourself.

Instead of doing this development, first look at the PEAR Web site and browse the available categories. Every category contains one or more packages, each with a short description so that you can quickly browse through and eventually find what you are looking for. To give you an idea, the top-level categories of the available PEAR modules are: Authentication Date and Time Database Encryption Internationalization Logging Mail Networking Payment Web Services XML

If this list looks interesting, be sure to visit the PEAR Web site, because this is only an extract of the available categories. To directly access the list of available packages, go to the following Web site: http://pear.php.net/packages.php

276 IBM System i Application Modernization: Building a New Interface to Legacy Applications 11.3.2 Installing PEAR packages One part of PEAR is a program that is called pear. It is the PEAR package manager, which helps to download and install additional PEAR packages. Recent installations of PHP already contain the PEAR base installation, unless PHP was compiled with the ./configure flag --without-pear. If that is not the case, you may have to install it manually. Windows users must manually run the batch file located in c:\php\go-pear.bat to install PEAR, for example.

11.3.3 Further information about PEAR You can find further information about PEAR, its history, and the available packages at the following Web address: http://pear.php.net

If you do not know PEAR yet, we recommend that you read the “About PEAR” section on the Web at: http://pear.php.net/manual/en/about-pear.php

11.4 Development tools that offer PHP support

Initially we planned to provide descriptions of the development tools that offer support for the development with PHP. But the reality is that this topic would be outdated by the time the book is available. At time at which this book was written, Zend Studio 5 and Zend Studio for i5/OS are available.

Furthermore, with Zend joining the Eclipse foundation, we can expect that there will be some important announcements in this context, too. If you are interested in using PHP with Eclipse, you may want to refer to the following Web addresses for more information and tools: SourceForge.net: PHPeclipse - PHP Eclipse-Plugin http://sourceforge.net/projects/phpeclipse PHPeclipse http://www.phpeclipse.de

Another reason not to provide a description of development tools is because there may be too many to include here.

For our tests in this chapter, we used Zend Studio 5 and Macromedia Dreamweaver 8. Zend Studio 5 was mainly used for all coding and especially debugging, because Dreamweaver does not provide a PHP specific debugger. Dreamweaver was used to create HTML templates and XML files; it would probably be used if we had to create more HTML pages that contain PHP code because of the visual design possibilities.

In addition to these products, many more tools are on the market that are worth looking at, depending on your needs and budget.

Here is a short list of PHP editors:

Zend Studio: This is the editor that we used for our sample applications. It is powerful and has many features, as you may expect it from the company who stands behind PHP. http://www.zend.com

Chapter 11. Designing a PHP client 277 Maguma: This editor comes as a free, open source version or as Studio or Workbench edition. It also offers support for Python scripting. http://www.maguma.com WeBuilder, Rapid PHP, HTMLPad: These code editors are not only for PHP, but also for cascading style sheets (CSS), HTML and more, depending on the edition. http://www.blumentals.net

You can find more PHP editors at the following Web address, which includes reviews of both commercial and free editors as well as feedback by actual users of the products: http://www.php-editors.com/review

11.5 Example: Consuming a Web service using PHP

In this section, we show you how to consume a Web service created in 7.3, “Creating a Web service” on page 127, using the PHP 5 environment running on Windows platform. If you followed the steps in 7.3.2, “Development steps” on page 128, you should have a running Web service as well as a Web Service Description Language (WSDL) file. With a WSDL file, creating a SOAP request becomes rather easy.

Example 11-8 shows the necessary PHP code embedded in an HTML file so that it can be used immediately. However, this code may not be ready to be used as is in a production environment.

Example 11-8 HTML/PHP code: How to consume a Web service Using a Web Service from PHP

Flights found:

1, "exceptions" => 0)); 1

// Create a class holding a SOAPData 2 class SOAPData { function SOAPData($from, $to, $date) { $this->FROMCITY = $from; $this->TOCITY = $to; $this->FLIGHTDATE = $date; } }// Create the Wrapper for the tags 3 class SOAPWrapper { function SOAPWrapper($strVal) { $this->inputData = $strVal; } }

// Create SOAPWrapper that contains SOAPData with values assigned to it 4

278 IBM System i Application Modernization: Building a New Interface to Legacy Applications $strSOAP = new SOAPWrapper(new SOAPData('Chicago', 'Orlando', '20050806')); // Create a SoapVar that contains our wrapped data 5 $soapstruct = new SoapVar($strSOAP, SOAP_ENC_OBJECT); try { // Call method to find flights 6 //$flights = $client->findflights_XML(new SoapParam($soapstruct, "inputData")); // this works ! //$flights = $client->findflights_XML($soapstruct); // this works, too ! $flights = $client->findflights_XML($strSOAP); // and this works, too !

// Create arrays for XML parser $arrFl = array();// values $idxFl = array();// index

// Loop throug returned array of flights foreach ($flights as $elem) {

// Create XML parser to parse the result 7 $xmlpars = xml_parser_create(); // Parse the result into an array 8 $ret = xml_parse_into_struct($xmlpars, $elem, $arrFl, $idxFl); if($ret == 1) { // Display array of values 9 echo"
Values:
"; print_r($arrFl); // Display array of indexes 10 echo"
Index:
"; print_r($idxFl); } // Free XML parser 11 xml_parser_free($xmlpars); }

// Uncomment the following to print out the string transmitted to the Web service and the ones received back 12 //print "

\n"; //print "Request :\n".htmlspecialchars($client->__getLastRequest()) ."\n"; //print "Response:\n".htmlspecialchars($client->__getLastResponse())."\n";

} catch (SoapFault $exception) { print_r( $exception ); } ?>

Let us review the more important and interesting parts of the code in Example 11-8. The following numbers refer to those in the code. 1 The new SoapClient statement receives the name of our WSDL file to create a SoapClient object on the fly, allowing us to call the methods that are available immediately. Note that we provide a second argument to the statement, an array that contains information that will allow us to retrieve useful information to check or debug the information passed from and to the Web service. 2 We create a class SOAPData that will allow us to pass arguments as a complex type to the method. 3 The second class, SOAPWrapper, is needed in our case to wrap the arguments with the and tags. Leaving these out will let the Web services call fail.

Chapter 11. Designing a PHP client 279 4 We instantiate the SOAPData structure, assigning values to the arguments. The resulting structure is embedded in the wrapper class right away and assigned to the variable $strSOAP. 5 We create a SoapVar containing our variable $strSOAP and assign it to $soapstruct. 6 We call the method findflights_XML, providing our wrapped data as an argument. For illustration, we provide three ways in which you can call the method; the first two are documented out. Any of these work. 7 We create an XML parser object to parse the result returned from the Web service. 8 The result set is parsed into the array $arrFl. Note that the values are parsed into $arrFl, while the corresponding indexes are going into $idxFl. Refer to the PHP documentation about the xml_parse_into_struct method for more details. You can find this documentation online at: http://us2.php.net/xml_parse_into_struct 9 We use the print_r method to display the values that are contained in the array of values... 10 ... followed by the display of the array of indexes. Because you have all the values in the array, you may decide for yourself how to further use them at this point. 11 We free the XML parser. 12 Remember that in 1 we mentioned the additional argument to catch trace information. By uncommenting one or both of the following lines, you can see exactly what is passed to the Web service and what was returned. This can be useful to debug your application.

This short example demonstrates that using a Web service with PHP is not a really complicated task.

11.6 Example: Calling a DB2 Stored Procedure with PHP

Before we dive deeper into the topic of accessing stored procedures on the iSeries server, we must provide some general remarks about our setup. We tested all the code in this chapter on an IBM eServer i5 model 520 running under i5/OS V5R3M0. The system has an Integrated xSeries Server on which we installed Windows Server 2003 Enterprise Edition and Microsoft IIS. PHP 5.0.3 is installed as a module on IIS.

Another factor that contributes to the success of PHP is its support for many database engines. PHP and mySQL were, and still are, a popular combination with Internet Service Providers and Web professionals alike.

However PHP is a good choice to talk to DB2 as well. In the following sample, we show you how you can access a DB2 SQL Stored Procedure on the iSeries server. We invoke it from the PHP environment running in Windows. First we create a table using SQL, as shown in Example 11-9. Then we fill this table with a few names. The code to insert the data is omitted here because this should not be difficult.

Example 11-9 SQL statement to create our sample table

CREATE TABLE REDBOOK/PERSON ( ID INT NOT NULL, NAME VARCHAR (30 ) NOT NULL WITH DEFAULT, FIRSTNAME VARCHAR (25 ) NOT NULL WITH DEFAULT, COUNTRY VARCHAR (30 ) NOT NULL WITH DEFAULT)

280 IBM System i Application Modernization: Building a New Interface to Legacy Applications Next we create an RPG program called GETPERS (see Example 11-10) that basically contains an SQL SELECT statement and opens a cursor. This program will be used as our stored procedure. Example 11-10 Stored Procedure source code

0001.00 *------0002.00 * Stored Procedure - Test for IBM Redbook 0008.00 *------0009.00 C/EXEC SQL 0010.00 C+ INCLUDE SQLCA 0011.00 C/END-EXEC 0012.00 C* 0013.00 C/EXEC SQL 0014.00 C+ WHENEVER SQLERROR CONTINUE 0015.00 C/END-EXEC 0016.00 C/EXEC SQL 0017.00 C+ WHENEVER SQLWARNING CONTINUE 0018.00 C/END-EXEC 0019.00 C* 0020.00 C/EXEC SQL 0021.00 C+ DECLARE NC1 CURSOR FOR 0022.00 C+ SELECT * 0023.00 C+ FROM REDBOOK/PERSON 0024.00 C/END-EXEC 0025.00 * 0026.00 C/EXEC SQL 0027.00 C+ OPEN NC1 0028.00 C/END-EXEC 0029.00 * 0030.00 C/EXEC SQL 0031.00 C+ SET RESULT SETS CURSOR NC1 0032.00 C/END-EXEC 0033.00 C RETRN

Then, using the SQL command CREATE PROCEDURE (see Example 11-11), we create the procedure GetPerson that calls the RPG program GETPERS.

Example 11-11 SQL command to create the stored procedure create procedure redbook/getperson() result sets 1 language rpg external name getpers reads sql data parameter style general

Now that the Stored Procedure is ready, we create a PHP file that uses this Stored Procedure to get data out from DB2 on our iSeries server and displays it on a Web page. Since we are using Open Database Connectivity (ODBC), we must first set up an ODBC connection to the appropriate library. In our setup, we created the ODBC connection on our Windows server.

In our PHP code, we are not only calling the stored procedure as you can see in Example 11-12. For demonstration purposes, after the successful connection via ODBC, we first execute a simple SQL SELECT statement and display the results in an HTML table.

Note: You must replace and (in bold) in the file with the appropriate values for your system, for example “RAK” and “password”.

Chapter 11. Designing a PHP client 281 Next we call the stored procedure and print an HTML table with all rows retrieved. We do this in only three lines. However, in a production environment you include code to check for errors. Finally, we call the stored procedure again, but instead of displaying all rows in a table, we fetch row by row and display them in a different format.

Example 11-12 HTML/PHP code calling the stored procedure and displaying the returned result set Access a DB2 Stored Procedure

IBM Redbook authors

,, SQL_CUR_USE_ODBC); if(empty($conn)) { echo "Connect to iSeries DB failed!"; die(); } else { echo "Connect successful!"; }

// First execute a simple SQL statement and display all rows echo "

Result of SQL select

"; $query = "SELECT * FROM REDBOOK.PERSON ORDER BY FIRSTNAME"; $result = odbc_exec($conn, $query); $ret = odbc_result_all($result);

// Call the stored procedure echo "

Result of Stored Procedure call

"; $query = 'CALL REDBOOK.GETPERSON()'; $result = odbc_exec($conn, $query); // Print a HTML table with all rows $ret = odbc_result_all($result);

// Call the stored procedure again, but fetch row by row $row = ''; echo "

Result of Stored Procedure call, fetch single row

"; $query = 'CALL REDBOOK.GETPERSON()'; $result = odbc_exec($conn, $query); if ($result) { while (odbc_fetch_into($result, $row)!=FALSE) { printf("ID: %d - %s %s (Country: %s)
", $row[0], $row[1], $row[2], $row[3]); } }

// Close the ODBC connection odbc_close($conn); ?>

282 IBM System i Application Modernization: Building a New Interface to Legacy Applications 11.7 PHP and XML

One reason why PHP is popular is because it is powerful but also simple to use. In the following example, we provide proof for this statement. First let us look at a simple XML file that contains some last and first names (see Example 11-13). We call this file myXML.xml. Example 11-13 Sample XML file containing names and first names Hartung Guenther Klaedtke Rolf Andre McCarthy Estela Motmans Els Nartovich Aleksandr

Chapter 11. Designing a PHP client 283 The sample HTML document that contains some PHP script as shown in Example 11-14. After checking for the existence of the file, we load the file using one statement and then loop through and print the elements read from the XML file, which in this case are the names of the authors of this redbook.

Example 11-14 HTML/PHP document that displays the content of the XML file Read an XML file

IBM Redbook authors

person AS $person) { printf($person->name . ' ' . $person->firstname . '
'); } } else { exit('Failed to open myXML.xml.'); } ?>

Note that the command simplexml_load_file() is available in PHP 5. There is support for XML in earlier versions of PHP, too, but not as simple as in version 5.

284 IBM System i Application Modernization: Building a New Interface to Legacy Applications

Appendix A. Additional material

This redbook refers to additional material that can be downloaded from the Internet as described below.

Locating the Web material

The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to: ftp://www.redbooks.ibm.com/redbooks/SG246671

Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks

Select the Additional materials and open the directory that corresponds with the redbook form number, SG246671.

Using the Web material

The additional Web material that accompanies this redbook includes the following files: File name Description flght400m.zip This file contains two save files with the development libraries.

System requirements for downloading the Web material The following system configuration is recommended: Hard disk space: 300 MB minimum Operating System: Windows XP Processor: Pentium IV or higher Memory: 2 GB assuming that you are using WebSphere Development Studio Client V6.0

© Copyright IBM Corp. 2006. All rights reserved. 285 How to use the Web material Create a subdirectory (folder) on your workstation and unzip the contents of the Web material zip file into this folder. Then send both SAVF files, using File Transfer Protocol (FTP), to your System i machine and run the following commands:

RSTLIB SAVLIB(FLGHT400) DEV(*SAVF) SAVF(your lib/FLGHT400) MBROPT(*ALL) ALWOBJDIF(*ALL) RSTLIB SAVLIB(FLGHT400M) DEV(*SAVF) SAVF(your lib/FLGHT400M) MBROPT(*ALL) ALWOBJDIF(*ALL)

Replace your lib with the name of the library when you save the SAVF files.

286 IBM System i Application Modernization: Building a New Interface to Legacy Applications Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

IBM Redbooks

For information about ordering these publications, see “How to get IBM Redbooks” on page 289. Note that some of the documents referenced here may be available in softcopy only. Building a Component for IBM Workplace, REDP-3952 IBM Rational Application Developer V6 Portlet Application Development and Portal Tools, SG24-6681 IBM Workplace Client Technology (Rich Client Edition) Technology Overview, REDP-3884 Mastering the IBM WebFacing Tool, SG24-6331 Modernizing IBM eServer iSeries Application Data Access - A Roadmap Cornerstone, SG24-6393 Rational Application Developer V6 Programming Guide, SG24-6449 WebSphere Application Server V6 Technical Overview, REDP-3918 WebSphere Development Studio Client for iSeries Version 5.1.2, SG24-6961 WebSphere Studio 5.1.2 JavaServer Faces and Service Data Objects, SG24-6361

Other publications

The following publication is also relevant as a further information source: Iyengar, Ashok; Gadepalli, Vankata; and Olson, Bruce; IBM WebSphere Portal Primer - Second Edition; 2nd Edition, MC Press July 2005; ISBN 1-931182-23-X

Online resources

These Web sites are also relevant as further information sources: Aiming for Zero Interactive on iSeries (WebFacing Performance Considerations) http://www-1.ibm.com/support/docview.wss?uid=swg27004617&aid=1 DDS Keyword Survey Tool http://www-1.ibm.com/support/docview.wss?uid=swg24001257 IBM System i Developer Roadmap http://www.ibm.com/systems/i/roadmap/index.html IBM WebFacing Deployment Tool with HATS Technology http://www.ibm.com/software/awdtools/wdht/

© Copyright IBM Corp. 2006. All rights reserved. 287 IBM WebFacing Tool PTFs http://www-1.ibm.com/support/docview.wss?rs=255&uid=swg27002213 IBM WebSphere Host Access Transformation Services (HATS) V6 InfoCenter http://publib.boulder.ibm.com/infocenter/hatshelp/v60/index.jsp Performance Management for IBM System i Resource Library http://www-03.ibm.com/servers/eserver/iseries/perfmgmt/resource.html Portlet Development Best Practices and Coding Guidelines, WebSphere Portal V5.1 http://www3.software.ibm.com/ibmdl/pub/software/dw/wes/pdf/PortletCodingGuidelines.pdf Rich Client Platform http://wiki.eclipse.org/index.php/Rich_Client_Platform Service-oriented architecture on Wikipedia http://en.wikipedia.org/wiki/Service-oriented_architecture SOA and Web services on developerWorks http://www-130.ibm.com/developerworks/webservices Toolbox for Java & JTOpen http://www-03.ibm.com/servers/eserver/iseries/toolbox/ WebSphere Application Server home page http://www-03.ibm.com/servers/eserver/iseries/software/websphere/wsappserver/ WebSphere Application Server product support http://www-306.ibm.com/software/webservers/appserv/was/support/ WebSphere Development Studio for iSeries http://www-306.ibm.com/software/awdtools/wds400/ WebSphere Development Studio Client for iSeries: Larry's Hot Tips http://www-306.ibm.com/software/awdtools/wdt400/library/hottips.html WebSphere Development Studio Client for iSeries support page http://www.ibm.com/software/awdtools/wdt400/support/ WebSphere Portal on iSeries http://www.ibm.com/servers/eserver/iseries/software/websphere/portal/ WebSphere Portal for Multiplatforms Version 5.1.x Information Center http://publib.boulder.ibm.com/infocenter/wpdoc/v510/index.jsp Zend home page http://www.zend.com/

288 IBM System i Application Modernization: Building a New Interface to Legacy Applications How to get IBM Redbooks

You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site: ibm.com/redbooks

Help from IBM

IBM Support and downloads ibm.com/support

IBM Global Services ibm.com/services

Related publications 289

290 IBM System i Application Modernization: Building a New Interface to Legacy Applications Index

design patterns 114 Numerics Distributed Component Object Model 159 5722-WDS 76 Domino Builder 204 Dynamic Web application 121 A dynamic Web services invocation model 124 administration console support 49 advanced solutions 11, 16 E advantages of rich-client technology 239 EAR (enterprise archive) 61 application design and implementation 115 Eclipse 240 application modernization 18 auto error fix 265 Assemble HATS Project 63 plug-in project 246 view 246 B Eclipse RCP 10, 19, 118, 245 B2B (business to business) 202 application development 246 B2C (business to consumer) 202 applications and IBM Workplace Managed Client 252 B2E (business to employee) 202 Eclipse Rich Client Platform 10, 19, 118, 245 Basic Mapping Support (BMS) 46 Eclipse Visual Editor 244 basic portal architecture 202 editor 245 basic solutions 11 embedded PHP 272 BMS (Basic Mapping Support) 46 ENPTUI 16, 45 business logic 162 enterprise archive (EAR) 61 business reasons for implementing portal server 199 event 241 business to business (B2B) 202 business to consumer (B2C) 202 F business to employee (B2E) 202 facade pattern 114 Button widget 262 FacesServlet 117 fat client 10, 238 C flexible architecture 116 Cascading Style Sheets - Positioning (CSS-P) 84 front end to a monolithic iSeries application 8 cascading style sheets (CSS) 12 CICS 46 H click-to-action 199 H spec 128 Cloudscape 275 HATS 14, 117 CODE 82 5250W connection 50 CODE Designer 12 application 31 Common Object Request Broker Architecture (CORBA) application deployment 61 159 application deployment to the iSeries 61 composite 241 application development 48 CORBA (Common Object Request Broker Architecture) application installation 64 159 application packaging 63 create, read, update, and delete functions 17 application preparation for production 59 CRTRPGMOD 138 business scenarios 16 CSS (cascading style sheets) 12 changes to the current business practices 15 CSS-P (Cascading Style Sheets - Positioning) 84 connection settings 50 default template 51 deployment requirements 27 D DAMP 270 development requirements 26 data definition specification (DDS) 67 example 48 database access method modernization 112 hardware 14 database physical file 112 hardware and software requirements 26 DCOM 159 installation and configuration 37 DDS (data definition specification) 67 installation of the application 64 design approaches 115 integration capabilities 28

© Copyright IBM Corp. 2006. All rights reserved. 291 investment 14 runtime license enablement file 35 loss of HATS perspective 43 IBM WebFacing Tool 9, 11 new features 45 business scenarios addressed 14 portlet 204 changes to the current business practices 13 preparation of your HATS application for production hardware 12 59 investment 11 project implementation requirements 28 skills 12 project implementation strategy 30 software 11 project initiation and problem identification 30 time 12 project scoping 29 IBM WebSphere Portal Server 202 proof of concept 33 IBM WebSphere Portal Server on System i 205 refresh pack 39 IBM Workplace Managed Client 10, 19, 252 rendering rules 55 IBM-provided tools 11 rules engine 28 ILE path pros and cons 111 runtime enablement 61 Integrated Language Environment (ILE) 109 runtimeenablement.jar file 62 INVITE 13 skills 15 iSeries skills requirement 29 error list 139 software 14 integration of applications and Java 112 time 15 iSeries Access for Web 9, 27, 117 typical case studies 32 portlets 204 unit and function testing and problem resolution 31 upgrade 39 user testing and problem resolution 31 J user training and project documentation 31 Java GUI API 240 HATS (Host Access Transformation Services) 14, 25 Java rich-client development options 240 HATS Studio 26 Java Standardization Request (JSR 168) 202 installation 37 JavaScript 12 updgrade 39 JavaServer Faces (JSF) 9, 16, 46, 117, 162, 164 HATS Toolkit 9, 35 JDBC Builder 204 installation 38 JDBC Portlet builder 208 HATS Trial Toolkit JFace 118 upgrade 44 JSF (JavaServer Faces) 9, 16, 46, 117, 162, 164 HATS Trial Toolkit upgrade 44 application testing 188 HATS V6.0 45 binding 163 HATS V6.0.1 47 binding Java beans to JSF pages 180 HATS V6.0.2 47 business scenarios addressed 18 HATS V6.0.3 47 changes to the current business practices 18 HATS V6.0.4 48 control generation for output JSF 184 Host Access Transformation Services (HATS) 14, 25 development environment 163 host server, starting 86 events 163 HTML 12 framework 162 hardware 17 investment 16 I Java beans added to the JSF pages 178 i5/OS PASE 274 JSF application testing 188 IBM System i Developer Roadmap 5 ProgramCall mechanism 165 IBM Systems Workload Estimator 208 properties 163 IBM Toolbox for Java 9 sample application 164 IBM Toolbox for Java API 10 skills 17 IBM Toolbox for Java ProgramCall mechanism 164 software 16 IBM WebFacing Deployment Tool for WebSphere Devel- time 17 opment Studio V6.0.1 with HATS Technology 34, 48 Web service invocation 164, 189 benefits 34 what’s next 196 enablement key 34 JSF (JavaServer Faces) components 163 for HATS customers 34 JSF technology 16 for WebFacing customers 35 overview 162 package contents 35 JSF-based interface 161 PTFs to enable 36 JSR 168 (Java Standardization Request) 202 purchasing 37 purchasing scenarios 36

292 IBM System i Application Modernization: Building a New Interface to Legacy Applications K PF (physical file) 112 KBS.js 15 PHP 20 keyboard mapping file 15 brief history 268 business scenarios addressed 21 client 267 L client design 267 label widget 262 community 268 LAMP 270 hardware 20 LF (logical file) 112 HTML templates 273 linking program 110 introduction 268 logical file (LF) 112 investment 20 Lotus QuickPlace 207 requirements 270 Lotus Sametime 207 simple examples 271 skills 21 software 20 M System i platform 274 MAMP 270 technology overview 269 markup fragment 201 users 269 MDI (Multiple Document Interface) 241 XML 283 MENUBR 13 PHP 5 269 Microsoft .Net 10 PHP example Microsoft Visual Basic 244 calling a DB2 Stored Procedure with PHP 280 MLTCHCFLD 13, 46 consuming a Web service using PHP 278 MNUBAR 46 PHP Extension and Application Repository 276 model view controller (MVC) 114, 162 PHP/FI 268 modernization 110 physical file (PF) 112 application 18 portal database access method 112 architecture 202 OPM program 110 framework 198 reasons for a change 4 pages and portlets 201 modular and monolithic host applications 18 project creation 210 modular RPG applications as Web service 10 Portal Document Manager 204 modularization 110 portal front end Multiple Document Interface (MDI) 241 for a modular RPG application 10 MVC (model view controller) 114, 162 to a monolithic iSeries application 9 controller 114 portal server design pattern 17 application and information integration 198 model 114 collaborative capabilities 198 view 114 common presentation 198 document management 199 N framework for Web services 198 native portlet support 84 improved decision making 199 increase in employee productivity 199 increased customer satisfaction and lower operating O cost 199 object oriented architecture 122 increased efficiency through automation 199 OPM (Original Programming Model) 8, 109 personalization and customization 198 OPM program modernization 110 quicker response to customer inquiries 199 OPM versus ILE RPG 110 single sign-on (SSO) 198 Original Programming Model (OPM) 8, 109 support for pervasive devices 198 out-of-the-box portlets 204 technical definition 198 technology overview 200 P portlet 10, 117, 200 applications 117 PCML (Program Call Markup Language) 137 catalog 204 PDM 204 container 200 PDM Screen Design Aid (SDA) 13 content produced 201 PEAR 276 creation to access iSeries application and data 207 PeopleSoft Portlet Builder 208 decorations 201 PERL 268 deployment 226 Personal Home Page/Form Interpreter 268

Index 293 title bar 201 technology choices 240 portlet API 10, 200 technology overview 238 Portlet Builder 208 widgets 241 Portlet Builder for Domino 208 window 241 portlet developer 203 RMI (Remote Method Invocation) 159 portlet development with iSeries Tools 207 RPG IV 128 portlet example 209 RSE (Remote Systems Explorer) 81 generating a Web service client 227 runtimeenablement.jar 62 invoking a Web service 227 invoking the ProgramCall bean 221 modification of the generated code 231 S modification of the portlet source code 216 SAP Portlet Builder 208 modifying JSP 219 scenarios overview 8 portlet testing 224 Screen Design Aid (SDA) 8, 13 SessionBean 217 screen scraper 28, 68 Program Call Markup Language (PCML) 137 SDA (Screen Design Aid) 8, 13 ProgramCall JavaBean 129 SDO (Service Data Objects) 18 ProgramCall Wizard 140 server-side scripting language 268 proxy 153 Service Broker 122 PSHBTNCHC 13 Service Data Objects (SDO) 18 PSHBUTTON 46 service provider 122 PULLDOWN 46 Service Provider Interface (SPI) 202 service requestor 122 service-oriented architecture (SOA) 122 Q SEU (Source Edit Utility) 8, 13 QqfEnvironment 13 SFLMLTCHC 46 SFLSNGCHC 46 Sieble Portlet Builder 208 R single sign-on (SSO) support 85 Rational Application Developer 26, 37 SNGCHCFLD 46 Rational Software Development Platform 77 SOA (service-oriented architecture) 122 Rational Studio Architect 26, 37 SOAP 124 Rational Web Developer 26, 37 SOAP Transport Layer 124 Redbooks Web site 289 Source Edit Utility (SEU) 8, 13 contact us xi SPI (Service Provider Interface) 202 refacing technologies 115 SQL (Structured Query Language) 112 Remote Method Invocation (RMI) 159 Standard Widget Toolkit (SWT) 10, 19, 118, 240 Remote Systems Explorer (RSE) 81 static invocation model 125 connection verification 81 stored procedure 281 rich client 10, 19, 238 structured host applications 18 advantages and disadvantages 239 Structured Query Language (SQL) 112 application accessing a Web service example 254 Swing API 10, 118, 240 applications 118 SWT (Standard Widget Toolkit) 10, 19, 118, 240 business scenarios addressed 20 SWT application development 244 clickable widgets 242 System i platform and PHP 274 closer look 241 system screens support 85 development platform 242 Eclipse IDE 242 Eclipse RCP application development 246 T focus events 242 table widget 262 front end for a modular RPG application 10 TableColumn widget 262 hardware 19 technology stack, Web services 123 investment 19 text widget 262 keyboard events 242 thin client 238 Microsoft .Net 253 thread safety implementation in an RPG program 128 multiple document interface 241 thread safety in an RPG program 128 shells 241 Tivoli Access Manager 27 skills 20 software 19 SWT application development 244 U technologies 19, 253 UDDI (Universal Discovery, Description and Integration)

294 IBM System i Application Modernization: Building a New Interface to Legacy Applications 123 sample WebFacing application 86 registry 125 starting host servers 86 UIM-based Help panel 13 starting the WebFacing server 87 UIM-based screen 13 support for system screens and non-WebFaced appli- Universal Discovery, Description and Integration (UDDI) cations 102 123 testing WebFacing application 96 up-front considerations and prerequisites 5 unit and function testing and problem resolution 75 user testing and problem resolution 76 versus screen scrapers 68 V WebFacing application deployment to the iSeries 101 VE (Visual Editor) 244 WebFacing project creation 88 view 245 WebFacing Deployment Tool for WebSphere Develop- Visual Basic 244 ment Studio V6.0.1 with HATS Technology 34 Visual Editor (VE) 244 WebFacing Deployment Tool with HATS Technology 34 WebFacing Runtime Server 69 W WebFacing Runtime Servlet 69 WAMP 270 WebSphere Application Portlet Builder 208 Web front end for a modular RPG application 9 WebSphere Development Studio Client Web service Agent Controller 79 client generation 227 creation of input and output JSF pages 174 consume (use) 158 Installing and configuring WebSphere Development creation 127 Studio Client V6.0 76 creation from the ProgramCall JavaBean 147 required PTFs 81 development cycle 125 starting 88 interface design hints 158 V6.0 upgrade 80 URI 151 WebSphere Development Studio Client for iSeries 8, 26, Web services 120 37 advantages and disadvantages 158 WebSphere Development Studio Client for iSeries V6.0 bottom up approach 126 69 consuming 158 WebSphere Development Studio Client V6.0 development approach 125 installation and configuration 76 interface considerations 127 upgrade 80 invocation model 124 WebSphere Portal 10, 117 meet-in-the-middle approach 126 WebSphere Portal Enable 205–206 methods 151 WebSphere Portal Extend 205, 207 security configuration 151 WebSphere Portal Server stateless versus stateful 126–127 basic content publishing 204 static invocation model 125 Click-to-Action 207 style and use 151 creation of portlets that access iSeries application and technology stack 123 data 207 testing and deployment 127 deployment requirements 208 top-down approach 126 development requirements 208 Web Services Description Language (WSDL) 123, 151 Domino Web Access 204 Web Settings view 83 hardware and software requirements 208 Web Site Designer 94 out-of-the-box portlets 204 WebFacing 116 People Finder 204 application deployment to the iSeries 101 portlet development with iSeries Tools 207 application installation on WebSphere Application prerequisites 208 Server V6.0 105 productivity components 204 deployment requirements 71 skills needed 209 development requirements 69 writing custom portlets 208 hardware and software requirements 69 WebSphere Portal UTE 224 WebSphere Portal Version 6.0 205 new features 83 packaging the application 105 widgetSelected event 242 portlet 204 WINDOW 46 project creation 88 workbench 245 project implementation strategy 73 Workplace Forms 207 project initiation and problem identification 74 Workstation Data Manager 69 recommended implementation phases 73 WPCP Portlet Builder 208 recommended skills 73 WSDL (Web Services Description Language) 123

Index 295 folder and file 151

X XAMPP 271 XML and PHP 283 XML message 124 XML parsing 122

Z Zend Core for i5/OS 20, 274 Zend Core for IBM 267 Zend engine 269 Zend Guard 20, 274 Zend Platform for i5/OS 274 Zend Studio for i5/OS 277

296 IBM System i Application Modernization: Building a New Interface to Legacy Applications

IBM System i Application Modernization: Building a New Interface to Legacy Applications

IBM System i Application Modernization: Building a New

IBM System i Application Modernization: Building a New Interface to Legacy Applications

(0.5” spine) 0.475”<->0.873” 250 <-> 459 pages

IBM System i Application Modernization: Building a New Interface to Legacy

IBM System i Application Modernization: Building a New Interface to Legacy Applications

Back cover ® IBM System i Application

Modernization Building a New Interface to Legacy Applications

Comparison of the This IBM Redbook examines many different alternatives for INTERNATIONAL different ways to accessing your IBM System i legacy applications. It provides recommendations for selecting different tools and technologies TECHNICAL access the IBM SUPPORT System i platform based on your existing environment and the goals that you are trying to achieve. It covers the IBM WebSphere -based solutions, ORGANIZATION Discussion of JSFs, such as IBM Host Access Transformation Services (HATS) and HATS, Web services, JavaServer Faces (JSF), as well as rich-client and PHP solutions. portlets, IBM The parts of this redbook are designed for company CIOs, BUILDING TECHNICAL WebFacing Tool, and architects, and developers. Within these parts, this redbook rich client INFORMATION BASED ON provides guidance for those who are selecting the most suitable PRACTICAL EXPERIENCE alternative for their existing IT environment. This redbook also Examples of building demonstrates the process of creating a sample application using IBM Redbooks are developed different client a specific technology. For those who are interested in a more by the IBM International interfaces detailed information, this redbook points to other publications Technical Support and online materials. Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information: ibm.com/redbooks

SG24-6671-00 ISBN 0738494844

Departure City	Time	Arrival City	Time	Airline	Price
<%=flight.getDEPARTCITY() %>	<%=flight.getDEPARTTIME() %>	<%=flight.getARRIVECITY() %>	<%=flight.getARRIVETIME() %>	<%=flight.getAIRLINE() %>	<%=flight.getPRICE() %>