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

An IBM Redbook Publication
IBM Redbook Form Number: SG24-6671-00
ISBN: 0738494844
ISBN: 9780738494845
Publication Date: 22-Sep-2006
Find Similar Download

Related People

Aleksandr Nartovich - Author [+5] [-5]
Guenther Hartung - Author
Rolf Andre Klaedtke - Author
Elena Lowery - Author
Estela McCarty - Author
Els Motmans - Author

Abstract

This IBM Redbooks publication 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 book are designed for company CIOs, architects, and developers. Within these parts, this book provides guidance for those who are selecting the most suitable alternative for their existing IT environment. This book also demonstrates the process of creating a sample application using a specific technology. For those who are interested in a more detailed information, this book points to other publications and online materials.

Language

English

Table of Content

Part 1. Looking at the alternatives
Chapter 1. Why you should consider new application interfaces
Chapter 2. Modernizing System i legacy applications: Common business scenarios
Part 2. Using IBM solutions
Chapter 3. Host Access Transformation Services
Chapter 4. The IBM WebFacing Tool
Part 3. Designing a new user interface
Chapter 5. Before you create a new user interface
Chapter 6. Application architecture, design, and implementation
Chapter 7. Designing a Web services interface
Chapter 8. Designing a JavaServer Faces-based interface
Chapter 9. Designing a portlet client
Chapter 10. Designing a rich-client interface
Chapter 11. Designing a PHP client
Appendix A. Additional material
ibm.com/redbooks
Front cover
IBM System i Application
Modernization
Building a New Interface to Legacy Applications
Guenther Hartung
Rolf Andre Klaedtke
Elena Lowery
Estela McCarty
Els Motmans
Aleksandr Nartovich
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


International Technical Support Organization
IBM System i Application Modernization: Building a
New Interface to Legacy Applications
September 2006
SG24-6671-00

© 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.
First Edition (September 2006)
This edition applies to IBM OS/400 V5R3 and IBM i5/OS V5R4.
Note: Before using this information and the product it supports, read the information in “Notices” on
page vii.

© Copyright IBM Corp. 2006. All rights reserved.
iii
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

iv
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Contents
v
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

vi
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

© Copyright IBM Corp. 2006. All rights reserved.
vii
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.

viii
IBM System i Application Modernization: Building a New Interface to Legacy Applications
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
AS/400®
Cloudscape™
CICS®
developerWorks®
Domino.Doc®
Domino®
DB2 Universal Database™
DB2®
eServer™
Everyplace®
Integrated Language Environment®
IBM®
iNotes™
iSeries™
i5/OS®
Language Environment®
Lotus Notes®
Lotus®
Notes®
OS/400®
POWER5™
pSeries®
QuickPlace®
Rational®
Redbooks™
Redbooks (logo) ™
Sametime®
System i™
System i5™
Tivoli®
VisualAge®
WebSphere®
Workplace™
Workplace Client Technology™
Workplace Forms™
Workplace Managed Client™
Workplace Web Content
Management™
xSeries®
z/OS®
zSeries®
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.

© Copyright IBM Corp. 2006. All rights reserved.
ix
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.
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 hartung@ubhartung.de.
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
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.

x
IBM System i Application Modernization: Building a New Interface to Legacy Applications
publisher of PowerTimes and has organized technical conferences and user group meetings
in Switzerland. You can contact Rolf by sending e-mail to r.klaedtke@raksoft.ch.
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 elowery@us.ibm.com.
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 EstelaMcCarty@fr.ibm.com.
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
els_motmans@be.ibm.com.
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 alekn@us.ibm.com.
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

Preface
xi
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:
redbook@us.ibm.com
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400

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

© Copyright IBM Corp. 2006. All rights reserved.
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
Part 1

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

© Copyright IBM Corp. 2006. All rights reserved.
3
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.
1

4
IBM System i Application Modernization: Building a New Interface to Legacy Applications
1.1 Reasons for a change
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.

Chapter 1. Why you should consider new application interfaces
5
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

6
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

© Copyright IBM Corp. 2006. All rights reserved.
7
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.
2

8
IBM System i Application Modernization: Building a New Interface to Legacy Applications
2.1 Considerations for the scenarios and possible solutions
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

Chapter 2. Modernizing System i legacy applications: Common business scenarios
9
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.

10
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 2. Modernizing System i legacy applications: Common business scenarios
11
because Web services do not have a UI. WebSphere Studio and Rational tools provide
wizards that simplify Web services development.
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).
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.

12
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 2. Modernizing System i legacy applications: Common business scenarios
13
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.
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.
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.

14
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 2. Modernizing System i legacy applications: Common business scenarios
15
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

16
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 2. Modernizing System i legacy applications: Common business scenarios
17
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.

18
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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))

Chapter 2. Modernizing System i legacy applications: Common business scenarios
19
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.

20
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 2. Modernizing System i legacy applications: Common business scenarios
21
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.

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

© Copyright IBM Corp. 2006. All rights reserved.
23
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
Part 2

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

© Copyright IBM Corp. 2006. All rights reserved.
25
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?
3

26
IBM System i Application Modernization: Building a New Interface to Legacy Applications
3.1 Requirements to prepare for a HATS implementation
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
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
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
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.
Note: You can reduce the minimum required disk space if optional features and test
environments are not installed.

Chapter 3. Host Access Transformation Services
27
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: 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.
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.

