App Builder Deploying Applications

BluePhoenix AppBuilder 2.1.0.
Deploying Applications Guide
BluePhoenix AppBuilder 2.1.0. Document Title April, 2003 Corporate Headquarters BluePhoenix Solutions Vlierwerf 7B 4704 SB Roosendaal The Netherlands +31 (0) 165 399 401 +31 (0) 165 396 308 fax USA Headquarters BluePhoenix Solutions USA, Inc. 8000 Regency Parkway Cary, NC 27511 United States +1 919.380.5100 +1 919.380.5111 fax www.bluephoenixsolutions.com
1992-2003 BluePhoenix Solutions All rights reserved. BluePhoenix is a trademark of BluePhoenix Solutions. All other product and company names mentioned herein are for identification purposes only and are the property of, and may be trademarks of, their respective owners. Portions of this product may be covered by U.S. Patent Numbers 5,495,222 and 5,495,610 and various other non-U.S. patents. The software supplied with this document is the property of BluePhoenix Solutions, and is furnished under a license agreement. Neither the software nor this document may be copied or transferred by any means, electronic or mechanical, except as provided in the licensing agreement. BluePhoenix Solutions has made every effort to ensure that the information contained in this document is accurate; however, there are no representations or warranties regarding this information, including warranties of merchantability or fitness for a particular purpose. BluePhoenix Solutions assumes no responsibility for errors or omissions that may occur in this document. The information in this document is subject to change without prior notice and does not represent a commitment by BluePhoenix Solutions or its representatives.
TABLE OF CONTENTS
Table of Contents
AppBuilder 2.1.0 Deploying Applications Guide
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1
Related Material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Deployment Terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 What is a Standalone Application? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 What is a Distributed Application?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 What is a Configuration?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 What is Preparation? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Configuring the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Setting Project Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Selecting Standalone Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Selecting Distributed Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Using the Configuration Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Adding Objects to the Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Using the Hierarchy Objects Toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Understanding Hierarchy Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Using the Insert Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Adding an Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Adding a Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 Building a Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 Setting Partition Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Associating Physical Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Configuring for Remote Mainframe Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Adding a Process Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14 Adding Rules to a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 Adding a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Using the Project Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17
Preparing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Understanding Preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Knowing Ways to Prepare. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Meeting Java Preparation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Avoiding Common Mistakes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparable Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generated Output Language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3-2 3-3 3-3 3-4 3-6
Preparing an Application (in the Hierarchy Window) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 From the Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 From the Project Tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 From the Repository Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Preparing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Using Advanced Preparation Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Workgroup Repository Rebuild
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Rebuild Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Enabling a Group Repository for Rebuild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Rebuild Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Rebuild Functionality Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7 Using Rebuild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Rebuilding from a Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12 Rebuilding from an Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-13 Sorting the Rebuild Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-14 Saving the Rebuild Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15 Running a Rebuild or Rebuild Report Using the Active Configuration. . . . . . . . . . . . . . . . . . . . . 4-15 Mark All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-15
Preparing to the Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Using Supported Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Installing and Configuring the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Configuring the Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2 Setting the Workbench Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 Preparing the Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4 Seeing the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Packaging the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

Handling a Standalone Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Handling a Thin Client (HTML) Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Finding the Generated Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Finding the Archive File and Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Creating Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Assembling and Deploying the Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 Handling a Java Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Table of Contents
Handling a Windows Client/Server Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 Finding the Generated Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 Deploying the Client Side of an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Deploying the Server Side of an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Migrating Modules to the Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Deploying Java on WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Configuring the Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Configuring the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Configuring for WebSphere 3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4 Configuring for WebSphere 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5 Deploying the EJB Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Deploying EJB on WebSphere 3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Deploying EJB on WebSphere 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6 Updating the Thin Client Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7 Deploying the Partition for Thin Client and Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7 Deploying Partition on WebSphere 3.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8 Deploying the Partition on WebSphere 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Testing the Deployed Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Testing Thin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9 Testing EJBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 Testing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
Deploying Java on WebLogic
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Configuring the Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2 Configuring the Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Deploying the EJB Partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Configuring for EJB Deployment in WebLogic 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Configuring for EJB Deployment in WebLogic 6.0 or Higher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Deploying EJB in WebLogic 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4 Deploying EJB in WebLogic 6.0 or Higher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6 Updating the Thin-Client Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 Deploying the Partition for Thin-Client and Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7 Deploying the Servlet Partition for WebLogic 5.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8 Deploying the Servlet Partition in WebLogic 6.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-8 Testing the Deployed Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Executing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

Extracting the Web Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 Customizing the Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 Setting Thin-Client Execution Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2 Setting Web Service Execution Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3
Table of Contents
Configuring for Thin Client Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Creating an Alias (or Context) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3 Creating a Start Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Configuring the Web Client Session Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-4 Setting Client Authentication with HTTP Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 Using Remote Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 Specifying Character Encoding for MLS Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-5 Recreating the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Executing an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Executing from the Construction Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Executing from the Start Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-6 Executing from the Command Line. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Executing a Java Applet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7 Setting up RMI Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12 Invoking an AppBuilder Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 AppBuilder Web Service XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-13 Sample Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-14 AppBuilder Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-17 Third-Party Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18 Running the Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-18 Invoking an AppBuilder RMI Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19 Understanding Execution Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-19 ObjectSpeak Event Differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-20 ObjectSpeak Property Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-21 ObjectSpeak Method Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22 Differences Between Java and C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-22 Using Date Completion Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23 Date Completion Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23 Sample Date Completions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-23
10 Deploying Java on Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

Configuring the Initialization Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1 Updating the Thin-Client Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Configuring Tomcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3 Testing the Deployed Java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4 Testing Thin Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4 Testing Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-5
11 Troubleshooting Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

Resolving Partitioning Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1 Resolving Packaging Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2 Resolving Communication Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3 Resolving Execution Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Table of Contents
Using System Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Supported Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Thin-Client (HTML Client with Servlet) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1 Java Client on a Departmental Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-2 Windows Client/Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-3 Traditional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-4
Sample Distributed Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Migrating Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Building Distributed Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 Deploying Application Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4 Running Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-5
Command Line Rules Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1
Table of Contents
Table of Contents
CHAPTER
INTRODUCTION
After you have designed and developed an application, you are ready to discover the real power of AppBuilder to generate and deploy the application that may execute on a number of different environments. This guide explains how to configure, partition, prepare, verify, and deploy your application in a multi-tier environment using AppBuilder. With the integrated tool suite of the Construction Workbench, you can prepare files for a distributed application on remote clients and servers, from Windows machines to UNIX servers to mainframe hosts. This includes support for COBOL, C Language, or Java, support for Web archive deployment and remote rule execution, and support for different execution modes (converse or event-driven). Your applications can use any of a variety of end-user interfaces: program group, pull-down menu option, or command line. This guide explains how to use the AppBuilder product to handle: Configuring the Application (including partitioning) Preparing the Application (including verification) Packaging the Application (for deployment on various machines) Deploying Java on WebSphere or Deploying Java on WebLogic or other application servers Executing the Application To help you get started with the deploying process, we have pointers to Related Material. Next, we begin by introducing some Deployment Terminology. For information on deploying parts of the application on a mainframe, refer to the enterprise documentation for migrating and preparing files. Prerequisites to using these procedures include basic application development experience and familiarity with Microsoft Windows (either NT or 2000). We assume you understand distributed environments and are familiar with the concepts of distributed applications, but may not know how to implement these types of applications with the AppBuilder product. We assume that you are already familiar with developing applications with AppBuilder using the Construction Workbench. If you are not familiar with these topics, refer to the Product Concepts Guide and the Developing Applications Guide before reading this one. For information on debugging the application, whether in C or in Java, refer to the Debugging Applications Guide.
1-1
Related Material
Related Material
One of the key strengths of using AppBuilder is the ability to develop and deploy distributed applications from a single workstation. With the Construction Workbench tool in cooperation with the repositories and mainframe tools, you can take an application and deploy it to remote clients and servers at several levels throughout your enterprise. For other basic concepts of distributed application development, refer to the Product Concepts Guide. For information about mainframe migration and preparation, refer to these documents: Enterprise Administration Guide Enterprise Development Guide Enterprise Migration Guide If you would like detailed information about the capabilities of AppBuilder, you can also refer to these other documents: Information Model Reference Guide Rules Language Reference Guide Workgroup Repository Administration Guide Personal Repository Administration Guide There is some setup required that is covered in the Installation Guide for Windows (or platform you are using). On desktop and workstation machines, you configure preparation and run-time hosts during a part of the installation procedure. There is also some setup described in the Configuring Communications Guide to handle remote preparation at development time and to execute remote procedure calls (RPCs) and eventing applications at run time.
Deployment Terminology
There are many terms that are unique to AppBuilder and to enterprise-wide deployment. Before you continue with deploying an application make sure you can answer these questions: What is a Standalone Application? What is a Distributed Application? What is a Configuration? What is Preparation?
What is a Standalone Application?

When you begin to develop an application, you can work in standalone mode in the Construction Workbench so that the generated files are put locally on your development workstation. This is the easiest way to test the execution of the application or parts of the application. Applications developed as standalone only run on the local workstation.
1-2
Introduction
What is a Distributed Application?

A distributed application can be executed on multiple platforms on multiple machines at any of several tiers throughout the enterprise while created on a single development workstation with AppBuilder. This can be done when you work in distributed mode in the Construction Workbench. The rules drive the application, and the windows they display to the end user function as vehicles for end-user input and output. A rule can take different actions based on input of an end user by means of the window controls. In a distributed application, different rules can run on different machines with different platforms. Most of the objects and controls appearing in the windows are data linked to fields in the AppBuilder repository. That repository may be a local (personal) repository or one shared by others on the network (group repository) or it may reside on the mainframe. The overall supporting organization of repository objects is called an application hierarchy and is defined using the Hierarchy window in the Construction Workbench. The application hierarchy is comprised of the applications function, processes, rules, windows, data views and fields, and so forth.
What is a Configuration?
Before an application can be deployed and executed, you must define within AppBuilder the configuration of the application. For a distributed application, configuration involves defining partitions, the assignments of parts of the application to various clients and servers on various machines in the network. A configuration is the way you specify how the application is to be deployed on specific machines. The settings for a Project include whether the function is standalone or distributed, and if distributed, which configuration or set of configurations apply.
What is Preparation?
When you are done developing your application and defining the configuration, you can prepare your application for the execution environment with AppBuilder. Preparation is the collection of steps that transform a humanly readable representation of actions and data into a machine-executable form. You can prepare client or server components for execution on diverse operating systems and machines against diverse database management tools. As long as you have specified a valid application configuration and installed the necessary preparation software on target machines, the Construction Workbench sends the generated code to the correct machine and compiles and links that code for the resident operating system of that machine.
1-3
Figure 1-1
Deployment scheme in a development environment
In the Construction Workbench, you can prepare application objects from either the Project tab or the Repository tab of the Hierarchy window or, if a distributed application configuration is selected, you can also prepare from the Configuration tab of the Hierarchy window. Remote preparation allows the objects you have selected to be prepared on the machine or machines on which they are executed, thus allowing you to develop on one machine and deploy on all the machines in the configuration. For Java applications, you can develop downloadable, thin-client Java applications that run on any platform that supports the Java virtual machine (JVM). This guide provides the information to deploy applications on the Java Virtual Machine. For information on developing these applications or on converting existing applications to generate Java client programs, refer to the Developing Applications Guide.
1-4
Introduction
CHAPTER
CONFIGURING THE APPLICATION
In an AppBuilder application, the project is the highest level of the application hierarchy; it contains the business function and associated configuration(s) of the application. A function represents the highest level business processthe purpose of the application. Functions contain groups of processes that subdivide the application. A configuration is how the application is to be deployed on specific machines. The settings for a Project include whether the application is standalone or distributed, and if distributed, which configuration or set of configurations apply. Before deploying the application, you must define the configuration of that application. Configuration involves defining partitions, the assignments of parts of the application to various clients and servers on various machines in the network. Use partitions to specify how the parts of the project are prepared (compiled). This section explains the procedures for configuring the application in the Construction Workbench and defining partitions using the Configuration tab of the Hierarchy window. Configuration involves: Setting Project Options Using the Configuration Hierarchy Adding Objects to the Hierarchy Adding an Application Configuration Adding a Partition Building a Partition Using the Project Toolbar
2-1
Setting Project Options

In the Construction Workbench, use the Project Options window to set the application's configuration to either Standalone or Distributed. Select File > Project Options or right-click on the project in the Project tab of the Hierarchy window and select Project Options, or use the short-cut Ctrl+Alt+P. Selecting Standalone Applications Selecting Distributed Applications
Figure 2-1 Project Options window
1. Select one.
2. If Standalone, select options. OR 2. If Distributed, select a configuration and partition.
There are two places where you specify whether you want to prepare for C or Java. If the project is open, then you specify it in the Project Options dialog. If no project is open, then you specify it in the Workbench Options, the Preparation tab, in the button under If no project is open. Java is generated if the Java application button is selected and C is generated if the Windows application is selected. In the Workbench Options, Preparation tab, the Application type combo box under Function prepare lets you specify different parameters for the Function prepare. For example you may want to create desktop objects for C and append functions on the menu for Java. For more information on the Workbench Options, refer to the Development Tools Reference Guide.
2-2
Configuring the Application
Selecting Standalone Applications

For standalone applications (those prepared and executed on a single workstation), select the Standalone application radio button in the By default, prepare as section of the Project Options dialog. A standalone application is any application that is intended to run only on one machine, independent of the rest of the network. This option also can be used for testing and debugging on your local workstation.
Figure 2-2 Standalone application options
Select the type of application.
Identify database, if used, and, if needed, the logon information.
Select if you want to prepare the rules locally that would go to the mainframe or just check syntax.
In that same dialog, select the application type (Java or Windows). Select the type and name of the database and if there is security, enter the logon information. Include Mainframe Rules When using an existing application that contains rules that execute on a mainframe and you want to prepare the entire application locally to test the business logic, select the Include Mainframe Rules. This allows you to prepare the application including those rules that usually get prepared on the mainframe; however, certain rules, including mainframe database rules, cannot be prepared locally. If you deselect this choice, the system only checks the syntax of the mainframe rules (and provides warnings) but does not prepare them. Click OK to accept any changes. For more information about standalone application development, refer to the Developing Applications Guide.
2-3
Selecting Distributed Applications

For distributed applications, configure the logical servers and clients on which the application executes by partitioning the application.
Figure 2-3 Distributed application options
Select the Application Configuration from the drop-down list then select the partition from the available partitions of that configuration.
Within the Construction Workbench the project must have a configuration that designates the clients and servers of the system by defining them in partitions. Use the Configuration tab in the Hierarchy window to define the application's configuration. You build the configuration hierarchy by adding objects and defining the properties of these objects. A project may have several configurations.
2-4
Using the Configuration Hierarchy
Using the Configuration Hierarchy

In the Hierarchy window, select the Configuration tab. If you have not yet defined the configuration, only the project name appears at the top of the window.
Figure 2-4 Sample configuration with multiple partitions
The configuration objects are shown in a hierarchy.
The appearance of the hierarchy in the Configuration tab is different from the view of the hierarchy in the Project tab. You can explore the content of the partitions until you find a rule that is a frontier rule of another partition of the same application configuration; those rules are marked with a special icon and cannot be expanded.
Note
To turn off the object type (only show the icon and the name) in the Configuration tab, go to Tools > Workbench Options and select the Hierarchy tab and deselect Display object types.
A rule may appear to belong to both the client partitions process and the server partitions server, but it is subtracted from the client process and is built only on the server. The order of preparation is to consider the client partition first and include all the rules underneath it in the configuration scheme and then subtract the rules that appear in the subsequent server and client partitions.
Figure 2-5 Typical configuration procedure
Step 1. Add to a Project an Application Configuration.
Step 2. Add at least a Client and Server Partition.
Step 3. For the Client Partition: Set partition properties to Client. Add a Machine and a Process container.
Step 4. For the Server Partition: Set partition properties to Server. Add a Machine and a Server container. Step 5. Add Rules.
2-5
Adding Objects to the Hierarchy
This involves creating a configuration from scratch. To create a configuration from rules that already exist in the repository, when you insert a rule, choose the rule from the Insert (Query) window by its name in the repository. Click Insert. As you build the configuration and add objects, commit the changes to the repository. While you work on the configuration, the changes are not saved to the repository until you click File > Commit (or select the Commit button on the toolbar). When you commit, the entire set of changes are made to the repository, both for object properties and relationships between objects.
Adding Objects to the Hierarchy

To add objects to the hierarchy in the Configuration tab, use one of these methods: Using the Hierarchy Objects Toolbar Using the Insert Menu (from right-click or from pull-down) Be sure you follow some basic instructions about the placement of objects in the hierarchy. Understanding Hierarchy Order
Using the Hierarchy Objects Toolbar

The Hierarchy Objects toolbar provides a method for quickly adding objects to your configuration. Within a project, you must first add a configuration. 1. 2. To display the toolbar, select View > Toolbars from the Construction Workbench menu. In the Toolbars window, select the Hierarchy - Objects toolbar and click Done.
Hierarchy Objects toolbar (used with Configuration tab) Process Machine File
Figure 2-6
Application Configuration
Partition
Server
Database
Rule
Understanding Hierarchy Order

An application configuration, as a collection of partitions, contains the information (and other objects) needed to prepare a distributed application, to migrate it to a production environment, and to administer the application at run-time on a particular machine or machines. The application configuration defines where and how the application is deployed.
2-6
Adding an Application Configuration
Using the Insert Menu

You can add objects to the configuration hierarchy by using one of the following methods: Right-click on an object type in the configuration hierarchy and select Insert. Select an object type in the configuration hierarchy and select Insert from the Construction Workbench. The contents of Insert menu differs depending on the object in the configuration hierarchy selected. If the new object can only be inserted as a child of the selected object, then the command works as an Insert Child. If the new object can only be inserted as a sibling of the selected object, the command works as an Insert Sibling. If the new object can be inserted as a child or a sibling, the operation specified on the Hierarchy tab of the Workbench Options dialog is tried first. and if it fails, then the other operation is tried. If the object can be created but cannot be linked as a child or as a sibling (perhaps because you do not have permissions to modify these objects), then the new object is inserted into the Repository tab. After you select an object type, an Insert (Query) window is displayed to allow you to select a specific object from the repository. From the Insert window, query the repository or type in the name of an object. Click Insert when you have selected the specific object you want to place in the configuration hierarchy.
Figure 2-7 Insert Menus Menu for Partition Menu for Process or Server or Machine
Menu for Application Configuration
Adding an Application Configuration

Use the hierarchy objects toolbar or the insert menu to begin to create your configuration by inserting an application configuration object in the Configuration tab. This is the highest level object in the configuration hierarchy that can be inserted. There can be several application configuration objects and each appears directly under the Project node in the hierarchy. You can define several different application configurations to allow the application to be configured for deployment on several different sets of machines in different environments. These different configurations can be managed from one project in the configuration hierarchy.
2-7
Adding a Partition
Adding a Partition
Partitions allow you to specify the information about the platform on which your application runs. Partitions define the associations between a client or server (or gateway) and its associated machines or databases. Each partition must be associated with an application configuration. For more information on building a partition by adding machine, process, and server objects, refer to Building a Partition. Client partitions Client partitions contain the projects processes to execute on the client-side. When you add a process from the projects hierarchy to the configuration, AppBuilder automatically includes all the necessary child objects (for example, rules, views, etc.). In addition, the client partition includes a machine object that indicates the clients execution environment. Server partitions Server partitions include a server object. This partition defines the type of server (for example, an EJB server). In the server partition, insert the rules that execute on the server-side. Gateway partitions - Gateway partitions forward client requests to a server partition running in the same or remote server. The Gateway partition should include an AppBuilder server object with all the associated rules. This server object should be the same as the one defined for the remote server as the gateway partition is forwarding requests for the same frontier rules. For preparation, select the specific configuration or partition to prepare. You can do this in several ways: directly from the Configuration tab by highlighting the partitions or configuration to prepare from the Project Options dialog box (as in Figure 2-3) by selecting the partitions or configuration to prepare from the drop-down lists of partitions and configurations in the Project toolbar For a gateway partition, the icon in the hierarchy distinguishes it from server partitions as shown in Figure 2-8.
Figure 2-8 Gateway partition in hierarchy
A gateway partition has a small i over the symbol.
For a gateway, only frontier rules are listed and are shown with a different Rule icon, one with an I over it.
2-8
Building a Partition
A partition contains the information about the machine on which the business logic is prepared and about which rules run on that machine. So a client partition has a machine object (to specify the machine that the client runs on) and a process object (to specify which part of the client application runs on that machine). There may be more than one process object for a partition. The machine object identifies the specific physical machine in the network, while the process object contains the rules that run on that client. Similarly, a server (or gateway) partition has a machine object and a server object. The server object contains the rules that run on that server. (For a gateway, only the frontier rules are specified.) These rules are excluded from the rules on the clients. The rules designated as belonging to the server are then subtracted from the rules in the process in the client application configuration. A database object (no more than one) can be attached to a partition to specify the database type and the database name. Building a partition consists of these tasks: Setting Partition Properties Associating Physical Machines Configuring for Remote Mainframe Preparation (for preparation to the mainframe) Adding a Process Container Adding Rules to a Process Adding a Database
2-9
Setting Partition Properties

After creating partitions, set the types of generated language and server interface (for servers) or client type (for clients) for each partition. With the partition selected, select View > Properties (or right-click Properties or double-click the partition) to view the partition properties.
Figure 2-9 Partition properties
Select whether this partition is for client or server. If client, select type. If server, select interface for communication. Select the language of the generated code.
A package name may be required if the server interface is EJB.
Caution
If the Server Interface is EJB, the package name (in the Package field) may be mandatory. This depends on which application server you are using. Some application servers (like WebSphere 3.5) require a package name for preparing EJBs, and if the package name is not supplied, an error occurs at deployment time. Check the application server documentation to find out whether a package name is required.
Select the following properties based on the type of platform on which the application executes.
Table 2-1 Platform Java client Web (HTML) client Windows client EJB server (Windows) C server RMI server Web service EJB gateway Web service gateway Configuration summary Partition Type Client Client Client Server Server Server Server Gateway Gateway Client Type EventDriven HTML Converse N/A N/A N/A N/A N/A N/A Server Interface N/A N/A N/A EJB NetEssential RMI Web service EJB Web service Language Java Java Default Java Default Java Java Java Java
2-10
Associating Physical Machines

Part of the task of building a partition is the assignment of the physical machine on which that partitions software is intended to execute. To associate a physical machine with a partition, add a machine object to the hierarchy. This applies whether the partition type is a client or server or gateway. This includes specifying the type of machine on which the prepared item is executed and the operating system of that machine. Select the machine icon in the Configuration tab and right-click to select Properties. In the Properties window, choose the operating system from the list and type in the implementation name. These properties are stored in the repository and associate the partition with a physical machine. When the client partition is being prepared on the users machine, the implementation name must be set to Local. "Local" is a keyword that can only be used for a client partition. When the implementation name is not set to Local, the client partition is prepared remotely to the machine that is listed.
Figure 2-10 Setting machine properties
Select the operating system. Enter Local to prepare this partition on this workstation.
2-11
Configuring for Remote Mainframe Preparation

