Creating a basic ZIETrans project

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. ZIETrans 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. ZIETrans 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 ZIETrans application that uses default values provided with the product. This chapter contains:

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 ZIETrans 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 ZIETrans 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 ZIETrans 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 Start with the Basic tutorial in the Getting started section of the Workbench User Guide.

Starting ZIETrans Toolkit and perspective

The ZIETrans Toolkit can be started two ways.

The ZIETrans perspective includes two main areas:

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) ZIETrans projects that do not display in the ZIETrans Projects view. These closed projects can be re-opened by right-mouse clicking and selecting Open Project.

The first time you start the ZIETrans Toolkit, you will see a ZIETrans tip, welcoming you to ZIETrans 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 ZIETrans perspective does not appear, you can open the ZIETrans perspective by clicking Window > Open Perspective > Other and selecting Z and I Emulator for Transformation from the list of available perspectives. If you close or rearrange some of the windows in the ZIETrans perspective, your arrangement is saved when you exit. When you return to ZIETrans Toolkit, it will be restored to your last successfully saved exit configuration. To restore the original ZIETrans windows, click Window > Reset Perspective.

Introducing the ZIETrans Welcome page

The ZIETrans Welcome page tutorial guides you through the process of developing a ZIETrans 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.

Sections on the Welcome page can be expanded by clicking the plus sign icon (+). Each section contains links that start ZIETrans functions and represents a stage in the process. A section is also provided that contains links to online information,

  1. Create your first project links to the Create a Project wizard and introduces the Debug on Server (for Web 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.
  2. Modify the template helps you update the template you chose as your project default.
  3. 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.
  4. 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.
  5. 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.
  6. 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 ZIETrans 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.
  7. Utilize host simulation describes the function that lets you work on your ZIETrans 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.
  8. Explore advanced functions of ZIETrans deepens your knowledge about basic ZIETrans concepts and introduces the project editor, capturing screens, administration, the connection editor, and more.
  9. Prepare your project for production shows you how to export the project as a WebSphere application (for Web projects).
  10. View the library of online information for ZIETrans provides links to the ZIETrans documentation, the ZIETrans product Web site, the ZIETrans Infocenter.

As you use other ZIETrans 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 ZIETrans tab, or by clicking the Open ZIETrans 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.

Starting ZIETrans functions

ZIETrans Toolkit provides several ways to start each ZIETrans function. You can:

In many cases, you can start a ZIETrans function in a way that creates linkage between ZIETrans resources. For example, you can create a screen customization based on a screen capture by right-clicking on the screen capture and selecting New ZIETrans > Screen Customization. The screen customization's properties will default to those of the screen capture.

Using ZIETrans icons

This table shows the ZIETrans icons that are placed on the Rational SDP main toolbar.

Table 1. ZIETrans toolbar icons
Create ZIETrans project
Create a ZIETrans project
Open host terminal
Open the ZIETrans host terminal
Create a ZIETrans connection
Create a ZIETrans connection
Create a ZIETrans host simulation file
Create a ZIETrans host simulation file
Create a ZIETrans macro
Create a ZIETrans macro
Create ZIETrans screen customization
Create a ZIETrans screen customization
Create ZIETrans screen customization
Create a ZIETrans screen combination
Create ZIETrans transformation
Create a ZIETrans transformation
Create ZIETrans template
Create a ZIETrans template
Create a Java file to run custom business logic
Create a Java file to run custom business logic
Test the ZIETrans project in debug mode
Test the selected ZIETrans project in the local test environment using debug mode
Export ZIETrans project
Export a project as a ZIETrans application
Open ZIETrans welcome page
Open the ZIETrans Welcome page

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.

ZIETrans tips

To guide you through the flow of creating a project and its resources, ZIETrans 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:

  1. From the main menu, click Window > Preferences.
  2. In the Preferences window, click ZIETrans in the tree on the left.
  3. On the right panel, locate the check box labeled Show ZIETrans tips. Check this box if you want tips to appear, or clear it if you do not want tips.
  4. Click OK at the bottom of the Preferences window.
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 ZIETrans tips check box and click Apply, then select the Show ZIETrans tips check box and click OK.

Developing a ZIETrans project

There are different paths you can take when building a ZIETrans 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 ZIETrans screen navigation and ZIETrans Integration Objects in the ZIETrans Tutorials section of the ZIETrans Infocenter located at

The procedures in this section will guide you through the process of developing an example ZIETrans project. The procedures include information about both ZIETrans Web projects. As you follow the procedures, you will perform these steps:

  1. Create a ZIETrans project, with default values, using a wizard in the ZIETrans Toolkit.
  2. Test the project using the local test environment.
  3. Make changes to the project. This process is known as customization. Common customization tasks are described in Customizing your ZIETrans project.
  4. Test the project again, and do more customization.
  5. Export the project to an application and transfer it to a production environment. These steps are described in Preparing your ZIETrans project for use as an application.

Creating a ZIETrans project

Begin on the Welcome page. If the Welcome page is not displayed, click the Open ZIETrans Welcome Page icon ZIETrans welcome page icon on the main toolbar.

  1. Expand the Create your first project section.
  2. Click the link to launch the Create a Project wizard.
  3. On the ZIETrans Project page:
    1. Type the name of the project you are creating.
    2. Type a description of the project. This is optional. You can keep notes here or use it however you want.
    3. Leave the Use default location check box selected.
    4. In the Deployment section select whether the project is for a Web application.
      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.
        • Leave the Optimize options for mobile devices check box cleared.
          For information about creating a ZIETrans Web project optimized for mobile devices, see the section, Developing ZIETrans applications for mobile devices, in the ZIETrans 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.
    5. Click Next.
  4. On the Connection Settings page:
    1. Type the name of the Telnet server to use to access the host application. This can be a host name, a domain name (such as, an alias, or an IP address.
    2. 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.
    3. Select the port, code page and screen size.
    4. Click Next.
  5. 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.
  6. If you selected the Use Dojo technology setting on the ZIETrans 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.
    To change Dojo settings after the ZIETrans project is created, from the ZIETrans Projects view right-click the project and select Properties. On the properties page select Dojo Toolkit.
  7. On the Default Template page, all of the templates provided with ZIETrans are displayed. Choose one to use as a starting point for your project. Click Finish.
  8. A progress bar displays as ZIETrans creates the project.

You have created a simple ZIETrans 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 ZIETrans Web projects in a WebSphere Application Server instance or other supported servers, as appropriate. In this mode you can modify and test the runtime settings, defined in the 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 ZIETrans application to a runtime environment. For more information about changing runtime settings see the ZIETrans User's and Administrator's Guide.

To use this mode, in the ZIETrans 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:

To use this mode, in the ZIETrans 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 ZIETrans Projects view right-click your project and select Profile on Server.

Testing your Web project

Begin on the Welcome page. If the Welcome to ZIETrans page is not displayed, click the Welcome to ZIETrans tab at the top of the editor pane.

  1. In the ZIETrans Projects view on the left side of the screen, select the name of the Web project you just created.
  2. On the Welcome page, click Debug On Server.
  3. 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.
  4. 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.
    The server selection must be compatible with the server you chose when creating your ZIETrans 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.

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:
  1. Edit the server by double clicking on the server in the Servers view.
  2. 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.
  3. In the Publishing section:
    • Select Never publish automatically.
  4. If the server is running, restart the server for the changes to take effect.
  5. 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, ZIETrans 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 ZIETrans projects is ZIETrans_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 ZIETrans project.

When using the Debug on Server function in the ZIETrans Toolkit to test your project, the Rational SDP console displays messages with the following information:

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:

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 ZIETrans Toolkit. For example, change the URL http://localhost:9080/myapp/ to

ZIETrans supports multiple browser instances from the same workstation accessing the same ZIETrans application. However, these multiple browser instances must not share the same HTTP session id.

While testing your project

When you test a newly created ZIETrans 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 ZIETrans 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), 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 ZIETrans 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:

  1. Create a ZIETrans project.
  2. Test it.
  3. Make changes based on what you see in the test environment.
  4. Refresh the test environment.
  5. Repeat until you are satisfied.

For more information about how to customize ZIETrans projects, see Customizing your ZIETrans project.