28
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.
Note: Each HATS application that you deploy requires additional disk space. The
minimum disk space required for each HATS application is approximately 30 MB.

Chapter 3. Host Access Transformation Services
29
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

30
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 3. Host Access Transformation Services
31
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.

32
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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 factors Customer situation
Business requirements To Web-enable RPG-based host applications running on the
iSeries server only
Web page look-and-feel
requirements
To use a company-defined template and default browser
behavior, with the Web pages as close as possible to
green-screen look because of conservative users
Screen flow and navigation change
requirements
None
Total number of screens 2500 to 3000 screens
Third-party or back-end applications
integration requirements
Requires the customer to receive input information from a
PC-based application and use this information to determine
the initial Web page and contents to display
Development or implementation
team skills
Resource group of 20 people with the following skills or roles:
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)
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

Chapter 3. Host Access Transformation Services
33
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.
Restriction: These estimates are
not
meant to replace the requirement of scoping your
HATS implementation based on properly-defined business, function, and user
requirements.

34
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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: The HATS hardware and software prerequisites are the same as described in 3.1.1,
“Hardware and software requirements” on page 26.
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.

Chapter 3. Host Access Transformation Services
35
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.
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.
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.
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.
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.

36
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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.
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.

Chapter 3. Host Access Transformation Services
37
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.

38
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 3. Host Access Transformation Services
39
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

40
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.

Chapter 3. Host Access Transformation Services
41
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

42
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 3. Host Access Transformation Services
43
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
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.
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).

44
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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.
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.

Chapter 3. Host Access Transformation Services
45
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
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
Note: This section is of value to those customers who have had previous experience with
HATS.

46
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
47
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.

48
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 3. Host Access Transformation Services
49
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

50
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
In the Type field, select 5250W.
Figure 3-8 Connection details
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.

Chapter 3. Host Access Transformation Services
51
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

52
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
53
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

54
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
55
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

56
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
57
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

58
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
59
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

60
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
61
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).

62
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 3. Host Access Transformation Services
63
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.
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.
Important: If the Build automatically option is turned off, you must
manually rebuild your
project or projects
to enable the runtime support.

64
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 3. Host Access Transformation Services
65
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.

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

© Copyright IBM Corp. 2006. All rights reserved.
67
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?
4

68
IBM System i Application Modernization: Building a New Interface to Legacy Applications
4.1 WebFacing versus screen scrapers
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.
Figure 4-1 WebFacing architecture
1
2
3
4
5

Chapter 4. The IBM WebFacing Tool
69
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.

70
IBM System i Application Modernization: Building a New Interface to Legacy Applications
Table 4-1 Hardware specifications
Type WebSphere Development
Studio Client Standard Edition
V6.0 - specification
WebSphere Development
Studio Client Advanced Edition
V6.0 - specifications
Server iSeries models 170, 250, 270, 7xx, 8xx, 520 or 570
Workstation minimum
For server
development
Intel Pentium II processor
512 MB RAM or better
Intel Pentium III processor
768 MB RAM
For Java, Web,
or WebFacing
development
Intel Pentium III processor
800 MHz recommended
1 GB RAM recommended
Intel Pentium III processor
1.2 GHz recommended
2 GB RAM recommended
For classical
tools only
Intel Pentium II processor
256 MB RAM or better
Hard disk space required
2200 MB
Additional space required for your
development resources
3.5 GB
Additional space required for your
development resources
Additional 1 GB of temporary
space required during installation
Additional 1 GB of temporary
space required during installation
More space is required on FAT32
than NTFS file systems
For classic tools
only
700 MB 700 MB
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

Chapter 4. The IBM WebFacing Tool
71
Table 4-2 Software specifications
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.
Type WebSphere Development
Studio Client Standard
Edition V6.0 - specification
WebSphere Development
Studio Client Advanced
Edition V6.0 - specifications
Server
For server-related
development
OS/400 V5R1 or later
Additional program temporary
fixes (PTFs) required
OS/400 V5R1 or later
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
applications
JRE™ 1.4.0 or higher TCP/IP installed and configured
for profiling applications
JRE 1.4.0 or higher
Run-time support for
WebFacing and Web
Tools applications
WebSphere Application Server
5.1, or 6.0 or Express 5.0, 5.1,
or 6.0
Note: You can reduce the minimum required disk space if optional features and runtimes
are not installed.

72
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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
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
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.
Note: Each application that you deploy requires additional disk space.

Chapter 4. The IBM WebFacing Tool
73
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.

74
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 4. The IBM WebFacing Tool
75
– 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

76
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 4. The IBM WebFacing Tool
77
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.

78
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
Figure 4-3 Selecting the features of the installation
6.On the summary information panel, 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.

Chapter 4. The IBM WebFacing Tool
79
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

80
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 4. The IBM WebFacing Tool
81
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.
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.
Important: The process of downloading and installing the latest fixes takes several
hours. Plan this step accordingly.

82
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.”
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.

Chapter 4. The IBM WebFacing Tool
83
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.

84
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 4. The IBM WebFacing Tool
85
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.
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
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.

86
IBM System i Application Modernization: Building a New Interface to Legacy Applications
– 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.

Chapter 4. The IBM WebFacing Tool
87
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.

88
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 4. The IBM WebFacing Tool
89
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.
Figure 4-12 Creating a new WebFacing Web project
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.

90
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 4. The IBM WebFacing Tool
91
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

92
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
Figure 4-15 Selecting the UIM source members to convert
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.