To allow entities from a local or group repository to be prepared on a remote mainframe, a mainframe partition must be defined in the hierarchy. The partition should contain at least one server, a machine, and a database (if using DB2, for example) as shown in the hierarchy in Figure 2-11. The hierarchy under the server should contain all of the objects that are to be prepared to the mainframe.
Note
Partitions (Configuration Units) are used differently for preparation when using the mainframe workbench. On the mainframe the preparable entity is added directly to the Partition. To use partitions on the mainframe, refer to the Enterprise Development Guide. Example remote preparation hierarchy
Figure 2-11
For each of these parts of the hierarchy, properties must be set. The following settings are the required configuration on the workstation for the application. Additional settings are required in the workbench option settings. Refer to Setting the Workbench Options in Chapter 5, Preparing to the Mainframe. The only configuration necessary on the mainframe side is the installation of the Enterprise Remote Preparation Server, described in the Enterprise Installation Guide. For more information on performing a remote prepare to the mainframe, refer to Chapter 5, Preparing to the Mainframe. Setting Partition Properties In the Partition properties, set the Partition Type to Server, the Server Interface to NetEssential, and the Language to Default.
Figure 2-12 Partition settings
2-12
The following fields can also be used to override the default version settings. Collection ID Server owner Server qualifier Minimum trans ID Maximum trans ID The order of precedence is similar to the mainframe, but the relationship between the partition and the preparable object is not supported on the workstation. Setting Database Properties If you are using a database (and DB2 is the one supported for the mainframe), in the Database properties, set the Type to DB2.
Figure 2-13 Database settings
AB20.USER.APPLDBRM
Set the Database directory path to the path where the database (DBRM)s are stored following a successful prepare. If nothing is entered, the system defaults to the library specified in the system version INI file. Set the Implementation name to the DB2 Subsystem ID. Setting Machine Properties The Machine properties must point to the Region that the object rule is running against (CICS or Batch). Each Region must have a mainframe INI file in the mainframe repository libraries that the remote preparation is running against.
Figure 2-14 Machine settings
Set the Operating system to either MVS or CICS/MVS. The CICS/MVS option is only used for preparing CICS rules. You cannot currently prepare MVS rules when the objects are set to this environment. Set the Machine group to the name of the region on the mainframe, for example a CICS region. Set the Implementation name to the TCP/IP host name of the mainframe.
2-13
Note
Use the Machine group name to create a remote preparation machine entry in the workbench options. Refer to Setting the Workbench Options in Chapter 5, Preparing to the Mainframe.
Rules use the Machine properties Operating system as the execution environment. If a CICS rule needs to be prepared, the Machine must specify an operating system of CICS/MVS and a Region name as CICS Region. The DB2 information contained in the Database object is used not the information in the Rule.
Adding a Process Container

For client Partitions, in the Configuration tab hierarchy, insert a Process object. For server and gateway Partitions, insert a Server object. Edit the properties of the Process or Server objects in the hierarchy to configure this container for that partition. (View > Properties, or double-click on the Process or Server.) In this container you add the business rules and parts of your application that are to be deployed on that machine. Refer to Adding Rules to a Process.
For Clients, Add a Process

For Java Client Use the Configuration tab of the Hierarchy window to configure how to prepare applications with a Java client. The configuration must contain a partition for the client application. To the partition, add the process(es) containing the client-side rules to this partition. For Thin HTML Client Use the Configuration tab of the Hierarchy window to configure how to prepare applications with a thin HTML client. The configuration must contain a partition for the thin-client application. To the partition, add the process(es) containing the client-side rules to this partition. For Windows Client Use the Configuration tab of the Hierarchy window to configure how to prepare applications with a Windows client. The configuration must contain a partition for the client application. To the partition, add the process(es) containing the client-side rules to this partition.
2-14
For Server or Gateway, Add a Server(s)

For EJB Server or Gateway Use the Configuration tab of the Hierarchy window to configure how to prepare applications with an EJB server or gateway. The configuration must contain a partition for the server or gateway application. Add the server(s) or gateway(s) containing the server-side rules to this partition. For Web Services Server or Gateway An application that has a Web services server or gateway on one machine can be prepared using the Configuration tab in the Hierarchy window of the Construction Workbench. The configuration must contain a partition for the server application. Add the server(s) containing the server-side rules to this partition. For RMI Server Use the Configuration tab of the Hierarchy window to configure how to prepare applications with an RMI server. The configuration must contain a partition for the server application. Add the server(s) containing the server-side rules to this partition. For (Windows) C Server Use the Configuration tab of the Hierarchy window to configure how to prepare applications with a C server (Departmental Server). The configuration must contain a partition for the server application. Add the server(s) containing the server-side rules to this partition.
Adding Rules to a Process

After you have created an application configuration and added partitions, you can add the business logic to the partitions. Typically, add rules to a process using the Project tab as you develop the application and then use the Configuration tab to add rules to the processes or servers.
Note
Application preparation fails if the leaf-level view does not include at least one field. That is, though a view can refer to any number of subordinate views, eventually the hierarchy must end in at least one field for all superior views to be valid.
In the Hierarchy diagram, the rules in a process that are logically part of that process but physically run on part of another partition (located on another machine) are displayed with an icon that distinguishes them from rules that are on that machine, as shown in Figure 2-15.
Figure 2-15 Rules icons
A rule on another machine is shown with this type of icon.
2-15
Adding a Database
To add access to a database, add a database object to a partition object in the Configuration tab of the Hierarchy Diagram in the Construction Workbench and set the following properties in the database object. Implementation name - this is the JDBC or ODBC connection name. Type - this determines the exact SQL that is output when the object is prepared. For database type, refer to Table 2-2. These table entries are valid when the Language setting for the partition is set to Default, that is, the native language (C or COBOL). For Java (Language set to Java), the only valid database settings are DB2/UDB and Oracle.
Table 2-2 Type DB2/2 DB2/400 DB2/600 DB2/UDB MS-SQLServer Oracle Database types Description for IBM UDB platform for IBM OS/400 platform (AS/400, iSeries) for IBM AIX platform (RISC 6000) for IBM UDB platform for Microsoft SQLServer database for Oracle database
Under the database object in the hierarchy, you may put the file objects to make clear to you which tables in the database are needed, but the files should also be under the rule in the partition. The file object in the hierarchy corresponds to the table of the database; the view object in the hierarchy corresponds to the column in the table. For more information about setting up access to a database, refer to the Developing Applications Guide. For client applications that use an EJB to access a database, you must create a database connection for the application server.
2-16
Using the Project Toolbar

The Project toolbar, part of the interface that is displayed by default, provides some shortcuts to access different projects and configurations. From the Project toolbar, you can: Select a project from a list of recent projects. Select the currently active configuration from a list of the configurations in a project. Select the currently active partition within a configuration from a list of all for a given configuration.
Figure 2-16 Project toolbar with drop-down lists
Select from a list of recent projects.
Select the active configuration from a list of configurations in a project.
Select the active partition from a list of partitions in a configuration.
Open the Project Options window to set the project options.
To turn off the Project toolbar, go to View> Toolbars and deselect the Project toolbar check box.
2-17
2-18
CHAPTER
PREPARING THE APPLICATION
This topic explains the procedures for preparing the application objects after the partitions are defined and the servers and clients are configured. In the Construction Workbench, you can prepare application objects from either the Project tab or the Repository tab of the Hierarchy window or, if a distributed application configuration is selected, you can also prepare from the Configuration tab of the Hierarchy window. This section explains how the preparation is done; the results are discussed in a separate section. This process involves: Understanding Preparation Preparing an Application (in the Hierarchy Window) Preparing Objects Re-Preparing Items with a Preparation List Considering Background Processing Interpreting the Results (Output) Using Advanced Preparation Options You can prepare from any of the hierarchy tabs and from most of the tools that manipulate preparable objects. The objects are prepared using the Application Configuration and the Partition specified in the Project options, unless you prepare them from the hierarchy diagram and an object has both an Application Configuration and a Partition as parents. This is true for the Configuration tab, but if you copy the Application Configuration from the Configuration tab to the Repository tab you get the same results. In a sense, the application hierarchy and configuration hierarchy are maps used by the system to understand how to prepare the objects. When an AppBuilder application is prepared, the following items are located and extracted from the repository, compiled, and otherwise made ready for execution: Functions and processes (application structure) Supporting rules (code) Objects defined within windows (including the windows themselves) Views and fields (data structures)
3-1
Understanding Preparation
Depending on the deployment and execution environment, preparation may include these steps: Create any database tables if database access is required Prepare any external files used by a rule Windows are prepared when you submit a window (for C client) or when you submit rule for preparation (for Java client) Transform rules and groupings of rules into an executable program Compile source code for any external code components used by a rule Prepare any sets that the application uses Make available to the run-time environment the menus, shortcuts, windows, and workstation reports that comprise the application end-user interface Prepare mainframe rules for test execution on the workstation or check the syntax of those rules Be sure to commit changes before preparing the application. You can prepare the entire application or individual application objects. To understand preparation, you should read: Knowing Ways to Prepare Meeting Java Preparation Prerequisites Avoiding Common Mistakes Preparable Objects Generated Output Language
Knowing Ways to Prepare

In the Construction Workbench there are several different ways to perform the same preparation action. With an object selected in one of the tabs (Project, Configuration, Repository, Inverted) or open in an editor or other tool, different preparation actions are available. You can select the preparation action in any of these ways. with the object selected in the hierarchy window, from the Build pull-down menu with the object selected in the hierarchy window, from the right-click menu with the object open in the tools area (like a rule in Rule Painter), from the Build pull-down menu with the object open in the tools area (like a rule in Rule Painter), from the right-click menu from the Preparation Query to select the objects at or below an object in the hierarchy from a window that lists all objects of that type from the Prep Status tab in the Output Window, if the object has previously been prepared With some parts of the application (or objects in the hierarchy) you can prepare the object and all its child objects. This is called super prepare. For example, a rule that may have several child rules can be superprepared. Be sure to prepare parent objects (such as rules) that contain child objects (such as views) if changes were made to any of the child objects.
3-2
Preparing the Application
Meeting Java Preparation Prerequisites

There are third-party components that are required for preparation of Java rules and applications. If you are going to create a server rule (a rule that runs on the server) in Java, then you are creating an Enterprise Java Bean (EJB). You need to install Java version 2 Enterprise Edition (J2EE) to prepare the EJB. To prepare server rules (EJBs), ensure that you have the following in your class path: j2ee_home\lib\j2ee.jar j2ee_home\lib\jhall.jar If you are using a database (such as Oracle or DB2), you need to install SQLJ to prepare database rules. For SQLJ rules, ensure that you have the following in your class path: db2java.zip runtime.zip sqlj.zip You also need the classes included in the 111.zip if you prepare for an Oracle database. Refer to the Installation Guide for Windows for general prerequisites for third-party support for Java development.
Avoiding Common Mistakes

Application preparation can fail for any number of reasons. Here is a list of common mistakes that can be avoided. Make sure that the leaf (bottom of hierarchy) view object includes at least one field object. Though a view can refer to any number of subordinate views, eventually the hierarchy must end in at least one field for all superior views to be valid. If the leaf view does not have a field, the view fails to prepare. Make sure that sets have symbols. If the set has no symbol, the set fails to prepare. Make sure that files have views. Similarly, a file cannot have more than one data view. If the file does not have a view or has more than one data view, the file fails to prepare. Make sure that each window has at least one view and that the view has at least one field. The window does not prepare if there is no view with a field attached to that view. Make sure that rules, user components, and windows do not have more than one input or output view. Also, rules and user components must not be empty of source code. Make sure each bitmap object has an attached image. For configuration, make sure that each partition has one and only one machine. Make sure that each client partition has at least one process. Make sure that each server partition has at least one server.
3-3
Preparable Objects
In an AppBuilder application, objects must be prepared to make them executable. Different preparation options are available depending on the type of object in the application hierarchy. For each type of object, whether they can be prepared or super prepared or both, the result of preparation, and what tabs you can prepare from are summarized in Table 3-1. The Prepare choice prepares only the selected object; SuperPrepare prepares the selected object and all of its children (at a lower level in the hierarchy). Some objects, like partition have other preparation actions available.
Table 3-1 Object preparation summary Super Prepare Yes Other Action
Object
Prepare
Results of Preparation Action Serves as a container of partitions and is shown in the Configuration tab, not the Project tab. Can only super prepare. Prepares all children (clients and servers) and creates package. If you only Create Package, then it packages previously prepared items. Deploy Package calls a user defined Deploy.bif script in order to deploy prepared package Generates the pull-down menu structure in the execution client or the desktop object (Start > Programs > folder name). Serves as a container for rules and other objects on the client (so nothing to Prepare, only Super Prepare). Generates the command in the pull-down menu in the execution client.
Available From Configuration, Repository, and Inverted tabs.
Application No Configuration
Partition
No
Yes
Configuration, Repository, and Inverted tabs.
Create Package Deploy Package
Function
Yes
Yes
Project, Repository, and Inverted tabs.
Process
No
Yes
All hierarchy tabs.
Server
No
Yes
Serves as a container for rules and other Configuration, objects to be prepared on the server Repository, and (so nothing to Prepare, only Super Prepare). Inverted tabs. Compiles the rule (or transforms it into an All hierarchy tabs; executable program) in the run-time directory open window in on the designated machine. Rule Painter. Creates the window (panel file) for C. In Java, nothing happens; the HTML and JavaScript are generated when the rule that owns the window is prepared. Generates DDL (data definition language) statement. The DDL can be used to create a table in the database. Generates the sets. Extracts and transfers the bitmap. Bitmaps and icons are converted to JPGs when you prepare for Java. JPGs are converted to Windows bitmaps when you prepare for C. Compiles the user-defined component (or transforms into an executable program) in the run-time directory on the designated machine. Do not prepare a Java component in a C partition. Reports can only be directly prepared from the mainframe. To prepare a report in Java, prepare the rule that has the report. Project and Repository tabs; open window in Window Painter. All hierarchy tabs. All hierarchy tabs. Create/ Delete Table
Rule
Yes
Yes
Window
Yes
No
File Set
Yes Yes
No No
Bitmap
Yes
No
All hierarchy tabs.
Component
Yes
No
All hierarchy tabs.
Report
Yes
No
N/A
3-4
Preparation Order You can prepare objects in any order with these exceptions: Prepare a rule or user component that accesses a database after creating the table for the corresponding file. For Java partition, you can have a C user component. For a C partition, the Java user component is not prepared. If you create a table that is part of a file, be sure to prepare both the file and prepare the table objects. Similarly, you may prepare individual objects, but be sure to prepare the entire function (or group of objects) that you wish to run to make sure that the function (or group of objects) is ready. If changes are made to a window and the window has a view attached, be sure to re-prepare the rule that has that window. For Java, if changes are made to a window, you must re-prepare the rule that owns that window. System components are not prepared. Their functionality is built into the runtime. Create and Delete Table For a file object, Create Table uses existing DDL files to create a table for the selected file. If DDL files do not exist for the selected files, Create Table generates them and creates tables for the files. In other words, you can skip the Prepare step. New tables cannot be created for files until existing duplicate tables have been deleted. A status of Successful in the Prep Status tab of the Output window means that the files corresponding table has been created successfully. For a file object, Delete Table deletes existing tables for the selected file. Super preparing a function does not create database tables for the files in the function hierarchy. Create the table with the Create Table action. If you have problems preparing files, check that you have specified the Implementation Name property of the file (which determines the name of the corresponding database table) and of the fields in the file view (which determine the names of the corresponding columns in the database table). Embedded SQL Embedded SQL is supported for Java rules as it is for other rules created by AppBuilder. When you prepare the rule, the system generates the appropriate SQL for Java (or SQLJ). That is, the original rule is converted to Java code with the SQL embedded in it. The system uses the industry-standard SQLJ translator as a precompiler to complete the translation to Java. Consequently, the SQLJ basis in JDBC (Java Database Connectivity) allows rules created by AppBuilder to access any JDBC-compliant database.
3-5
Generated Output Language

AppBuilder determines the generated output language when preparing from the Construction Workbench by following these guidelines: For Standalone applications, and the project is open, you can specify the language in the Project Options dialog accessible via File > Project Options. You can select either Java or Windows (which is C) to be generated on your local desktop. For Standalone applications, if no project is open, you can specify it in the Preparation tab in the Workbench Options (Tools > Workbench). Java is generated if Java application is checked and C will be generated if Windows application is checked. For Distributed applications, whether or not the project is open, the language in which the object will be prepared is determined in the Properties of that Partition object. The Application type combo box under Function prepare lets you specify different parameters for Function prepare. For example you may want to create desktop objects for C and Append functions on the menu for Java. For remote preparation to the mainframe, you can prepare to COBOL by preparing to the mainframe.
3-6
Preparing an Application (in the Hierarchy Window)

Although you prepare primarily From the Configuration Tab, you can prepare some objects From the Project Tab or From the Repository Tab with certain restrictions. In addition, you can also use the Preparation Query and Preparation List functions of the Output window. There are some restrictions on preparing an application; the order of preparation is important in some applications. For example, if you try to prepare a file for C and rules prior to creating the table that this file generates and the rules use, all your SQL rules fail.
From the Configuration Tab

Within a configuration, you can select one or more partitions to prepare at one time.
Figure 3-1 Super preparing two partitions in a configuration
Selecting the two partitions in one configuration by clicking and holding down Ctrl key.
Right-click and select Super Prepare (or choose Build > Super Prepare) to perform preparation of both partitions and all their child objects.
Process and Server objects are only containers for rules and other objects on the client and server respectively, so there is nothing to prepare except the objects it contains. These have only the SuperPrepare option. Other objects, like Window, Set, and Bitmap, do not contain objects that are preparable, so no SuperPrepare option is available. Some objects, like Symbols, Fields, and Views, are not preparable. When you prepare a remote client or server rule, the generated code for the rule is copied to a preparation server machine, then compiled and linked for the operating system residing on the machine. Other objects in the rule hierarchy are prepared in similar fashion. Be sure to commit changes before preparing the application. You can also prepare some objects From the Project Tab or From the Repository Tab.
3-7
From the Project Tab

If you are preparing from the Project tab of the Hierarchy window, you can specify which configuration and which partition within that configuration is active. Then all the objects selected in the Project tab that are also in that particular partition will be prepared. Before preparing all or part of an application configuration, select the partition in a configuration in the Project Options dialog. Select File > Project Options (or use the short-cut Ctrl+Alt+P).
Figure 3-2 Distributed application with partition selected
The Distributed Application radio button must be selected in order for the Configuration and partition selection to work in the Project tab. The selection of a partition applies only to the preparations performed from the Project tab. From the Project Options dialog, if only one partition is selected, then only objects in that partition can be prepared in the Project tab. A Super Prepare only prepares up to that partition and a Prepare can only be done for objects in that partition. From the Project tab, if you select a rule in another partition, a message appears in the Output window. That partitions selection applies only to the Project tab. (If you want to prepare more than one partition or entire configuration, then you should perform a preparation from selecting those from the Configuration tab. Refer to From the Configuration Tab.)
From the Repository Tab

From the Repository tab, you can prepare only standalone applications. Any prepare done from the Repository tab is considered done in Standalone mode. Files are put on your local machine if you prepare objects from that Hierarchy window. Any prepare done from the Configuration tab is implicitly considered a distributed preparation. Refer to From the Configuration Tab.
3-8
Preparing Objects
Preparing Objects
Preparing Individual Objects with a Preparation Query
There are several ways to select the parts of the application to be prepared. In the Configuration tab of the Hierarchy window, you can select the objects in the configuration and do either a Prepare or SuperPrepare. Another way is to bring up a Preparation Query window and select the objects from a list that is created by querying the repository of objects. With the function selected, from the right-click menu, you can bring up a preparation query for an object. Which objects appear in the menu depend on which tab you are in and which object you have selected. Figure 3-3 shows how to select a preparation query for an object from the menu. Figure 3-4 shows the Preparation Query window.
Figure 3-3 Menu selection of Preparation Query
Figure 3-4
Example Rule Preparation Query window
1. Select the type of object type when you select Preparation Query. 3. Select which of the objects in the repository for a given configuration and partition to prepare, and click Query. 2. Select whether to prepare the objects locally (standalone) or distributed. If standalone, select only those in this Project or in the entire repository. 4. Click Prepare (to do only the rule) or SuperPrepare (to do everything underneath it in the hierarchy).
3-9
Preparing Objects
Re-Preparing Items with a Preparation List

After you have prepared an object or collection of objects, the system adds that preparation job to the Preparation List (or Prep List) tab of the Output window in the Construction Workbench. Refer to Prep List Tab in Chapter 10, Output Window of the Development Tools Reference Guide for an explanation of the Prep List tab.
Considering Background Processing

AppBuilder prepares objects in the background -- allowing you to continue working within the Construction Workbench. Use the Output window to monitor the preparation status. You may even exit the Construction Workbench while a preparation is running, though this is not recommended. For more information about the Output window, refer to the Development Tools Reference Guide.
Validating Sets Option

There is a setting in the system initialization file (hps.ini) in the AP Global section that determines whether a value set of "small integer", "decimal" and "character" types are validated during preparation. To have the validation occur, set the value of VALIDATE_SET to Y for yes. To have AppBuilder avoid the validation, select N for no.
Interpreting the Results (Output)

Use the tabs of the Output window to monitor the preparation process. If the Output window is not showing, use the View > Output menu choice. For more information about the Output window, refer to the Development Tools Reference Guide.
3-10
Using Advanced Preparation Options

In the Construction Workbench, you can modify the options for preparation. To view or modify the options, from the Tools menu in the Construction Workbench, select Workbench Options. These include: Local Preparation Options Remote Preparation Options For a complete description of all the Workbench Options, refer to the Development Tools Reference Guide. In the system initialization file (hps.ini), you can modify other options for preparation. These include: Global Character Support Option Database Preparation Option Editing the Configuration File From the Management Console, you can modify the configuration settings in the INI file for that resource (such as a computer). To edit the configuration file, select the icon of the resource to configure (for example, the particular computer icon), right click on the object and select Edit HPS.INI. Each tab is a section of the file and you can modify values as needed. This is the recommended way to edit the file.
Figure 3-5 Example INI file
Each section of the file is available on a tab.
Each variable of that section is available in this list.
You can modify the value and click Set.
If there is help available for that value, it is displayed here.
3-11
Global Character Support Option

In the AP GLOBAL section of the system initialization file, hps.ini, there is a place to enable the functionality for a double-byte character set (DBCS). The setting is DBCSEnable, which by default is set to N for no. (In previous versions of the product, this was in the AP.INI file.) This string is used by the code generator to determine whether this is a DBCS environment or not. Development in a non-DBCS environment does not use this string. To enable DBCS support, set it to Y for yes. For example, [AP GLOBAL] DBCSEnable=Y
Database Preparation Option

In the AP GLOBAL section of the system initialization file, hps.ini, there is a place to set the database preparation options. The setting is PREP_DB_OPTIONS. What settings you choose to set depends on the database you are using. This setting simply sends the options you set to the database in a single command. This allows you to use some value other than DATETIME ISO (which is previously set by AppBuilder) and specify other options. To specify more than one option, separate the options by a space. For example, [AP GLOBAL] PREP_DB_OPTION=GRANT BLOCKING
Local Preparation Options

AppBuilder allows you to specify the following options for local preparation: Extent of debugging Type of function object Local database Default settings for standalone application To view or modify the options, from the Tools menu in AppBuilder, select Workbench Options > Preparation. For a complete description of all the Workbench Options, refer to the Development Tools Reference Guide.
Remote Preparation Options

AppBuilder allows you to specify the following options for remote preparation: Local machine name Results server name Remote preparation server name To view or modify the remote preparation options, from the Tools menu in AppBuilder, select Workbench Options > Remote Preparation. For a complete description of all the Workbench Options, refer to the Development Tools Reference Guide.
3-12
CHAPTER
WORKGROUP REPOSITORY REBUILD
The Rebuild facility is available from within Construction Workbench when connecting to a Rebuildenabled Workgroup Repository. Rebuild is only supported for Workgroup Repositories on Windows 2000 platforms and Microsoft SQL Server 2000. Rebuild allows you to perform a rebuild of an application, in conjunction with an Application Configuration or Partition, that selectively updates and rebuilds only those objects impacted by a particular change. The rebuild facility updates a record each time an object is prepared for a particular Application Configuration or Partition.
Rebuild Overview
Workgroup Rebuild is designed to assist with change management in a development environment. During development you need to manage all of your source code and track your changes. In addition to managing your source, you will need to manage change in the executable application itself. With rebuild, you can know what executables are effected by your changes and only build what is required without having to do extensive analysis on your changes. The analysis normally required is done automatically when you are connected to a Rebuild enabled Workgroup Repository. By properly partitioning applications, you can rely on AppBuilder to tell you what needs to be Prepared. For instance, if an application is deployed in Java on the client, and COBOL on the server using CICS, you can set up an Application Configuration (APPCFG) to partition the application into two logical pieces. You can create one partition for the client and configure it to prepare Java locally, and one partition for the server and configure it to prepare remotely to the target CICS region. Once this configuration is in place, you can build the application for the first time and start tracking the rebuild status of the objects.
Enabling a Group Repository for Rebuild

