Your company has character-based 3270
or 5250 applications (host applications) and has decided to provide an easy-to-use graphical
user interface (GUI) for those applications. This
involves creating new applications that exchange data with the
host and can be accessed by users through either a Web browser or
a rich client platform application. HATS protects your company's
investment in its host applications while customers, business partners,
and employees can access them easily using a modern GUI.
You have been assigned the task of creating a new
application that provides a GUI for a host application. HATS gives
you the tools you need to do the job.
The information in this chapter gets you started. By following
the procedure in this chapter, you will create a simple, working HATS application
that uses default values provided with the product. This chapter contains:
Introductory information that is helpful
to understand as you create your application:
After completing this chapter, you can update or customize the
application to make it fit the specific needs of your business.
Introducing the Rational SDP
environment
All of the steps in developing a HATS application are performed
using the Eclipse-based IBM® Rational® Software Delivery Platform (Rational SDP).
The Rational SDP provides the user interface
and integrated development environment (IDE) from which you launch
wizards to create resources, view lists of resources, and use editors
to modify resources. It also contains help information about both HATS and Rational SDP.
When you start Rational SDP,
you see a single window in which one or more perspectives are displayed.
A perspective is a collection of views and editors that allow you
to create, edit, view, and run resources which belong to a specific
type of project--in this case a HATS project. More than one
perspective can be open at a time, although you can view and work
with only one at a time.
At the far right of the Rational SDP window is a shortcut bar that
allows you to open new perspectives and move between perspectives
that are already open. The name of the active perspective appears
in the title of the window, and the toolbar contains icons associated
with the active perspective.
If you are not familiar with the Eclipse-based Rational SDP environment,
refer to the Eclipse Help site at http://www.eclipse.org/documentation/.
Start with the Basic tutorial in the Getting started section of the
Workbench User Guide.
Starting HATS Toolkit and perspective
The HATS Toolkit can be started two ways.
Start Rational SDP from the Windows start menu and then open
the HATS perspective.
Start HATS Toolkit from
the Windows start
menu to start Rational SDP and automatically open
the HATS perspective.
Notes:
The HATS Toolkit start menu
item is located in the IBM HATS
V9.5 group under the Rational SDP profile in which you have installed
HATS.
When you use the HATS Toolkit start
menu item, the HATS Toolkit starts in the language installed for Rational SDP,
assuming the HATS Toolkit is translated in the same language. When
installed on an Arabic translation of Rational SDP, two HATS Toolkit
start menu items are provided, HATS Toolkit
(Arabic), which starts the Arabic translation of HATS Toolkit,
and HATS Toolkit (English), which starts
the English translation of HATS Toolkit. For more information see
the chapter, Language support, in the HATS User's and Administrator's Guide.
The HATS perspective includes two main areas:
The HATS Projects view, which lists your HATS projects in
an expandable tree view.
A text filter entry field is provided to aid you in searching
for HATS artifacts. An asterisk (*) can be used as a wild card to
represent parts of the resource name. For example, using a filter
of *.css or *css returns the same matches.
Notes:
A wildcard is appended to the end of the text that you enter into
the filter field. For example, if you enter *.j in the filter field,
an asterisk is appended to the *.j, resulting in a filter of *.j*.
This filter would show you all .jsp and .jpg files.
Filtering is not case-sensitive.
To clear the text in the filter field, click the x beside the filter entry field.
The editor window, which initially
contains the HATS Welcome page. You will also use editors in this
window to work with HATS resources. Below and to the right of the
editor are views that aid in editing resources in the editor.
The Navigator view, which is a default view in Rational SDP, provides
a hierarchical view of the resources in the workbench including project
.ear files and other local artifacts. It also displays
closed (or archived) HATS projects that do not display in the HATS Projects view.
These closed projects can be re-opened by right-mouse clicking and
selecting Open Project.
The first time you start the HATS Toolkit, you will see a HATS tip,
welcoming you to HATS and giving pointers about getting started.
You can use the check boxes on the tip windows to control which tips
you see.
If you start Rational SDP and the HATS perspective does not appear,
you can open the HATS perspective by clicking Window
> Open Perspective > Other and selecting Host Access Transformation Services from
the list of available perspectives. If you close or rearrange some
of the windows in the HATS perspective, your arrangement is saved when you exit. When you return to HATS Toolkit,
it will be restored to your last successfully saved
exit configuration. To restore the original HATS windows, click Window > Reset Perspective.
Introducing the HATS Welcome page
The HATS Welcome page tutorial guides you through
the process of developing a HATS application. As you develop the application
and customize it, it is known as a project. A project is then packaged
as an application for a production runtime environment.
A project for a Web application is packaged in a Java™ EE web
module (.war file) and one or more web modules are packaged in a Java EE Enterprise
Application (.ear file), which is a WebSphere® application. The application is transferred
to and installed on a WebSphere Application
Server system.
A project for a portlet is packaged in a Java EE web module (.war file)
and transferred to and installed on a WebSphere Portal system.
A project for a rich client application is packaged
as a plug-in in an Eclipse feature which is
uploaded to an update site from which it can then be downloaded by
clients on rich client platforms.
Sections on the Welcome page can be expanded
by clicking the plus sign icon (+). Each section contains links that
start HATS functions and represents a stage in the process. A section is also provided that
contains links to online information,
Create
your first project links to the Create a Project wizard and introduces
the Debug on Server (for Web applications) and Debug (for rich client applications)
testing modes, which enable you to preview and test your project.
The testing function is described in detail in Testing your project. A link to the License Settings dialog is also provided.
License settings must be configured to enable your application for
the runtime environment.
Modify the template helps you update
the template you chose as your project default.
Edit the default rendering
set and global rules describes the conversion rules used by the
default transformation, and provides information on the use
of global rules.
Customize a screen introduces the
host terminal screen and the Create a Screen Customization wizard.
You can create a simple transformation to see how it changes your
host screen.
Combine screens introduces
the Create a Screen Combination wizard. You can create a simple screen
combination that collects information from a series of host screens
and presents the results as one page.
Work with macros, Integration Objects
and Web services (SOA) explains how macros can be used in your
projects, and introduces Integration Objects. Integration Objects,
supported in HATS Web applications, are standard Java beans that play macros.
You can create Integration Objects from macros in your projects and
create Web services from Integration Objects. Integration
Objects can also be used in EJB projects.
Interoperate with WebFacing introduces
the IBM WebFacing Tool for IBM i feature
of the HATS Toolkit. This feature provides the ability to convert
data description specification (DDS) display file
source members into a Web-based user interface for your existing IBM i programs.
Links are provided to the Create Linked HATS/WebFacing project wizard
and to the WebFacing perspective and WebFacing Help. This section
is only displayed if the WebFacing feature of HATS
is installed.
Utilize host simulation describes
the function that lets you work on your HATS project without requiring
an active connection to the host. You can record host simulation trace
files that can be saved and then used later instead of a live host
connection.
Explore advanced functions of HATS deepens
your knowledge about basic HATS concepts and introduces the project
editor, capturing screens, administration, the connection
editor, and more.
Prepare your project for
production shows you how to export the project as a WebSphere application (for
Web projects) or as an Eclipse feature (for rich client projects).
View the library of online information
for HATS provides links to the HATS documentation, the HATS
product Web site, the HATS Knowledge Center, the IBM Education Assistant, and the IBM Support Assistant.
As you use other HATS functions, focus switches
from the Welcome page to editors or other tools. Each page in
the editor window is given a tab at the top to enable you to move
from one page to another. You can return to the Welcome page by clicking
the Welcome to HATS tab, or by clicking
the Open HATS Welcome page icon on
the main toolbar. You can double-click any tab to toggle that tab's
page between its initial size and a full-screen view.
A welcome page for the WebFacing component of the
HATS Toolkit exists in the WebFacing perspective.
Starting HATS functions
HATS Toolkit provides several ways to start each HATS function. You
can:
Right-click a HATS resource in the HATS Projects view and
select the function you want from the pop-up menu.
Click a HATS icon on the toolbar. These icons are
described below.
Click the HATS item
on the menu bar and select from the list of available menu items.
Click a link on the Welcome page.
Click on the HATS Tools item
on the menu bar (used when editing a transformation for a Web application).
Click on an item from the Palette view (used when
editing a transformation for either Web or rich client applications).
Use the Properties view to edit components in a transformation.
In many cases, you can start a HATS function in a way that creates
linkage between HATS resources. For example, you can create a screen
customization based on a screen capture by right-clicking on the screen
capture and selecting New HATS > Screen
Customization. The screen customization's properties will default
to those of the screen capture.
Using HATS icons
This table shows the HATS icons that are placed on the Rational SDP main
toolbar.
Table 1. HATS toolbar icons
Create a HATS project
Open the HATS host terminal
Create a HATS connection
Create a HATS host simulation file
Create a HATS macro
Create a HATS screen customization
Create a HATS screen combination
Create a HATS transformation
Create a HATS template
Create a Java file
to run custom business logic
Test the selected HATS project
in the local test environment using debug mode
Export a project as a HATS application
Open the HATS Welcome page
Create a linked HATS/WebFacing
project (available only if the WebFacing feature of HATS is installed)
Other icons are available from certain windows, such as the
host terminal window. Those icons will be identified in the sections
that describe those windows.
HATS tips
To guide you through the flow of creating
a project and its resources, HATS provides tips when you do certain
tasks. You can use the check boxes at the bottom of the tip window
to specify whether you want to see that particular tip in the future
and whether you want to see any tips. You can also control whether tips are shown by following these steps:
From the main menu, click Window > Preferences.
In the Preferences window, click HATS in the tree on the left.
On the right panel, locate the check box labeled Show HATS tips. Check this box if you
want tips to appear, or clear it if you do not want tips.
Click OK at the bottom of the Preferences window.
Note:
If you have chosen to disable showing
one or more individual tips, but have not disabled tips completely,
you can re-enable showing the individual tips. To do so, clear the Show HATS tips check box and click Apply, then select the Show HATS tips check box and click OK.
Developing a HATS project
There are different paths you can take when building a HATS application.
You might want to build an application that allows an end-user to
navigate the host screens in an emulator-like fashion, or you might
want to build an application that uses Integration Objects to collect
data from the host and present that data on a Web page. You can even
combine host screen navigation in the GUI with host
data collection using Integration Objects in one Web application.
You can see step-by-step examples of HATS screen navigation and
HATS Integration Objects in the
HATS Tutorials section of the HATS Knowledge Center located at http://www.ibm.com/support/knowledgecenter/SSXKAY.
The procedures in this section will guide you through
the process of developing an example HATS project. The procedures
include information about both HATS Web and rich client projects.
As you follow the procedures, you will perform these steps:
Create a HATS project, with default values, using a wizard in
the HATS Toolkit.
Test the project using the local test
environment.
Make changes to the project. This process is known as customization.
Common customization tasks are described in Customizing your HATS project.
Test the project again, and do more customization.
Begin on the Welcome page. If the Welcome page is
not displayed, click the Open HATS Welcome
Page icon
on the main toolbar.
Expand the Create your
first project section.
Click the link to launch
the Create a Project wizard.
On the HATS Project page:
Type the name of the project you are creating.
Type a description of the project. This is optional. You can keep
notes here or use it however you want.
Leave the Use default location check
box selected.
In the Deployment section select whether the project is for a
Web application or a rich client application.
Note:
If the Web deployment option is disabled, this
indicates that no server runtimes are defined. To define server runtimes,
go to Window > Preferences > Server > Installed
Runtimes and add at least one runtime definition.
Web
Select the target server you want to use for your application.
Supply a name to use for the Enterprise application (.ear file)
project or take the default.
The Portlet API selection is only active if a WebSphere Portal server is
selected for the target server.
Leave the Optimize options for mobile
devices check box cleared.
Note:
For information about
creating a HATS Web project optimized for mobile devices, see the
section, Developing HATS applications for mobile devices, in the HATS User's and Administrator's Guide.
Select Use Dojo technology if
you want to use Dojo widgets in this project.
Leave the Add administration
console support check box selected.
Rich client
Accept the Plug-in ID and Plug-in version defaults.
Select the target platform.
Click Next.
On the Connection Settings page:
Type the name of the Telnet or WebFacing server
to use to access the host application. This can be a host name, a
domain name (such as myhost.mycompany.com), an alias, or an IP address.
If your host application uses 3270 protocols, select
the 3270 or 3270E connection type depending on the functions required
by the application. For example, printing support requires the 3270E
connection type. If your host application uses 5250 protocols, select
the 5250 connection type if it is accessed through a 5250 Telnet server.
Select the 5250W connection type if it is accessed through a WebFacing
server.
Select the port, code page and screen size.
Click Next.
On the Project Theme page, select the overall
appearance and behavior you want for the application.
You can select whether you want the application to appear and behave more like an emulator, more like a modern
application, or a custom setting somewhere in between. Click Next.
If you selected the Use Dojo technology setting
on the HATS Project page, the Dojo Project Setup page is displayed
at this point. To change the Dojo default settings, click Change these setup options. To accept the
defaults, click Next.
Note:
To
change Dojo settings after the HATS project is created, from the HATS Projects view
right-click the project and select Properties.
On the properties page select Dojo Toolkit.
On the Default Template page, all of the
templates provided with HATS are displayed. Choose one to use as
a starting point for your project. Click Finish.
A progress bar displays as HATS creates the project.
You have created a simple HATS project. Next, you
will test the project using the local test environment.
Testing your project
Testing modes for Web projects
Three different modes can be used for testing your Web projects,
Run on Server, Debug on Server, and Profile on Server.
Run on Server
Use this mode to test HATS Web and portlet projects in a WebSphere Application Serveror WebSphere Portal instance
or other supported servers, as appropriate. In this mode you can modify
and test the runtime settings, defined in the runtime.properties file,
that are deployed to the runtime environment.
Be aware that any changes made to the runtime settings while testing
in this mode are retained and become effective when you deploy the
HATS application to a runtime environment. For
more information about changing runtime settings see the HATS User's and Administrator's Guide.
To use this mode, in
the HATS Projects view right-click your project and select Run on Server.
Debug on Server
Same as Run on Server and in addition enables you to:
Use the display terminal to see host screens as they are navigated
while testing your project.
See debug messages in the Rational SDP console.
See changes you make to your project, for example
changing the template or a transformation, without having to restart
your application on the test server.
Modify and test runtime settings, defined
in the runtime-debug.properties file, without modifying the settings,
defined in the runtime.properties file, that are deployed to the runtime environment.
Step through Java code,
such as HATS business logic.
To use this mode, in the HATS Projects view right-click your
project and select Debug on Server.
Profile on Server
Same as Run on Server, and in addition enables you to locate
the operations that require the most time, and identify actions that
are repeated, to eliminate redundancy. You can use this function for
performance analysis, helping you to get a better understanding of
your application.
To use this mode, in the HATS Projects view right-click
your project and select Profile on Server.
Testing your Web project
Begin on the Welcome page. If the Welcome
to HATS page is not displayed, click the Welcome
to HATS tab at the top of the editor pane.
In the HATS Projects view on the left side of the
screen, select the name of the Web project you
just created.
On
the Welcome page, click Debug
On Server.
You are given the option to see the display terminal
while running the project. Click Yes to
see the host screens in the display terminal as
they are navigated while you test your project.
The Server Selection window opens, where you select
the server on which to run your project. Select the server to use.
Click Finish to complete the run on
server process.
Note:
The server selection must be
compatible with the server you chose when creating your HATS
project.
Rational SDP launches an instance of the selected server
to run your project on your local system. When you test your
project, you are using a local copy of the server that is provided
with Rational SDP. This local server is also called the local test
environment.
Note:
If after launching it, the local server
stays in either Starting or Publishing state, the CPU utilization
spikes to 100%, or your Web project starts but displays a blank page,
then make the following local server configuration changes to try
to remedy these issues:
Edit the server by double clicking on the server in the Servers
view.
In the Server section:
Select Manually provide connection settings.
Clear the RMI Connection Type,
and select the SOAP Connection Type.
Select Terminate server on workbench
shutdown.
In the Publishing section:
Select Never publish automatically.
If the server is running, restart the server for the changes to
take effect.
One other tip: Do not use the same EAR name across different
workspaces. If the same EAR file names are used in different workspaces,
404 errors can occur or the wrong application is presented. At project
creation time, HATS always defaults to an EAR name that is based on
the version of WebSphere Application Server for which you are creating the project. For example,
when the target server is WebSphere Application Server v8.0, the default
EAR name for all HATS projects is HATS_EAR8.
To ensure that different EAR names are used for different workspaces,
specify a unique name in the Enterprise
application project field when creating your HATS project.
When using the Debug on Server function in
the HATS Toolkit to test your project, the Rational SDP console
displays messages with the following information:
The HATS runtime version and build information
The name of the transformation being applied
The name of the macro being played
The name of the Java method
being executed for business logic
The name of the macro being played and the connection on which
the macro is playing during a macro transaction
The name of the event being processed, such as the start or unmatched screen events,
or your screen customization.
Indications that settings have changed
The
messages are displayed by default. If you want to disable the messages,
locate and double-click the web.xml file in the Web Content/WEB-INF/
path in the Navigator view to edit it. Select the Source tab, find the showStudioRuntimeMessages parameter,
change the value to false, and save the web.xml file.
A Web browser is launched within Rational SDP which
displays a Web page with which you can test your
project. The Web page is divided into two main areas:
The template, which usually covers the top and left sides of the
Web page, comprising a graphical banner and navigation links. The
template area typically remains the same for all, or most of, the
Web pages in your project, giving your users a consistent appearance.
The transformation area which presents the transformed host application.
The content of the transformation area is different on each Web page
in the project.
To view the application as the user would see it,
change the preferences in Rational SDP to use an external Web browser.
To do this, from the Rational SDP menu bar, select Window > Preferences > General > Web Browser,
select Use external Web browser, and
select the external Web browser to use. The Web browser opens with
a URL similar to the following: http://localhost:9080/myapp/. To enable
other users to see the Web page from a different machine, give them
a URL containing the IP address of the machine that is running HATS Toolkit.
For example, change the URL http://localhost:9080/myapp/ to http://myworkstation.mycompany.com:9080/myapp/.
Note:
HATS supports multiple browser instances
from the same workstation accessing the same HATS application. However,
these multiple browser instances must not share the same HTTP session
id.
Testing modes for rich client projects
Three different modes can be used for testing your rich client projects,
Run, Debug, and Profile.
Run
Use this mode to test HATS rich client projects in a new Eclipse, Lotus Notes®, or Lotus® Expeditor Client instance.
In this mode you can modify and test the runtime settings, defined
in the runtime.properties file, that are deployed to the runtime environment.
Be aware that any changes made to the runtime settings while testing
in this mode are retained and become effective when you deploy the
HATS application to a runtime environment. For
more information about changing runtime settings see the HATS User's and Administrator's Guide.
To use this mode, in
the HATS Projects view right-click your project and select Run.
Debug
Same as Run and in addition enables you to:
use the display terminal to see host screens as they are navigated
while testing your project
see debug messages in the Rational SDP console
see changes you make to your project, for example
changing the template or a transformation, without having to restart
your application
modify and test runtime settings, defined
in the runtime-debug.properties file, without modifying the settings,
defined in the runtime.properties file, that are deployed to the runtime environment
step through Java code,
such as HATS business logic
To use this mode, in the HATS Projects view right-click your
project and select Debug.
Profile
Same as Run, and in addition enables you to locate the operations
that require the most time, and identify actions that are repeated,
to eliminate redundancy. You can use this function for performance
analysis, helping you to get a better understanding of your application.
To
use this mode, in the HATS Projects view right-click your project
and select Profile.
Testing your rich client project
Begin on the Welcome page. If the Welcome
to HATS page is not displayed, click the Welcome
to HATS tab at the top of the editor pane.
In the HATS Projects view on the left side of the screen, select
the name of the rich client project you just
created.
On the Welcome page, click Debug.
You are given the option to see the display terminal while running
the project. Click Yes to see the
host screens as they are navigated while you test your
project.
The Debug window opens, where you can create,
manage, and run configurations. For HATS projects
with a target platform of Eclipse RCP, HATS
provides a default Eclipse Application configuration named hostaccess
that you can use. Click Debug to
complete the process.
Rational SDP launches an instance of the Eclipse RCP runtime
environment to run your project on your local system. When you test your project, you are using a copy of the Eclipse RCP that is embedded in Rational SDP. This environment
is also called the local test environment.
When the runtime environment is launched, the Host
Access perspective is displayed which contains an Applications view
on the left. Your HATS application is listed
in this view. To launch the application, right-click and select Open.
When you open your HATS application it displays in the transformation view. In the transformation view
you see the toolbar, template, and transformation areas.
The toolbar contains buttons for application-level actions as
well as buttons for actions contributed by the toolbar widget.
The template provides the overall appearance of the application.
It typically remains the same for all, or most of, the pages in your
application, giving your users a consistent appearance.
The transformation area presents the transformed
host application. The content of the transformation area is different
on each page in the application.
When you test a newly created HATS project,
you see what your host application looks like when the default transformation
is applied. This transformation is part of each project and uses default
rendering to provide an automatic conversion of your host application
screens into a GUI. Part of what you do with
the HATS Toolkit is to design transformations that improve the conversion
of your host application screens into a meaningful, usable GUI.
If you make changes to your project while you are testing it in debug on server mode (for Web projects)
or debug mode (for rich client projects), you do not generally
need to start a new test environment to view your changes. Instead,
click the Refresh button on the GUI that is already displayed.
Some of the changes you make may not appear when you
use a local test environment until you rebuild and refresh the workspace.
You can set preferences in Rational SDP that cause the workspace automatically
to be rebuilt and refreshed when you make changes. To do this, from
the Rational SDP menu bar select Window > Preferences > General > Workspace and
select the Build automatically and Refresh automatically check boxes. This
will enable the changes you make to appear immediately when you use
the local test environment.
After testing your initial project,
you may then want to customize it. For example, you may want to put
your own company name into the template and define widgets (fields,
input areas, and other GUI controls) in the transformation area. As
you develop your HATS project, you can use the test
environment to test it and to see how it will look to a user.
Here is a sequence of steps you may typically follow:
Create a HATS project.
Test it.
Make changes based on what you see in the test environment.