Chapter 4. The IBM WebFacing Tool
93
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

94
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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
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.

Chapter 4. The IBM WebFacing Tool
95
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.

96
IBM System i Application Modernization: Building a New Interface to Legacy Applications
2.After the conversion, the DSPF Conversion Log (Figure 4-21) is displayed in the editor
panel of your workbench.
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).
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.

Chapter 4. The IBM WebFacing Tool
97
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

98
IBM System i Application Modernization: Building a New Interface to Legacy Applications
3.On the Web Browser page that opens (Figure 4-24), click Launch.
Figure 4-24 Launching the application

Chapter 4. The IBM WebFacing Tool
99
4.In the next Web page (Figure 4-25), log on using your iSeries user profile and password.
Figure 4-25 Signon screen

100
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 4. The IBM WebFacing Tool
101
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.

102
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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).
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
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.

Chapter 4. The IBM WebFacing Tool
103
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

104
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 4. The IBM WebFacing Tool
105
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.
Installing the application on WebSphere Application Server V6.0
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.
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.
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).

106
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

© Copyright IBM Corp. 2006. All rights reserved.
107
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
Part 3

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

© Copyright IBM Corp. 2006. All rights reserved.
109
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.
5

110
IBM System i Application Modernization: Building a New Interface to Legacy Applications
5.1 Modularizing an existing iSeries application
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.
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.
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
.

Chapter 5. Before you create a new user interface
111
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.

112
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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/

© Copyright IBM Corp. 2006. All rights reserved.
113
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.
6

114
IBM System i Application Modernization: Building a New Interface to Legacy Applications
6.1 Model view controller
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

Chapter 6. Application architecture, design, and implementation
115
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

116
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 6. Application architecture, design, and implementation
117
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.

118
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

© Copyright IBM Corp. 2006. All rights reserved.
119
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.
7

120
IBM System i Application Modernization: Building a New Interface to Legacy Applications
7.1 From buzzword to reality: What Web services are
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.

Chapter 7. Designing a Web services interface
121
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.
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.
Static Web Applications
Dynamic Web Applications
Web Services
Portlet Applications

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

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
Figure 7-2 SOA interactions using Web services Description Language
Broker
Provider
Publish WSDL
Look up WSDL
Use WSDL to bind/invoke
2
3
1
Requestor

Chapter 7. Designing a Web services interface
123
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
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
...
<element name="sayHello">
<complexType>
<sequence>
<element name="name" nillable="true" type="xsd:string"/>
</sequence>
</complexType>
</element>
<element name="sayHelloResponse">
<complexType>
<sequence>
<element name="sayHelloReturn" nillable="true" type="xsd:string"/>
</sequence>
</complexType>
</element>
Service or mechanism Technology
Discovery UDDI, Web Services Invocation Language (WSIL)
Description WSDL
XML Messaging SOAP
Transport HTTP, JMS, FTP, SMTP

124
IBM System i Application Modernization: Building a New Interface to Legacy Applications
</schema>
</wsdl:types>
...
<wsdl:service name="GreetingsBeanService">
<wsdl:port binding="intf:GreetingsBeanSoapBinding" name="GreetingsBean">
<wsdlsoap:address
location="http://localhost:9080/WebServiceDemo/services/GreetingsBean"/>
</wsdl:port>
</wsdl:service>
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.
Figure 7-3 Dynamic Web services invocation model
Broker
Requestor
Provider
Implements a service Requests a service
Lists all services

Chapter 7. Designing a Web services interface
125
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.
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.
Web Service Client
(Requestor)
Web Service
(Provider)

126
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
127
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
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.

128
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
129
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.
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.
Web Service
Implemented by programmers
Generated by WebSphere
Development Studio Client
Program Call Bean
RPG
Program
Generated by WebSphere
Development Studio Client

130
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
131
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

132
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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.
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.

Chapter 7. Designing a Web services interface
133
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

134
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
135
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.

136
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
137
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.
Figure 7-15 One step Web services wizard
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.

138
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
139
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.

140
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
141
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

142
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
143
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

144
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
145
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

146
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
147
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

148
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
149
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

150
IBM System i Application Modernization: Building a New Interface to Legacy Applications
7.In the Service Deployment Configuration panel (Figure 7-34), accept the default values.
Note that they should reflect
your
project name. Click Next.
Figure 7-34 Service Deployment Configuration panel
The wizard performs some actions. Be patient.
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.

Chapter 7. Designing a Web services interface
151
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.

152
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 7. Designing a Web services interface
153
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

154
IBM System i Application Modernization: Building a New Interface to Legacy Applications
13.In the Web Service Client Test panel (Figure 7-40), click Finish.
Figure 7-40 Web Service Client Test panel

Chapter 7. Designing a Web services interface
155
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.

156
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
strResult.append("<FINDFLIGHTS>\n");
strResult.append(" <FLIGHTCOUNT>"
+ getflightinfo.getData("FINDFLIGHTS.FLIGHTCOUNT",
ProgramCallBean.INTEGER, idx) + "</FLIGHTCOUNT>\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).

Chapter 7. Designing a Web services interface
157
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).

158
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 7. Designing a Web services interface
159
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

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

© Copyright IBM Corp. 2006. All rights reserved.
161
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.
8

162
IBM System i Application Modernization: Building a New Interface to Legacy Applications
8.1 Overview of JSF technology
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
).

Chapter 8. Designing a JavaServer Faces-based interface
163
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.

164
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
165
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.