Set REBUILD_ENABLED=TRUE in the FREEWAY_SERVER section of the hps.ini file in the appbuilder directory. The Freeway Service must be stopped an re-started for this change to take effect.
4-1
Rebuild Overview
Figure 4-1
Rebuild Process Overview Local Prepare
Java Client Partition Application Java/PC
CICS Server Partition
Remote Prepare Partition applications Mainframe CICS
Rebuild Analysis
Rebuild Analysis happens in a 3 phase process as shown in Figure 4-2. Part of the processing happens when you commit your changes to the repository. The remaining processing occurs when the user requests a rebuild action. 1. 2. During development, the changed objects are identified and stored in a change list. During rebuild analyze, impact analysis is performed to determine which additional objects need to be prepared. Each object that requires prepare causes an update in the Impact list to the impact time. During the partition analysis, every object in the selected Application Configuration or Partition is checked against the Impact list to see if it has been prepared since the last impact.
3.
4-2
Rebuild Overview
Figure 4-2
Rebuild Overview
Significant Change Analysis

During development, the changed objects are identified and stored in a change list. When you Commit changes to objects in the repository, the Change List table is updated. The impact type is used to handle special circumstances other than the typical significant change.
4-3
Rebuild Overview
Changed List
Table 4-1 Field Object ID Version ID Impact type Changed List Purpose To relate this back to the effected object To scope this to a specific version Whether this is Source only change or other special circumstances.
Impact Analysis
During rebuild analyze, a full impact analysis is performed to determine which additional objects need to be prepared. Each object that requires preparation is added or updated in the Impact List table with the impact time. Impact List
Table 4-2 Field Object ID Version ID Impact time Impact List Purpose To relate this back to the effected object To scope this to a specific version To track the time that the object was last impacted.
After the analysis is complete at Phase I, the objects are ready for rebuild. When an object is rebuilt, the rebuild time of the object is compared to the impact time of the changed object in the Impact List, and is prepared only if the rebuild time is different than the impact time. The impact time is then updated if the object is prepared successfully. However, the location of the rebuild in the hierarchy when it was selected effects which objects are eventually prepared. Impact Analysis Examples Impact analysis determines which objects are effected by a specific change or set of changes. For example, a rule might be effected by changing a field in a view of a child rule. However, a source change to a child rule does not effect a parent rule. Every impacted object is added to the impact table. *** = changed @ = impacted Figure 4-3 illustrates how a change to a field impacts the rules associated with it.
Figure 4-3 Field Change
4-4
Rebuild Overview
Figure 4-4
Rule Source Change
Partition Analysis
When the impact analysis is complete, the results represented in the impact table are used to determine which objects within a partition will be rebuilt.
4-5
Rebuild Overview
Rebuild Status Table

Table 4-3 Field Object ID AppCfg ID Partition ID Version ID Rebuild time Rebuild Status Table Purpose To relate this back to the affected object To scope this to a specific Application Configuration To scope this to a specific partition To scope this to a specific version To compare to the last impacted time on the impact list.
Partition Analysis Example In the following example, Partition 1 and Partition 2 are server partitions that contain different sets of objects. If a single change is made to Field 1, both Rule 1 and Rule 2 are added to the impact table. However, if only partition 2 is rebuilt, then only Rule 2 will be built, as Rule 1 is not in Partition 2. If Partition 1 is then built after Partition 2, not only will Rule 1 be built, but Rule 2 will be built again because it has not yet been built for that specific partition.
4-6
Rebuild Overview
Figure 4-5
Partition Example
Rebuild Functionality Notes

Note
All information related to the build status of an object is stored only in the repository. Rebuild will not prevent overwriting of libraries built from a different Repository, Partition or Application Configuration.
What happens when you change a partition?

Changes that affect the PARTITION or APPCFG as a whole are not tracked by rebuild. When making significant changes to how an application is partitioned or how a partition is deployed, it is recommended that you mark the partition as UnPrepared and rebuild the entire partition. For more information refer to Mark All
4-7
Rebuild Overview
Differences in behavior for Versioned and Non-Versioned Repositories

Versioned Repository For the Versioned Repository, both the Impact List and Rebuild Status tables are unique to the Working Version. If no workspace has been selected, then no Rebuild updates are made. Non-Versioned Repository For the Non-versioned Repository, both the Impact List and Rebuild Status tables are unique to the entire repository. In this case, the Version ID would be set to zero (0).
Significant Objects
Table 4-4 Significant ObjectsTable Attributes System Id Type Implementation Name Impacts Report Rule Window Objects/Relationships Bitmap
Component*
System Id Name Execution Environment Language Subroutine DBMS Usage Implementation Name
Component Rule
File
System Id Name File Type Implementation Name
Component Rule
Field
System Id Name Field Picture Storage Field Picture Display Screen Literal Long Field Format Field Length Field Fraction Range Minimum Value Range Maximum value Reference Table Name
View
4-8
Rebuild Overview
Table 4-4
Significant ObjectsTable Screen Literal long Implementation Name
Form**
System Id Name Form Environment Base Country Language
Report
Help**
System Id Name Format Description Country Language
Window
Help Text**
System Id Name Country Language
Window
Panel**
System Id. Name Coordinate System X-Resolution Y-Resolution Description Country Language Base GUI
Window
Physical Event
System Id Name Event Type Event Class Event Scope
Rule
Report
Report Id Name Execution Environment Page Size Line Size Left Margin Top Margin
Report Rule
4-9
Rebuild Overview
Table 4-4
Significant ObjectsTable Printer Type Orientation Implementation Name
Rule*
System Id Name Execution Environment DB2 Plan Name DBMS Usage Execution Mode CICS/IMS transaction Id Implementation Name Package Isolation Mode
Rule
Section
System Id Name Implementation Name
Report
Set
System Id. Name Field Picture Storage Set Format Set Length Set Fraction Implementation Name Style Representation Length
Component Report Rule Window
Symbol
System Id Name Define Encoding Display
Set
Values
System Id. Name Value
Set
View
System Id Name Implementation Name
Component File Report
4-10
Rebuild Overview
Table 4-4
Significant ObjectsTable Rule View Window
Window Content**
System Id Name GUI
Window
Report/Section
Type Break Sequence Number Page Placement Break Field Break Qualifier Left Margin Print Option
Report
Set/Value
Sequence Number Symbol
Set
Entity/View
Usage
Component File Report Rule View Window
View/Entity
Sequence Number Occurs Number of Times Null Indicator for DB2
Field View
4-11
Using Rebuild
Using Rebuild
The following procedures are listed in this section: Rebuilding from a Partition Rebuilding from an Application Configuration Sorting the Rebuild Report Saving the Rebuild Report Running a Rebuild or Rebuild Report Using the Active Configuration Mark All
Rebuilding from a Partition

All the objects that are changed in the Partition and contained in the Impact List will be rebuilt. Once the changed object has been rebuilt, the rebuild time is replaced with the impact time of the changed object. The Partition rebuild is fundamentally a super prepare of all the changed objects in the partition, but only of objects that exist in the Impact List. The preparation order for rebuild is the same as for a super prepare. Prepares do not update any significant fields in the repository. Procedure - Performing a Rebuild from a Partition The first step is to connect to a workgroup repository. 1. From within Construction Workbench, choose File>Open Project. You can either open an existing Project or create a new one. If you are creating a new one, refer them to Rebuilding from a Partition.
Construction Workbench Rebuild Interface
Figure 4-6
Project Tab
Configuration Tab
2.
When you select Rebuild while in the Project tab, the default APPCFG and PARTITION will be submitted for rebuild. The items that are selected in the hierarchy have no impact on what is rebuilt.
4-12
Using Rebuild
From the Configuration tab, You have to select the APPCFG or PARTITION that you want to rebuild, rebuild report, or mark All. Procedure - Running the Rebuild from Project or Partition You can conduct a Rebuild from either of two views in Construction Workbench: from the Project tab or from the Configuration tab (Figure 4-6). Running Rebuild from Project View: 1. 2. Select the repository partition (item in hierarchy) that you want to rebuild. Select Build>Rebuild (Figure 4-7).
From the Project tab, you can only run a rebuild when you are in Distributed Mode. Chose File>Project Options and Select Distributed Application.
Note
3.
The Rebuild status will display in the status box located at the bottom of the Construction Workbench window.
Project Tab Rebuild
Figure 4-7
View Rebuild Report results here
Running a Rebuild Report on a Partition 1. 2. 3. 4. Select the partition using the options in the drop-down box at the top of the Construction Workbench. Select the object you want to obtain a rebuild report for from the hierarchy. Select Build>Rebuild Report (Figure 4-7). The report results display in the spreadsheet columns at the bottom of the Construction Workbench window.
Rebuilding from an Application Configuration

Rebuilding from an Application Configuration results in a rebuild of each child partition.
4-13
Using Rebuild
Running Rebuild from an Application Configuration 1. From Construction Workbench, select the Configuration tab (Figure 4-8).
Configuration Tab Figure 4-8
2. 3. 4.
Select the Application Configuration you want to rebuild. Choose Build>Rebuild, or right-click on the Application Configuration name and select Rebuild. The status window in the lower left corner of the window displays the status of the rebuild (Figure 4-9).
Rebuild Status Display
Figure 4-9
Running a Rebuild Report on an Application Configuration 1. 2. 3. Select the Application Configuration using the options in the drop-down box at the top of the Construction Workbench. Select Build>Rebuild Report (Figure 4-7). The report results display in the spreadsheet columns at the bottom of the Construction Workbench window.
Sorting the Rebuild Report

You can sort the report results in the window by clicking on the top heading cell of the columns (Figure 4-10).
4-14
Using Rebuild
Figure 4-10
Sorting and Saving the Report Results
Right-click on the report window to save the report
Click on the column heading to sort the report
Saving the Rebuild Report

Save the Rebuild report by right-clicking the RebuildReport window and selecting Save Rebuild Report. Name the file, choose the destination location, and click OK (Figure 4-10).
Running a Rebuild or Rebuild Report Using the Active Configuration

When in distributed mode, the active configuration will be used to submit a rebuild when working in the Project, Repository, or Inverted tab. To set the active configuration go to File>Project Properties, select the APPCFG in the drop-down list and then select one of the available PARTITIONs.
Mark All
Select Mark All>Unprepared to clear the rebuild status so that all the objects in the Partition will be selected and prepared in the next Rebuild. When an APPCFG is selected, the Mark All operation will effect all child partitions of this APPCFG. Use Mark All>Prepared to cause all of the objects in the selected partition to be marked as prepared. If a rebuild is performed on the partition directly after marking All Prepared, no objects will be detected as requiring rebuild. Changing the rebuild status is most useful when making significant changes to the way an application is deployed or when you are deploying an application for the first time.
4-15
Using Rebuild
4-16
CHAPTER
PREPARING TO THE MAINFRAME
This topic explains the procedures for preparing the application objects remotely from the workstation to a mainframe. In summary, from the Construction Workbench on the workstation you set the configuration and tell AppBuilder which entities are to be prepared on the mainframe. When preparation is performed, AppBuilder invokes the Enterprise Preparation Server. This server performs data extraction from the workstation and sends the data to the mainframe where it is processed in a batch job. This process involves: Using Supported Entities Installing and Configuring the Server Configuring the Partition Setting the Workbench Options Seeing the Results
Caution
Remote preparation to a mainframe is a feature that should be used only for development. It is not intended for use in QA or production environments. It does not use the safeguards that mainframe prepare and rebuild use. It does not update the repository, entity, or status tables. We also recommend that you use a separate repository version on the mainframe, as it does update the version data sets.
Note
The ENT_METHOD_STATUS table is not updated with the remote preparation to the mainframe. We recommend that you have a separate repository version on the mainframe to use for remote prepares. Then you do not have a conflict with others using the same repository.
Using Supported Entities

The following entities in the AppBuilder information model can be remotely prepared to the mainframe. rule component set window report file
5-1
Installing and Configuring the Server
For CICS rules, a transaction assignment is the function that assigns transaction codes to CICS to allow execution in the respective transaction processing environments. For remote prepare these transactions are stored in a VSAM file, so when the rule is prepared again, the rule uses the same transaction. Currently, DB2 packages are supported, but plans are not supported. If your settings, PKLIST and PCKG, are set to use plans, the preparation and execution results could be unpredictable. For user components, the supported languages are COBOL, PL/I, and Assembler. Subroutines are supported for COBOL and PL/I components. File prepare only works for existing DB2 tables. As it does on the mainframe, AppBuilder creates a DCLGEN member for PL/I, COBOL, and C.
Installing and Configuring the Server

Refer the Enterprise Installation Guide for details on how to install the Enterprise Preparation Server and setting up the INI file and JCL. The installation and configuration of the Enterprise Preparation Server are necessary for use of remote preparation to the mainframe.
Configuring the Partition

In order to prepare entities on the mainframe, specify the mainframe as the target machine for the entities in the configuration hierarchy. Refer to the Configuring for Remote Mainframe Preparation section of Chapter 2, Configuring the Application for procedures on how to configure a partition for use with remote preparation to the mainframe.
5-2
Preparing to the Mainframe
Setting the Workbench Options
Setting the Workbench Options

To view or modify the remote preparation options, from the Tools menu in AppBuilder, select Workbench Options > Remote Preparation. See Figure 5-1. Refer to the Development Tools Reference Guide for information on setting Workbench Options in general. This section contains information on the Remote Preparation Tab for mainframe remote preparation in particular.
Figure 5-1 Remote Preparation options
Add a machine to the list. Remove a machine from the list.
ne20
For each (remote) machine, specify various other parameters that depend on the machine and platform.
Table 5-1 Field Local
Remote preparation tab parameters Description For a remote preparation, you must specify parameters for two machines, local workstation and remote or destination machine. This area specifies information about the local workstation. Specify the current local machine name for the workstation. If you are using a loopback adapter, you can specify your IP address instead of the local machine name. Specify the name of the results server, which is the port number that the AppBuilder system service uses to communicate the results. For a remote preparation, you must specify parameters for two machines, local workstation and remote or destination machine. This area specifies information about the remote or destination machine. For the destination, you can add several remote machine names to the list and specify different server names and user identifiers. For each mainframe CICS or Batch region, create one machine name using the same name as the Machine group name specified in the properties of the machine associated with the partition in the repository. (See Configuring for Remote Mainframe Preparation in Chapter 2, Configuring the Application.) For remote prepare to UNIX and Windows, you would use the Implementation Name of the machine. Select the destination platform. For remote preparation to the mainframe, select Mainframe. This displays several more fields that must be specified to accurately setup communications with a mainframe. Select the preparation server ID, which is by default ne20. The rest of the fields are necessary for logging in to a mainframe. This represents the port number that the Enterprise Preparation Server is running on the mainframe.
Local machine name
Results server name
Remote
Machines
Platform
Preparation Server
5-3
Preparing the Object
Table 5-1 Field User ID and Password Repository and Version and Code page
Remote preparation tab parameters (Continued) Description Fill in the user ID and password. (For remote preparation to the mainframe, use the mainframe user ID and mainframe password.) For remote preparation to the mainframe there are some additional fields. Specify the name and version of the repository to which the files are to be prepared, specified in the @HPSENV INI file on the mainframe. Select the code page from the drop-down list.
If you are using a loopback adapter, you can specify your IP address instead of the local machine name on the Remote Preparation tab. Click Apply to apply the changes but leave the dialog open; click OK to accept the changes and close the dialog.
Preparing the Object

Part of the configuration involves adding the rules to the hierarchy that are to be prepared remotely. Make sure that the rules you want to prepare are attached to the server under the partition. This is done in the Configuration tab of the hierarchy window. When workbench options are set and the values for the various objects in the partition are set, you are ready to prepare the rules (or super prepare the entire partition). From the Configuration tab, select the object to prepare a root rule of a server or the entire partition and select Prepare or Super Prepare. If you right-click on the object, you can select Prepare or Super Prepare (or use the short-cuts F7 or Ctrl+F7, respectively) from the pop-up menu. Likewise, if you select the object, you can select Build > Prepare or Build > Super Prepare (or use the short-cuts F7 or Ctrl+F7, respectively). If you select Super Prepare for a root rule of a server, it prepares that rule and any child rules on that server. If the settings are correct, the object is prepared to the destination machine you have specified. Refer to Seeing the Results to find out about the results of the prepare.
5-4
Seeing the Results
Seeing the Results

When the preparation is done, the results can be seen in the Prep Status tab of the Output window as shown in Figure 5-2. The status indicates whether the objects prepared successfully. Details can be shown by double-clicking on any line in the status window.
Figure 5-2 Results of remote prepare
Details of remote prepare Results of remote prepare
For most of the types of object prepared to the mainframe, the libraries specified by the USRVQUAL variable in the Qualifiers section of the @USERENVn INI file are updated. As in a typical mainframe prepare, the results contain several files including the compiler listing and link listing. Due to the size of these files, an INI setting on the mainframe, REMPREP.SNDLIST in the @USRENVn INI file, is defaulted to 'N', so these files are not sent. If you would like these files sent, set the INI setting to 'Y' for the repository and version to which you are preparing. When done with configuring the entities and installing the server, refer to the Enterprise Application Guide for more information about preparing applications on the mainframe in general and handling remote preparation to the mainframe in particular. Nothing is required for configuring the mainframe beyond what is described in the Enterprise Installation Guide for installing the Enterprise Remote Preparation Server.
5-5
Seeing the Results
5-6
CHAPTER
PACKAGING THE APPLICATION
This section explains the procedures for handling the application objects that are created as a result of the preparation process and the procedures for deploying them on various platforms. The procedures for preparation were discussed earlier; this section discusses the results of those procedures. For some preparation, such as rules created in C to run on a Microsoft Windows (either NT or 2000) machine, you can prepare the rules remotely, from the development workstation to the remote machine. But with Java and EJB modules, the preparation only prepares the files locally. The following lists the options for deploying an application: Handling a Standalone Application Handling a Thin Client (HTML) Application Handling a Java Application Handling a Windows Client/Server Application Migrating Modules to the Mainframe When AppBuilder prepares the application, files are generated in an ordered set of directories on the local workstation. For standalone applications, whether C or Java, all the files are stored on the local workstation. For remote prepare, some files are generated on remote machines; however, files are not always generated remotely. For Java (thin or thick client) applications, files are generated on the local machine and must be deployed separately. For C applications, files can be remotely prepared. For deploying to the mainframe, files must be migrated from the workstation to the mainframe. Each of these cases is considered and the location of the generated files is detailed.
Understanding the Directory Structure

AppBuilder creates a specific directory structure for organizing the generated files. This is typically in the <AppBuilder> directory under a directory called RT (for run-time), where <AppBuilder> is the drive and directory where AppBuilder is installed, for example C:\AppBuilder. For a Java application, the generated files are stored in <AppBuilder>\Java\RT\. Within that directory are several subdirectories. There is a separate subdirectory for each application configuration since one function may have multiple configurations. Also, the number of partitions in each configuration may be different. For example, one function has one partition with Client, EJB Server, and Host Server and another partition has a Client and an EJB Server. The contents of the EJB Server folders are different in these cases. For a Windows (C Language) application, the files are stored in <AppBuilder>\NT\RT\. If you rename a partition, a new subdirectory is created when the preparation is performed. The old files are not removed or changed.
6-1
Handling a Standalone Application
Handling a Standalone Application

For standalone mode, the result of preparation is the generation of locally stored files. For a Java application, the generated files are stored in <AppBuilder>\Java\RT\Local. For a Windows (C Language) application, the files are stored in <AppBuilder>\NT\RT\Local, where <AppBuilder> is the drive and directory where AppBuilder is installed, for example C:\AppBuilder. Since standalone mode is most often used for testing an application locally, there is no configuration information and thus no additional deployment instructions. For more information on preparing rules and windows in standalone mode, refer to the Developing Applications Guide.
Handling a Thin Client (HTML) Application

For Java thin client (HTML) applications with partitions for distributed client pieces and server pieces, there are several steps to follow to deploy the application. Finding the Generated Files (application files that result from the preparation) Finding the Archive File and Deployment Descriptor Creating Database Access (for those applications that use a database) Assembling and Deploying the Files The J2EE specification from Sun provides a standard for packaging its components that enables portable deployment to any compliant application server. AppBuilder creates J2EE packages for thin-client and EJB components allowing these components to be deployed to any of a number of application servers, thereby increasing the flexibility and portability of the applications.
Figure 6-1 Rule deployment of Web application
6-2
Packaging the Application
Finding the Generated Files

AppBuilder generates files in the locations on the workstation hard drive as illustrated in Figure 6-3.
Figure 6-2 Directory structure of generated Java files
6-3
Figure 6-3
Directory structure for multiple partitions
The contents of the various subdirectories in the run-time directory are summarized in Table 6-1.
Table 6-1 Directory contents for Java files Description of Contents DDL is copied here (to create a table based on this). Subdirectory DBM LOCAL MENU *.MNU, *.FNM files are copied here.
6-4
Preparing a partition generates and extracts Java classes, HTML, and bitmaps etc., for the selected partition. The main run-time directory for an Application Configuration in the install directory is a Java\RT directory. For example, if the Application Configuration is named Config1 and within that is a partition named ClientPart1, the path of the files is: <AppBuilder>\Java\RT\Config1\ClientPart1 Within that directory, there are subdirectories: html - for HTML, CSS and JavaScript files, images - for bitmap files When the partition is super prepared, an archive file with the name of the partition is created. This archive file can be copied on to the servlets home directory. The generated JAR file of a partition resides in each directory associated with the current application configuration object, under the <AppBuilder>\Java\RT directory. The name of the JAR file is the name of the Partition that has been super prepared.
Note
If you change the name of a partition, AppBuilder creates a new directory structure at the next prepare on the new partition. (The RT directory also contains the old files; there is no mechanism to adjust or delete directories upon partition name changes.)
During preparation, AppBuilder creates the HTML files for a Web application. You must compile and deploy them on the client as necessary. The HTML files and the associated CSS and JavaScript files are extracted from the repository and placed in the RT (run-time) directory. HTML is generated to the main partition directory. If the HTML file is not created for a given window panel, the HTML generator is called to create HTML, CSS, and JavaScript files and copied into the run-times partition directory. The HTML files can reference any multimedia file or other file type and these referenced files can be saved in the repository and prepared. These miscellaneous files can be saved under a folder associated with any specific window or globally with the function. These files are extracted from the repository and copied to the includes subdirectory under the run times HTML directory.
Finding the Archive File and Deployment Descriptor

When the partition object is super prepared, it creates an application archive file with a WAR extension with the file name being the name of the partition. For a partition called Hello_World_1, the Web archive (WAR) file is hello_world_1.war. This file is created under the application configuration directory. This file contains all the application Java rule classes, HTML, CSS, JavaScript, include files for HTML, bitmaps, views, and set classes, etc. required to execute the rules in the partition. In addition, it also contains the deployment descriptor for the application and, if the application server has a specific descriptor, an application server specific descriptor is generated for the application server. A client program that needs to access the EJB does so by using JNDI to locate the EJB deployed on a particular host machine. The client program uses the jndi-name entry specified in the Application Server specific descriptor that is generated by Preparation.
6-5
Creating Database Access

If the EJB accesses a database, a database connection pool must be created for the application server. The Database Imp Name property of the Database object in the repository is used as the connection pool name. So, the Database Imp Name property and the connection pool name must have the same value. The generated EJB application uses jdbcDatabase as the logical database name and this is mapped to the connection pool name through the jndi-name property in the descriptor of the specific application server.
Assembling and Deploying the Files

The precise steps to assemble and deploy an EJB application depend on the application server on which they are going to be deployed. Refer to the corresponding application server documentation for assembling and deploying the generated EJB files. The AppBuilder setup program installs a Java archive, appbuilder.jar. It contains the J2EEcompliant servlet support classes for the application in the <AppBuilder>\Java\RT directory. Ensure that this run-time Java archive file is in the application server classpath. For thin-client applications, AppBuilder creates a Web archive (WAR) file, Partition_Name.war. This file contains the J2EE-compliant generated classes for the servlet the objects (rule, view, HTML) and associated includes a deployment descriptor (specific to the application server) required to execute the application an error page (ErrorPage.html) the configuration files (appbuilder.ini and appbuildercom.ini) The archive file is named <partitionname>.war, where partitionname is the name of the partition. It is installed in the <AppBuilder>\Java\RT directory during preparation (when the partition is super prepared). Ensure that the run-time Web archive file is in the application server classpath. Extract this archive on the servlet context directory. The servlet can be deployed on various application servers listed below. IBM WebSphere application server (with IBM HTTP Web server) BEA WebLogic application server Apache or Netscape application server using Tomcat servlet engine Because the specific procedures for installing applications may vary, depending on the application server, refer to the corresponding application server documentation for assembling and deploying the generated Web files.
6-6
Handling a Java Application
Handling a Java Application