166
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 8. Designing a JavaServer Faces-based interface
167
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

168
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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).

Chapter 8. Designing a JavaServer Faces-based interface
169
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

170
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
171
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

172
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
173
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

174
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 8. Designing a JavaServer Faces-based interface
175
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.

176
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
.

Chapter 8. Designing a JavaServer Faces-based interface
177
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

178
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
179
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.

180
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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).

Chapter 8. Designing a JavaServer Faces-based interface
181
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.
6.Click the Submit button to highlight it.
Note: You may also modify the labels for your input fields to make them more readable.

182
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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";

Chapter 8. Designing a JavaServer Faces-based interface
183
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

184
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 8. Designing a JavaServer Faces-based interface
185
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

186
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
187
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.

188
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
189
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.

190
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 8. Designing a JavaServer Faces-based interface
191
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.
Figure 8-30 Web services search
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.

192
IBM System i Application Modernization: Building a New Interface to Legacy Applications
Click the URL.
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.
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
.

Chapter 8. Designing a JavaServer Faces-based interface
193
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

194
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 8. Designing a JavaServer Faces-based interface
195
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

196
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

© Copyright IBM Corp. 2006. All rights reserved.
197
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.
9

198
IBM System i Application Modernization: Building a New Interface to Legacy Applications
9.1 Portal framework
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.

Chapter 9. Designing a portlet client
199
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, pro-
cesses 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
.

200
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
201
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.
Figure 9-1 Portal page
Navigation
Sign in portlet
Portlets

202
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
203
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

204
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 9. Designing a portlet client
205
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.

206
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
207
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.

208
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
209
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.

210
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.
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.

Chapter 9. Designing a portlet client
211
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)

212
IBM System i Application Modernization: Building a New Interface to Legacy Applications
8.If the Confirm Enablement window (Figure 9-7) opens, click OK.
Figure 9-7 Confirm Enablement window
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.

Chapter 9. Designing a portlet client
213
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.
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.
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.

214
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 9. Designing a portlet client
215
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

216
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 9. Designing a portlet client
217
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 = "";

218
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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;
}
}

Chapter 9. Designing a portlet client
219
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" %>
<portlet:defineObjects/>
<%
Flight400PortletSessionBean sessionBean =
(Flight400PortletSessionBean)renderRequest.getPortletSession().getAttribute(Flight400Portlet.SESSION_BEAN);
%>
<DIV style="margin: 6px">
<H3 style="margin-bottom: 3px">Flight Lookup</H3>
<DIV style="margin: 12px; margin-bottom: 36px">
<FORM method="POST" action="<portlet:actionURL/>">
<TABLE>
<tr>
<TD>From City</TD>
<TD><INPUT name="<%=Flight400Portlet.TEXT_FROMCITY%>" type="text"/> </TD>
</tr>
<tr>
<TD>To City</TD>
<TD><INPUT name="<%=Flight400Portlet.TEXT_TOCITY%>" type="text"/> </TD>
</tr>
<tr>
<TD>Flight Date</TD>
<TD><INPUT name="<%=Flight400Portlet.TEXT_FLIGHTDATE%>" type="text"/> </TD>
</tr>
</TABLE>
<INPUT name="<%=Flight400Portlet.FORM_SUBMIT%>" type="submit" value="Submit"/>
<HR>
<TABLE border="1" cellspacing="3" cellpadding="5">
<tr>
<td> Departure City </td>
<td> Time </td>
<td> Arrival City</td>
<td> Time </td>
<td> Airline </td>
<td> Price </td>

220
IBM System i Application Modernization: Building a New Interface to Legacy Applications
</tr>
<% // Java scriplet to display search results %>
<%
FINDFLIGHTSResult results = sessionBean.getResults();
if(results != null) {
FLIGHTINFO[] flightInfo = results.getFLIGHTS();
FLIGHTINFO flight = null;
for(int i=0;i<flightInfo.length;i++){
flight = flightInfo[i];
%>
<tr>
<td><%=flight.getDEPARTCITY() %> </td>
<td><%=flight.getDEPARTTIME() %> </td>
<td><%=flight.getARRIVECITY() %> </td>
<td><%=flight.getARRIVETIME() %> </td>
<td><%=flight.getAIRLINE() %> </td>
<td><%=flight.getPRICE() %> </td>
</tr>
<%
}
}
%>
</TABLE>
</FORM>
<% /******** End of sample code *********/ %>
</DIV>
</DIV>
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

Chapter 9. Designing a portlet client
221
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);
}
/**

222
IBM System i Application Modernization: Building a New Interface to Legacy Applications
* Serve up the <code>view</code> 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("<b>NO PORTLET SESSION YET</b>");
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;

Chapter 9. Designing a portlet client
223
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";
}
}

224
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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
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.

Chapter 9. Designing a portlet client
225
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

226
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 9. Designing a portlet client
227
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

228
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.

Chapter 9. Designing a portlet client
229
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

230
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
231
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;
%>
<jsp:useBean id="com1ibm1flight4001beans1FINDFLIGHTSInput_2id" scope="session"
class="com.ibm.flight400.beans.FINDFLIGHTSInput" />
<%
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
*
*/

232
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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 <code>view</code> 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());

Chapter 9. Designing a portlet client
233
// Check if portlet session exists
Flight400PortletSessionBean sessionBean = getSessionBean(request);
if (sessionBean == null) {
response.getWriter().println("<b>NO PORTLET SESSION YET</b>");
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();

234
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 9. Designing a portlet client
235
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.
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.

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

© Copyright IBM Corp. 2006. All rights reserved.
237
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.
10

238
IBM System i Application Modernization: Building a New Interface to Legacy Applications
10.1 Overview of the rich-client technology
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

Chapter 10. Designing a rich-client interface
239
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).

240
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 10. Designing a rich-client interface
241
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).

242
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
243
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.

244
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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/

Chapter 10. Designing a rich-client interface
245
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.

246
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 10. Designing a rich-client interface
247
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:
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.
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

248
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
249
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

250
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
251
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.

252
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 10. Designing a rich-client interface
253
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

254
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
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.
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.

Chapter 10. Designing a rich-client interface
255
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).
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.
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:
<wsdlsoap:address
location="http://localhost:9080/WebSvc/services/FINDFLIGHTSServices" />

256
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
257
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

258
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
259
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.

260
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 10. Designing a rich-client interface
261
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.
Click Run.
Figure 10-24 VM arguments in the Run wizard
Note: If you are getting “DLL not Found” error messages, try to copy the DLL into a
directory with a shorter path.

262
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
263
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

264
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 10. Designing a rich-client interface
265
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.
Figure 10-30 The getFlights() method
b.Fix the compile errors by adding import statements.
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();
}
}
Note: Use Eclipse’s auto error fix by clicking the error icon on the left side bar and
selecting the import statement.

266
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.
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.
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();
}
});

© Copyright IBM Corp. 2006. All rights reserved.
267
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.
11

268
IBM System i Application Modernization: Building a New Interface to Legacy Applications
11.1 Introducing PHP
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.

Chapter 11. Designing a PHP client
269
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.

270
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

Chapter 11. Designing a PHP client
271
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>IBM Redbook: Hello World</title>
</head>
<h3>Plain HTML</h3>
<p>Hello, World</p>
<body>
</body>
</html>

272
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>IBM Redbook: Hello World</title>
</head>
<h3>PHP embedded in HTML</h3>
<p>
<?php echo "Hello, World" ?></p>
<body>
</body>
</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
<?php
// Include the PHPFunctions file
include_once("phpfunctions.php");
?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>IBM Redbook: Hello World</title>
</head>
<h3>HTML calling an externally defined PHP function</h3>
<p>
<?php HelloWorld(); ?></p>
<body>
</body>
</html>
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 <br>. 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.

Chapter 11. Designing a PHP client
273
Example 11-4 The PHP function definition (file phpfunctions.php)
<?php
function HelloWorld ()
{
// Display "Hello, World"
echo "Hello, World";
}
function Hello10 ()
{
// Display "Hello, World" 10 times
for ($i = 1; $i < 11; $i++)
{
printf("Hello, World<br>");
}
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title><?php echo $template->doctitle ?></title>
</head>
<body>
<?php echo $template->contentTitle; ?>
<?php echo $template->content; ?>
</body>
</html>
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)
<?php
class Template {
public $template_dir;
function show($doc) {
$template = $this;
include($this->template_dir.$doc);
$this->showFooter();
}

274
IBM System i Application Modernization: Building a New Interface to Legacy Applications
function showFooter() {
printf("<br><br><br>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
<?php
include('TemplateClass.php');
$template = new Template;
$template->doctitle = 'PHP using an HTML template';
$template->template_dir = '';
$template->contentTitle = '<h3>PHP using an HTML template</h3>';
$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).

Chapter 11. Designing a PHP client
275
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.

276
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

Chapter 11. Designing a PHP client
277
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

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

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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Using a Web Service from PHP</title>
</head>
<body>
<h2>Flights found:</h2>
<?php
// Create SOAP client
$client = new SoapClient("http://itso:9080/WebSvc/wsdl/com/ibm/flight400/beans/GETFLIGHTINFOServices.wsdl",
array("trace" => 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 <inputData> tags
3
class SOAPWrapper {
function SOAPWrapper($strVal)
{
$this->inputData = $strVal;
}
}
// Create SOAPWrapper that contains SOAPData with values assigned to it 4

Chapter 11. Designing a PHP client
279
$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"<br>Values:<br>";
print_r($arrFl);
// Display array of indexes 10
echo"<br>Index:<br>";
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 "<pre>\n";
//print "Request :\n".htmlspecialchars($client->__getLastRequest()) ."\n";
//print "Response:\n".htmlspecialchars($client->__getLastResponse())."\n";
} catch (SoapFault $exception) {
print_r( $exception );
}
?>
</body>
</html>
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
<inputData> and </inputData> tags. Leaving these out will let the Web services call fail.

280
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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)

Chapter 11. Designing a PHP client
281
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 <user-id> and <password> (in bold) in the file with the appropriate
values for your system, for example “RAK” and “password”.

282
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Access a DB2 Stored Procedure</title>
</head>
<body>
<h3>IBM Redbook authors</h3>
<?php
// First we connect to the iSeries via ODBC
$conn = odbc_connect('Redbook',<user-id>,<password>, 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 "<h3>Result of SQL select</h3>";
$query = "SELECT * FROM REDBOOK.PERSON ORDER BY FIRSTNAME";
$result = odbc_exec($conn, $query);
$ret = odbc_result_all($result);
// Call the stored procedure
echo "<h3>Result of Stored Procedure call</h3>";
$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 "<h3>Result of Stored Procedure call, fetch single row</h3>";
$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) <br>", $row[0], $row[1], $row[2], $row[3]);
}
}
// Close the ODBC connection
odbc_close($conn);
?>
</body>
</html>