For Java (thick client) applications with partitions for distributed client pieces and server pieces, there are several steps to follow to deploy the application. Finding the Generated Files (application files that result from the preparation) Deploying the Files (the files for the application)

For Java clients, the preparation creates Java files as described in this section. Since the applications that are generated are pure Java, they can be deployed in a variety of ways. Applications can be downloaded from a Web server as needed or in the form of an entire Java archive (JAR) file.
Deploying the Files

To prepare and test AppBuilder objects you must install a server on your development workstation and this server is called the Preparation and Test Server. For a distributed application in which AppBuilder prepares objects on remote clients and servers, (whether for test or for production) you must install additional objects on each of those machines. The procedures involve running the install wizard from the CD on those machines and selecting the parts of the product from a list of possible options. Instructions for general installation can be found in the Installation Guide.
Handling a Windows Client/Server Application

For distributed Windows applications with partitions for client pieces and server pieces, there are several steps to follow to deploy the application. Finding the Generated Files (application files that result from the preparation) Deploying the Client Side of an Application Deploying the Server Side of an Application
6-7

The generated files for a C application in a Microsoft Windows (either NT or 2000) environment are located in the directory structure shown inFigure 6-4.
Figure 6-4 Directory structure of generated C (Windows) files
The contents of the various subdirectories in the run-time directory are summarized in Table 6-2.
Table 6-2 Directory contents on Windows platform Description of Contents Bitmap files Prepared components files DDL (to create table based on this) Native operating system help for some system component s (The location is in the appbuilder.ini setting GUI_HELP_DIR.) AppBuilder-generated online help files Menu bar Window (panel) files Only for debugging. When running RuleView, this set of configuration files (with .CFG extension) are used to find out the hierarchy of the objects. Prepared set executable Client-side run-time rules DLLs (See SERVER for server run-time rules DLLs.) Source code for rule Script files for access to mainframe Server-side run-time rules DLLs (See RULEBIN for client-side run-time rules DLLs.) Subdirectory BMP CMPBIN DBM GUIHLP HLP MENU PNL PROCESS REF RULEBIN RULESRC SCRIPT SERVER
6-8
Deploying the Client Side of an Application

To deploy the client side of the application, perform the following: Copy or move the client-side run-time files from the run-time directory (the entire RT directory contents except SERVER subdirectory). Copy or move the appbuilder.ini and appbuildercom.ini files. Add the path for appbuilder.ini and appbuildercom.ini files to the path environment variables. Copy or move the run-time DLLs that are installed as part of the production install. (Refer to the Installation Guide for instructions on installing the Preparation and Test Servers.) AppBuilder puts the files for rules in the RULEBIN subdirectory unless hashing is turned on.
Tip
Figure 6-5
With hashing turned on, AppBuilder creates subdirectories in the rulebin directory for easy reference to find the files needed for large applications. Directory structure for rules with hashing set
Deploying the Server Side of an Application

To deploy the server side of the application, perform the following: Run Communications > Configurator with dna.ini Set the Conversation server (AppBuilder NetEssential conserv) port numbers, etc. Copy or move the server-side run-time files in the RT directory (the entire RT/SERVER subdirectory contents). Copy or move the run-time DLLs that are installed as part of the production install. (Refer to the Installation Guide for Windows for instructions on installing the Preparation and Test Servers.)
6-9
Migrating Modules to the Mainframe
Migrating Modules to the Mainframe