Chapter 11. Designing a PHP client
283
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
<?xml version="1.0" encoding="iso-8859-1"?>
<myXML>
<person>
<name>Hartung</name>
<firstname>Guenther</firstname>
</person>
<person>
<name>Klaedtke</name>
<firstname>Rolf Andre</firstname>
</person>
<person>
<name>McCarthy</name>
<firstname>Estela</firstname>
</person>
<person>
<name>Motmans</name>
<firstname>Els</firstname>
</person>
<person>
<name>Nartovich</name>
<firstname>Aleksandr</firstname>
</person>
</myXML>

284
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Read an XML file</title>
</head>
<body>
<h3>IBM Redbook authors</h3>
<?php
if (file_exists('myXML.xml')) {
$x = simplexml_load_file('myXML.xml');
foreach ($x->person AS $person) {
printf($person->name . ' ' . $person->firstname . '<br>');
}
}
else {
exit('Failed to open myXML.xml.');
}
?>
</body>
</html>
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.

© Copyright IBM Corp. 2006. All rights reserved.
285
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
A

286
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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.

© Copyright IBM Corp. 2006. All rights reserved.
287
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/

288
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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/

Related publications
289
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

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

© Copyright IBM Corp. 2006. All rights reserved.
291
Index
Numerics
5722-WDS 76
A
administration console support 49
advanced solutions 11, 16
advantages of rich-client technology 239
application design and implementation 115
application modernization 18
Assemble HATS Project 63
B
B2B (business to business) 202
B2C (business to consumer) 202
B2E (business to employee) 202
Basic Mapping Support (BMS) 46
basic portal architecture 202
basic solutions 11
BMS (Basic Mapping Support) 46
business logic 162
business reasons for implementing portal server 199
business to business (B2B) 202
business to consumer (B2C) 202
business to employee (B2E) 202
Button widget 262
C
Cascading Style Sheets - Positioning (CSS-P) 84
cascading style sheets (CSS) 12
CICS 46
click-to-action 199
Cloudscape 275
CODE 82
CODE Designer 12
Common Object Request Broker Architecture (CORBA)
159
composite 241
CORBA (Common Object Request Broker Architecture)
159
create, read, update, and delete functions 17
CRTRPGMOD 138
CSS (cascading style sheets) 12
CSS-P (Cascading Style Sheets - Positioning) 84
D
DAMP 270
data definition specification (DDS) 67
database access method modernization 112
database physical file 112
DCOM 159
DDS (data definition specification) 67
design approaches 115
design patterns 114
Distributed Component Object Model 159
Domino Builder 204
Dynamic Web application 121
dynamic Web services invocation model 124
E
EAR (enterprise archive) 61
Eclipse 240
auto error fix 265
plug-in project 246
view 246
Eclipse RCP 10, 19, 118, 245
application development 246
applications and IBM Workplace Managed Client 252
Eclipse Rich Client Platform 10, 19, 118, 245
Eclipse Visual Editor 244
editor 245
embedded PHP 272
ENPTUI 16, 45
enterprise archive (EAR) 61
event 241
F
facade pattern 114
FacesServlet 117
fat client 10, 238
flexible architecture 116
front end to a monolithic iSeries application 8
H
H spec 128
HATS 14, 117
5250W connection 50
application 31
application deployment 61
application deployment to the iSeries 61
application development 48
application installation 64
application packaging 63
application preparation for production 59
business scenarios 16
changes to the current business practices 15
connection settings 50
default template 51
deployment requirements 27
development requirements 26
example 48
hardware 14
hardware and software requirements 26
installation and configuration 37
installation of the application 64
integration capabilities 28

292
IBM System i Application Modernization: Building a New Interface to Legacy Applications
investment 14
loss of HATS perspective 43
new features 45
portlet 204
preparation of your HATS application for production
59
project implementation requirements 28
project implementation strategy 30
project initiation and problem identification 30
project scoping 29
proof of concept 33
refresh pack 39
rendering rules 55
rules engine 28
runtime enablement 61
runtimeenablement.jar file 62
skills 15
skills requirement 29
software 14
time 15
typical case studies 32
unit and function testing and problem resolution 31
upgrade 39
user testing and problem resolution 31
user training and project documentation 31
HATS (Host Access Transformation Services) 14, 25
HATS Studio 26
installation 37
updgrade 39
HATS Toolkit 9, 35
installation 38
HATS Trial Toolkit
upgrade 44
HATS Trial Toolkit upgrade 44
HATS V6.0 45
HATS V6.0.1 47
HATS V6.0.2 47
HATS V6.0.3 47
HATS V6.0.4 48
Host Access Transformation Services (HATS) 14, 25
host server, starting 86
HTML 12
I
i5/OS PASE 274
IBM System i Developer Roadmap 5
IBM Systems Workload Estimator 208
IBM Toolbox for Java 9
IBM Toolbox for Java API 10
IBM Toolbox for Java ProgramCall mechanism 164
IBM WebFacing Deployment Tool for WebSphere Devel-
opment Studio V6.0.1 with HATS Technology 34, 48
benefits 34
enablement key 34
for HATS customers 34
for WebFacing customers 35
package contents 35
PTFs to enable 36
purchasing 37
purchasing scenarios 36
runtime license enablement file 35
IBM WebFacing Tool 9, 11
business scenarios addressed 14
changes to the current business practices 13
hardware 12
investment 11
skills 12
software 11
time 12
IBM WebSphere Portal Server 202
IBM WebSphere Portal Server on System i 205
IBM Workplace Managed Client 10, 19, 252
IBM-provided tools 11
ILE path pros and cons 111
Integrated Language Environment (ILE) 109
INVITE 13
iSeries
error list 139
integration of applications and Java 112
iSeries Access for Web 9, 27, 117
portlets 204
J
Java GUI API 240
Java rich-client development options 240
Java Standardization Request (JSR 168) 202
JavaScript 12
JavaServer Faces (JSF) 9, 16, 46, 117, 162, 164
JDBC Builder 204
JDBC Portlet builder 208
JFace 118
JSF (JavaServer Faces) 9, 16, 46, 117, 162, 164
application testing 188
binding 163
binding Java beans to JSF pages 180
business scenarios addressed 18
changes to the current business practices 18
control generation for output JSF 184
development environment 163
events 163
framework 162
hardware 17
investment 16
Java beans added to the JSF pages 178
JSF application testing 188
ProgramCall mechanism 165
properties 163
sample application 164
skills 17
software 16
time 17
Web service invocation 164, 189
what’s next 196
JSF (JavaServer Faces) components 163
JSF technology 16
overview 162
JSF-based interface 161
JSR 168 (Java Standardization Request) 202

Index
293
K
KBS.js 15
keyboard mapping file 15
L
label widget 262
LAMP 270
LF (logical file) 112
linking program 110
logical file (LF) 112
Lotus QuickPlace 207
Lotus Sametime 207
M
MAMP 270
markup fragment 201
MDI (Multiple Document Interface) 241
MENUBR 13
Microsoft .Net 10
Microsoft Visual Basic 244
MLTCHCFLD 13, 46
MNUBAR 46
model view controller (MVC) 114, 162
modernization 110
application 18
database access method 112
OPM program 110
reasons for a change 4
modular and monolithic host applications 18
modular RPG applications as Web service 10
modularization 110
Multiple Document Interface (MDI) 241
MVC (model view controller) 114, 162
controller 114
design pattern 17
model 114
view 114
N
native portlet support 84
O
object oriented architecture 122
OPM (Original Programming Model) 8, 109
OPM program modernization 110
OPM versus ILE RPG 110
Original Programming Model (OPM) 8, 109
out-of-the-box portlets 204
P
PCML (Program Call Markup Language) 137
PDM 204
PDM Screen Design Aid (SDA) 13
PEAR 276
PeopleSoft Portlet Builder 208
PERL 268
Personal Home Page/Form Interpreter 268
PF (physical file) 112
PHP 20
brief history 268
business scenarios addressed 21
client 267
client design 267
community 268
hardware 20
HTML templates 273
introduction 268
investment 20
requirements 270
simple examples 271
skills 21
software 20
System i platform 274
technology overview 269
users 269
XML 283
PHP 5 269
PHP example
calling a DB2 Stored Procedure with PHP 280
consuming a Web service using PHP 278
PHP Extension and Application Repository 276
PHP/FI 268
physical file (PF) 112
portal
architecture 202
framework 198
pages and portlets 201
project creation 210
Portal Document Manager 204
portal front end
for a modular RPG application 10
to a monolithic iSeries application 9
portal server
application and information integration 198
collaborative capabilities 198
common presentation 198
document management 199
framework for Web services 198
improved decision making 199
increase in employee productivity 199
increased customer satisfaction and lower operating
cost 199
increased efficiency through automation 199
personalization and customization 198
quicker response to customer inquiries 199
single sign-on (SSO) 198
support for pervasive devices 198
technical definition 198
technology overview 200
portlet 10, 117, 200
applications 117
catalog 204
container 200
content produced 201
creation to access iSeries application and data 207
decorations 201
deployment 226

294
IBM System i Application Modernization: Building a New Interface to Legacy Applications
title bar 201
portlet API 10, 200
Portlet Builder 208
Portlet Builder for Domino 208
portlet developer 203
portlet development with iSeries Tools 207
portlet example 209
generating a Web service client 227
invoking a Web service 227
invoking the ProgramCall bean 221
modification of the generated code 231
modification of the portlet source code 216
modifying JSP 219
portlet testing 224
SessionBean 217
Program Call Markup Language (PCML) 137
ProgramCall JavaBean 129
ProgramCall Wizard 140
proxy 153
PSHBTNCHC 13
PSHBUTTON 46
PULLDOWN 46
Q
QqfEnvironment 13
R
Rational Application Developer 26, 37
Rational Software Development Platform 77
Rational Studio Architect 26, 37
Rational Web Developer 26, 37
Redbooks Web site 289
contact us xi
refacing technologies 115
Remote Method Invocation (RMI) 159
Remote Systems Explorer (RSE) 81
connection verification 81
rich client 10, 19, 238
advantages and disadvantages 239
application accessing a Web service example 254
applications 118
business scenarios addressed 20
clickable widgets 242
closer look 241
development platform 242
Eclipse IDE 242
Eclipse RCP application development 246
focus events 242
front end for a modular RPG application 10
hardware 19
investment 19
keyboard events 242
Microsoft .Net 253
multiple document interface 241
shells 241
skills 20
software 19
SWT application development 244
technologies 19, 253
technology choices 240
technology overview 238
widgets 241
window 241
RMI (Remote Method Invocation) 159
RPG IV 128
RSE (Remote Systems Explorer) 81
runtimeenablement.jar 62
S
SAP Portlet Builder 208
scenarios overview 8
Screen Design Aid (SDA) 8, 13
screen scraper 28, 68
SDA (Screen Design Aid) 8, 13
SDO (Service Data Objects) 18
server-side scripting language 268
Service Broker 122
Service Data Objects (SDO) 18
service provider 122
Service Provider Interface (SPI) 202
service requestor 122
service-oriented architecture (SOA) 122
SEU (Source Edit Utility) 8, 13
SFLMLTCHC 46
SFLSNGCHC 46
Sieble Portlet Builder 208
single sign-on (SSO) support 85
SNGCHCFLD 46
SOA (service-oriented architecture) 122
SOAP 124
SOAP Transport Layer 124
Source Edit Utility (SEU) 8, 13
SPI (Service Provider Interface) 202
SQL (Structured Query Language) 112
Standard Widget Toolkit (SWT) 10, 19, 118, 240
static invocation model 125
stored procedure 281
structured host applications 18
Structured Query Language (SQL) 112
Swing API 10, 118, 240
SWT (Standard Widget Toolkit) 10, 19, 118, 240
SWT application development 244
System i platform and PHP 274
system screens support 85
T
table widget 262
TableColumn widget 262
technology stack, Web services 123
text widget 262
thin client 238
thread safety implementation in an RPG program 128
thread safety in an RPG program 128
Tivoli Access Manager 27
U
UDDI (Universal Discovery, Description and Integration)