For distributed applications that include some modules running on a mainframe, you must migrate or upload those modules from a personal repository or a workgroup (Freeway) repository to the enterprise repository. The mainframe rebuild produces an advice file for the client side objects. Refer to the Enterprise Migration Guide for information on the migration processes and the Enterprise Rebuild Guide for information on the rebuild process. Refer to the Enterprise Development Guide for information about actions executed on the mainframe.
6-10
CHAPTER
DEPLOYING JAVA ON WEBSPHERE
With AppBuilder, you can develop, deploy, and test enterprise applications targeted for Java environments. This may include a servlet or an Enterprise Java Bean (EJB) or both running on an application server. This section describes the procedures to deploy and run these parts of an application on the IBM WebSphere application server (either version 3.5 or 4.0). This set of procedures assumes that you have WebSphere on your development machine along with AppBuilder. The procedures are (depending on which version of WebSphere you are using): Configuring the Initialization Files (with WebSphere as the application server) Configuring the Application Server Deploying the EJB Partition (the EJB part of the application) Updating the Thin Client Archive Deploying the Partition for Thin Client and Web Services (the HTML part or Web service part of the application) Testing the Deployed Application on WebSphere The configuring procedures apply to any implementation involving WebSphere. If you only need the EJB implementation, follow procedures for updating and deploying the EJB. If you only need the servlet implementation, follow procedures for updating and deploying the servlet. If you need both the servlet and EJB parts of the application, follow all the procedures. These instructions assume you have WebSphere installed. For more information about WebSphere configuration and operation, refer to the WebSphere documentation (http://www-4.ibm.com/software/ webservers/appserv/library.html). An application with database access generated for WebSphere 4.0 also requires UDB 7.1 with FP3 or UDB 7.2. DB2 should be configured to use JDBC 2.0. Be sure also to put on the latest fix pack for Internet Explorer. As well, be sure to install the latest Internet Explorer fix pack. These instructions use the following conventions for directory names: WebSphere is the name for the drive and directory where WebSphere is installed (for example, c:\WebSphere\AppServer). AppBuilder is the name for the drive and directory where AppBuilder is installed (for example, c:\AppBuilder). Database is the name, if you are using a database, for the drive and directory where IBM DB2/UDB is installed (for example, c:\SQLLib).
Note
Remember that application servers are case sensitive. Be sure to double-check any commands or URLs typed at a command prompt, in a command file, or in the entry fields in the interface.
7-1
Configuring the Initialization Files

These steps describe how to configure the initialization (INI) files in AppBuilder so that it knows which application server is used and where to look for Java classes as needed. These steps should be performed before the partitions are prepared in AppBuilder. Refer to Chapter 3, Preparing the Application for information on preparing partitions. Perform these steps on the development workstation where you are running AppBuilder. Use the INI file editor from the Management Console to edit the INI files; for more information on the use of the Management Console and the INI file editor, refer to the Configuring Communications Guide. 1. Modify the AppBuilder system initialization file (AppBuilder\hps.ini) with the location of the Java classes. While you could add the classpath information to your environment variable for your workstation, we recommend that you edit the INI file with this information. In the AP Java section of the hps.ini file, add the paths to the JAVA_CLASSPATH variable. For example, [AP Java] JAVA_CLASSPATH=.; AppBuilder\Java\RT\appbuilder.jar; WebSphere\lib\ujc.jar; WebSphere\lib\servlet.jar 2. Select the application server in the Construction Workbench in the Workbench Options, Preparation tab, as shown in Figure 7-1.
Selecting application server in Preparation options
Figure 7-1
Select the specific application server from the drop-down list. This is equivalent to setting the value in the hps.ini file.
WebSphere
Or you can modify the AppBuilder system initialization file (AppBuilder\hps.ini) so that the selected application server is WebSphere. In the AP Java section, uncomment or change the APPLICATION_SERVER value and comment out or remove the lines for the other servers. For example, APPLICATION_SERVER=WebSphere ; APPLICATION_SERVER=WebLogic
Note
3.
The value WebSphere works for WebSphere version 3.5. If you are deploying WebSphere 4.0, use the value WebSphere40 instead.
For thin clients, the generated partition includes an HTML start page and an error page, both generated from a default template. The default template can be overridden by setting the path to the new template files by setting the values in the system initialization file, hps.ini, using: THINCLIENT_START_HTML=c:\defaultstart.html THINCLIENT_ERROR_HTML=c:\defaulterr.html where defaultstart.html and defaulterr.html are the names of template files.
7-2
Deploying Java on WebSphere
Note
Most web browsers do not support DBCS html file names.
The default templates, svlt-startpage.htpl and svlt-errorpage.html, are in: AppBuilder\AD\CFG\DATA The start page template is assumed to have the following entry: <form method="get" action="$(SVLTCLS)"> where $(SVLTCLS) gets replaced by the generated action target. The error page template is copied as is during prepare. You may use any or all of the following lines in the error page to get more information displayed. <input type="text" name="LVEL_ERROR_CODE" size="20"> <input type="text" name="LVEL_ERROR_DESC" size="77"> <textarea rows="8" name="LVEL_ERROR_CONTEXT" cols="78"> </textarea> The keywords are replaced by AppBuilder during execution if an error is encountered. The code (LVEL_ERROR_CODE) is a number representing the error. (Refer to the Messages Reference Guide.) The description (LVEL_ERROR_DESC) is a short sentence or two describing the error. The context (LVEL_ERROR_CONTEXT) is a stack of calls that led to the error. If these lines do not appear in the error page, then the information is not displayed. 4. For creating the deployable EJB archive, set the WebSphere home directory in the AppBuilder system initialization file (AppBuilder\hps.ini) in the AP Java section. For example, WAS_HOME=c:\WebSphere\AppServer the drive and directory where WebSphere is installed. 5. Prepare the partitions according to the instructions in Chapter 3, Preparing the Application. Refer to Chapter 6, Packaging the Application to understand where AppBuilder puts the generated files. Briefly, the generated (archive) files are put in: AppBuilder\Java\RT\EachAppConfig\YourPartition Make sure the initialization files (appbuilder.ini and appbuildercom.ini) are in the AppBuilder\Java\RT directory of the client machine or in the directory where the client application resides (which is by default AppBuilder\Java\RT\YourAppConfig). If you have modified these initialization files before preparing the partitions, the information is included; if not, you must modify each instance of these files created for each EJB and servlet after preparation.
Caution
In the Partition Properties window, if the Server Interface is EJB, the package name is mandatory. Some application servers (like WebSphere 3.5) require a package name for preparing EJBs, and if the package name is not supplied, an error occurs at deployment time. Check the application server documentation to find out whether a package name is required. For information about the Partition Properties window, refer to Setting Partition Properties on page 2-10
6.
If you are developing and preparing EJBs (server rules) in a Java version 2 Enterprise Edition (J2EE) environment, make sure you have the following in your class path: j2ee_home\lib\j2ee.jar j2ee_home\lib\jhall.jar If you are using a database (such as Oracle or DB2), you need to install SQLJ to prepare database rules. For SQLJ rules, ensure that you have the following in your class path: db2java.zip runtime.zip
7-3
Configuring the Application Server
sqlj.zip You also need classes 111.zip if you prepare for an Oracle database. 7. For invoking EJBs from Java or thin-client, modify the initialization file (AppBuilder\Java\RT\appbuildercom.ini) with the name of the default server set to the WebSphere server. In the SERVER section, uncomment the SERVER.EJBWebSphere lines. The easiest way to do this is with the Communications Configurator. (Refer to the Configuring Communications Guide.) For example:
; Sample entries for WebSphere EJB Server [SERVER.EJBWebSphere] TYPE=EJB INITIAL_CONTEXT_FACTORY=com.ibm.ejs.ns.jndi.CNInitialContextFactory PROVIDER_URL=iiop://localhost:900 In the ROUTES section, set the route to WebSphere (or to the other server name if creating servlets only that are to run on remote servers). For example, [ROUTES] ; $ANY specifies the default server entry for remote rules $ANY=EJBWebSphere The value for $ANY must match the case of the name in the SERVER section of the file described above. For individual rules (as opposed to all the rules), specify the server by: RuleName1=EJBWebSphere RuleName2=EJBWebSphere

Depending on which version of WebSphere application server you are using, follow either: Configuring for WebSphere 3.5 Configuring for WebSphere 4.0
Configuring for WebSphere 3.5

These steps describe how to configure the WebSphere 3.5 application server so that it knows where to look for the generated (archive) files, the Java classes (and any database references), and the AppBuilder configuration files (appbuilder.ini and appbuildercom.ini). 1. Add the indicated Java archive (JAR) files to the dependent classpath for the application server. In the WebSphere Administrative Console, with the View set to Topology, click on the current server in the hierarchy. In the General tab, in the Dependent classpath field, enter the JAR files specified below. Otherwise you must modify the admin.config file, which IBM strongly recommends against (and we agree). AppBuilder\Java\RT\appbuilder.jar; AppBuilder\Java\RT; where the last path is the location of the INI files. If your application uses a database, also add the location of the database-related files to this classpath: Database\Java\db2java.zip; Database\Java\runtime.zip;
7-4
Database\Java\sqlj.zip
Note
This configuration must be performed only once. The values are shown on separate lines to make them easier to read; in the field, enter them all on one line.
If you are running the application server on a different machine from the one on which AppBuilder is installed, move the JAR files and the INI files mentioned so far in the AppBuilder\Java\RT directory to a directory named AppBuilder on the application server. If your application uses a Web service, the client- and the server-side use a Simple API for XML (SAX) parser for parsing the XML. One of the widely used SAX parsers can be downloaded from http://xml.apache.org/xerces2-j/index.html. After download and install of this parser package, include "xerces.jar" in the classpath. 2. If your application uses database access, create a JDBC data source in the WebSphere Administrative Domain in the Administrative Console. Use the same name as the database implementation name. Make sure the JDBC DSN and the ODBC DSN match. Also, make sure the drivers are the same. For example, if you specified db2Pool as the implementation name of the repository database associated with the EJB partition, then you must create a datasource named db2Pool in the Administrative Console. Make sure you use precisely the same capitalization in both places.
Configuring for WebSphere 4.0

These steps describe how to configure the WebSphere 4.0 application server so that it knows where to look for the generated (archive) files and the Java classes (and any database references) and AppBuilder configuration files (appbuilder.ini and appbuildercom.ini). 1. Add the indicated Java archive (JAR) files to the JVM classpath for the application server. In the WebSphere Administrative Console, go to Nodes > Server name > Application servers > Default server > Process definition > JVM settings, and add: $(WAS_HOME)\lib\j2ee.jar; AppBuilder\Java\RT\appbuilder.jar; AppBuilder\Java\RT; where the last path is the location of the INI files. If your applications uses a database, also add the location of the database-related files to this classpath: Database\Java\db2java.zip; Database\Java\runtime.zip; Database\Java\sqlj.zip
Note
This configuration needs to be performed only once. The values are shown on separate lines to make them easier to read; in the field, enter them all on one line.
If you are running the application server on a different machine from the one on which AppBuilder is installed, move the JAR files and the INI files mentioned so far in the AppBuilder\Java\RT directory to a directory named AppBuilder on the application server. 2. If your application uses database access, create a JDBC data source in the WebSphere Administrative Domain in the Administrative Console. Use the same name as the database implementation name. Make sure the JDBC DSN and the ODBC DSN match. Also, make sure the drivers are the same. For example, if you specified db2Pool as the implementation name of the repository database associated with the EJB partition, then you must create a datasource named db2Pool in the Administrative Console. Make sure you use precisely the same capitalization in both places.
7-5
Deploying the EJB Partition
If you use DB2, then you must use COM.ibm.db2.jdbc.DB2ConnectionPoolDataSource implementation class name for the JDBC driver.

Depending on which version of WebSphere application server you are using, follow either: Deploying EJB on WebSphere 3.5 Deploying EJB on WebSphere 4.0
Deploying EJB on WebSphere 3.5

As a result of preparing an EJB for WebSphere 3.5, an archive file is created under the AppBuilder\Java\RT\YourAppConfig directory. For example, the hello_ejb.jar is created for the server partition HELLO_EJB. This archive can be deployed using the WebSphere Admin Console. 1. 2. Start the WebSphere Administration Server. From the Start menu, select Programs > IBM WebSphere > Application Server > Start Admin Server. Start the Administrative Console. From the Start menu, select Programs > IBM WebSphere > Application Server > Administrators Console. In the Administrative Console, right-click Default Server and click Start. In the Administrative Console, right-click the Default Container (or whichever container you are creating the EJBs in) and Create > EnterpriseBean. Enter a name. Write it here so you can remember it. EJB Name:______________________________________________ Browse for the Java archive file (using the example from previously): AppBuilder\Java\RT\hello_world\hello_ejb.jar If you modified the output file name in the websphere-ejb-jar.xml file in the previous procedure, browse to that new file name. Select the JAR file and click Open. 5. Click Yes on the Confirm dialog and select Deploy Only on the next dialog. Click OK for each deployed bean. The output file is stored (with a prefix of Deployed) as WebSphere\DeployedEJBs\Deployedhello_ejb.jar
3.
4.
Deploying EJB on WebSphere 4.0

As a result of preparing an EJB for WebSphere 4.0, an archive file is created under the AppBuilder\Java\RT\YourAppConfig directory. For example, the hello_ejb.jar is created for the server partition HELLO_EJB. This archive can be deployed using the WebSphere Admin Console. 1. 2. Start the WebSphere Administration Server. From the Start menu, select Programs > IBM WebSphere > Application Server V4.0 > Start Admin Server. Start the WebSphere Application Assembly Tool. From the Start menu, select Programs > IBM WebSphere > Application Server V4.0 > Application Assembly Tool. Create a new application and name it. Import your EJB jar file into an EJB Modules section. Select Generate code for deployment and modify the dependent classpath (<AppBuilder>\Java\RT\appbuilder.jar). Click Generate now. You should get a deployed module in the deployed module location with the .ear extension.
7-6
Updating the Thin Client Archive
3.
Start the Administrative Console. From the Start menu, select Programs > IBM WebSphere > Application Server V4.0 > Administrators Console. Go to Nodes > Server name > Enterprise Applications and click Install. Specify the path to your .ear deployed file. Select Next and see a list of your EJBs, select Next again and see a list of your resources. Select Next again and un-check the re-deploy option and click Finish. Save your configuration. Stop the application server and restart it again. You are ready to call your EJBs from a client side.
Updating the Thin Client Archive

When preparing a partition for a thin-client Java application, AppBuilder creates a Java archive (JAR) or Web archive (WAR) in the root of the application configuration directory. The name of the Java archive is partition_name.jar. This file includes: all the generated classes for the servlet, rule, view, sets etc. HTML and the associated includes an error page (errorpage.html) an HTML start page Extract this archive to the servlet context directory for each servlet. Follow these steps for each servlet: 1. Extract the generated Java archive to a temporary directory using the command: jar xvf partition_name.jar 2. The generated Java archive (partition_name.jar) contains a default HTML start page to launch the application and an HTML page for displaying errors. These pages can be edited to include company logo and to make other changes. Alternatively, templates can be defined during prepare so that the correct file is included automatically. Refer to Configuring the Initialization Files for details. Recreate the Java archive using the following command, jar cvf partition_name.jar * When a Web application is deployed, define an alias or context that the Web browser uses to refers to this application. This alias or context is mapped to a physical directory, context_home in the application server. For instance a catalog application has an alias or context called catalog and this alias is mapped to a directory CatalogWebApp.
3.
Deploying the Partition for Thin Client and Web Services

Depending on which version of WebSphere application server you are using, follow either: Deploying Partition on WebSphere 3.5 Deploying the Partition on WebSphere 4.0
7-7
Deploying the Partition for Thin Client and Web Services
Deploying Partition on WebSphere 3.5

1. 2. Start the WebSphere Administration Server. From the Start menu, select Programs > IBM WebSphere > Application Server > Start Admin Server. Start the Administrative Console. From the Start menu, select Programs > IBM WebSphere > Application Server > Administrators Console. Use the Create Web Application wizard to set up a Web application. On the first panel, define the Web Application Name with a unique name, referred to hereafter as appname, enable options for Enable File Servlet and Enable JSP 1.1, and click Next. On the next screen, expand the nodes, choose Default Servlet Engine, and click Next. For the Web Application parameters, use all the defaults, including Virtual Host as default_host and make sure the Web Application Web Path is set to /webapp/appname. On the next screen, change the Document Root property from web directory to servlets. Click Finish. Note:If instead of using the wizard you use right-click Create Web Application, be sure to enable the file servlet and enable to JSP 1.1, which are separate steps but included in the wizard. 3. From the console, expand the Default Servlet Engine and select the Web Application. Right-click and select Create and select Servlet to create a servlet as a child of the Web application. In the General tab of the Create Servlet window, set the Servlet Name to appnameServlet and write it here so you can remember it. Servlet Name:__________________________________________ For thin client servlets, set the Servlet Class Name property to RootRuleClassNameSvlt. RootRuleClassName is derived from the RootRuleName. For example if the root rule is HELLO_WORLD, then the RootRuleClassName is Hello_World and RootRuleClassNameSvlt is Hello_WorldSvlt. When AppBuilder prepares the partition containing the application, a Java servlet class is created with the Svlt suffix added to the name of the root rule. For Web services servlets, set the Servlet Class Name property to the name of the partition defined in AppBuilder. In the Servlet Web Path List area, click Add. Enter the servlet path by typing in the appnameServlet to the default path. Click OK. In the General tab, click OK. 5. In Windows, under the WebSphere\hosts\default_host directory, create a subdirectory with the name of your application, appname, from the previous step. Within that directory, create a servlets subdirectory. This directory holds the static HTML pages for the application, the generated rules and view classes, the generated HTML, etc. Expand the generated archive, partition_name.jar, into the servlets directory. When preparing a servlet, the system puts the archive by default in the following directory: AppBuilder\Java\RT\partitionname\partitionname.jar 7. For thin client servlets, modify the start page for the application. In the HTML file for the start page, in the FORM tag, set the action attribute to the location of the servlet: WebApplicationWebPath/appnameServlet where the WebApplicationWebPath is set in Step 2 as a Web Application parameter and appnameServlet is set in Step 3. When creating a start page for thin-client applications, create at least one input field with a name and value field. For example, <input type="submit" name="Start Application" value="">
4.
6.
7-8
Testing the Deployed Application
For Web services servlet, the webApplicationWebPath/appNameServlet is used in the HOST_URL for targeting to this Web service. When you configure the Client (as either Java or Thin-Client), create a new server entry and set the type of Server to WEBSERVICE and set the HOST_URL to: http://hostname:port/webApplicationWebPath/appNameServlet 8. For thin client configurations, put the start page file (by default RootRuleClassName.html) in the servlets directory. Copy the start page file (by default RootRuleClassName.html) to the HTTP server (IBM HTTP Server\htdocs) for the application server to find it.
Deploying the Partition on WebSphere 4.0

1. 2. 3. 4. Start the WebSphere Administration Server. From the Start menu, select Programs > IBM WebSphere > Application Server V4.0 > Start Admin Server. Start the Administrative Console. From the Start menu, select Programs > IBM WebSphere > Application Server V4.0 > Administrators Console. Use the Create Web Application wizard to set up a Web application. Go to Nodes > Server_name > Enterprise Applications and click Install. Specify the path to your .war file and enter the application name (any one you like) and the Context root (which is the document root for your start page, for example, /myContext). Click Next and see a list of your resources, click Next again, and click Finish. Select Regenerate plug-in information. Save your configuration. Stop the application server and restart it again. You are ready to call your servlets.
5. 6.

This includes: Testing Thin Client Testing EJBs Testing Web Services If you are deploying servlets, deploy and execute the servlet before testing the EJB.
Testing Thin Client

Restart the WebSphere application server hosting this application. From a Web browser, use the following URL to load the start page, http://hostname/myContext/startpage.html where hostname is the name of the machine. And myContext refers to the Web path defined in step 2 of Deploying EJB on WebSphere 3.5 for WebSphere 3.5. In WebSphere 4.0, myContext refers to the context root defined when deploying the thin-client Web archive (WAR). And the startpage.html is the name of the HTML file for the start page.
AppBuilder 2.1.0 Deploying Applications Guide 7-9
Testing EJBs
If you are using EJBs with a Java client, copy the command files from the AppBuilder/NT/Sys/HLP/ CommandFiles directory to your local drive in the directory associated with you application configuration. If you are using EJBs with a Java client, modify the run-client command file (runWSClient.cmd) previously copied to the directory associated with your application configuration. Look in AppBuilder\Java\RT\YourAppConfig. Modify the call line with the drive letter and directory of your local installation as above. Modify the application configuration directory and the client JAR file name in the Java command, and type in the name of the top level rule of the client partition of your application at the end of the line. For example, java -classpath AppBuilder\Java\RT\helloworld\hello_html.jar; %WAS_CP%;%JARS_NEEDED%;%CLASSPATH%; Hello_World_Client_Rule Execute the run-client command file (runWSClient.cmd). Update the client-side initialization files as in step 7 of Configuring the Initialization Files.
Note
If you are using EJBs with a remote servlet, you need to include the deployed EJB jar file (EJB stubs) in the remote server classpath (the same place where you have appbuilder.jar).
Testing Web Services

The Web services can be invoked from an AppBuilder client (Java thick or thin client) or from a third party client. The AppBuilder client can be made to invoke a Web service similar to invoking other Servers simply by creating a new Server Route entry in appbuildercom.ini and there is no other change required on the client. The easiest way to do this is to use the Communications Configurator (refer to the Configuring Communications Guide). For example: [SERVER.myServer] TYPE=WEBSERVICE HOST_URL=http://hostname:port/ServletContext/ServletName where hostname is the name of the server port is the TCP/IP port number on which the servlet engine is listening. Typically, the default server is listening on ports 80, 9080, or 9090, but it can be configured to run on other port numbers. The Web service servlet can be deployed on any of these ports by the application server. Check the port numbers because the application server does not display on which port this servlet is deployed. The port number must be specified even if a default port, for instance 80, is used. ServletContext is the WebApplicationWebPath ServletName is the appnameServlet and, for using the Web service from a third-party client, refer to Chapter 9, Executing the Application. The application is now deployed and ready to receive requests.
7-10
Suggestion After you have fully tested your application, it is a good idea to drop that application from the hierarchy in the WebSphere Console and delete the home directory of the application from the disk. On WebSphere, even if you drop the application from the hierarchy and use a different name for the application and have an EJB that was being deployed, your new application that you are trying to test loads the classes for the old application. This can cause major conflicts not to mention you may have no idea what you are testing. Also, when you deploy an EJB, WebSphere puts that jar file in a directory called deployedEJBs. so you may want to delete that from the disk as well. On IBM AS/400 On the IBM AS/400 platform, to access a DB2 database with Java in WebSphere, you must put a different file in the classpath. What was originally db2java.zip is now apparently db2_classes.jar. Also, the JDBC driver we specify in the appbuilder.ini for UDB does not work as it does for other platforms. IBM has changed the call from: COM.ibm.db2.jdbc.app.DB2Driver to: com.ibm.db2.jdbc.app.DB2Driver The first three letters are lower case. It seems the files in the Java archive (JAR) are lower case now.
7-11
7-12
CHAPTER
DEPLOYING JAVA ON WEBLOGIC
With AppBuilder, you can develop, deploy, and test enterprise applications targeted for Java environments. This may include a servlet or an Enterprise Java Bean (EJB) or both running on an application server. This section describes the procedures to deploy and run Java applications on the BEA WebLogic application server, versions 5.1 and 6.0 or higher. This set of procedures assumes that you have WebLogic on your development machine along with AppBuilder. The procedures are: Configuring the Initialization Files (with WebLogic as the application server) Configuring the Application Server Deploying the EJB Partition (the EJB part of the application) Updating the Thin-Client Archive Deploying the Partition for Thin-Client and Web Services (the servlet part of the application) Testing the Deployed Application on WebLogic The configuring procedures apply to any implementation involving WebLogic. If you only need the EJB implementation, follow the procedures for updating and deploying the EJB. If you only need the servlet implementation, follow the procedures for updating and deploying the servlet. If you need both the servlet and EJB parts of the application, follow all the procedures. These instructions assume that you have WebLogic installed. For more information about developing applications for WebLogic, refer to the WebLogic documentation (http://www.weblogic.com/docs51/ resources.html). These instructions use the following conventions for directory names: WebLogic is the name for the drive and directory where WebLogic is installed (for example, c:\WebLogic). AppBuilder is the name for the drive and directory where AppBuilder is installed (for example, c:\AppBuilder). If you are using a database (not essential for WebLogic) the following instructions assume that you have installed IBM DB2/UDB or Oracle in the Database drive and directory (for example, c:\db2dir). Examples in this set of procedures use DB2/UDB 6.1 (or 7.1) database.
Note
Remember that application servers are case sensitive. Be sure to double-check any commands or URLs typed at a command prompt or in a command file or in entry fields in the interface.
8-1

These steps describe how to configure the initialization (INI) files in AppBuilder so that it knows which application server is used and where to look for Java classes as needed. These steps should be performed before the partitions are prepared in AppBuilder. Refer to the Chapter 3, Preparing the Application for information on preparing partitions. Perform these steps on the development workstation where you are running AppBuilder. Use the INI file editor from the Management Console to edit the INI files. 1. Select the application server in the Construction Workbench in the Workbench Options, Preparation tab, as shown in Figure 8-1.
Figure 8-1
Or you can modify the AppBuilder system initialization file (AppBuilder\hps.ini) so that the selected application server is WebLogic. In the AP Java section, uncomment or change the APPLICATION_SERVER value and comment out or remove the lines for the other servers. For example, APPLICATION_SERVER=WebLogic ; APPLICATION_SERVER=WebSphere For a thin client configuration, the generated partition includes an HTML start page and an error page, both generated from a default template. The default template can be overridden by setting the path to the new template files in the system initialization file, hps.ini, using these values: THINCLIENT_START_HTML=c:\defaultstart.html THINCLIENT_ERROR_HTML=c:\defaulterr.html where defaultstart.html and defaulterr.html are the names of template files. The default templates, svlt-startpage.htpl and svlt-errorpage.html, are in: AppBuilder\AD\CFG\DATA The start page template is assumed to have the following entry: <form method="get" action="$(SVLTCLS)"> where $(SVLTCLS) gets replaced by the generated action target. The error page template is copied as is during prepare. You may use any or all of the following lines in the error page to get more information displayed. <input type="text" name="LVEL_ERROR_CODE" size="20"> <input type="text" name="LVEL_ERROR_DESC" size="77"> <textarea rows="8" name="LVEL_ERROR_CONTEXT" cols="78"> </textarea>
8-2
The keywords are replaced by AppBuilder during execution if an error is encountered. The code (LVEL_ERROR_CODE) is a number representing the error. (Refer to the Messages Reference Guide.) The description (LVEL_ERROR_DESC) is a short sentence or two describing the error. The context (LVEL_ERROR_CONTEXT) is a stack of calls that led to the error. If these lines do not appear in the error page, then the information is not displayed. 2. Prepare the partitions according to the instructions in Chapter 3, Preparing the Application. Refer to Chapter 6, Packaging the Application to understand where AppBuilder puts the generated files. Briefly, the generated (archive) files are put in: AppBuilder\Java\RT\EachAppConfig\YourPartition Make sure the initialization files (appbuilder.ini and appbuildercom.ini) are in the AppBuilder\Java\RT directory of the client machine or in the directory where the client application resides (which is by default AppBuilder\Java\RT\YourAppConfig). If you have modified these initialization files before preparing the partitions, the information is included; if not, you must modify each instance of these files created for each EJB and servlet after preparation. 3. If you are developing and preparing EJBs (server rules) in a Java version 2 Enterprise Edition (J2EE) environment, make sure you have the following in your class path: j2ee_home\lib\j2ee.jar j2ee_home\lib\jhall.jar If you are using a database (such as Oracle or DB2), you need to install SQLJ to prepare database rules. For SQLJ rules, ensure that you have the following in your class path: db2java.zip runtime.zip sqlj.zip You also need classes 111.zip if you prepare for an Oracle database. If your application uses a Web service, the client- and the server-side use a Simple API for XML (SAX) parser for parsing the XML. One of the widely used SAX parsers can be downloaded from http://xml.apache.org/xerces2-j/index.html. After download and install of this parser package, include "xerces.jar" in the classpath. 4. For invoking EJBs from Java or thin-client, modify the initialization file (AppBuilder\Java\RT\appbuildercom.ini) with the name of the default server set to the WebLogic server. In the SERVER section, uncomment the SERVER.EJBServer lines. ; Sample entries for WebLogic EJB Server [SERVER.EJBWebLogic] TYPE=EJB INITIAL_CONTEXT_FACTORY=weblogic.jndi.WLInitialContextFactory PROVIDER_URL=t3://WebLogic_Server:7001
Note
If you have multiple servers and some rules will be put on different servers, two separate server entries need to be created for each appserver referenced. In this scenario, instead of using the $ANY setting in the [ROUTES] section, use RuleName=AppServer, where AppServer is the server entry.
For servlets only (no EJBs) that are to run locally, leave the default values for servers. For servlets only (no EJBs) that are to run on remote servers, either set the default server as RMI or NetEssential by uncommenting the appropriate lines or create a new server name. In the ROUTES section, set the route to WebLogic (or to the other server name if creating servlets only that are to run on remote servers). For example, [ROUTES] ; $ANY specifies the default server entry for remote rules $ANY=EJBWebLogic The value for $ANY must match the case of the name in the SERVER section of the file described above. For individual rules (as opposed to all the rules), specify the server by:
AppBuilder 2.1.0 Deploying Applications Guide 8-3
RuleName1=EJBWebLogic RuleName2=EJBWebLogic

Follow these steps to configure the WebLogic application server. 1. 2. Add the indicated Java archive (JAR) file, weblogicaux.jar, and the WebLogic\classes to the classpath. If your application uses database access, create in WebLogic a data source with the same name as the database implementation name in AppBuilder. Make sure that you use exactly the same capitalization in the properties file under weblogic.jdbc.connection-pool.

The following topics are included in this section: Configuring for EJB Deployment in WebLogic 5.1 Configuring for EJB Deployment in WebLogic 6.0 or Higher Deploying EJB in WebLogic 5.1 Deploying EJB in WebLogic 6.0 or Higher
Configuring for EJB Deployment in WebLogic 5.1

1. Modify the command files, setenv.cmd and startweblogic.cmd, so that the classpath includes the appbuilder.jar. In setenv.cmd, add appbuilder.jar to the CLASSPATH variable. In startWebLogic.cmd add appbuilder.jar to the WEBLOGIC_CLASSPATH variable. Also in the command files, add the AppBuilder\Java\RT directory to the classpath for including appbuilder.ini and appbuildercom.ini files.
2.
Configuring for EJB Deployment in WebLogic 6.0 or Higher

1. In WebLogic 6.0, each domain has a set of configuration files like setenv.cmd and startweblogic.cmd under the config directory. Modify the startweblogic.cmd for the required domain, so that the classpath includes both the appbuilder.jar and the AppBuilder\Java\RT directory.
Deploying EJB in WebLogic 5.1

As a result of preparing the EJB, the system creates an archive. For example:
8-4
Appbuilder\Java\RT\hello_world\hello_ejb.jar This archive can be used within the WebLogic EJB deploy tool to prepare a deployable Java archive (JAR) that can be dynamically deployed on a WebLogic application server. The deploy tool can be invoked from the WebLogic program folder or can be run from the command line. 1. To run it from the command line on a Microsoft Windows (either NT or 2000) machine, from the WebLogic home directory, type: setenv.cmd and run this command: java -mx64m -ms64m weblogic.EJBDeployerTool where the first option (-mx64m) increases the heap size to 64 MB and the second option (-ms64m) increases the stack size to 64 MB. For UNIX, you would run this command: . setEnv.sh 2. Define the EJB C Properties for the Java compiler and create server entries with host name, port number, password, etc. Then open the created Java archive file (File > Open). For example, AppBuilder\Java\RT\hello_world\hello_ejb.jar and click generate container, which creates a deployable Java archive. This can be deployed using the Deploy command. 3. 4. Save the deployable Java archive. Click Save As and enter a name for the file. Add the compiled Java archive to the EJB section of the properties file (weblogic.properties). For example, weblogic.ejb.deploy=Target\hello_ejb.jar 5. 6. Add the deployed Java archive file to the classpath WEBLOGIC_CLASSPATH in the start command file (startWebLogic.cmd) for starting the WebLogic application server. If your application uses a database, you need to add a connection pool entry in the properties file (weblogic.properties). Associate the pool name with a physical database. For example, weblogic.jdbc.connectionPool.PoolName=\ url=jdbc:db2:DBName,\ driver=COM.ibm.db2.jdbc.app.DB2Driver,\ loginDelaySecs=1,\ initialCapacity=1,\ maxCapacity=4,\ capacityIncrement=1,\ allowShrinking=true,\ shrinkPeriodMins=15,\ refreshMinutes=10,\ testTable=TableName,\ props=user=UserID;password=Password;server=WLServer where: PoolName is pool name associated by the administrator with a physical database, DBName is a physical database name, like ABDEMO,
8-5
TableName is the database table name used by the database, UserID is the user of the database, Password is the user password of the database, WLServer is the name of the machine where the WebLogic Server resides. Associate the database JNDI name with the pool name already defined. The TXDataSource for the connection pool should be: weblogic.jdbc.TXDataSource.DBJNDIName=PoolName where: DBJNDIName is the database implementation name from the AppBuilder repository, PoolName is pool name associated by the administrator with a physical database, Access settings include weblogic.allow.reserve.weblogic.jdbc.connectionPool.PoolName= everyone 7. If you are using DB2/UDB (installed on Database) as a database, in startWebLogic.cmd, to the WEBLOGIC_CLASSPATH, add: Database\Java\db2java.zip, Database\Java\runtime.zip, Database\Java\sqlj.zip. 8. Start the WebLogic Server by issuing startWebLogic.cmd in the WebLogic directory. Once the WebLogic Server started message is displayed without any errors, the client is ready to run.
Deploying EJB in WebLogic 6.0 or Higher

As a result of preparing the EJB, the system creates a Java archive. For example: AppBuilder\Java\RT\hello_world\hello_ejb.jar This archive can be directly deployed under the WebLogic server. Each domain in the WebLogic server has an applications subdirectory to which the deployable archive files should be copied. Copy the hello_ejb.jar to this directory and when the server for this domain is started, the newly copied archives are deployed. And to refresh with a new copy of the archive, just overwrite the existing archive in this directory. If your application uses a database, define a connection pool and associate the pool name with a JNDI name by defining a TxDataSrource in the WebLogic Server Console. For example, to create a connection pool, follow these steps: 1. Right-click on the Connection Pool entry under JDBC section and invoke Create a new JDBC Connection Pool. Enter the Pool Name, the URL to the physical database (jdbc:db2:DBName for db2), the driver name (com.ibm.db2.jdbc.app.DB2Driver), and define the required properties (user=UserID, password=Password, server=WLServer). Right-click on TxDataSources and Create a new JDBC Tx Data Source, enter a DataSource name, set the JNDI Name to the database implementation name from the AppBuilder repository and set the pool name to the one defined above.
2.
8-6
Updating the Thin-Client Archive
3.
Include the required database archives into the CLASSPATH defined in startWebLogic.cmd. To use DB2/UDB, include Database\java\db2java.zip Database\java\runtime.zip Database\java\sqlj.zip
4.
Restart the Server for the modified domain. The server is ready to run.

When preparing a partition for a thin-client Java application, AppBuilder creates a Web archive (WAR) in the root of the application configuration directory. The name of the Web archive file is partition_name.war. This file includes: the generated classes for the servlet, rule, view, sets etc. HTML and the associated includes a deployment descriptor specific to WebLogic an HTML error page (errorpage.html) an HTML start page Follow these instructions for each servlet: 1. Extract the generated Web archive on to a temporary directory using the command: jar xvf partition_name.war 2. The generated Web archive, partition_name.war, contains a default HTML start page (rootrulename._r.html) to launch the application and an HTML page for displaying errors. These pages can be edited to include company logo and to make other changes. Alternatively, templates can be defined during prepare so that the correct file is included automatically. Refer to Configuring the Initialization Files for details. You can change the name of the start page. Recreate the archive using the following command, jar cvf partition_name.war * When a Web application is deployed, define an alias or context that the Web browser uses to refer to this application. This alias or context is mapped to a physical directory, context_home in the application server. For instance a catalog application has an alias or context named catalog, and this alias is mapped to a directory named CatalogWebApp.
3.
Deploying the Partition for Thin-Client and Web Services

The following topics are included in this section: Deploying the Servlet Partition for WebLogic 5.1 Deploying the Servlet Partition in WebLogic 6.0
8-7
Deploying the Partition for Thin-Client and Web Services
Deploying the Servlet Partition for WebLogic 5.1

1. Edit the properties file (weblogic.properties) and add an entry for the Web application, weblogic.httpd.webApp.context= WebLogic\myServer\public_html\context_home context is the URL alias when invoked from the Web browser and context_home refers to the directory to which the Java archive has been extracted. 2. Extract the contents of the Web archive (partition_name.war) to the context home (context-home) for the web application, cd WebLogic\myServer\public_html\context_home jar xvf partition_name.war 3. Edit the command script file (startweblogic.cmd) to include the context home context_home, the location of the AppBuilder.ini file, and the AppBuilder.jar in the WebLogic classpath. Set it using the following entry, set WEBLOGIC_CLASSPATH = AppBuilder\Java\RT; AppBuilder\Java\RT\AppBuilder.jar; WebLogic\myserver\public_html\context_home 4. 5. Put the start page file (rootrulename._r.html by default) for the application server to find it. Restart the WebLogic application server.
Deploying the Servlet Partition in WebLogic 6.0

In WebLogic 6.0, each domain has a set of configuration files like setenv.cmd and startWebLogic.cmd under the config directory. Modify the startWebLogic.cmd for the required domain to include appbuilder.jar and AppBuilder\java\rt directory in the CLASSPATH. When preparing a partition, AppBuilder creates a Java archive (JAR) or a Web archive (WAR) in the root of the application configuration directory. This archive can be directly deployed under the WebLogic server. Each domain in the WebLogic server has an applications subdirectory to which the deployable archive file should be copied. When the server for this domain is started, the newly copied archive is deployed. And to refresh it with a new copy of the archive, simply overwrite the existing archive. Restart the Server for the modified domain.
8-8

This section includes: Testing Thin Client Testing EJBs Testing Web Services 1. If you are deploying servlets, deploy and execute the servlet before testing the EJB.
Testing Thin Client

2. Restart the WebLogic application server hosting this application. From a Web browser, use the following URL to load the start page, http://hostname:7001/context/startpage.html where hostname is the name of the machine and the startpage.html is the name of the HTML file for the start page and the context refers to the webApp name defined (in WebLogic Server 5.1) or to the name of web archive without extension (in WebLogic Server 6.0).
Testing EJBs
3. Copy the command files from the AppBuilder/NT/Sys/HLP/CommandFiles directory to your local drive in the directory associated with your application configuration. If you are deploying servlets with EJBs, get the run-client command file (runWLClient.cmd). The run-client command file runs the thick-Java client. If you are using EJBs with a thick-Java client, modify the run-client command file (runWLClient.cmd) previously copied to the directory associated with your application configuration. Look in AppBuilder\Java\RT\YourAppConfig. Modify the call line with the drive letter and directory of your local installation as above. Modify the application configuration directory and the client JAR file name in the Java command, and type in the name of the top level rule of the client partition of your application at the end of the line. For example, call e:\weblogic\setenv.cmd java -classpath AppBuilder\Java\RT\YourAppConfig\YourClientJar.jar; %CLASSPATH% YourTopLevelClientRule 5. Execute the run-client command file (runWLClient.cmd).
If you are using EJBs with a remote servlet, you need to include the deployed EJB jar file (EJB stubs) into the remote server classpath (the same place where you have appbuilder.jar).
4.
Note

The Web services can be invoked from an AppBuilder client (Java thick or thin client) or from a third party client. The AppBuilder client can be made to invoke a Web service similar to invoking other Servers simply by creating a new Server Route entry in appbuildercom.ini and there is no other change
8-9
required on the client. The easiest way to do this is to use the Communications Configurator (refer to the Configuring Communications Guide). For example: [SERVER.myServer] TYPE=WEBSERVICE HOST_URL=http://hostname:port/ServletContext/ServletName where hostname is the name of the server port is TCP/IP port number on which the servlet engine is listening. The default is 7001 or 7002. ServletContext refers to the context defined in the weblogic.properties under WebLogic version 5.1. In WebLogic version 6.0, this context refers to the Web archive (WAR) name. ServletName is name of the Web service partition in AppBuilder. and, for using the Web service from a third-party client, refer to Chapter 9, Executing the Application. The application is now deployed and ready to receive requests.
8-10
CHAPTER
EXECUTING THE APPLICATION
AppBuilder 2.1 Deploying Applications Guide
After you develop and prepare an AppBuilder application in the Construction Workbench, the system creates the run-time files for the graphical user interface (GUI) for end-user access. The same run-time system is used whether the application runs transparently on a production workstation or from within the Construction Workbench on a development workstation. Some generated applications operate as client/server systems on both workstations and servers. Other applications operate as distributed processing systems on both workstations (or dumb terminals) and mainframes. There is built-in AppBuilder support for both scenarios. Configuring communications includes setting the route table and other settings in the dna.ini file (for internal AppBuilder communications). After an application is prepared, the required portions of the underlying structure are compacted into efficient executable form, and the application can be run from a pull-down menu or a start programs item. On a development workstation, an application is run either by selecting a start item or entering a command-line program name. Once the menu bar (or start item) is displayed, selecting individual menu choices (or submenu items) begins execution of the associated process or rule. The execution of a distributed application includes running the application objects on several machines. The application can be run from the Construction Workbench or the command line. This section explains the procedures for executing the distributed application. The basic steps are: Extracting the Web Archive Customizing the Initialization Files (the INI files) Configuring for Thin Client Execution (and adding a start page for Web applications) Recreating the Archive Executing an Application Invoking an AppBuilder Web Service (if you are using Web services) Understanding Execution Differences (if you want to understand how thin clients differ from thick clients at execution time) Using Date Completion Shortcuts (if you want to use some shortcuts)
9-1
Extracting the Web Archive
Extracting the Web Archive

Before you execute a thin-client application, you must extract the generated Web archive (WAR) file to a temporary directory. To do so, use the command: jar xvf <partitionname>.war When we use the 'jar' command to extract the application from the Java archives, we lose the original timestamp and there is no option to override that. This in not so much a problem with AppBuilder as much as it is with the Java Development Kit. When we use WinZip, it seems to retain the original timestamp after extraction. In the Windows environment, we suggest using WinZip and suggest using a similar extractor for other environments such as UNIX.
Customizing the Initialization Files

Before you execute a Java thick-client or thin-client application, you can edit the configuration files appbuilder.ini and appbuildercom.ini in the Java run-time directory (<AppBuilder>\Java\RT by default) to customize the settings for your application. The easiest way to do that is to use the Communications Configurator (refer to the Configuring Communications Guide). This includes: Setting Thin-Client Execution Parameters Setting Web Service Execution Parameters
Setting Thin-Client Execution Parameters

There are several configurable parameters that affect the execution of an AppBuilder thin-client application in the appbuilder.ini file. The parameters that can be set in the SERVLET section are summarized in Table 9-1.
Table 9-1 Thin-client execution parameters Action description The amount of time (in milliseconds) from the last access that a session times out. Default is 300000 (5 minutes). Whether to have all sessions retained in memory (set to MEMORY_CACHE) or all sessions saved in the application servers file system (set to FILE_CACHE) or partly in memory and partly in the file system (set to BOTH). Default is BOTH. The URL of the custom error page from the context of the servlet. For example, if the error page, myErrorPage.html is created in a subdirectory custom under the servlet context directory, set ERROR_PAGE=custom\myErrorPage.html. This is valid only when CACHE_TYPE is set to BOTH. This is the maximum number of sessions to have in MEMORY_CACHE. All new sessions beyond this limit are saved in FILE_CACHE. Default is 1000. The maximum number of concurrent users. If this number is exceeded, the message Server too busy is displayed. Default is 10000. This is valid only when CACHE_TYPE is set to BOTH. This is the amount of time (in milliseconds) from the last access that a memory cache session times out. Then the session is transferred to a FILE_CACHE if the APPLICATION_TIMEOUT is greater than the MEMORY_CACHE_TIMEOUT. Default is 180000 (3 minutes). Specify character encoding for languages.
SERVLET parameter name APPLICATION_TIMEOUT
CACHE_TYPE
ERROR_PAGE
MAX_CACHED_SESSIONS MAX_CONCURRENT_SESSIO N
MEMORY_CACHE_TIMEOUT
CHARACTER_ENCODINGS
9-2
Executing the Application
Configuring for Thin Client Execution
Setting Web Service Execution Parameters

There are several configurable parameters that affect the execution of an AppBuilder application under Web services in the appbuilder.ini file. The parameters that can be set in the WEBSERVICE section are summarized in Table 9-2.
Table 9-2 Web service execution parameters Action description This selects the SAX (Simple API for XML) Parser. Since the SAX Parser is supplied by various vendors and the package names for each one of them may be different, this parameter is provided to let you set the parser. By default, AppBuilder uses the SAX Parser part of xerces.jar from Apache (org.apache.xerces.parsers.SAXParser). The SAX parser from Apache can be downloaded from http://xml.apache.org/xerces2-j/index.html. After download and install, include the xerces.jar in the classpath of both client and server. This sets the buffer size for the parser in bytes. The Web service request handler needs to peek-through the input stream to validate the service name and the request. This peek needs a buffered stream and a buffer size big enough to include this information. The default is 4096. This sets whether to log the SOAP/XML request and response into a temporary file as a record of the transaction. Each request and response pair can be logged in a temporary file created under the servlet context. Refer to the application server documentation for the exact location of these files. The files have AB as the prefix and .req and .res as extension names.
WEBSERVICE parameter name
SAX_PARSER
PARSER_BUF_SIZE
LOGGING

For some distributed applications, additional set up is required for execution. This is true for a thinclient application, which is deployed on the Web server (or application server) and the output (in the form of HTML) is sent to the Web browser. The application can be kicked off using an HTML start page from the Web browser. Once the application starts, the current or top window (in the form of HTML) is displayed with the dynamic data. Setting up for Web execution includes: Creating an Alias (or Context) Creating a Start Page Configuring the Web Client Session Cache Setting Client Authentication with HTTP Cookies Using Remote Rules Specifying Character Encoding for MLS Support
Creating an Alias (or Context)

For a Web application, define an alias or context that can be used from the Web browser when referring to the application. This alias is mapped to a physical directory, <context_home> in the application server. For example, a catalog application has an alias catalog and this is mapped to CatalogWebApp, a subdirectory.
9-3
Creating a Start Page

For a Web application, you must create a start page. When a partition containing a servlet is prepared, a servlet class is generated with the long name of the rule with a suffix Svlt. The long name in AppBuilder is defined with underscores and is converted into a class name following the conventions of Java notations. For example, a rule with the long name of HELLO_WORLD is converted as Hello_WorldSvlt.class treating the first letter and every letter following the underscore as upper case and other characters as lower case. The start page for the application should refer to the generated servlet class in the form action statement. For the example mentioned previously the HTML required would be: <form method="post" action="Hello_WorldSvlt"> Example Here is a sample start page for the HELLO_WORLD servlet: <html> <head> <title>Initial Page for Servlet</title> </head> <body> <form method="post" action="Hello_WorldSvlt"> <input type=text name="LVEL_SESSION_ID" value="0" > <input type=text name="LVEL_PAGE_ID" value="0" > <input type=text name="LVEL_ROOT_RULE" value="Br_Test" > <p> <input type=submit> </form> </body> </html>
Configuring the Web Client Session Cache

The servlet-based application is started on the Web server and a client session is created that maintains the state of the application. The state of the application includes the current dynamic data in Views and Fields and the currently active rule calling stack (the sequence of rules called from other rules to return when the rules are exiting). This session can either be cached in memory (MEMORY_CACHE) or in the protected Web servers file system (FILE_CACHE) or partly in MEMORY_CACHE and partly in FILE_CACHE. The cached session is automatically reactivated or reloaded when a subsequent request arrives for the client session. Configure the caching scheme by using the execution parameters discussed in Customizing the Initialization Files. The MEMORY_CACHE uses the system memory and the session can be reactivated faster when the subsequent request arrives. The memory usage increases with the number of active client sessions as more and more dynamic data and rule calling stacks are added. Depending on the size and availability of the system memory, the MEMORY_CACHE should be configured. The FILE_CACHE uses the local file system to save the client sessions state and is reloaded into memory when the subsequent request arrives. The files are placed within the context of the servlet and application server.
9-4
Setting Client Authentication with HTTP Cookies

For thin client applications, HTTP transfers cookies that contain data in the form of a name and value pair with an expiry time on them. This helps the end user from having to enter personal information such as user identifier, password, etc. more than once. These cookies can be created from the servletbased application and sent to the Web browser and this cookie lives on the browser environment as long as the expiry time. There can be any number of cookies defined in the application and these are sent along with the HTML response. Whenever the cookie information arrives from the Web client, it is copied to the client session. The rules can read these cookies. Refer to the ObjectSpeak Reference Guide for methods on the Rule object that make use of cookies.
Using Remote Rules

A thin-client rule can invoke any remote rule (like any other rule) and it does so by using these server interfaces: 1. 2. 3. 4. 5. NetEssential Enterprise Java Beans (EJB) Remote Method Invocation (RMI) MQ Web service
Specifying Character Encoding for MLS Support

Here are two different scenarios for using character encoding: When using the default country (locale) for the window. The locale is not set in Construction Workbench. By default, an application written and prepared for a particular locale works properly when the server is in the same locale. For example, an application written and prepared for Japanese will work on a Japanese server. When the country is set to a specific country (locale) for a window in Construction Workbench. An application written and prepared for a particular locale will also work independent of the server locale, provided the appbuilder.ini setting CHARACTER_ENCODINGS in the [SERVLET] section is specified. The syntax for this appbuilder.ini setting is: CHARACTER_ENCODINGS=<iso lang_code1>=<encoding1>;<iso_lang_code2>=<encoding2>; When language encoding is not specified, the system default encoding is used. For example, if the server is running in en_US locale and serving two different applications, one written in Japanese and the other in English, then: CHARACTER_ENCODINGS=en=windows-1252;ja=Cp943; The en=windows-1252 is optional when the server is in a US locale.
9-5
Recreating the Archive
Recreating the Archive

Before you execute a thin-client application, create the Web archive (WAR) file. To do so, use the command: jar xvf partitionname.war
Executing an Application
There are several ways to execute an application: Executing from the Construction Workbench Executing from the Start Menu Executing from the Command Line Whether you have prepared the application with the menu and menu choices or with the shortcut and Start menu option, the application execution is the same. When you run the application, the choices in the menu bar (or entries in the Start menu) corresponds to the functions in your application hierarchy and the choices in each pull-down menu (or entries in the submenu of the Start menu) correspond to the processes within that function. For example, the Java execution client is displayed as shown in Figure 9-1. From that window, select the menu to see the functions that were prepared for that application.
Figure 9-1 Java Execution Client window
Project name Function name
Executing from the Construction Workbench

Within the Construction Workbench, you can launch the application. From the Run pull-down menu, select either Java or Windows, depending on the environment chosen for the application.
Executing from the Start Menu

In Windows, from the Start menu, you can launch the application. Select Start > Programs > AppBuilder > Execution Client. Then select either Java or Windows, depending on the environment chosen for the application. Optionally, for a Windows application, if you have created a menu item under Start > Programs >, you can launch the application from there.
9-6
Executing from the Command Line

For C applications in a Windows environment, the application (a rule) can be launched from a command line in a command line window. Refer to Appendix C, Command Line Rules Execution for a description of the command and a list of valid parameters. For Java applications, the command issued depends on the type of application. The simplest form that can be used for a standalone application is: java yourRule where yourRule is the name of the generated java class. This command should be executed from the <AppBuilder>\Java\RT\local directory, unless you have the Environment Settings set properly. The command line command is case sensitive.
Executing a Java Applet

The prepared Java application can be deployed as an Applet to be run from a remote Web/App Server. The Applets generated from AppBuilder can be displayed as Java Frames which pop out from the Browser as separate windows, or they can be displayed as Java Internal Frames. When displaying Java Frames, multiple application windows will be running as separate windows outside of the browser. When using Internal Frames, the windows will be displayed as frames inside the browser. These frames are called MDI windows in Windows terminology. The Java Internal Frames are light weight frames, and will stay within the given applet pane. The type of Frame to be used in the Applets can be dynamically configured in the appbuilder.ini. The following are the steps involved in deploying AppBuilder Applets: Creating a Java Applet class Creating an HTML to Start the Applet Configuring AppBuilder Configuring Web/AppServer Executing from Web Browser
Creating a Java Applet class

To execute a Java applet, a Java class which derives from JApplet should be created. This class should invoke the Root Rule startup class and the generated Java class will execute from there. The AppBuilder contains a built-in Applet class which can be used instead of writing one. The html file under AppBuilder\Java\html, ExecutionClient.html which works similar to the execution clients in the AppBuilder program group, uses the built-in applet. When the html is loaded on the browser, It will list all the prepared processes as a menu and any one of them can be kicked-off to run as an applet. The following sample shows a simple applet which invokes any given Root Rule. import appbuilder.*; import appbuilder.util.*; import javax.swing.*; import java.util.*; import java.awt.*; public class FrameApplet extends JApplet
AppBuilder 2.1 Deploying Applications Guide 9-7
{ //override JApplets init method to set the desktop pane and //kick-off the Root Rule public void init() { try { /*Create a new JDesktopPane and set it as the content of the Applets viewing area. This also should be set in AppBuilder to be used as a container for the application windows. The DesktopPane is required when using the InternalFrames for the app windows. Refer to the Configuring the AppBuilder for information on the different types of Applet window. */ JDesktopPane p=new JDesktopPane(); //set DesktopPane to be the content pane setContentPane(p); //set it as a parent of all AppBuilder windows AbfSystem.setDesktopPane(p); /*Prompts for root rule name and invokes it. Make sure the Root Rule and other application classes are included in the archive param when defining the applet in the starting HTML. */ String ruleName=JOptionPane.showInputDialog("Enter Root Rule Name:"); //convert the Rule name to Java class name Sting ruleClassName=AbfModule.genClassName(ruleName); //Kick-off the rule AbfModuleStartup rs=new AbfModuleStartup(null, null, ruleClassName, false, null); rs.startup(); getContentPane().setBackground(SystemColor.window); } catch(NoSuchElementException ex) { showErrorMessage("NoSuchMethodException"); } } public void start() { } public void stop() { } private void showErrorMessage(String errorMessage) {
9-8
String showPopup=System.getProperty("appbuilder.showMessage"); if (showPopup==null||!showPopup.equals("NO")) { JOptionPane.showMessageDialog(null, errorMessage, null JOptionPane.ERROR_MESSAGE); { } //a method called from Javascript... public Sting showMsg(Sting msg) { return"Hello from Java"; //JOptionPane.showMessageDialog(null, mesg); } }
Creating an HTML to Start the Applet

This section describes the standard way to describe an Applet and the associated configuration and class files. The AppBuilder installs a ExecutionClient.html as described above. The following sample html loads the applet, FrameApplet described in the previous section. It will be used in both Internet Explorer and Netscape browsers and it uses standard Java 1.3 plug-in. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso8859-1"> <TITLE>Bluephoenix Solutions AppBuilder</TITLE> </HEAD> <BODY LINK="#0000ff" VLINK="#0000ff" ALINK="#0000ff"> <FORM NAME="AppFrame"> <input type="button" name="Submit" value="InvokeJava" onClick="javascript: CallJava()" language="Javascript"> <OBJECT ID="TestApp" classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93" width="700" height="500" align="baseline" codebase="http://java.sun.com/products/plugin/1.3/jinstall-13win32.cab#Version=1,3,1,4"> <PARAM NAME="code" VALUE="FrameApplet.class"> <PARAM NAME="codebase" VALUE=".">  <PARAM NAME="archive" VALUE="app.jar"> <PARAM NAME="type" VALUE="application/x-java-applet;version=1.3"> <PARAM NAME="scriptable" VALUE="true"> <COMMENT> <EMBED type="application/x-java-applet;version=1.3"
AppBuilder 2.1 Deploying Applications Guide 9-9
width="700" height="500" align="baseline" code="FrameApplet.class" archive="appbuilder.jar" scriptable=false pluginspage="http://java.sun.com/products/plugin/1.3/plugininstall.html"> <NOEMBED> </COMMENT> alt="Your browser understands the <APPLET> tag but isn't running the applet, for some reason." Your browser is completely ignoring the <APPLET> tag! </NOEMBED> </EMBED> </OBJECT> <script LANGUAGE="JAVASCRIPT"> function CallJava() { // display a message returned from Java applet alert( document.forms[0].TestApp.showMsg() ) //FrameApplet.showMsg( "message from Java script" ) } </script>    <TABLE BORDER="0" CELLSPACING="0" CELLPADDING="2" WIDTH="100%"> <TR> <TD><IMG ALT="Bluephoenix Solutions" SRC="BPLogo.jpg"></TD> </TR> </TABLE> <BR> <B><FONT TYPE="ARIAL" SIZE=5>AppBuilder - Frame Internal Applet</ FONT></B> <BR>    <TABLE BORDER="0" CELLSPACING="0" CELLPADDING="2" WIDTH="750"> <TR> <TD WIDTH="25"></TD> <TD ALIGN="center" VALIGN="top" WIDTH="700">    
9-10
  </TD> <TD WIDTH="25"></TD> </TR> </TABLE>    <BR> <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=2 WIDTH="750"> <TR> <TD WIDTH="600"></TD> <TD WIDTH="150"> <P ALIGN="right"><FONT FACE="Arial" SIZE=1 COLOR="#000000"> last updated on 07-Oct-2001 </FONT></P> </TD> </TR> </TABLE> <HR ALIGN="left" WIDTH="750"> </BODY> </HTML>
Configuring AppBuilder
AppBuilder provides two different types of Applet windows beginning in Version 2.1. The generated AppBuilder windows can be displayed as a separate popup windows and it will be displayed outside the Browsers display area. This will be the default behavior. In Version 2.1, it can also be configured to be displayed as Internal windows which runs entirely within the Browsers display area. To use the browser's display area as a container, AppBuilder API should be used to set the container. Refer to "Creating Java Applet class" for how this API can be used. In addition to using the API, the setting FRAME_TYPE should be set to INTERNAL in the [NC] section of appbuilder.ini. By default, this will be set to WINDOW. When using Java internal frames, the parent/containers desktop pane can be set using the following API, AbfSystem.setDesktopPane( pane ); And this should be invoked before trying to load the AppBuilder Rule class. And the desktopPane should also be added to the applet's content pane. Refer to "Creating a Java applet class" for details. AbfSystem.getDesktopPane() method can be used to get the container back. [NC] ; WINDOW - for using Java Frames as in previous versions. ; INTERNAL_FRAME - for using Internal Frames ; The default will be WINDOW. FRAME_TYPE=WINDOW
9-11
Setting up RMI Server
Configuring Web/AppServer
Please refer to the Web/AppServers documentation on deploying the HTML to start the Applet. Create an alias for the application to be deployed and map the alias to a physical directory. Deploy the AppBuilder.jar, the configuration files (appbuilder.ini, appbuildercom.ini, font.ini) and the generated application java archives (PARTITION_NAME.jar) with the HTML.
Executing from Web Browser

Load the HTML from the Server using http://myserver/myapp/FrameApplet.html where myserver is the host name of the Web/App Server and myapp is the alias to a physical directory in the Web Server.
Known Issues in using the Internal Frame/Windows

The internal frame is a child frame and requires a main parent frame to show it. When you use internal frames for java-client rules, you must create your own main frame window and add the AppBuilder System's desktoppane(AbfSystem.getDesktopPane()) to the main frame window.
Setting up RMI Server

The RMI Server can be used to quickly set up Test environments for the Java client applications. The RMI Server is really easy to setup compared to setting up an App Server for running EJBs. The RMI Server can also be used for debugging the server side applications. The following are the sequence of required steps, 1. 2. The RMI Server comes as part of the regular JDK and so it does not require any additional installs. 2. The RMI Server programs uses a naming registry, RMI Registry that allows the client programs to get a reference to remote objects. The registry can be started using the following command WIN32: start rmiregistry UNIX: rmiregistry& By default, the registry will be running under port 1099. 3. Set the classpath to include the prepared server jar, WIN32: set classpath=%classpath%;c:\AppBuilder\java\rt\my_partition\my_rmi_serve r.jar
Note
4.
This classpath is required only for the server and the registry should not include it.
Edit appbuilder.ini to define the RMI_SERVER_HOST and RMI_SERVER_PORT under DEBUG section. The HOST refers to the name of the server running the RMI Registry service and the PORT number on which the service is listening. Start the RMI server: java appbuilder.server.AbfRmiServer
5.
9-12
Invoking an AppBuilder Web Service
The server will register it's name with the naming registry. 6. 7. The server is now ready to process client requests. Edit the client side appbuildercom.ini or use the Management console to create a new server entry for the RMI Server. Set the REGISTRY_URL to rmi://host:1099, where host is the name of the workstation running the server in Step 4 and 1099 is the port number the naming registry is listening to. Define a new Route entry using the RMI server entry. Run the Java client or Thin-client to invoke the RMI server.
8. 9.
Refer to http://java.sun.com/docs/books/tutorial/rmi/running.html for further RMI setup issues. Refer to Debugging Applications for using the RMI Server for debugging purposes.

The AppBuilder server application can be deployed as a Web service and invoked from an AppBuilder client or any other third-party client application, which can handle HTTP and the XML. The Web service is deployed as a servlet in the supported application servers. The deployed archive has the following components: SOAP schema, defining the interface, for each frontier rule of the server partition. Refer to the AppBuilder Web service schema for more details. Servlet with the appropriate deployment descriptors for the chosen APPLICATION_SERVER. Generated Java classes for the frontier rule if the Web service is deployed as a server partition. If it is deployed as a gateway partition, there are no Java classes for the frontier rule. Input and output views as Java classes for encoding and decoding to and from XML.
AppBuilder Web Service XML Schema

The input and output view definitions of the frontier rule deployed as a Web service can be represented as XML schema using the data types supported in XML. There is a mapping table describing the AppBuilder data types and the corresponding XML data types. The AppBuilder client would automatically convert the request to XML data if the SERVER routing entry were set to WEB SERVICE. And, on receiving the response in XML, it will be converted back to the Java representation. But, if you are using a third-party client, the request needs to encode in XML using the mapping table as shown in Table 9-3.
Table 9-3 AppBuilder to XML mapping of data types XML data type Boolean String with maxLength set to the AppBuilder Field Length Date. The format of the Date values are in '%Y/%0m/%0d' format.
AppBuilder data type Boolean Character Date
9-13
Table 9-3
AppBuilder to XML mapping of data types (Continued) XML data type Decimal with total digits and fraction digits set to Field Length and Field Fractions respectively String (unicode) Not Supported Int String (unicode) Not Supported decimal with total digits and fraction digits Short Not Supported Time. The values will be in '%0t:%0m:%0s' format. DateTime. In addition to Date and Time, it has the remaining time value as fraction. The space is the separator between these three values. So the whole format is: %Y/%0m/%0d %0t:%0m:%0s xxx where xxx is a numeric value. String with maxLength set to the AppBuilder Field Length Represented as a complexType using the name of the view as the type name Represented as a complexType with a suffix occurs attached to the view name. And the view itself will be the only data member of this type.
AppBuilder data type Decimal DBCS Image Integer Mixed Object Ref Picture Small Integer Text Time
Timestamp
Varchar VIEW VIEW with OCCURS
Sample Schemas
See Sample 1 and Sample 2.
Sample 1
For this example, the following are shown: CUSTOMER_INFO view as defined in AppBuilder Generated XML Schema Instance of CUSTOMER_INFO view in XML CUSTOMER_INFO view as defined in AppBuilder CUSTOMER_INFO : view CUSTOMER_ID: integer field COMPANY_NAME: character 30 ADDRESS : view STREET: character 30 CITY: character 20 ZIP : character 10 Generated XML Schema <xsd:schema xmlns:xsd=http://schemas.xmlsoap.org/soap/encoding>
9-14
<xsd:complexType name=ADDRESS_TYPE> <xsd:sequence> <xsd:element name=STREET> <xsd:simpleType base=xsd:string> <maxLength value=30/> </xsd:simpleType> </xsd:element> <xsd:element name=CITY> <xsd:simpleType base=xsd:string> <maxLength value=20/> </xsd:simpleType> </xsd:element> <xsd:element name=ZIP> <xsd:simpleType base=xsd:string> <maxLength value=10/> </xsd:simpleType> </xsd:element> </xsd:sequence> <xsd:complexType> <xsd:complexType name=CUSTOMER_INFO> <xsd:sequence> <xsd:element name=CUSTOMER_ID type=xsd:int/> <xsd:element name=COMPANY_NAME> <xsd:simpleType base=xsd:string> <maxLength value=30/> </xsd:simpleType> </xsd:element> <xsd:element name=ADDRESS type=ADDRESS_TYPE/> </xsd:sequence> </xsd:complexType> Instance of CUSTOMER_INFO view in XML <CUSTOMER_INFO> <CUSTOMER_ID>1234</CUSTOMER_ID> <COMPANY_NAME>ABC Company</COMPANY_NAME> <ADDRESS> <STREET>xyz street</STREET> <CITY>a city name</CITY> <ZIP>12345-1234</ZIP> </ADDRESS> </CUSOMTER_INFO>
Sample 2
For this example, the following are shown: CUSTOMER_ORDERS view with a nested occurs view. Generated XML schema Instance of CUSTOMER_ORDER view in XML
9-15
CUSTOMER_ORDERS view with a nested occurs view. CUSTOMER_ORDER : view ORDER_ID : integer field CUSTOMER_ID: integer ORDER_DATE: date ORDERS : view OCCURS 10 PRODUCT_ID : integer UNIT_PRICE : decimal(15,2) QUANTITY : small Integer Generated XML schema <xsd:schema xmlns:xsd=http://schemas.xmlsoap.org/soap/encoding> <xsd:complexType name=ORDERS_TYPE> <xsd:sequence> <xsd:element name=PRODUCT_ID type=xsd:int/> <xsd:element name=UNIT_PRICE> <xsd:simpleType base=xsd:decimal> <totalDigits value=15/> <fractionDigits value=2/> </xsd:simpleType> </xsd:element> <xsd:element name=QUANTITY type=xsd:short/> </xsd:sequence> </xsd:complexType> <xsd:complexType name=CUSTOMER_ORDER> <xsd:sequence> <xsd:element name=ORDER_ID type=xsd:int/> <xsd:element name=CUSTOMER_ID type=xsd:int/> <xsd:element name=ORDER_DATE type=xsd:date/> <xsd:complexType name=ORDERS_OCCURS> <xsd:element name=ORDERS type=ORDERS_TYPE maxOccurs=10/> </xsd:complexType> </xsd:sequence> </xsd:complexType> Instance of CUSTOMER_ORDER view in XML <CUSTOMER_ORDER> <ORDER_ID>12345</ORDER_ID> <CUSTOMER_ID>54321</CUSTOMER_ID> <ORDER_DATE<2001-08-15</ORDER_DATE> <ORDERS_OCCURS> <ORDERS> <PRODUCT_ID>1111</PRODUCT_ID> <UNIT_PRICE>1234.56</UNIT_PRICE> <QUANTITY>10</QUANTITY> </ORDERS> <ORDERS> <PRODUCT_ID>2222</PRODUCT_ID> <UNIT_PRICE>1234.56</UNIT_PRICE> <QUANTITY>20</QUANTITY>
9-16
</ORDERS> <ORDERS> <PRODUCT_ID>3333</PRODUCT_ID> <UNIT_PRICE>1234.56</UNIT_PRICE> <QUANTITY>30</QUANTITY> </ORDERS> <ORDERS> <PRODUCT_ID>4444</PRODUCT_ID> <UNIT_PRICE>1234.56</UNIT_PRICE> <QUANTITY>40</QUANTITY> </ORDERS> <ORDERS> <PRODUCT_ID>5555</PRODUCT_ID> <UNIT_PRICE>1234.56</UNIT_PRICE> <QUANTITY>50</QUANTITY> </ORDERS> </ORDERS_OCCURS> </CUSTOMER_ORDER>
AppBuilder Client
AppBuilder makes it very easy to invoke a Web service from its client application and it is similar to invoking other Server interfaces such as NetEssential, EJB, or MQ. Configure the client to invoke a server rule published as a Web service by defining the ROUTES and the SERVER entries in appbuildercom.ini. Create a server section with the following entries: [SERVER.ws_server] TYPE=WEBSERVICE URL=http://hostname:port/context/servlet where hostname refers to the server hosting the Web service, port is the TCP port on which the servlet engine (like WebLogic, WebSphere or TOMCAT) runs context is the servlet application name or the context servlet the Web service partition name And define a routes entry to this server: [ROUTES] $ANY=ws_server
Tip
Refer to Setting Web Service Execution Parameters for additional configuration information.
With these, any AppBuilder client (thick Java or thin HTML) application using this configuration sends a SOAP/XML request to the server and receives the response in SOAP/XML as well. The AppBuilder VIEW to XML conversion and vice versa is handled by AppBuilder.
9-17
Third-Party Client
The AppBuilder Web service server uses standard SOAP/XML and any third-party client application can be used to send a request per the SOAP/XML specifications. As well, the response sent from the server complies with the standard. The client application can be in any one of the programming languages such as Java, Microsofts VisualBasic, etc. The AppBuilder package has a sample client application in Microsoft VisualBasic (VB) under the samples directory. The file SoapTest.zip contains the VB source files and an executable SoapTest.exe. Refer to: Running the Sample Application Building the Sample VB Application
Running the Sample Application

To run this application, follow these steps: 1. 2. 3. Start SoapTest.exe. Enter the host name for the target server where the AppBuilder Web service is deployed. Enter /contextname/servletname. Refer to the Testing Web Service sections (in previous topics) for the corresponding application server to get the right context name. The default servlet name is the name of the partition. Enter the port number for the target HTTP server. Enter the XML request for the Web service. This should be a SOAP/XML request. Either cut and paste the XML request or type it by hand into the Outbound Text field. Either type the fully qualified file name of an XML file containing the XML request or use the [...] browse button to select the file for the Outbound File field. 6. Send the XML request. Click Send Text to send the Outbound Text data. Click Send File to send the Outbound File data. 7. The response is displayed in the Inbound Response field.
4. 5.
Building the Sample VB Application

1. 2. 3. 4. 5. Unzip SoapTest.zip into a directory of your choice. Start MicroSoft Visual Basic 6.0. Regardless of the VB6.0 startup mode, open the project file SoapTest.vbp. Select File > Make SoapTest.exe and target the results to the original directory. This sample uses the Internet Transfer Control, MSINET.OCX, an ActiveX control that is distributed with Microsoft Visual Basic 6.0.
9-18
Understanding Execution Differences
Invoking an AppBuilder RMI Server

1. Set up the client communication parameters using the Management console. Refer to Configuring Communications for details on setting up a Server Entry for RMI. Create a Route entry using this Server Entry. On the server side, there are two components that needs to be started. One is the RMI registry, a naming facility that allows remote clients to get a reference to the server object. Use the following command to start the registry: unset classpath (remove the CLASSPATH environment variable) start rmiregistry nnnn where nnnn is the TCP port number on which this registry is listening. If nnnn is not given, it uses 1099 by default. The port number and hostname of the machine where this registry is running should be used on the client side setting of Step 1. 3. The second step on the server side involves starting the AppBuilder RMI Server. It uses two appbuilder.ini entries (RMI_SERVER_HOST and RMI_SERVER_PORT). This again refers to the hostname and port number of the listening RMI registry. This is required on the server side because the client and server are running on two different machines. By default, it is set to localhost and 1099 respectively. Also, include the server side application jar in the classpath and start the server using the following command: java appbuilder.server.AbfRmiServer 4. Now the server is ready to receive requests from the client. Execute the client application and try invoking the RMI Server application.
2.

The differences between Java thick clients and Java thin clients at execution (run time) include: ObjectSpeak Event Differences ObjectSpeak Property Differences ObjectSpeak Method Differences The differences between Java thick clients and C clients at execution (run time) include: Differences Between Java and C
9-19
ObjectSpeak Event Differences

These differences include: Data Change Not Propagated on Focus Change No Click or Focus Events No Error and Validation Events No CloseEvent for Window Refer to the ObjectSpeak Reference Guide for a complete list of events supported.
Data Change Not Propagated on Focus Change

Whenever focus changes from one field to the next on an AppBuilder window, the data entered on any graphical user interface (GUI) control is mapped to the associated datalink and in turn all the GUI controls that are linked to this datalink get updated with the new value. In a thin-client environment, any value entered on the INPUT control is mapped to its datalink only when the FORM is submitted to the server. And the next refresh of the window coming from the server has the same value mapped to all controls with the same datalink. If this behavior is required to be supported on the client-side, include a Javascript for a focus-out event (onblur) to map the values to the required field.
No Click or Focus Events

These events are not supported: Click DoubleClick GotFocus LostFocus for these GUI objects: Radio Button Check Box Combo Box List Box The support of all these events would involve submitting the FORM to the server for invoking the event handlers and would create lot of network traffic and also would result in a new HTML page in the browser. As this is not a desirable behavior for the end-users, this is not supported.
9-20
No Error and Validation Events

These events are not supported in thin (HTML) clients: FieldError FieldValidation The support of all these events would involve submitting the HTML FORM to the server for invoking the event handlers and would create a large amount of network traffic and also would result in a new HTML page in the browser. As this is not a desirable behavior for the end users, this is not supported for the thin client.
No CloseEvent for Window

AppBuilder supports CloseEvent to handle the action of closing windows by clicking the Close(X on the title bar of the window). An AppBuilder window is equivalent to an HTML FORM in a thin-client environment. Any user interaction in an HTML FORM is only through the HTML elements within the FORM and there is no corresponding Window Close action possible within a FORM; therefore, CloseEvent is not supported for the thin client.
ObjectSpeak Property Differences

These differences include: No Mandatory Property for PushButton No IgnoreValidation Property for PushButton No ImmediateReturn Property No Duplicate or Blank System IDs
No Mandatory Property for PushButton

The Mandatory property on the PushButton object can be done using a Javascript on the client side to make sure all the required fields are filled-in before submitting the request to the server. This is not supported on the currently supplied JavaScript. Refer to the ObjectSpeak Reference Guide for a complete list of objects and properties supported.
No IgnoreValidation Property for PushButton

The IgnoreValidation property is not supported for PushButton. Refer to the ObjectSpeak Reference Guide for a complete list of objects and properties supported.
No ImmediateReturn Property
The ImmediateReturn property is supported on both Java and HTML clients for CheckBox and RadioButton objects. For other objects, it is supported for Java clients only. Refer to the ObjectSpeak Reference Guide for a complete list of objects and properties supported.
9-21
No Duplicate or Blank System IDs

The system identifier (HPSID) is used as the name or ID for the HTML FORM INPUT field and it must be unique. Hence the thin client does not support duplicate system IDs. Also, the thin client does not support blank system IDs.
ObjectSpeak Method Differences

These differences include: No Editable and EditLimit No Format Properties
No Editable and EditLimit

The multi-column list box (MCLB) object in a thin client is not editable and hence the Editable and EditLimit methods are not supported in thin clients.
No Format Properties
The setting and getting of color, font, and size attributes involve parsing the style sheet information associated with each HTML Input element. For performance reasons, these methods are not supported. SetForeground and GetForeground SetBackground and GetBackground SetFontand GetFont SetSize and GetSize
Differences Between Java and C

These differences include: Default Title Bar
Default Title Bar

In C clients, you can disable the title bar by setting the Title Bar property of the window to False. The current version of the standard Java Development Kit (JDK) has a title bar by default on all windows and this cannot be changed. So Java clients cannot disable the title bar.
9-22
Using Date Completion Shortcuts

In the runtime client, in a date field, you can type in shortcuts when entering a date and AppBuilder runtime client can interpret it and complete the date.
Date Completion Conventions

If hyphen (-) or slash (/) is entered into the date field, it is taken as the entire current date. If data is entered into an edit field, it gets converted into a date field according to the edit format specified in date field. If there is no edit format specified, the locale-specific format is used. If the initialization file (appbuilder.ini) variable DEFAULT_DATE_FORMAT in the NC section is defined, it takes precedence over locale-specific format as the edit format. The data entered is parsed according to the order of the format string specified. If there is a partial date, the rest of the data is assumed and extracted from current system date. That is, if the format specified is day-month-year, and if '5' is entered , 5 is taken as the day part of the date and the month and year are extracted from the current date. So, if today is 24th May, 2001, the entry is 5th May, 2001. See the examples below. If separators are also entered, the year entered may be just the year part without the century or the full year. If the century part is not specified, the century part is derived from the YEARS_IN_THE_FUTURE variable in the NC section in appbuilder.ini, which has a default value of 35. Years in the future indicates the number of years in the future (from the current year) which is supported. If you set years in the future to 35 then future years are supported up to the current year plus 35. Any year value above that amount is taken as a year in the past. If the current year is 2001, the years up to 2036 are supported; if 35 is entered, it is interpreted as 2035 and if 37 is entered, it is interpreted as 1937. There does not need to be a separator for the date entry, but the exact number of digits correspond to those required by edit format. Typically, day and month data are two digits long, and year are four digits long, and Julian day (001-366) is three digits long. For example, if the edit date format is %m/%d/%y, and 05041945 is entered, it is interpreted as 4th May, 1945.
Sample Date Completions

In the examples in Table 9-4, the edit format is %d/%m/%0y and YEARS_IN_THE_FUTURE is 35.
Table 9-4 Field entry / 1/1 13/1 1/6/03 Date completion examples Date Result entire current date entire current date 1st January, 2001 13th January, 2001 1st June, 2003
9-23
Table 9-4 Field entry 05 0502 03041999 21102000 12/1/01 9/9/43
Date completion examples Date Result 5th May, 2001 (if current day is 24th May, 2001. It keeps the rest of the date.) 5th February, 2001 3rd April, 1999 21st October, 2000 12th January, 2001 9th September, 1943
9-24
CHAPTER
10
DEPLOYING JAVA ON APACHE
With AppBuilder, you can develop, deploy, and test enterprise applications targeted for Java environments on an Apache Web server. This section describes the procedures to deploy and run Java applications on this server and servlets if you also have Tomcat. AppBuilder supports Apache Web server with Tomcat servlet container. Tomcat is a plug-in to run servlets in Apache, Microsoft IIS, and Netscape Web servers. This set of procedures assumes that you have Apache on your development machine along with AppBuilder. This set of procedures describes only the Apache server; for using Tomcat with the other servers, refer to the Apache Web site. The procedures include: Configuring the Initialization Files (for Apache as the Web server) Updating the Thin-Client Archive Configuring Tomcat Testing the Deployed Java on the Web server These instructions assume you have Tomcat installed. For more information about Tomcat, refer to the Jakarta Web site for Tomcat documentation (http://jakarta.apache.org or http://apache.org). These instructions use the following conventions for directory names: Tomcat is the name for the drive and directory where Apache and Tomcat are installed (for example, c:\Apache). AppBuilder is the name for the drive and directory where AppBuilder is installed (for example, c:\AppBuilder). If you are using a database (not essential for Apache), the following instructions assume that you have installed IBM DB2/UDB in the Database directory (for example, c:\SQLlib).
Note
Remember that application servers are case sensitive. Be sure to double-check any commands or URLs typed at a command prompt or in a command file or in entry fields in the interface.

These steps describe how to configure the initialization (INI) files in AppBuilder so that it knows which application server is used and where to look for Java classes as needed. These steps should be performed before the partitions are prepared in AppBuilder. Refer to Chapter 3, Preparing the Application for information on preparing partitions. Perform these steps on the development workstation where you are running AppBuilder. Use the INI file editor from the Management Console to edit the INI files.
10-1
5.
Select the application server in the Construction Workbench in the Workbench Options, Preparation tab, as shown in Figure 10-1.
Figure 10-1
Tomcat
Or you can modify the AppBuilder system initialization file (AppBuilder\hps.ini) so that the selected application server is Tomcat. In the AP Java section, uncomment or change the APPLICATION_SERVER value and comment out or remove the lines for the other servers. For example, if you change the value with the Management Console, it is: APPLICATION_SERVER=Tomcat The generated partition includes an HTML start page and an error page, both generated from a default template. The default template can be overridden by setting the path to the new template files in the system initialization file, hps.ini, using these values: THINCLIENT_START_HTML=c:\defaultstart.html THINCLIENT_ERROR_HTML=c:\defaulterr.html where defaultstart.html and defaulterr.html are the names of template files. The default templates, svlt-startpage.htpl and svlt-errorpage.html, are in: AppBuilder\AD\CFG\DATA The start page template is assumed to have the following entry: <form method="get" action="$(SVLTCLS)"> where $(SVLTCLS) gets replaced by the generated action target. The error page template is copied as is during prepare. You may use any or all of the following lines in the error page to get more information displayed. <input type="text" name="LVEL_ERROR_CODE" size="20"> <input type="text" name="LVEL_ERROR_DESC" size="77"> <textarea rows="8" name="LVEL_ERROR_CONTEXT" cols="78"> </textarea> The keywords are replaced by AppBuilder during execution if an error is encountered. The code (LVEL_ERROR_CODE) is a number representing the error. (Refer to the Messages Reference Guide.) The description (LVEL_ERROR_DESC) is a short sentence or two describing the error. The context (LVEL_ERROR_CONTEXT) is a stack of calls that led to the error. If these lines do not appear in the error page, then the information is not displayed. 6. Prepare the partitions according to the instructions in Chapter 3, Preparing the Application. Refer to Chapter 6, Packaging the Application to understand where AppBuilder puts the generated files. Briefly, the generated (archive) files are put in: AppBuilder\Java\RT\EachAppConfig\YourPartition
10-2
Deploying Java on Apache
Make sure the initialization files (appbuilder.ini and appbuildercom.ini) are in the AppBuilder\Java\RT directory of the client machine or in the directory where the client application resides (which is by default AppBuilder\Java\RT\YourAppConfig). 7. Modify the AppBuilder\Java\RT\appbuildercom.ini file so that the default server is RMI or AppBuilder communications (NetEssential).

In AppBuilder, the installation program installs a Java archive, appbuilder.jar, containing the servlet support classes in the AppBuilder\Java\RT directory. Include this archive in the execution. The procedures below refer to this archive. It also creates a sample start page in AppBuilder\Samples directory that you can use in these procedures if you copy it to the same directory as the Java archive for the servlet. When preparing a partition for a thin-client Java application, AppBuilder creates a Web archive (WAR) in the root of the application configuration directory. The name of the Web archive file is partition_name.war. This file includes: the generated classes for the servlet, rule, view, sets etc. HTML and the associated includes an HTML error page (errorpage.html) an HTML start page Follow these instructions for each servlet: 1. Extract the generated Web archive on to a temporary directory using the command: jar xvf partition_name.war 2. The generated Web archive, partition_name.war, contains a default HTML start page to launch the application and an HTML page for displaying errors. These pages can be edited to include company logo and to make other changes. Alternatively, templates can be defined during prepare so that the correct file is included automatically. Refer to Configuring the Initialization Files for details. Recreate the archive using the following command, jar cvf partition_name.war * When a Web application is deployed, define an alias or context that the Web browser uses to refer to this application. This alias or context is mapped to a physical directory, context_home in the application server. For instance a catalog application has an alias or context named catalog, and this alias is mapped to a directory named CatalogWebApp.
3.
Configuring Tomcat
1. Create a configuration file, configfile.conf using the generated configuration file (tomcat-apache.conf) as the base in the Tomcat/conf subdirectory. (This file is created only after Tomcat has been started). Add the following entries for the Web application, Alias /context Tomcat/webapps/context_home <Directory "Tomcat/webapps/context_home"> Options Indexes FollowSymLinks
Testing the Deployed Java
</Directory> ApJServMount/context/RootRule_Svlt/context <Location /context/WEB-INF/> AllowOverride None deny from all </Location> where context refers to the URL alias used from the Web Browser, context_home refers to a subdirectory under the Tomcat/webapps directory, and RootRule_Svlt refers to the name of the generated servlet. Use forward slash (/) for a path separator. If the context and context_home are different, add this server.xml entry: <Context path="/context" docBase="webapps/context_home" debug="0" reloadable="true"> If the server.xml entry is dropped, Tomcat automatically loads the servlet from the webapps/ context_home directory with a context of /context_home. 2. This configuration file should include the other entries defined in the generated configuration file (tomcat-apache.conf), such as JServModule, etc., which defines the adapter to the Apache server. Refer to the Tomcat documentation for configuring these entries. Include this configuration file with the Apache configuration file, httpd.conf, using: include Tomcat/conf/configfile.conf 4. Create a subdirectory using the name defined in the configuration file, context_home under the Tomcat/webapps directory. Extract the generated Web archive, partition_name.war, to this subdirectory. Restart Tomcat using the startup script in Tomcat/bin directory.
3.
5.

This section includes: Testing Thin Client Testing Web Services
Testing Thin Client

1. From a Web browser, load the start page with the following URL: http://hostname/context/startpage.html where hostname is the name of the machine and the startpage.html is the name of the HTML file for the start page.
10-4

The Web services can be invoked from an AppBuilder client (Java thick or thin client) or from a third party client. The AppBuilder client can be made to invoke a Web service similar to invoking other Servers simply by creating a new Server Route entry in appbuildercom.ini and there is no other change required on the client. The easiest way to do this is to use the Communications Configurator (refer to the Configuring Communications Guide). For example: [SERVER.myServer] TYPE=WEBSERVICE HOST_URL=http://hostname:port/ServletContext/ServletName where hostname is the name of the server port is the TCP/IP port number for the Tomcat servlet engine. The default is 8080. ServletContext is the name of the context defined in the Tomcat configuration file or the name of Web archive (WAR). ServletName is the name of the server partition in AppBuilder. For using the Web service from a third-party client, refer to Chapter 9, Executing the Application. The application is now deployed and ready to receive requests.
10-5
10-6
CHAPTER
11
TROUBLESHOOTING PROBLEMS
Several types of problems might prevent the successful preparation or execution of the distributed application. Be sure to verify and debug your application at each stage of development. Review error messages and logs for more information about the particular problem you are having. This section explains the procedures for determining the type of problem with a distributed application and basic troubleshooting of those problems. The problems may be categorized by the stage in the application development process. The job of resolving problems includes the following tasks. Resolving Partitioning Problems Resolving Packaging Problems Resolving Communication Errors Resolving Execution Problems Partitioning problems involve some mistake in the configuration of the application. Packaging problems involve preparation, packaging, or deploying the code for that application. Communications problems involve the communication between modules on different platforms. Execution problems involve limitations specific to the target environment.
Resolving Partitioning Problems

Partitioning problems involve some mistake in the configuration of the application.
Re-Prepare Parent Objects

Be sure to prepare parent objects (such as rules) that contain child objects (such as views) if changes were made to any of the child objects. If changes are made to a window and the window has a view attached, be sure to re-prepare the rule that has that window.
11-1
Resolving Packaging Problems
Resolving Packaging Problems

The packaging problems involve any problems during preparation, packaging, or deploying of the code for that application. These problems include: Java Installed Incorrectly Component Folders not Latest
Java Installed Incorrectly

You must have Java installed on your machine and the Java environment set in your classpath if you are creating Java applications. Otherwise you get error messages when you try to prepare the parts of the application. If you prepare a rule and get a notification in the Prep Status tab of the Status Display, double-click on the line that says Unsuccessful or right-click on the line and from the drop-down menu, select Details.
Figure 11-1 Status window with Details menu choice
The Details window displays the message. Scroll down to the bottom of that window to see a summary.
Figure 11-2 Resulting Details window with message
The message says that the Java compiler is not in the classpath.
Component Folders not Latest

Problems encountered preparing or verifying rules with ObjectSpeak (Java objects supported by Rules) in them may be caused by component folders that are not the new component folders being used to store events, properties, and methods. This condition can result from working in a new workgroup repository or attempting to implement ObjectSpeak in your rules the first time. To fix this, refer to the Workgroup Repository Administration Guide.
11-2
Troubleshooting Problems
Resolving Communication Errors
Resolving Communication Errors

These problems may include errors in communications for traditional converse windows.
Traditional Converse Windows

The Rules Language USE RULE statement corresponds one-to-one with a communications (NetEssential) remote procedure call (RPC). The system makes an RPC every time a client rule uses a server rule on a remote workstation. You can use the HPS_COMM_ERROR_RULE system rule to get protocol-specific or communications error codes. Refer to The default repository contains this rule and its input view. The run-time system automatically invokes the rule whenever a communications error occurs in an AppBuilder application. You can use the HPS_COMM_ERROR_RULE system rule to get protocol-specific or communications error codes. You must have project authorization to the AppBuilder project to update HPS_COMM_ERROR_RULE or change its relationships. The default repository contains this rule and its input view. The run-time system automatically invokes the rule whenever a communications error occurs in an AppBuilder application. Display the error codes by mapping the input view to a window and coding the rule with a CONVERSE_WINDOW statement in a DOENDDO loop.
Resolving Execution Problems

The execution problems involve limitations specific to the target environment. These problems can be minimized by: Setting Cache Space Customizing the HTML Error Page Handling Re-Prepare Properly PIC Field Length Limitation
Setting Cache Space

To enhance the performance of the execution of an application on a server, you can edit the appbuilder.ini file to set the following: PANEL_BUFFERS - to set the number of windows to be cached. The larger the number cached, the more system space is consumed. RULE_BUFFERS - to set the number of rules to be cached. The larger the number cached, the more system space is consumed.
11-3
Resolving Execution Problems
Customizing the HTML Error Page

The application servlets created by AppBuilder could experience execution errors such as session time out or not being able to load a required resource. By default the error information is substituted in an HTML page (ErrorPage.html) and sent to the Web browser. This page can be customized by replacing it with either different content or a different file. To use a different file, define the location (the URL) for the file in the appbuilder.ini in the SERVLET section. The error reporting looks for the following pieces of information (in variables) in the HTML: the error code (LVEL_ERROR_CODE) the error description (LVEL_ERROR_DESC) the context in which the error occurred (LVEL_ERROR_CONTEXT) When the error is reported, the values of these variables are updated and displayed. Example Here is a sample HTML file for a custom error Web page. The page can optionally contain any or all of the error variables discussed above. You may edit the HTML and save it as your own file. <html> <head> <title>Error in processing your request</title> </head> <body> <form method="Post" action=""> <input type="text" name="LVEL_ERROR_CODE" value="" > <input type="text" name="LVEL_ERROR_DESC" value="" > <textarea name="LVEL_ERROR_CONTEXT"> </textarea> </form> </body> </html>
Handling Re-Prepare Properly

This error may occur when a change is made to a child object but the parent object is not re-prepared. Be sure to prepare parent objects (such as rules) that contain child objects (such as views) if changes are made to any of the child objects. If changes are made to a window and the window has a view attached, be sure to re-prepare the rule that has that window.
PIC Field Length Limitation

The size of a picture field is determined by the Field picture-storage attribute. The picture property for a FIELD object in the repository is 30 characters long (Field picture-storage and Field picture-display) However in the Rules Language one should be able to use a longer local PIC field for data manipulations within the rule code.
11-4
Using System Rule
Using System Rule

You can use the system rule HPS_COMM_ERROR_RULE to get protocol-specific or communications error codes. The default repository contains this rule and its input view. The run-time system automatically invokes the rule whenever a communications error occurs in an AppBuilder application. You must have project authorization to the AppBuilder project to update HPS_COMM_ERROR_RULE or change its relationships. The default repository contains this rule and its input view. The run-time system automatically invokes the rule whenever a communications error occurs in an AppBuilder application. Display the error codes by mapping the input view to a window and coding the rule with a CONVERSE_WINDOW statement in a DOENDDO loop. You can enable the use of this system rule in the appbuilder.ini configuration file. There are several other settings that can be used in conjunction with this rule.
11-5
Using System Rule
11-6
APPENDIX
SUPPORTED CONFIGURATIONS
Supported configurations include the following. This is not an exhaustive list of possible configurations. The intention is to give you an idea of the flexibility of deploying with AppBuilder. Thin-Client (HTML Client with Servlet) Java Client on a Departmental Server Windows Client/Server Traditional
Thin-Client (HTML Client with Servlet)

AppBuilder supports multiple configurations for thin-client Java.
Figure A-1 Sample Java client/Java server (with servlets) configuration
A-1
Java Client on a Departmental Server
Figure A-2
Possible server architectures
Java Client on a Departmental Server

For a Java client running directly on a Departmental Server (C server or RMI server), the following configurations are possible. The client can talk to a C server and various levels of servers or to an RMI server that can communicate with a host.
Figure A-3 Sample Java client/Departmental Server configuration
A-2
Supported Configurations
Windows Client/Server
Figure A-4
Sample Java client/RMI server configuration
Windows Client/Server
Figure A-5 Sample client/server configuration
A-3
Traditional
Traditional
The traditional configuration includes a client with the server rules running on a host.
Figure A-6 Sample distributed configuration
A-4
Supported Configurations
APPENDIX
SAMPLE DISTRIBUTED APPLICATION
The standard AppBuilder installation includes a sample application (HELLO_WORLD) and a set of sample configurations that demonstrate the various application configurations and deployment possibilities. You can use this set of sample applications, different configurations of a HelloWorld application, to test the deployment of various configurations on different platforms. Step through the deployment of a sample distributed application by doing the following: migrating the sample application to a repository so that it is available to AppBuilder building the distributed configurations from the Construction Workbench deploying the application configurations to machines running the sample application to check the results When AppBuilder is installed, a SAMPLES directory is created. In that directory is a compressed file with all the repository files that are needed. The procedures that follow explain how to migrate these files to a personal or group repository from which you can then prepare and deploy the versions of the application. The versions of the application are: a client-only application called C_HelloWorldHTML a client/server application called CS_HelloWorldHTML The C_HelloWorldHTML application is a client-only application that executes an AppBuilder rule and displays a Hello World string as HTML. The CS_HelloWorldHTML application is a client/server application that invokes a server rule to concatenate a string to the Hello World string and display it as HTML. The client rule can use any of the supported AppBuilder server interfaces (NetEssential, EJB, or RMI).
B-1
Migrating Sample Application
Migrating Sample Application

You can create the sample distributed application from a personal repository or from a workgroup repository. In either case you can use the Freeway Explorer to make the files available by migrating them from your hard drive to the repository. For more information on the use of the Freeway Explorer, refer to the Workgroup Repository Administration Guide. 1. 2. 3. 4. 5. 6. 7. From the SAMPLES directory (wherever AppBuilder is installed), uncompress (unzip) the hello_world.zip file. Create a directory (called HelloWorld for example) and put all these files in it. Launch the Freeway Explorer. (From the Start menu, Programs > AppBuilder > Repository > Freeway Explorer.) From the Freeway Explorer toolbar, select Session > Connect, enter your user name and password, and click Connect to connect to the workgroup repository. From the Freeway Explorer toolbar, select Tools > Migration Import to open the Migration Import window. In that window, select File > Choose Directory and select the directory on your hard drive where you copied the sample application files and click OK. Also in the Migration Import window, select Action > Analyze to analyze the differences between the existing data in the repository and the data being imported. Review the Migration Import report. If the data is identical, there is no need to import the data and you can skip this and the following step. Otherwise, select Action > Import to import the sample application data into the repository. From Freeway Explorer, select Session > Commit session changes to save the imported data in the workgroup repository.
8.
Building Distributed Configuration

For Client-Only Configuration
Follow these steps for preparing the application in a thin-client (HTML client) configuration. 1. 2. On the development machine, start the AppBuilder Construction Workbench and open the Hierarchy window. From the Configuration tab, right-click the Project entity in the hierarchy and select Add Application Configuration.
3.
In the Insert Application Configuration window, select the HELLO_HTML application configuration (from the repository) and click Insert.
B-2
Sample Distributed Application
Building Distributed Configuration
4.
This configuration now appears under the Project entity. It can be expanded, but has only one partition, HELLO_HTML. Select the partition, right-click, and select Properties to view the properties for the partition. Set the properties: Partition type to Client Client type to HTML Server interface to N/A Language to Java Package (by default, the name of the partition) to HELLO_HTML Click OK. If you get a message about a failure because you do not have permission to update this file, check with the System Administrator about permissions to those files in that location.
5.
In the Configuration hierarchy, expand this partition and see that it has a Process and a Machine. Select Properties for the Machine entity and set the Implementation name to Local for preparing the partition to the local machine. Commit the changes to the repository by selecting File > Commit. Prepare the partition and all its parts by selecting the partition in the Configuration hierarchy, right-clicking, and selecting Super Prepare.
6. 7.
For Client/Server Configuration

Follow these steps for preparing the application in a client/server configuration. 1. 2. On the development machine, start the AppBuilder Construction Workbench and open the Hierarchy window. From the Configuration tab, right-click the Project entity in the hierarchy and select Add Application Configuration.
3. 4.
In the Insert Application Configuration window, select the HELLO_HTML application configuration (from the repository) and click Insert. This configuration now appears under the Project entity. It can be expanded, but has only one partition, HELLO_HTML. Select the partition and right-click and select Properties to view the properties for the partition. Set the properties: Partition type to Client Client type to HTML Server type to N/A Language to Java Server interface to NetEssential, EJB, or RMI, depending on where the server rule is to run. Select NetEssential as the interface for this sample if you are not sure which to select.
B-3
Deploying Application Configuration
Package (by default, the name of the partition) to HELLO_HTML Click OK. 5. In the Configuration hierarchy, expand this partition and see that it has a Process and a Machine. Select Properties for the Machine entity and set Implementation name to Local for preparing the partition to the local machine. Commit the changes to the repository by selecting File > Commit. Prepare the partition and all its parts by selecting the partition in the Configuration hierarchy and right-click select Super Prepare.
6. 7.
Deploying Application Configuration

Follow these steps for deploying the application in a thin-client (HTML client) configuration. 1. After you prepare the client-only partition (the thin-client version of the application), the system creates a Java archive file under AppBuilder\Java\RT\hello_html with the name of the package, for example hello_html.jar. The default package name is the name of the partition. This archive file contains all the generated Java classes, HTML files, and other included files. Copy this Java archive file to the servlets home directory.
2.

Follow these steps for deploying the application in a in a client/server configuration. 1. When you super prepare this partition, a Java archive file is created under AppBuilder\Java\RT\hello_cs_client_html with the name of the package, for example hello_cs_client_html.jar. The default package name is the name of the partition. This archive file contains all the generated Java classes, HTML files, and other included files. Copy this Java archive file to the servlets home directory. Select the partition for HELLO_CS_SERV_HTML, right-click, and select Properties to view the properties for the partition. Set the properties: Partition type to Server Generated language to Default (if an AppBuilder communications, NetEssential, interface is used) or to Java (if using EJB or RMI). Set it to default for this sample. Click OK. 4. This partition has a Server and a Machine entity. For the Machine entity, select Properties and set Implementation name to the host name for the server machine where the AppBuilder communications server is running. Commit the changes to the repository by selecting Session > Commit session changes. Start the remote preparation server on the machine where the server rule is going to be run. From the desktop on that machine, Start > Programs > AppBuilder > Communications > TCP agent on ne20.
2. 3.
5. 6.
B-4
Running Sample Application
7. 8. 9.
Start the preparation result server on the development machine. From the desktop of that machine, Start > Programs > AppBuilder > Communications > TCP agent on ne20. Super prepare this partition. The server rule is prepared to the targeted machine using the default language. Start the remote execution server on the AppBuilder communications server machine. From that machine, Start > Programs > AppBuilder > Communications > TCP agent on ne20.

Follow these steps for running the application in a thin-client (HTML client) configuration. 1. Load the start page in a Web browser from the application server. Point the browser to: http://appsvr_hostname:webport/ABServlet/ABStartPage.html where appsvr_hostname is the host name where the application server is running and webport is the port number when web/http service is listening for requests in a port number other than the default port 80. 2. From the loaded HTML, enter a name and click Start Application. This kicks off the HelloWorld rule and displays a message with Hello World name.

Follow these steps for deploying the application in a in a client/server configuration. 1. Load the start page in a Web browser from the application server. Point the browser to: http://appsvr_hostname:webport/ABServlet/ABStartPage.html where appsvr_hostname is the host name where the application server is running and webport is the port number when web/http service is listening for requests in a port number other than the default port 80. 2. From the loaded HTML, enter a name and click Start Application. This kicks off the HelloWorld rule that sends a request to the AppBuilder communications server where the Hello World string gets concatenated with a string. The result is returned to the client rule and is displayed as HTML.
B-5
B-6
APPENDIX
COMMAND LINE RULES EXECUTION
For Windows applications, rules without input views can be run from the command line. This is available at execution time for C clients only. Use the master.exe command: master.exe -r yourrule sysid [-u database] where yourrule is the name of the rule, sysid is the system identifier, and database is the name of the database. The -u option (and the database name) is only needed when you are executing an application with a database. The following are valid parameters in the run-time executable master.exe.
Table C-1 Valid master.exe parameters
Parameter
Description Specify code page support Specify execution environment (for mainframe) host name Specify default help file name Specify an icon for the upper left corner of a window Specify procedure name an AppBuilder process name Specify root rule to execute an AppBuilder rule name Specify the system initialization file (hps.ini) location Specify the database name database manager file name
-c -e -h -i -p -r -s -u
If you have created a function (executing from the menu), and you add or change your application from a non-database application to a database application (for local execution), you must re-prepare the function. Re-preparing the function adds the -u option to the menufile.mnu. Without the -u option, the application runs, but tries to interact with a database, which results in an error -1024 (connection does not exist to database).
C-1
C-2
Command Line Rules Execution
Index
INDEX
A
advice file 6-10 alias or context (for Web application 9-3 Apache application server (using Tomcat) 6-6 Apache Web server 10-1 appbuilder.ini file 6-6, 6-8, 6-9, 9-2, 9-3, 11-3, 11-4 appbuilder.jar file 6-6 appbuildercom.ini file 6-6, 6-9, 9-2 Applet 9-7 application sample B-1 Application Configuration rebuild 4-1 application configuration 2-6 application execution 9-6 application server WebLogic 8-1 WebSphere 7-1 associating clients and servers with machines 2-11
B
background, preparation running in 3-10 BEA WebLogic application server 6-6, 8-1 bind files using existing 3-12 blank system IDs (not supported) 9-22 buffer size, parser 9-3 build See preparing an application. building See preparing.
client/server configuration 6-7, 9-1, A-3, B-1, B-3, B-4, B-5 code page option for command line C-1 command line rules execution C-1 committing changes 2-6 common mistakes 3-3 compiler listing 5-5 configuration application 2-6 definition 1-3, 2-1 example with multiple partitions 2-5 partitions of 2-8 WebLogic 8-4 WebSphere 7-4 configuration file for Tomcat 10-4 Configuration tab 1-4, 2-1, 2-5, 2-6, 2-11, 2-14, 2-15, 3-1, 3-4, 3-7, 3-8, 3-9 Construction Workbench 1-4, 3-1 context (for Web application) 9-3 Conversation server 6-9 cookies, HTTP (for authentication) 9-5 Create Table in prepare 3-5 creating application start page 9-3 menu (for function) 3-12 shortcut (for function) 3-12 Web client session 9-3 Ctrl+Alt+P, select Project Options 2-2
D
data change with focus change 9-20 data types, AppBuilder to XML 9-13 database EJB access 2-16 database connection pool 6-6 database files location 7-4, 7-5 database option for command line C-1 database options 3-12 date and time 9-23 date completion 9-23
C
C execution client 9-6 -c, code page option for command line C-1 cache 9-4 Changed List Table 4-4 character encoding 9-5 classpath 11-2 client authentication 9-6 client partitions 2-8
date field 9-23 DB2 packages 5-2 DB2 plans 5-2 DBCS support 3-12 debugging rule 3-12 default settings (for preparing standalone application) 3-12 Delete Table in prepare 3-5 dependent classpath 7-4 deploying client/server B-4 EJB partition 7-6, 8-4 sample application B-4 thin-client (HTML) B-4 deploying the servlet partition 7-8, 7-9 deployment descriptor 6-5, 6-6 Details 11-2 development environment 1-3 differences between runtime clients 9-19 directory structure (of generated files) 6-1 disable title bar 9-22 distributed application definition 1-3 one partition selected (figure) 3-8 dna.ini file 9-1 double-byte character set (DBCS) support 3-12 duplicate system ID 9-22 duplicate system IDs (not supported) 9-22
execution parameters 9-2 execution time parameters C-1
F
file appbuilder.ini 6-6, 6-8, 6-9, 9-2, 9-3, 11-3, 11-4 appbuilder.jar 6-6 appbuildercom.ini 6-9, 9-2 dna.ini (communications) 9-1 ErrorPage.html 6-6 generated 6-1 hps.ini 3-11, 3-12, 7-2 INI 7-2, 7-3, 7-4, 8-2, 10-2 JAR (Java archive) 6-5, 6-7, B-4 WAR (Web archive) 6-6, 9-2, 9-6 Web archive (WAR) 6-5 form 9-21, 9-22 forward slash (/) as path separator 10-4 function execution from Start menu 9-6 preparation as menu item 9-6 settings 3-12
G
gateway 2-10 gateway partitions 2-8 generated files 6-1 generated output language 3-6 global character support 3-12
E
-e, execution environment option for command line C-1 EJB accessing a database 2-16 definition 3-3 partition 7-6, 8-4 preparing 3-3 testing 7-9, 8-9 embedded SQL 3-5 embedded SQL (in prepare) 3-5 Enterprise Java Bean (EJB) 3-3, 7-1, 7-6, 7-9, 8-4, 8-9, 9-6 error code (LVEL_ERROR_CODE) 11-4 context (LVEL_ERROR_CONTEXT) 11-4 custom error Web page 11-4 description (LVEL_ERROR_DESC) 11-4 message in Status window 11-2 page in HTML 11-4 ErrorPage.html 6-6 executing function from Start menu 9-6 executing the application 9-6 execution differences 9-19 execution environment 1-3, 3-2 execution environment option for command line C-1
H
-h, default help file option for command line C-1 hashing 6-9 HelloWorld application B-1 help file default option for command line C-1 hierarchy objects toolbar 2-6 Hierarchy window Configuration tab 1-4, 2-1, 2-5, 2-6, 2-11, 2-14, 2-15, 3-1, 3-4, 3-7, 3-8, 3-9 Project tab 1-4, 3-1, 3-8 Repository tab 1-4, 3-1, 3-8 hps.ini file 3-11, 3-12, 7-2 setting location from command line C-1 HTML form 9-21, 9-22 HTML Input element 9-22 HTML start page 9-3, 9-4
I
-i, icon option for command line C-1 IBM DB2/UDB 7-1, 8-1, 10-1
Index
IBM WebSphere application server 6-6, 7-1 icon option for command line C-1 IgnoreValidation property 9-21 ImmediateReturn property 9-21 Impact Analysis 4-4 Impact List Table 4-4 implementation name 7-5 initialization file (INI file) 7-2, 7-3, 7-4, 8-2, 10-2 install wizard 6-7 interpreting results 3-10 IP address for remote prepare 5-3
menu items, preparation of function as 9-6 migrating sample application B-2 MLS support character encoding 9-5 multi-column list box (MCLB) 9-22
N
Netscape application server (using Tomcat) 6-6
O
objects verifying 3-10 objects, preparable 3-4 ObjectSpeak events 9-20 ObjectSpeak properties 9-21 option validating sets 3-10 options preparation 3-11 remote preparation 3-11 See Workbench Options. Oracle database 8-1 preparation for 3-3, 7-4, 8-3 output language, determining 3-6 Output window 3-10 purpose 3-10
J
J2EE as prerequisite 3-3 compliant servlet 6-6 environment 7-3, 8-3 specification for packaging 6-2 J2EE-compliant servlet 6-6 Japanese character support 3-12 Java Applet 1-1 Frames 9-7 Internal Frames 9-7 Java archive (JAR) file 6-5, 6-7, 7-4, 7-5, B-4 Java clients 6-7 Java Development Kit (JDK) 9-22 Java execution client 9-6 Java version 2 Enterprise Edition (J2EE) 3-3 Java virtual machine (JVM) 1-4 JDBC (Java Database Connectivity) 3-5 JNDI (Java Naming and Directory Interface) 9-6
P
-p, procedure name option for command line C-1 package name B-4 default to partition name B-4 Java archive file B-4 required 2-10, 7-3 parameters, runtime 9-7 parser buffer size 9-3 parser, Simple API for XML 7-5, 8-3, 9-3 Partition rebuild 4-1 partition client 2-8 definition 2-8 gateway 2-8 properties 2-10 selecting (for preparation) 3-8 server 2-8 setting properties 2-10 path separator 10-4 Prep Status tab 11-2 PREP_DB_OPTIONS option 3-12 preparable objects 3-4 Preparation and Test Server 6-7
L
language of generated output 3-6 launching the application 9-6 link listing 5-5 list recent projects 2-17 local machine name 5-3 loopback adapter use IP address for remote prep 5-3
M
machine setting properties 2-11 machine group name 2-13, 5-3 mainframe libraries 5-5 Mandatory property 9-21 mapping of data types 9-13 master.exe parameters 9-7, C-1 menu file name 3-12
Index
preparation options 3-11, 3-12 Preparation Query window 3-9 preparation See preparing. prepare Create Table action 3-5 Delete Table action 3-5 order of 3-5 when changing from non-database to database application C-1 Prepare, using 3-4 preparing all children of an object 3-8 application 1-3 definition 1-3 EJB rules 3-3 from Project tab 3-8 from Repository tab 3-8 generated output language 3-6 of function as menu items 9-6 options 3-11 parent objects of changed child objects 3-5, 11-1, 11-4 remote 1-2, 1-4 running in background 3-10 sample application B-2 standalone 6-2 to remote mainframe 5-3 windows 3-3 problems communications, troubleshooting of 11-1 execution, troubleshooting of 11-1, 11-3 packaging, troubleshooting of 11-1, 11-2 partitioning, troubleshooting of 11-1 procedure name option for command line C-1 process insert 2-14 properties 2-14 process name (option for command line) C-1 project options distributed application 2-4 standalone application 2-3 Project Options window 2-2, 2-17, 3-8 Project tab of Hierarchy window 3-8 preparing from 3-8 Project toolbar 2-17 properties machine 2-11 partition 2-10 process 2-14
R
-r, root rule option for command line C-1 Rebuild 4-1 analysis process 4-2 Bitmap 4-8 Changed List 4-4 Changed List Table 4-4 commit changes 4-3 Component 4-8 Enabling 4-1 Entity 4-11 Field 4-8 File 4-8 Form 4-9 from a Partition 4-12 from a partition 4-12 Help 4-9 Impact List 4-4 Mark All 4-15 Mark Prepared 4-15 Panel 4-9 Partition 4-5 partition example 4-6 performing 4-1 Physical Event 4-9 Rebuild Status 4-6 Report 4-9, 4-11, 4-13, 4-14, 4-15 Rule 4-10 running from an application configuration 4-13 running from Project tab 4-13 Section 4-10 Set 4-10, 4-11 Significant Objects 4-8 status 4-5 status table 4-6 Symbol 4-10 user interface 4-12 Values 4-10 View 4-10, 4-11 Window Content 4-11 Rebuild Status Table 4-6 recent projects, list of 2-17 region name 2-13 region, specifying 5-3 remote EJB using JNDI 9-6 Remote Method Invocation (RMI) 9-5 remote preparation 1-2, 1-4 configuring 2-12 options 5-3 remote preparation options 3-12, 5-3 remote preparation server name 3-12 Remote Preparation tab of Workbench Options 5-3 remote prepare results 5-5
Index
remote prepare support entities 5-1 languages 5-2 remote procedure calls (RPCs) 1-2 remote rule 9-5 Repository non-versioned 4-8 versioned 4-8 repository committing to 2-6 Repository tab preparing from 3-8 re-prepare 3-5, 11-1, 11-4 restrictions preparing 3-7 results interpreting 3-10 see Output window 3-10 results server name 3-12, 5-3 root rule option for command line C-1 RSvlt suffix 9-4 rule debugging 3-12 remote 9-5 rule execution 9-6 rules execution from command line C-1 Rules Language USE RULE statement 11-3 run-client command file 7-10 running sample application B-5 runtime differences 9-19 run-time parameters 9-7, C-1
Start menu 9-6 execution of application from 9-6 start page create 9-3, 9-4 load B-5 start page file 7-9 suffix servlet class 9-4 Super Prepare, using 3-4 superprepare 3-7, 3-8 supported configurations and platforms A-1 supported entities in remote prepare 5-1 supported languages in remote prepare 5-2 supported ObjectSpeak events 9-20 system identifier (HPSID) 9-22 system initialization file (hps.ini) 3-11, 3-12 system initialization file option for command line C-1
T
test execution 3-2 third-party support 3-3 Title Bar property 9-22 Tomcat configuration file 10-4 documentation 10-1 servlet container 10-1 servlet engine 6-6 toolbar configuration objects 2-6 hierarchy objects 2-6 Project 2-17 top menu caption 3-12 transaction assignment 5-2 troubleshooting application 11-1
S
-s, system ini file option for command line C-1 sample application B-1 sample schema, XML schema (samples) 9-14 SAMPLES directory B-2 SAX Parser 7-5, 8-3, 9-3 server 2-10 preparing and testing 6-7 server partitions 2-8 servlet execution parameters 9-2 servlet partition 7-8, 7-9 servlet support classes 6-6 setting database options 3-12 SOAP/XML request 9-3 SQLJ (SQL Java) 3-3, 3-5, 7-3, 8-3 standalone application default preparation settings 3-12 preparing 6-2
U
-u, database option for command line C-1 USE RULE statement 11-3 using existing bind files 3-12 USRENVn INI file 5-5
V
VALIDATE_SET value 3-10 validating sets option 3-10 verifying objects 3-10 versioning non-versioned in Rebuild 4-8 VSAM file 5-2
Index
W
Web application alias 9-3 context 9-3 start page 9-4 Web archive (WAR) 7-7, 7-9, 8-10, 10-5 Web archive (WAR) file 6-5, 6-6, 8-7, 9-2, 9-6, 10-3 Web browser B-5 Web client session, creating 9-3 Web services 2-10, 2-15, 7-8, 7-9, 9-13 invoking 9-13 testing 7-10 XML schema 9-13 WebLogic application server 6-6, 8-1 configuring 8-4 WEBSERVICE section 9-3 WebSphere Administrative Console 7-4, 7-5 Administrator Console 7-8, 7-9 application server 6-6, 7-1 configuring 7-4 documentation 7-1 start admin server 7-8, 7-9 Workbench Options Preparation 3-11, 3-12 Remote Preparation 3-12, 5-3
X
XML schema 9-13 XML schema samples 9-14
Index

App Builder Deploying Applications

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

App Builder Deploying Applications

Încărcat de

Drepturi de autor:

Formate disponibile

BluePhoenix AppBuilder 2.1.0.

Deploying Applications Guide

AppBuilder 2.1.0 Deploying Applications Guide

Configuring the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

AppBuilder 2.1.0 Deploying Applications Guide

Preparing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Workgroup Repository Rebuild

Preparing to the Mainframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Packaging the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

AppBuilder 2.1.0 Deploying Applications Guide

Deploying Java on WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

Deploying Java on WebLogic

Executing the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

10 Deploying Java on Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

11 Troubleshooting Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

AppBuilder 2.1.0 Deploying Applications Guide

Using System Rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-5

Supported Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .A-1

Sample Distributed Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Command Line Rules Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .C-1

AppBuilder 2.1.0 Deploying Applications Guide

AppBuilder 2.1.0 Deploying Applications Guide

AppBuilder 2.1.0 Deploying Applications Guide

What is a Standalone Application?

What is a Distributed Application?

AppBuilder 2.1.0 Deploying Applications Guide

Deployment scheme in a development environment

CONFIGURING THE APPLICATION

AppBuilder 2.1.0 Deploying Applications Guide

AppBuilder 2.1.0 Deploying Applications Guide

Setting Project Options

Setting Project Options

2. If Standalone, select options. OR 2. If Distributed, select a configuration and partition.

Configuring the Application

Setting Project Options

Selecting Standalone Applications

Select the type of application.

Identify database, if used, and, if needed, the logon information.

AppBuilder 2.1.0 Deploying Applications Guide

Setting Project Options

Selecting Distributed Applications

Configuring the Application

Using the Configuration Hierarchy

Using the Configuration Hierarchy

The configuration objects are shown in a hierarchy.

Step 1. Add to a Project an Application Configuration.

Step 2. Add at least a Client and Server Partition.

AppBuilder 2.1.0 Deploying Applications Guide

Adding Objects to the Hierarchy

Adding Objects to the Hierarchy

Using the Hierarchy Objects Toolbar

Understanding Hierarchy Order

Configuring the Application

Adding an Application Configuration

Using the Insert Menu

Menu for Application Configuration

Adding an Application Configuration

AppBuilder 2.1.0 Deploying Applications Guide

A gateway partition has a small i over the symbol.

Configuring the Application

AppBuilder 2.1.0 Deploying Applications Guide

Setting Partition Properties

A package name may be required if the server interface is EJB.