Index
295
123
registry 125
UIM-based Help panel 13
UIM-based screen 13
Universal Discovery, Description and Integration (UDDI)
123
up-front considerations and prerequisites 5
V
VE (Visual Editor) 244
view 245
Visual Basic 244
Visual Editor (VE) 244
W
WAMP 270
Web front end for a modular RPG application 9
Web service
client generation 227
consume (use) 158
creation 127
creation from the ProgramCall JavaBean 147
development cycle 125
interface design hints 158
URI 151
Web services 120
advantages and disadvantages 158
bottom up approach 126
consuming 158
development approach 125
interface considerations 127
invocation model 124
meet-in-the-middle approach 126
methods 151
security configuration 151
stateless versus stateful 126–127
static invocation model 125
style and use 151
technology stack 123
testing and deployment 127
top-down approach 126
Web Services Description Language (WSDL) 123, 151
Web Settings view 83
Web Site Designer 94
WebFacing 116
application deployment to the iSeries 101
application installation on WebSphere Application
Server V6.0 105
deployment requirements 71
development requirements 69
hardware and software requirements 69
new features 83
packaging the application 105
portlet 204
project creation 88
project implementation strategy 73
project initiation and problem identification 74
recommended implementation phases 73
recommended skills 73
sample WebFacing application 86
starting host servers 86
starting the WebFacing server 87
support for system screens and non-WebFaced appli-
cations 102
testing WebFacing application 96
unit and function testing and problem resolution 75
user testing and problem resolution 76
versus screen scrapers 68
WebFacing application deployment to the iSeries 101
WebFacing project creation 88
WebFacing Deployment Tool for WebSphere Develop-
ment Studio V6.0.1 with HATS Technology 34
WebFacing Deployment Tool with HATS Technology 34
WebFacing Runtime Server 69
WebFacing Runtime Servlet 69
WebSphere Application Portlet Builder 208
WebSphere Development Studio Client
Agent Controller 79
creation of input and output JSF pages 174
Installing and configuring WebSphere Development
Studio Client V6.0 76
required PTFs 81
starting 88
V6.0 upgrade 80
WebSphere Development Studio Client for iSeries 8, 26,
37
WebSphere Development Studio Client for iSeries V6.0
69
WebSphere Development Studio Client V6.0
installation and configuration 76
upgrade 80
WebSphere Portal 10, 117
WebSphere Portal Enable 205–206
WebSphere Portal Extend 205, 207
WebSphere Portal Server
basic content publishing 204
Click-to-Action 207
creation of portlets that access iSeries application and
data 207
deployment requirements 208
development requirements 208
Domino Web Access 204
hardware and software requirements 208
out-of-the-box portlets 204
People Finder 204
portlet development with iSeries Tools 207
prerequisites 208
productivity components 204
skills needed 209
writing custom portlets 208
WebSphere Portal UTE 224
WebSphere Portal Version 6.0 205
widgetSelected event 242
WINDOW 46
workbench 245
Workplace Forms 207
Workstation Data Manager 69
WPCP Portlet Builder 208
WSDL (Web Services Description Language) 123

296
IBM System i Application Modernization: Building a New Interface to Legacy Applications
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

(0.5” spine)
0.475”<->0.873”
250 <-> 459 pages
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
IBM System i Application Modernization: Building a New Interface to Legacy

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


®
SG24-6671-00 ISBN 0738494844
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed
by the IBM International
Technical Support
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
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
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.
Back cover
First page image
We are pleased to offer a download of this document free of charge.
Files available for download:
  • a representative PDF of the primary file (contains all the relevant information for most users)
To obtain the file, please enter the "captcha" below and click the Download button.
Avoid entering CAPTCHAs! Sign In or Create a Free Account.

Challenge image
  • Please enter letters and numbers only; no spaces.
  • Cannot read this one? Click the image.
  • Difficulty with captchas? Contact us with the URL of this page and we will email it to you.