HCL Z and I Emulator for Web Version 1.0

Planning, Installing, and Configuring Z and I Emulator for Web


Contents

About this book
About the other Z and I Emulator for Web documentation
Conventions used in this book
Terminology
Terms relating to Java
Planning for Z and I Emulator for Web
Introducing HCL Z and I Emulator for Web
What is Z and I Emulator for Web?
How does Z and I Emulator for Web work?
Why use Z and I Emulator for Web?
A cost-effective approach to connectivity
Centralized management of configuration data
Connect directly to any Telnet server
Supports many different platforms and network environments
Support for Java
Support for Internet Protocol Version 6
Supports many national languages
Secure connections
Custom HTML files
Toolkit for creating new e-business applications
Z and I Emulator for Web Session Manager APIs
Support for WebSphere Portal
Connections to DB2 databases on IBM System i servers
Planning for deployment
Understanding the HTML-based model
Understanding the configuration server-based model
Understanding the combined model
Client deployment considerations
Planning for Java on the client
Improvements to the cached client for Java
Limits of support
Downloading a client with Java
Cannot download a component not in the preload list
HTML files do not contain some components
Mac OS X with Java
Mac OS X limitations
Slightly slower startup times with Java clients
Limitations of specific Java plug-ins
Limitations with customer-supplied applets and Java
Limitations with restricted users and Java
Browsers and Java plug-ins
Java-enabled browsers
Browsers and plug-ins supported by Z and I Emulator for Web clients
Microsoft Internet Explorer with a Java plug-in
Firefox with a Java plug-in
Planning for security
Transport Layer Security (TLS)
How TLS security works
TLS for Z and I Emulator for Web
Web server security
Configuration security
The Redirector
Why use the Redirector?
How the Redirector works
Redirector load capacity
Operating systems supported by the Redirector
Using Z and I Emulator for Web with a firewall
Configuring firewall ports
Connecting to a host system through a proxy server
User ID security
Web Express Logon
Native Authentication
Windows Domain logon
FIPS environments
Planning for national language support
Supported languages
Supported host code pages
3270 and 5250 code pages
VT code pages
CICS Gateway code pages
Japanese JIS2004 Unicode support
User-defined character mapping
Unicode Support for i/OS and OS/400
Installing, upgrading, and uninstalling Z and I Emulator for Web
Installing the Z and I Emulator for Web server and related software
Installing Z and I Emulator for Web using Installation Manager
Important links
Before the ZIEWeb Installation
Preparing to Install
Installing Z and I Emulator for Web
Using the Installation Manager GUI to install
Deployment Wizard
Installing the Deployment Wizard
Downloading the Deployment Wizard installation image from a Z and I Emulator for Web server
Host Access Toolkit
Installing the Host Access Toolkit
Installing in the Console Mode
About installing in the Console Mode
Before installing ZIEWeb on IBM iSeries
Installation procedure
Installing Deployment wizard in Console mode
Installing Host Access Toolkit in console mode
Installing in Silent Mode
Installation procedure
Installing the configuration servlet
Deploying the servlet on WebSphere Application Server
Uninstalling the Z and I Emulator for Web server
Uninstalling Z and I Emulator for Web using Installation Manager Console mode
Configuring Z and I Emulator for Web
Configuring Z and I Emulator for Web emulator clients
Creating Z and I Emulator for Web HTML files
Configuring Z and I Emulator for Web sessions
Using the Deployment Wizard
Distributing the Deployment Wizard output to your Z and I Emulator for Web server
Using Z and I Emulator for Web administration and new user clients
Loading administration and new user clients
Administration clients
Directory Utility
New user clients
Using Z and I Emulator for Web emulator clients
Loading emulator clients
Selecting the appropriate client
Web Start client
Installing the Web Start client
Configuring your Web server for Web Start
Upgrading the Web Start client
Adding Web Start components after the initial install
Web Start and Windows Restricted Users
Bookmarking sessions with Web Start
Using Web Start with HTTPS
Removing the Web Start client
Deploying customer-supplied Java archives and classes
Using the AdditionalArchives HTML parameter
Deploying from the Publish directory
Hints and tips for archive files
Using Database On-Demand clients
Database functions in Display Emulation clients and in macros
Starting a Database On-Demand client
Database On-Demand predefined clients
Configuring Database On-Demand for users
Obtaining and installing a JDBC driver
File formats for database access
Using multiple code pages with Database On-Demand
Supported Database On-Demand code pages
Creating and deploying server macro libraries
Deploying a server macro library to a Web server
Deploying a server macro library to a shared drive
Modifying session properties dynamically
Setting up the initial HTML file
Setting the Code base
Add the ConfigBase Parameter
Overriding HTML parameters
Specific session properties that can be overridden
Example #1: Overriding the LU name based on the client's IP address
Example #2: Allowing the user to specify the host to connect to using an HTML form
Configuring Z and I Emulator for Web on zSeries
Setting up separate read/write private and publish directories
Set up a separate File System for the Z and I Emulator for Web private directory
Set up a separate user publish directory
Installing the Development Wizard from the z/OS server
Configuring Z and I Emulator for Web on IBM System i
Configuring, starting, and stopping the Z and I Emulator for Web Service Manager on IBM System i
Configure
Start
Stop
Work with ZIE Server status
Certificate Management
Start Information Bundler
Create ZIEWeb Printer Definition Table
Using the Deployment Wizard with IBM System i
Configuring IBM System i servers for secure connection
Installing and configuring Z and I Emulator for Web with TLS on i/OS and OS/400
Configuring a Telnet server for secure connection
Configuring the Z and I Emulator for Web CustomizedCAs keyring
Client authentication
Configuring the Z and I Emulator for Web OS/400 proxy for secure connections
Secure Web serving
Unicode Support for i/OS and OS/400
General information
Host programming information
Deploying Z and I Emulator for Web with WebSphere Portal
Eclipse-Plugin support
Creating Z and I Emulator for Web plug-ins
Setting Session Properties Dynamically
Using a separate user publishing directory
View IDs used in Z and I Emulator for Web plugin
Limitations on using Z and I Emulator for Web in a Eclipse-Plugin environment
Configuring Z and I Emulator for Web Server to use LDAP
Setting up LDAP support
Installing the schema extensions
Configuring the Z and I Emulator for Web server to use LDAP as a data store
Appendixes
Appendix A. Using locally installed clients
Operating systems that support the locally installed client
Installing the local client
Starting the local client
Removing the local client
Appendix B. Using the IKEYCMD command-line interface
Environment set-up for IKEYCMD command-line interface
IKEYCMD command-line syntax
IKEYCMD list of tasks for Z and I Emulator for Web
Creating a new key database
Setting the database password
Changing the database password
Listing CAs
Creating a new key pair and certificate request
Storing the server certificate
Receiving a CA-signed certificate
Storing a CA certificate
Creating a self-signed certificate
Making server certificates available to clients
Adding the root of an unknown CA to CustomizedCAs.p12
Exporting keys
Importing keys
Showing the default key in a key database
Storing the encrypted database in a stash file
IKEYCMD command-line parameter overview
IKEYCMD command-line options overview
Command-line invocation
User properties file
Appendix C. P12 Keyring utility
Usage
Options
Examples
Appendix D. Native platform launcher command line options
Appendix E. Notices
Appendix F. Trademarks

About this book

The Planning, Installing, and Configuring Z and I Emulator for Web guide helps you to plan for, install, and configure the Z and I Emulator for Web program. This book is written for administrators. It contains three major parts.

Planning for Z and I Emulator for Web gives you information about Z and I Emulator for Web for you to consider before installation and deployment. For example, which server platform will you use? Which deployment model will you use? How will you handle security?

Installing, upgrading, and uninstalling Z and I Emulator for Web offers step-by-step procedures based on each operating system.

Configuring Z and I Emulator for Web describes different configuration models to specify how session configuration information is defined and managed, how to dynamically modify session configuration information, how to customize new clients, and how to deploy Z and I Emulator for Web to your users.

After you install and configure Z and I Emulator for Web, use the online help to learn how to define sessions and perform other administrative tasks.

Planning, Installing, and Configuring Z and I Emulator for Web is also available at https://zieweb.hcldoc.com/help/index.jsp.

About the other Z and I Emulator for Web documentation

Most of the documentation is also included on the Z and I Emulator for Web product or Toolkit.

Conventions used in this book

The following typographic conventions are used in Planning, Installing and Configuring Z and I Emulator for Web:

Table 1. Conventions used in this book
Convention Meaning
Monospace Indicates text you need to enter at a command prompt and values you need to use literally, such as commands, functions, and resource definition attributes and their values. Monospace also indicates screen text and code examples.
Italics Indicates variable values you need to provide (for example, you supply the name of a file for file_name). Italics also indicates emphasis and the titles of books.
Return Refers to the key labeled with the word Return, the word Enter, or the left arrow.
> When used to describe a menu, shows a series of menu selections. For example, "Click File > New" means "From the File menu, click the New command."
When used to describe a tree view, shows a series of folder or object expansions. For example, "Expand Config Servlet > Sysplexes > Plex1 > J2EE Servers > BBOARS2" means:
  1. Expand the Config Servlet folder
  2. Expand the Sysplexes folder
  3. Expand the Plex1 folder
  4. Expand the J2EE Servers folder
  5. Expand the BBOARS2 folder

Graphic Image
This graphic is used to highlight notes to the reader.
Graphic Image
This graphic is used to highlight tips for the reader.

Terminology

This section describes the terminology used throughout this book.

applet
A program written in Java that is referenced in an HTML file. An applet is launched by a Java Virtual Machine (JVM) running in a Web browser.
application
A program or suite of programs that perform a task or specific function.
cached client
A Z and I Emulator for Web cached client is any Z and I Emulator for Web client whose components have been cached (stored locally for quick access) on the hard disk of a user's workstation.
default publish directory
The default publish directory is the subdirectory ZIEWeb in your Z and I Emulator for Web server's install directory, for example, c:\Program Files\HCL\ZIEForWeb\ZIEWeb\ on Windows platforms and /opt/HCL/ZIEForWeb/ZIEWeb on AIX, Linux, Solaris, /QHCL/Programs/HCL/ZIEForWeb/ZIEWebon i(as/400), and /usr/lpp/ZIEWeb/zieforweb/ZIEWeb on z/OS platforms.
download client
Download clients download the necessary applet files each time users access the HTML files. Download clients are generally used in LAN-connected environments because high-speed network connections reduce the time it takes to download them from the Web server.
emulator client
An emulator client is a Z and I Emulator for Web client that launches a terminal emulator session. Z and I Emulator for Web includes the following emulator clients: cached client, Web Start client, and download client.
separate user publish directory
Provides a separate writeable location for deploying custom HTML files, isolating them from the files provided by Z and I Emulator for Web. This keeps the Z and I Emulator for Web publish directory read-only and makes it easier to apply future Z and I Emulator for Web upgrades.
Note:
Other user-modified files (such as custom applets and HACL programs) still need to run from the Z and I Emulator for Web publish directory.
Web Application Server
The run time for dynamic Web applications. Web application server includes support for Java servlets, JavaServer Pages (JSP), and other enterprise Java application programming interfaces (APIs). A Web application server provides communications, resource management, security, transaction management, and persistence capabilities for Web applications. It also typically includes an administration interface for managing the server and deployed applications.
Web server
A server on the Web that serves requests for HTTP documents. A Web server controls the flow of transactions to and from the browser. It protects the confidentiality of customer transactions and ensures that the user's identity is securely transmitted to the server.
Web Start client
The Web Start client allows users to run Z and I Emulator for Web sessions without a browser. Users start Z and I Emulator for Web sessions from the Java Web Start Application Manager.

Terms relating to Java

Note the following terms and their use in this document.

Java
Refers to Java Runtime Environment (JRE) on either the ZIE server or the ZIEWeb client.
Java-enabled browser
A Web browser that runs Java applets on the Java JVM of an installed Java plug-in, for example, Firefox and Internet Explorer with a Java plug-in. For more information, refer to Browsers and Java plug-ins.
Java emulator client, Java cached client, Java download client
A version of the Z and I Emulator for Web client. The Java version consists of a complete set of Z and I Emulator for Web client components compiled with a Java compiler.

Planning for Z and I Emulator for Web

Introducing HCL Z and I Emulator for Web

What is Z and I Emulator for Web?

HCL Z and I Emulator for Web provides cost effective and secure host access to users in intranet-based and extranet-based environments. Z and I Emulator for Web is installed on a Web server, simplifying administrative management and deployment, and the Z and I Emulator for Web applet or application is downloaded to the client browser or workstation, providing user connectivity to critical host applications and data.

Z and I Emulator for Web supports emulation for common terminal types, communications protocols, communications gateways, and printers, including the following:

You can use the Java component-based Host Access Toolkit to create customized e-business applications. This Toolkit contains a rich set of Java libraries and application programming interfaces: Host Access Class Library (HACL), Host Access Beans for Java, and Java Enterprise Edition (J2EE) connectors. Z and I Emulator for Web also includes Database On-Demand, which provides an interface for sending Structured Query Language (SQL) queries to IBM DB2 databases hosted on IBM System i7 systems.

How does Z and I Emulator for Web work?

The following figure and explanation show how a Z and I Emulator for Web system works. Z and I Emulator for Web is a client/server system. Z and I Emulator for Web clients are Java applets that are downloaded from the Web server to a Web browser on a remote computer.

Figure 1. How Z and I Emulator for Web works
How Z and I Emulator for Web works

Step 1. The user opens a browser and clicks a hyperlink.

Step 2. HCL Z and I Emulator for Web applet downloads to the client workstation.

Step 3. When the applet is downloaded, HCL Z and I Emulator for Web connects directly to any Telnet server to access host applications.

Session information is configured in the HTML file or Z and I Emulator for Web configuration server. For more information about the configuration server, see Planning for deployment.

Z and I Emulator for Web client applets can be run as download clients, Web Start clients, or cached clients. Download clients are downloaded from the Web server every time they are used. Cached client and Web Start clients are downloaded from the Web server and stored on the client computer. After the initial download, the cached client is loaded from the local machine. The cached client checks the Z and I Emulator for Web server for new versions of the client and automatically downloads the updated version.

Z and I Emulator for Web includes the following administrative components:

In addition, a number of predefined clients are also supplied with Z and I Emulator for Web to demonstrate Z and I Emulator for Web's client functions for users and administrators (for example, emulation, Database On-Demand, cached client removal, and problem determination utilities).

Why use Z and I Emulator for Web?

A cost-effective approach to connectivity

You can reduce maintenance costs and increase your return on investment by installing Z and I Emulator for Web on a Web server, eliminating the need to manage individual user desktops.

Since the applets reside on a server and are downloaded to Web browsers when needed, you no longer have to schedule maintenance and upgrades. Upgrade the software on the server and users can receive the upgrade the next time they access the client applet.

Centralized management of configuration data

Administrators can centrally define and control all session configuration information available to their users, including connection options, security features, macro definitions, keyboard specifications, and color mappings. Furthermore, administrators have full control over which fields the user can or cannot modify, and can choose where user updates should be stored.

On Windows platforms, the default Z and I Emulator for Web graphical user interface is based on the Nimbus Look and Feel provided by Java 1.6 and later.

Connect directly to any Telnet server

With Z and I Emulator for Web, the client applet contains the emulation functionality. With the emulator residing on the client, the middle-tier server, such as IBM Communications Server or a third-party SNA server, can be eliminated. Any performance and security issues introduced with this intermediary piece will also be removed. Once the applet is served to the client, it is easy to connect directly to any standard Telnet server that provides the best access to the required data. You can access many host sessions concurrently. By eliminating the need for a middle-tier server, Z and I Emulator for Web also minimizes capacity restrictions. To see how this works, refer to Figure 1.

Supports many different platforms and network environments

Z and I Emulator for Web servers and clients are supported on a wide variety of platforms and can be used over any TCP/IP network. This gives you a great deal of flexibility in setting up your system and enables Z and I Emulator for Web to be deployed in your computing environment without having to purchase new hardware.

Support for Java

Z and I Emulator for Web is compatible with browsers that support Java standards. In addition, some new features of Z and I Emulator for Web take advantage of capabilities offered only by Java.

Support for Internet Protocol Version 6

Support for Internet Protocol Version 6 requires Java 1.4 or higher. However, Z and I Emulator for Web Version 1.0 supports Java 1.6 or higher.

An Internet Protocol is a protocol used to route data from its source to its destination through an Internet environment. An IP is an intermediary between higher protocol layers and the physical network.

Internet Protocol Version 6 is the replacement for Internet Protocol Version 4. Internet Protocol Version 6 expands the number of available IP addresses and makes improvements in routing and network configuration. Both Internet Protocol Version 6 and Internet Protocol Version 4 were designed by the Internet Engineering Task Force (IETF).

Most of the Internet currently uses Internet Protocol Version 4. Internet Protocol Version 6 is expected to replace Internet Protocol Version 4 over a period of years.

Graphic Image

The Z and I Emulator for Web server also supports Internet Protocol Version 6 for the Redirector. For more information, refer to Redirector support for IPv6.

Supports many national languages

Z and I Emulator for Web is available in multiple languages, including double-byte character set (DBCS) languages. Support for the European currency symbol, as well as keyboard and code page support for many more languages such as Arabic, Hebrew and Thai, is also provided. All language versions are available on the same media, and multiple language versions can be accessed concurrently.

Secure connections

Using Transport Layer Security (TLS), Z and I Emulator for Web extends secure host data access across intranets, extranets, and the Internet. Mobile workers access a secure Web site, receive authentication and establish communication with a secure enterprise host. With client and server certificate support, Z and I Emulator for Web can present a digital certificate to the Telnet server - such as IBM Communications Server for z/OS - for authentication.

Z and I Emulator for Web can also be configured for use in environments that include firewalls. Firewall ports need to be opened for the functions defined in your Z and I Emulator for Web session definitions. For more information, refer to Using Z and I Emulator for Web with a firewall.

Custom HTML files

Z and I Emulator for Web includes a Deployment Wizard that you can use to create custom HTML files. With these files you can tailor the content of the client and the function necessary to meet the needs of specific groups of users. For more information about the Deployment Wizard, refer to Configuring Z and I Emulator for Web emulator clients.

Toolkit for creating new e-business applications

Z and I Emulator for Web includes the Java component-based Host Access Toolkit for creating customized e-business applications. This Toolkit contains a rich set of Java libraries and application programming interfaces, including the Host Access Class Library (HACL), Host Access Beans for Java, and Java Enterprise Edition (J2EE) connectors.

HACL provides a non-visual API for interacting with back-end host machines running applications originally designed for human interaction. Host applications rely on readable character presentation, formatted fields, color-coding, and keyboard responses. HACL provides specialized classes for functionalities needed to mimic traditional interaction with a series of host screen presentations (green screens). HACL contains no GUI (visible component) classes. For example, a Java program could be running on a mainframe as a secondary application. The secondary application program interacts first with another mainframe running a CICS data application, and then with a client browser through dynamically generated HTML pages. The secondary application interprets client inputs into simulated terminal actions which are sent to the CICS machine using the HACL API. The response screens from the CICS machine are captured using HACL APIs, converted into dynamic HTML pages, and sent back to the client.

Z and I Emulator for Web J2EE Connector provides a set of Resource adapters that communicate to 3270, 5250, CICS, and VT hosts. These resource adapters are deployed to a conforming application server, such as IBM Application Server. The users can write Web applications using the APIs provided in Z and I Emulator for Web J2EE Connector via WebSphere Studio Application Developer Integration Edition.

Z and I Emulator for Web Session Manager APIs

In addition to the application programming interfaces (APIs) provided with the Host Access Toolkit, Z and I Emulator for Web provides specialized public APIs that provide support for embedding host sessions in Web pages using JavaScript. These JavaScript-based APIs help application developers manage host sessions and text-based interactions with host sessions and are available through the Z and I Emulator for Web Session Manager. Refer to the Session Manager API Reference for more information.

Support for WebSphere Portal

Z and I Emulator for Web can run as a portlet on Portal Server, a component of WebSphere Portal. Portal Server has sophisticated desktop management and security features that offer administrators more control over user access rights and users control over the appearance and arrangement of the portal desktop.

Administrators can create customized Z and I Emulator for Web portlets quickly and easily using the Deployment Wizard and then load them directly into Portal Server.

Note:
Portal Server is a separate product and requires independent installation.

Connections to DB2 databases on IBM System i servers

Database On-Demand is included with Z and I Emulator for Web to provide access to DB2 information stored on IBM System i5 servers using a Java Database Connectivity (JDBC) driver. Database On-Demand is a Java applet that allows you to perform Structured Query Language (SQL) requests to IBM System i5 databases through a JDBC driver. Database On-Demand is a separate applet from the Z and I Emulator for Web applet and is started by a separate HTML file. You can also use the Data transfer support from within an emulator session to perform SQL requests if you need both terminal emulation and support for SQL queries.

Planning for deployment

Z and I Emulator for Web provides access to host applications from a Web browser. The browser downloads the Z and I Emulator for Web Java applet from the Web server and then connects to any Telnet server to access host applications. The Z and I Emulator for Web applet needs configuration information to determine which host to connect to and other host session properties. This configuration information can be provided to the Z and I Emulator for Web applet from an HTML file that is used to launch Z and I Emulator for Web or by the Z and I Emulator for Web configuration server. The configuration server is a part of that centrally stores session configuration information and user preferences by user and group IDs. Users then access session information and user preferences by contacting the configuration server. The configuration server is managed through the administration client. For information on configuring the Z and I Emulator for Web configuration server, see the online help.

As Web browsers start to eliminate support for Java plug-ins, Z and I Emulator for Web clients will continue to work with some limitations as documented in Z and I Emulator for Web browser support.

You can create custom client HTML files using the Deployment Wizard. When creating these HTML files, you can choose from three different configuration models to specify how session configuration information and user preferences are defined and managed: the HTML-based model, the configuration server-based model, and the combined model.

These models are described below. For detailed information on each model and benefits and limitations to using each model, see the online help.

Understanding the HTML-based model

If you choose the HTML-based model, all host session configuration information is contained in the HTML file itself, and nothing more is needed to define host sessions. Therefore, you are not required to use the configuration server to specify sessions, which means you do not have to open up a port on your firewall. If you allow users to save changes to the host session configuration information, their changes are stored on the local file system where the browser is running.

You are suggested not using the port 8999 because you do not need to start the ZIE server by using the HTML-based model. In this case the server resource is saved.

This option of defining configuration information in the HTML files is only available in clients that are created using the Deployment Wizard.

Figure 2. HTML-based model
HTML-based model

Understanding the configuration server-based model

In the configuration server-based model, host session information is maintained on the configuration server using the Administration client, and the information is defined using a user and group structure. By default, the configuration server stores its data directly on the Z and I Emulator for Web server machine, though it can be configured to use LDAP instead. Users access their configurations using either custom HTML files created in the Deployment Wizard or by using one of several HTML files that are provided as part of Z and I Emulator for Web. User IDs are defined in the configuration server, and in most cases the user needs to log on to the Z and I Emulator for Web server before viewing his sessions. If administrators allow users to save changes, user preferences are stored in the configuration server by user ID. Because their customizations are saved on the configuration server, this model may be the best choice if users need to access their sessions from multiple machines.

By default, the Web browser communicates directly to the configuration server. If you communicate through a firewall, you need to open the configuration server's port on the firewall. Alternatively, you can use the configuration servlet to eliminate the need to open the configuration server's port on the firewall. The Web browser connects to the configuration servlet over an HTTP or HTTPS connection and the configuration servlet then interacts with the configuration server. See Configuring the configuration servlet for more information about using the configuration servlet.

Figure 3. Configuration server-based model and combined model
Configuration server-based model and combined model
Figure 4. Configuration server-based model and combined model using configuration servlet
Configuration server-based model and combined model using configuration servlet

Understanding the combined model

Z and I Emulator for Web supports a combined model, where the host session information is defined in the configuration server (like the configuration server-based model) and user updates are saved on the user's machine (like the HTML-based model). In addition, like the HTML-based model, users of the combined model do not need to log on to the Z and I Emulator for Web server to view their sessions.

Client deployment considerations

Additionally, for client deployment considerations, you need to decide whether to use cached, download, or Web Start clients (see Using Z and I Emulator for Web emulator clients) and which version of Java to use (see Planning for Java on the client).

Planning for Java on the client

This chapter provides detailed information related to running the Z and I Emulator for Web client on a Java-enabled browser.

Improvements to the cached client for Java

With the Java cached client, you can do the following:

Note:
The following restriction apply:

A few Java cached client types cannot be upgraded in the background. See Limits of supportfor more information.

Almost all Z and I Emulator for Web Java cached clients support these improvements. The Java Web Start client also supports these improvements.

Limits of support

The following types of Java cached clients do not support the improvements to the Java cached client:

Downloading a client with Java

The following sections discuss the limitations in downloading a client with Java.

Cannot download a component not in the preload list

With the Java download client, a user cannot download a Z and I Emulator for Web client component that is not in the original preload list. Consequently, you need to specify all the components that your users might require in the preload list.

This limitation is caused by a conflict between the method used by a download client to download components not on the preload list and security restrictions imposed by the Java plug-in.

HTML files do not contain some components

With Java, the default download client HTML files (default_xx.html, where xx is the two-letter language suffix) do not contain the following client components:

These less frequently used components were removed from the preload list of the Java default download HTML files to shorten download time. However, with the Java download client, any component not in the preload list cannot be downloaded later.

If you want some or all of these components to be in the preload list, perform one of the following actions:

Mac OS X with Java

Z and I Emulator for Web Mac OS X emulator and database clients support Safari , Firefox, and the Mac version of Internet Explorer. Z and I Emulator for Web does not support the administration clients on Mac OS X. Z and I Emulator for Web Version 1.0 supports Java 1.6 or higher.

The Duplicate Key Support feature requires a Java Plug-in of 1.4.2 or newer on Macintosh clients. However, Z and I Emulator for Web Version 1.0 supports Java 1.6 or higher.

Mac OS X limitations

Mac OS X does not support the Java cached client improvements described in Improvements to the cached client for Java.

Slightly slower startup times with Java clients

With a Java-enabled browser, the Z and I Emulator for Web client starts a little more slowly (5 to 15 seconds slower, depending on the workstation type). The delay is caused by the system loading the Java plug-in.

Also, with a Java-enabled browser, a host session on the Z and I Emulator for Web client desktop can take a little longer to start.

Limitations of specific Java plug-ins

If you are using a Oracle Java plug-in and Hindi characters are not displayed correctly, make sure your Oracle JRE level is the latest.

Limitations with customer-supplied applets and Java

If a user runs a customer-supplied applet (that is, an applet written by your company or a third party) with a session (such as 3270 Display) launched from a Java Z and I Emulator for Web client, and if this applet requires any Java permissions, you are suggested taking one of the following actions to meet the security requirements of Java:

If you do not meet the security requirements of Java, the applet silently fails.

Limitations with restricted users and Java

Restricted users do not have the authority to install the Java plug-in. A user with administrative authority must install the Java plug-in.

Browsers and Java plug-ins

This section discusses issues involved in using Java-enabled browsers and Java plug-ins.

Java-enabled browsers

A Java-enabled browser does not have a JVM included with it. It can display HTML files on its own, but it needs a separate Java plug-in installed to launch a Java applet such as the Z and I Emulator for Web client. Examples of Java-enabled browsers are Firefox and Microsoft Internet Explorer with the Java plug-in installed.

Browsers and plug-ins supported by Z and I Emulator for Web clients

Users with client workstations running Windows can download the IBM Java plug-in from Fix Central under the Z and I Emulator for Web product as long as company is entitled to ZIEWeb.

As vendors of Java plug-ins such as Oracle and IBM publish new versions of their Java plug-ins, and as HCL extends Z and I Emulator for Web to support these new versions, HCL will update the Software Product Compatibility Reports for support of new versions of JRE.

Microsoft Internet Explorer with a Java plug-in

When a Java plug-in is properly installed and configured on a Windows client workstation, Microsoft Internet Explorer will function as a Java-enabled browser, depending on how Z and I Emulator for Web chooses to launch the client.

Firefox with a Java plug-in

To run a Java applet on Firefox, you need to install a Java plug-in.

Consequently, Z and I Emulator for Web expects you to configure the Java plug-in so that it is the default Java Runtime for Firefox.

Note:
Restricted users, such as restricted users sharing a cached client on Windows, or restricted users on a Linux or Aix workstation, cannot install the Java pug-in

Planning for security

Whether you are implementing Z and I Emulator for Web purely within your corporate network, or you are using it to provide access to your host systems over the Internet, security is a concern. This chapter provides an overview of Z and I Emulator for Web security.

Transport Layer Security (TLS)

How TLS security works

TLS is based on the SSL protocol. TLS uses the initial handshake protocol for establishing client/server authentication and encryption. For detailed information on TLS, see the description of The TLS Protocol Version 1.0.

The TLS protocol uses public-key and symmetric-key cryptographic technology. Public-key cryptography uses a pair of keys: a public key and a private key. Information encrypted with one key can be decrypted only with the other key. For example, information encrypted with the public key can be decrypted only with the private key. Each server's public key is published, and the private key is kept secret. To send a secure message to the server, the client encrypts the message by using the server's public key. When the server receives the message, it decrypts the message with its private key.

Symmetric-key cryptography uses the same key to encrypt and decrypt messages. The client randomly generates a symmetric key to be used for encrypting all session data. The key is then encrypted with the server's public key and sent to the server.

TLS provides three basic security services:

Message privacy
Achieved through a combination of public-key and symmetric-key encryption. All traffic between a client and a server is encrypted using a key and an encryption algorithm negotiated during session setup.
Message integrity
Ensures that session traffic does not change en route to its final destination. TLS uses a combination of public/private keys and hash functions to ensure message integrity.
Mutual authentication
Exchange of identification through public-key certificates. The client and server identities are encoded in public-key certificates, which contain the following components:
Table 2. Tip
Graphic Image
You can also use secure HTTP (HTTPS) to ensure that a client's security information is not compromised as it is downloaded from a server.

Certificates

Security is controlled by digital certificates that act as electronic ID cards. The purpose of a certificate is to assure a program or a user that it is safe to allow the proposed connection and, if encryption is involved, to provide the necessary encryption/decryption keys. They are usually issued by Certificate Authorities (CAs), which are organizations that are trusted by the industry as a whole and whose business is the issuing of Internet certificates. A CA's certificate, which is also known as a root certificate, includes (among other things) the CA signature and a validity period.

Encryption and authentication are performed by means of a pair of keys, one public, one private. The public key is embedded into a certificate, known as a site or server certificate. The certificate contains several items of information, including the name of the Certificate Authority (CA) that issued the certificate, the name and public key of the server or client, the CA's signature, and the date and serial number of the certificate. The private key is created when you create a self-signed certificate or a CA certificate request and is used to decrypt messages from clients.

A TLS session is established in the following sequence:

  1. The client and the server exchange hello messages to negotiate the encryption algorithm and hashing function (for message integrity) to be used for the session.
  2. The client requests an X.509 certificate from the server to prove its identity. Optionally, the server can request a certificate from the client. Certificates are verified by checking the certificate format and the validity dates and by verifying that the certificate includes the signature of a trusted certificate authority (or is self-signed).
  3. The client randomly generates a set of keys that is used for encryption. The keys are encrypted with the server's public key and securely communicated to the server.

TLS for Z and I Emulator for Web

There are three areas where you can configure security for Z and I Emulator for Web: session security, Web server security, and configuration security.

Session security

Z and I Emulator for Web Version 1.0 uses the TLS protocol to provide security for emulator and FTP sessions.

The TLS protocol provides communications privacy across a TCP/IP network. TLS is designed to prevent eavesdropping, message tampering, or message forgery. TLS also provides a framework that allows new cryptographic algorithms to be incorporated easily. Z and I Emulator for Web supports encryption of emulation and FTP sessions and server/client authentication according to TLS Protocol Version 1.0.

Support is provided for the following:

For Z and I Emulator for Web, you can use a CA certificate, but you can also create your own self-signed certificate, as described in the Using a self-signed certificate topic in the online help.

A graphical Certificate Management utility (available on Windows and AIX platforms) is provided to:

IKEYCMD is a tool, in addition to the Certificate Management utility, that you can use to manage keys, certificates, and certificate requests. IKEYCMD is functionally similar to Certificate Management and is meant to run from the command line without a graphical interface. For more information, refer to Appendix B. Using the IKEYCMD command-line interface.

To support TLS services, Z and I Emulator for Web uses six databases:

ServerKeyStore.jks
Redirector can be configured to use Java Secure Socket Extension (JSSE) . When configured with JSSE, redirector reads the private key and certificates from ServerKeyStore.jks. Refer to "The Redirector" for more information.
CustomizedCAs.p12
The CustomizedCAs.p12 is a PKCS#12 format file that contains the root certificates of unknown CAs and self-signed certificates that are not in the WellKnownTrusted list. CustomizedCAs.p12 file is used with SSLite, where CustomizedCAs.jks is used with JSSE support. If you use a self-signed certificate or a certificate from an unknown authority (CA), you need to create or update the CustomizedCAs.p12. Z and I Emulator for Web does not install a CustomizedCAs.p12 file by default. The function of the CustomizedCAs.p12 is to make the certificates available to the client and is used during the TLS handshaking process between the client and the host.

If you create the CustomizedCAs.p12 file for the first time using the Z and I Emulator for Web Certificate Management utility (IKEYMAN), you will also want to have the older CustomizedCAs.class file in your publish directory so that older clients can still operate with the new server. Also, when you subsequently update the CustomizedCAs.p12 file, you will want to make sure these changes are picked up by the CustomizedCAs.class file. For Windows platforms, if these files are in the default publish directory, c:\Program Files\HCL\Z and I Emulator for Web\ZIEWeb, each time you open IKEYMAN to update the CustomizedCAs.p12 file and then close IKEYMAN, the CustomizedCAs.class file is automatically updated along with the CustomizedCAs.p12 file. If these files are not in the default publish directory, you need to manually run the reverse-migration tool from your publish directory using the following command. The command appears on three lines, but you should type it on one line.

..\zieweb_jre\jre\bin\java -cp ..\lib\sm.zip;
com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT
CustomizedCAs.p12 zieweb CustomizedCAs.class

On AIX, for the CustomizedCAs.class file to pick up the changes you make to the CustomizedCAs.p12 file, you need to run this reverse-migration tool manually from your publish directory using the following command. The command appears on three lines, but you should type it on one line.

../zieweb_jre/jre/bin/java -cp ../lib/sm.zip 
com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT
CustomizedCAs.p12 zieweb CustomizedCAs.class
CustomizedCAs.class

The CustomizedCAs.class is a Java class file that contains the certificates of unknown CAs and self-signed certificates that are not in the WellKnownTrusted list. If you use a self-signed certificate or a certificate from an unknown authority (CA), you need to update the CustomizedCAs.class file. However, note that you can no longer create or update the CustomizedCAs.class file using the Certificate Management utility on Windows or AIX platforms. In Z and I Emulator for Web Versions 1.0, you can only create a newer version of this file called CustomizedCAs.p12.

WellKnownTrustedCAs.class, WellKnownTrustedCAs.p12, and WellKnownTrustedCAs.jks
The WellKnownTrustedCAs.class, WellKnownTrustedCAs.p12, and WellKnownTrustedCAs.jks are the files supplied by Z and I Emulator for Web that contain the public certificates of all the CAs that Z and I Emulator for Web trusts. You should not modify these files.

WellKnownTrustedCAs.class/WellKnownTrustedCAs.p12 and WellKnownTrustedCAs.jks, CustomizedCAs.p12 and/or CustomizedCAs.class and CustomizedCAs.jks must be present in the Z and I Emulator for Web publish directory. The Z and I Emulator for Web client uses these files to trust the server's certificate during the TLS handshake.

CustomizedCAs.jks
The CustomizedCAs.jks file is different from the CustomizedCAs.p12 file, but both files have the same function. You can create a CustomizedCAs.jks file either by converting the existing CustomizedCAs.p12 to JKS format or by creating a new file in this format. You can use the Certificate Management utility that is installed with Z and I Emulator for Web or keytool.exe command-line tool, which is a Java Key and Certificate Management Tool available in the JRE for this purpose.

Basic TLS enablement for Z and I Emulator for Web clients

When you select the TLS protocol for the Z and I Emulator for Web client, a basic TLS session is established. During the TLS negotiation process, the server presents its certificate to the client. With basic TLS enablement, the certificate must be signed by an authority that the client trusts. The client checks WellKnownTrustedCAs.class/WellKnownTrustedCAs.p12 first, followed by the CustomizedCAs.p12 or the CustomizedCAs.class. If Z and I Emulator for Web is configured to use JSSE for TLS enablement, WellKnownTrustedCAs.jks and CusomizedCAs.jks files will be used. The client rejects the session if it does not find the signer in these files. If the client finds the signer in these files, the session is established. This is basic Server Authentication. Z and I Emulator for Web allows you to configure a more enhanced form of Server Authentication in its client configuration. Refer to the following section for more information.

Server authentication
Encrypting the data exchange between the client and the server does not guarantee the client is communicating with the correct server. To help avoid this danger, you can enable server authentication, so that the client, after making sure that the server's certificate can be trusted, checks whether the Internet name in the certificate matches the Internet name of the server. If they match, the TLS negotiation will continue. If not, the connection ends immediately. See server authentication in the online help for more information.
Client authentication
Client authentication is similar to server authentication except that the Telnet server requests a certificate from the client to verify that the client is who it claims to be. Not all servers support client authentication, including the Z and I Emulator for Web Redirector. To configure client authentication, you need to do the following: Refer to configuring clients to use client authentication in the online help for more information.
Express Logon
There are two types of Express Logon:
TLS-based Telnet security
Telnet-negotiated security allows the security negotiations between the client and the Telnet server to be done on the established Telnet connection. You can configure Telnet-negotiated security for Z and I Emulator for Web 3270 display and printer sessions.

The Telnet server must support TLS-based Telnet security (as described in the IETF Internet-Draft TLS-based Telnet Security) for the Z and I Emulator for Web clients to use Telnet-negotiated security. The Communications Server for z/OS supports TLS-based Telnet security.

For more information regarding Telnet-negotiated security, see the Telnet-negotiated security overview in the online help. Refer to your Telnet server's documentation for more information about configuring TLS on the Telnet server, and refer to the Security topic in the online help for more information about configuring a client to connect to a secure Telnet server.

TLS-based FTP Security
Z and I Emulator for Web provides TLS-based secure file transfer for FTP sessions. The FTP session does not support implicit/unconditional TLS negotiations to port 990/989. So, port 990 should not be used for secure FTP sessions. It only supports explicit/conditional (AUTH command) TLS negotiations to any other port.

The security properties of the FTP session are independent of the emulator session's security properties. For an integrated FTP session, you need to configure FTP security information using the new Security tab in FTP session properties. If you configure an emulator session to be secure and the File Transfer Type is set to FTP, the FTP session will not be secured automatically. In this situation, the following message appears when you click the OK button: If a secure file transfer session is desired, configure the security information in File Transfer Defaults.

The TLS based secure FTP function is supported by z/OS V1R2 or later.

Examples of when to use session security

Refer to the following examples as situations where you might want to use session security:

Web server security

You can configure your Web server to use TLS, so that the data stream from your Web server to your browser is encrypted. See your Web server documentation for more information about configuring your Web server for TLS. Once the client is loaded in a browser, however, it communicates directly with the host. You can configure Z and I Emulator for Web to provide TLS security to your host sessions. For more information, see Configuring TLS in the online help.

Configuration security

If you use the HTML model, your session configuration information will be encrypted if you use HTTPS. For all other models, you need to configure Z and I Emulator for Web to use the configuration servlet over HTTPS (after configuring your Web application server) to encrypt the session configuration instead of communicating directly with the configuration server. See Installing the configuration servlet in this guide for more information about installing the configuration servlet, and see configuring the configuration servlet in the online help for more information about configuring clients to use the configuration servlet.

The Redirector

The Redirector is a service that runs on the Z and I Emulator for Web server and that allows a Z and I Emulator for Web client to communicate with a Telnet server by connecting to a Redirector port on the Z and I Emulator for Web server.

Normally, a Z and I Emulator for Web client:

However, when the Redirector is used, the Redirector acts as an intermediary between the client and the Telnet server. The client, instead of connecting directly to the Telnet server, connects to a Redirector port on the Z and I Emulator for Web server. The Redirector then sends to the Telnet server the data received from the client. When the Telnet server replies, the Redirector sends to the client the data received from the Telnet server. This process continues until the session ends.

Why use the Redirector?

If your Telnet server does not support TLS, and if you are running the Z and I Emulator for Web server on one of the operating systems on which the Redirector supports secure sessions (see Operating systems supported by the Redirector), you can configure the Z and I Emulator for Web Redirector to provide the TLS support.

Table 4. Tip
Graphic Image
Many Telnet servers support TLS (for example, IBM Communications Servers on zSeries, IBM System i, AIX, or NT). If your Telnet server supports TLS, we strongly recommend using your Telnet server. If your Telnet server does not support TLS, the Communications Server for AIX Redirector offers a more scalable alternative to the Z and I Emulator for Web Redirector.

The Redirector acts as a transparent Telnet proxy that uses port remapping to connect the Z and I Emulator for Web server to other Telnet servers. Each defined server can configure a set of local-port numbers. Instead of connecting directly to the target Telnet server, a client connects to the server and port number. The Redirector maps the local-port number to the host-port number of the target and makes a connection.

Table 5. Recommendation
Graphic Image
The recommended solution for a Telnet proxy is to use Load Balancer, a feature of WebSphere Application Server's Edge Components, or a similar product that provides address translation as part of the overall firewall solution, instead of the Z and I Emulator for Web Redirector.

How the Redirector works

Figure 5 illustrates how the Redirector sends the client data to the Telnet server and sends to the client the responding data from the Telnet server.

Figure 5. How the Redirector works
How the Redirector works

The Redirector can be configured in any one of the following four modes:

Before you use the Client-side, Server-side, or Both modes, you need to create the ServerKeyStore.jks (if configured to use JSSE) for the Redirector.

You can use the Pass-through mode when encryption by the Redirector is not necessary, either because the data stream does not need to be encrypted, or because the data stream is already encrypted between the client and the Telnet server. you need to use the Pass-through mode if the Z and I Emulator for Web client is connecting through the Redirector to a host that requires client authentication or Express Logon.

Refer to Adding a host to the Redirector in the online help for more information.

Redirector load capacity

For Redirector load capacity recommendations, refer to the Readme.

Operating systems supported by the Redirector

The Redirector now supports:

Not every Redirector mode is supported on every operating system. The next two subsections describe Redirector support in more detail. For more information on IPv4 and IPv6 see Support for Internet Protocol Version 6.

Operating systems that support IPv4

For operating systems that support IPv4 the Redirector supports the following:

Note:
z/OS and iSeries do not support these modes.

Table 6 show this information:

Table 6. 64-bit Operating systems and Redirector modes for which the Redirector supports IPv4 using JSEE
Operating Systems Pass-through: Client-side: Host-side: Both:
Windows Yes Yes Yes Yes
AIX Yes Yes Yes Yes
Linux Yes Yes Yes Yes
All other operating systems Yes No No No

Redirector support for IPv6

Table 7 show the operating systems and the Redirector modes for which the Redirector supports Internet Protocol Version 6 (IPv6):

Table 7. 64-bit Operating systems and Redirector modes for which the Redirector supports IPv6 using JSEE
Operating system: Pass-through: Client-side: Host-side: Both:
Windows Yes Yes Yes Yes
Linux Yes Yes Yes Yes
AIX Yes Yes Yes Yes

Using Z and I Emulator for Web with a firewall

If you are configuring Z and I Emulator for Web to go through a firewall, we recommend that the firewall administrator open only those ports required for the clients to function. Telnet ports allow TLS-encrypted session traffic.

Figure 6. Session security through a firewall or proxy server
Session security through a firewall or proxy server

If you are using the configuration server-based or combined models, the Z and I Emulator for Web configuration servlet allows Z and I Emulator for Web clients to communicate with the configuration server across either HTTP or HTTPS.

Figure 7. Configuration security with and without the configuration servlet through a firewall or proxy server
Configuration security with and without the configuration servlet through a firewall or proxy server

For Z and I Emulator for Web clients connecting to a host system through open ports in the firewall, see Configuring firewall ports for details. For Z and I Emulator for Web clients connecting to a host system through a Socks or HTTP proxy server, see Connecting to a host system through a proxy server for details.

Configuring firewall ports

If you are using the configuration server-based model or the combined model, your Z and I Emulator for Web clients will need to communicate with the configuration server. To allow this through a firewall, you will need to either open the Z and I Emulator for Web Service Manager port or use the Z and I Emulator for Web configuration servlet. The Service Manager listens on port 8999 by default. You can change this default to any other available port number. For details, refer to Changing the Service Manager port in the online help. The Z and I Emulator for Web configuration servlet allows Z and I Emulator for Web clients to communicate with the configuration server across either HTTP or HTTPS. Therefore, the Service Manager port does not need to be open on the firewall. (See Figure 4.) Refer to Installing the configuration servlet and Configuring the configuration servlet in the online help for details on using the configuration servlet.

If you are using the HTML-based model, there is no requirement for Z and I Emulator for Web clients to access the configuration server, and the Service Manager port does not need to be open on the firewall. The clients will still attempt to contact the configuration server for license counting but will fail silently if the Service Manager port is not open.

In addition to the Service Manager port, make sure the firewall administrator opens any ports that are being used for functions your clients use. For example, if you have a TLS session with the Redirector on port 5000, port 5000 must be open for Telnet traffic. The following table summarizes the ports that Z and I Emulator for Web can use.

Table 8. Z and I Emulator for Web functions and the ports they use
Z and I Emulator for Web Function Ports Used
Display emulation (3270 and VT) and 3270 Printer emulation 23 (Telnet), 80 (HTTP), or 443 (TLS) and 8999 (config server)3
5250 Display and Printer emulation 23 (Telnet) or 992 1 (TLS) or 80 (HTTP) or 443 (TLS) and 8999 (config server) 3
3270 file transfer 23 (Telnet), 80 (HTTP), or 443 (TLS) and 8999 (config server)3
5250 file transfer - savfile 80 (HTTP), 8999 (config server)3, 21 (FTP)4, >1024 (FTP)4, 446 (drda)4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, 8475 (as-rmtcmd)1 4, and 8476 (as-signon)1 4
5250 file transfer - database 80 (HTTP), 8999 (config server)3, 446 (drda)4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, 8475 (as-rmtcmd)1 4, and 8476 (as-signon)1 4
5250 file transfer - stream file 80 (HTTP), 8999 (config server)1 2 4, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8473 (as-file)1 4, and 8476 (as-signon)1 4
FTP 21 (FTP), 80 (HTTP), 8999 (config server)1 2 4, and >1024 (FTP)5
CICS 2006
Database On-Demand 80 (HTTP), 8999 (config server)3, 449 (as-svrmap)4, 8470 (as-central)1 2 4, 8471 (as-database)1 4, and 8476 (as-signon)1 4
Z and I Emulator for Web clients 23 (Telnet), 80 (HTTP), and 8999 (config server)3
Administration clients 80 (HTTP) and 8999 (config server)3
SSH (the Secure Shell) 22

Table 9. Notes
Notes:
1 You can change the port numbers with the command WRKSRVTBLE . The port numbers listed are the default values.
2 The port for as-central is used only if a codepage conversion table needs to be created dynamically (EBCDIC to/from Unicode). This is dependant on the JVM and the locale of the client.
3 You can change the config server port. Port 8999 is the default.
4 These ports do not need to be opened on the firewall if you are using IBM System i proxy server support. You will need to open the default proxy server port 3470. You can change this port.
5 In passive (PASV) mode, the FTP client initiates both connections to the server, solving the problem of firewalls filtering the incoming data port connection to the client from the server. When opening a FTP connection, the client opens two random unprivileged ports locally (N>1024 and N+1). The first port contacts the server on port 21, but instead of then issuing a PORT command and allowing the server to connect back to its data port, the client issues the PASV command. As a result, the server then opens a random unprivileged port (P>1024) and sends the PORT P command back to the client. The client then initiates the connection from port N+1 to port P on the server to transfer data.

From the server-side firewall's standpoint, to support passive mode FTP, you need to open the following communications ports:

  • Port 21 of the FTP server from anywhere (client initiates connection)
  • Port 21 of the FTP to remote ports >1024 (server responds to client's control port)
  • Ports of the FTP server >1024 from anywhere (client initiates data connection to random port specified by server)
  • Port of the FTP server >1024 to remote ports >1024 (server sends ACKs (and data) to client's data port)

If you do not want to open port 8999 on the firewall, you can still allow users to access Z and I Emulator for Web. There are two options:

Connecting to a host system through a proxy server

Z and I Emulator for Web clients can use a proxy server to transparently access host systems from behind a firewall. Two types of proxy servers are supported:

Before you can connect to a host system through a proxy server, you need to find out which protocol the proxy server supports. Decide whether you want to specify the proxy server settings through the Web browser or explicitly identify a proxy server for the session. If you decide to explicitly identify a proxy server, you need to specify the protocol that the proxy server uses, the proxy server name and port number, and other information.

In general, if a Socks proxy server is available, configure Z and I Emulator for Web sessions to use it. Configure sessions to use an HTTP proxy server if that is the only type of proxy server supported at your site.

Connecting through a Socks proxy server

Many organizations use Socks proxy servers to protect computing resources behind a firewall. Socks is a protocol for TCP/IP-based network proxies. It allows applications on one side of a Socks proxy server to gain full access to hosts on the other side of the Socks proxy server without directly connecting to them. Proxy servers are generally used in conjunction with firewalls. Under the Socks protocol, a client that requests a connection to a host system through a firewall actually connects to a Socks proxy server. The Socks proxy server acts as an intermediary between the client and the host system. It authorizes communication requests, connects to the host on behalf of the client, and relays data between the two systems.

Z and I Emulator for Web supports both version 4 and version 5 of the Socks protocol.

The Java Virtual Machine (JVM) used in most Web browsers supports Socks version 4. A session can access either a Socks version 4 or version 5 proxy server, bypassing the proxy server settings in the Web browser. You can also have the session negotiate a Socks version 4 connection if the proxy server does not support version 5. For more information on Socks proxy server settings, refer to Proxy Server in the online help.

Connecting through an HTTP proxy server

HTTP proxy servers handle HTTP requests through firewalls. They act as intermediaries between private local networks and the Internet. The HTTP proxy server is connected to both the local network and the Internet. Local users configure their browsers to pass HTTP requests through the HTTP proxy server by specifying the proxy server's IP address and TCP port number. The HTTP proxy server accepts these HTTP requests and forwards them to the actual Web servers specified by the URLs entered in the browser.

For Z and I Emulator for Web clients, HTTP proxy servers act as forwarding agents for connections to a host system. The HTTP proxy server opens a connection to the host system and sends data back and forth between the host system and the client. Although an HTTP proxy server usually closes a connection after servicing an HTTP request, Z and I Emulator for Web keeps the connection open for host traffic by using the HTTP Connect method (if it is enabled for the proxy server).

To have a session use a HTTP proxy server, you need to select HTTP proxy as the proxy type and specify the proxy server name and port number. For more information on HTTP proxy server settings, refer to Proxy Server in the online help.

User ID security

Web Express Logon

If you have a network security application in place and you are using the configuration server-based model, you can select Web Express Logon in the Deployment Wizard to allow users to access hosts and host-based applications without providing an additional user ID and password. Entering the full URL of the Credential Mapper Server tells Z and I Emulator for Web where to locate the Credential Mapper Servlet, which processes the HTTPS request from the user, performs a lookup, and returns the user's credentials. The credentials are then used to perform a secure, automated Z and I Emulator for Web login.

Native Authentication

If you use the configuration server-based model, you can configure your Z and I Emulator for Web users to be natively authenticated. This option allows users to log on to Z and I Emulator for Web using the same password as they would to log on to the operating system (AIX or z/OS) where Z and I Emulator for Web is active. When a user logs on to Z and I Emulator for Web, their password is validated against the operating system password, rather than a separate Z and I Emulator for Web password. This gives the administrator a single point of control for password administration and the user a single password to remember.

Refer to Native Authentication in the online help for more information on enabling this option.

Windows Domain logon

If your users are logged on to a Windows domain, this option (available with the configuration server-based model in the Deployment Wizard) automatically logs users on to Z and I Emulator for Web using their Windows user name. The Z and I Emulator for Web logon window does not appear and the Windows user name is used as the Z and I Emulator for Web user ID. If a Z and I Emulator for Web user ID does not already exist (matching the Windows user name), you can also choose to have a user ID automatically created in the specified Z and I Emulator for Web group.

Refer to Logon Type in the online help for more information about choosing how users access the Z and I Emulator for Web configuration server.

FIPS environments

If you are in an environment that mandates or requires that your security components use Federal Information Processing Standards (FIPS)-certified components/modules, consider the following. For secure Telnet and FTP connections, Z and I Emulator for Web uses FIPS-compliant modules by default. If your environment requires the connection to an IBM System i host for file transfer or data transfer, ensure that your system meets the following requirements:

When you have a secure connection to an IBM System i host and are accessing the file transfer capabilities, you will be asked to enter the path and the password for the JSSE Trust Store. If you are performing data transfer to an IBM System i host, you will also see additional fields for entering the path and password for the JSSE Trust Store.

Another way to enter the path and password is to use a Run Applet that is provided with Z and I Emulator for Web. To do this, take the following steps:

  1. From the menu of a display session, select Actions > Run Applet.
  2. Enter com.ibm.eNetwork.HOD.util.jsse.JSSESetup in the field for the class name.
  3. Click OK.

You only need to configure the JSSE Trust Store oncec. It is a global setting that applies to all sessions. After you have entered the values, they persist until the browser is restarted.

The current version of Z and I Emulator for Web provides a menu option to enable or disable the FIPS mode for each session. By default, FIPS mode is enabled for all the sessions.

Planning for national language support

Z and I Emulator for Web is provided in multiple languages. The session windows, configuration panels, help files, and the documentation have been translated. In addition, display, keyboard, and processing support are provided in Arabic, Hebrew, Thai, and Hindi. This support is fully explained in the online help.

All the translated versions are provided in the download. When you install Z and I Emulator for Web on i/OS, OS/400, Windows, AIX, Linux, and Solaris using the graphical installation program, you can choose which languages to install. On z/OS, you can choose the language via console mode.

Graphic Image
National language support is operating-system dependent, so the appropriate font and keyboard support for the language you want to use must be installed in the operating system. For example, if you want to use Korean as the host-session language but do not have the Korean font and keyboard support installed, you may not be able to display the correct characters.
Graphic Image
DBCS cannot be used as the HTML file name.

Supported languages

The languages into which Z and I Emulator for Web has been translated are listed below, along with the language suffixes you can use to load translated versions of the Z and I Emulator for Web clients. For example, HTML pages have language extensions to identify different language installations and different language predefined HTML files, such as ZIEWeb_en.html for English.

Language Language suffix
Simplified Chinese zh
Traditional Chinese zh_TW
Czech cs
Danish da
Dutch nl
English en
Finnish fi
French fr
German de
Greek el
Hungarian hu
Italian it
Japanese ja
Korean ko
Norwegian no
Polish pl
Brazilian Portuguese pt
Portuguese pt_PT
Russian ru
Slovenian sl
Spanish es
Swedish sv
Turkish tr
Catalan Ca

Supported host code pages

Z and I Emulator for Web supports multiple code pages. You can specify these code pages on a session-by-session basis.

3270 and 5250 code pages

The code pages specified below are supported by the 3270 and 5250 emulators. You can select them in the Session Configuration window.

Country or region Code page Note
Arabic Speaking 420
Austria 273
Austria (Euro) 1141
Belarus 1025
Belarus (Euro) 1154
Belgium 037
Belgium (Euro) 1140
Belgium (Old Code) 274
Bosnia/Herzegovina 870
Bosnia/Herzegovina (Euro) 1153
Brazil 037
Brazil (Euro) 1140
Brazil (Old) 275
Bulgaria 1025
Bulgaria (Euro) 1154
Canada 037
Canada (Euro) 1140
China (Simplified Chinese Extended) 1388
Croatia 870
Croatia (Euro) 1153
Czech Republic 870
Czech Republic (Euro) 1153
Denmark 277
Denmark (Euro) 1142
Estonia 1122
Estonia (Euro) 1157
Finland 278
Finland (Euro) 1143
France 297
France (Euro) 1147
FYR Macedonia 1025
FYR Macedonia (Euro) 1154
Germany 273
Germany (Euro) 1141
Greece 875
Hebrew (New Code) 424
Hebrew (Old Code) 803
Hindi 1137 5250 display only
Hungary 870
Hungary (Euro) 1153
Iceland 871
Iceland (Euro) 1149
Italy 280
Italy (Euro) 1144
Japan (Katakana) 930
Japan (Katakana Extended) 930
Japanese (Katakana Unicode Extended;JIS2004) 1390 3270 only
Japan (Latin Extended) 939
1399 Japanese (Latin Unicode Extended;JIS2004) 1399
Kazakhstan (Euro) 1166
Korea (Euro) 1364 3270 only
Korea (Extended) 933
Latin America 284
Latin America (Euro) 1145
Latvia 1112
Latvia (Euro) 1156
Lithuania 1112
Lithuania (Euro) 1156
Multilingual 500
Multilingual ISO (Euro) 924
Multilingual (Euro) 1148
Netherlands 037
Netherlands (Euro) 1140
Norway 277
Norway (Euro) 1142
Open Edition 1047
Poland 870
Poland (Euro) 1153
Portugal 037
Portugal (Euro) 1140
Romania 870
Romania (Euro) 1153
Russia 1025
Russia (Euro) 1154
Serbia/Montenegro (Cyrillic) 1025
Serbia/Montenegro (Cyrillic; Euro) 1154
Slovakia 870
Slovakia (Euro) 1153
Slovenia 870
Slovenia (Euro) 1153
Spain 284
Spain (Euro) 1145
Sweden 278
Sweden (Euro) 1143
Taiwan (Traditional Chinese Extended) 937
Taiwan (Traditional Chinese Extended; Euro) 1371
Thai 838
Thai (Euro) 1160
Turkey 1026
Turkey (Euro) 1155
Ukraine 1123
Ukraine (Euro) 1158
United Kingdom 285
United Kingdom (Euro) 1146
United States 037
United States (Euro) 1140

Notes:

VT code pages

Language Code page
Arabic ASMO 708 and ASMO 449
British 1101
DEC Greek
DEC Hebrew
DEC Multinational Replacement Character Set 1100
DEC Technical
Dutch 1102
Finnish 1103
French 1104
French Canadian 1020
German 1011
Hebrew NRCS
ISO Greek Supplemental (ISO Latin-7) 813
ISO Hebrew Supplemental
ISO Latin-1 819
Italian 1012
Norwegian/Danish 1105
PC Danish/Norwegian 865
PC International 437
PC Multilingual 850
PC Portugese 860
PRC GBK 936
PC Spanish 220
Spanish 1023
Swedish 1106
Swiss 1021
United States 1100

CICS Gateway code pages

Code page Character set
000 Auto Detect (default)
437 Latin-1
813 ISO Greek (8859_7)
819 ISO Latin 1 (8859_1)
850 Latin 1
852 Latin 2
855 Cyrillic
856 Hebrew
857 Latin 5
864 Arabic
866 Cyrillic
869 Greek
874 Thai
912 ISO Latin 2 (8859_2)
915 ISO Cyrillic (8859_5)
920 ISO Latin 5 (8859_9)

Japanese JIS2004 Unicode support

The JIS2004 support can now be enabled by selecting the existing host code pages 1390 Japanese (Katakana Unicode Extended) and 1399 Japanese (Latin Unicode Extended). The following features are supported:

Functions not included due to Unicode formats not currently supported in ZIEWeb:

User-defined character mapping

For double-byte character set (DBCS) languages, you can use customized user-defined character (UDC) mapping in your session (3270, 5250, 3270 host print) instead of the default mapping. You can create a UDC translation table using the UDC mapping editor to store customized mapping for your session. For instructions for how to use the UDC mapping editor to change your character mapping, see Using the user-defined character (UDC) mapping editor in the online help.

Unicode Support for i/OS and OS/400

See Unicode Support for i/OS and OS/400.

Installing, upgrading, and uninstalling Z and I Emulator for Web

Installing the Z and I Emulator for Web server and related software

This chapter discusses installing the following three Z and I Emulator for Web components:

Installing Z and I Emulator for Web using Installation Manager

You need the IBM Installation Manager to install Z and I Emulator for Web. IBM Installation Manager needs to be installed first in Administrator Mode on the system where Z and I Emulator for Web is planned to install. Then you can use the Installation Manager to install the Z and I Emulator for Web.

IBM Installation Manager Version 1.8.3 or higher is required to install Z and I Emulator for Web.

Important links

Refer to the instructions from the Installing or Updating Installation Manager for installing the Installation Manager. For more information about IBM Installation Manager, refer to the IBM Installation Manager Knowledge Center.

Before the ZIEWeb Installation

Preparing to Install

Ensure the machine on which the installation takes place meets all prerequisites.

The software requirements for Z and I Emulator for Web can be found in the Software Products Compatibility Reports. Check the list below for the preparation:

Installing Z and I Emulator for Web

You can install Z and I Emulator for Web using the IBM Installation Manager on all the supported platforms. Using the Installation Manager (IM), you can install in using the IM GUI, command mode or Console Mode. Most platforms support the Installation Manager GUI except z/OS. To install on z/OS, you can use Console Mode or running BPXBATCH jobs.

Using the Installation Manager GUI to install

Installation Manager GUI:

  1. Start Installation Manager according to instructions for the platform.
  2. Select File > Preferences.
  3. Select Repositories on the left. This option shows the available repositories that have been added to Installation Manager.
  4. Select Add Repository if Z and I Emulator for Web is not listed.
  5. Click Browse and navigate to the location of the extracted Z and I Emulator for Web path. Select the diskTag.inf file present in the disk1 folder for the initial install.
  6. Click OK and the new repository location should be listed.
  7. Click Test Connections to ensure that the Repository URL is available.
  8. From the start page of the Installation Manager, click Install. The Installation Manager searches the defined repositories for available packages.
  9. Select the Z and I Emulator for Web package. Click Next.
  10. Read the license agreements. If you agree to the terms of the license agreement, click I accept the terms of the license agreement, and click Next to continue.
  11. Select Create a new package group and choose the Architecture.
  12. If operating system is 64-bit, you need to select 64-bit or 32-bit to install the product in the corresponding bit mode.
  13. Click Next.
  14. Select the languages you want to install. The default is English. Click Next.
  15. Select the Z and I Emulator for Web 1.0 feature. Click Next.
  16. Review and specify all information under the Z and I Emulator for Web 1.0 tab.
    1. On the Publish Information panel under Z and I Emulator for Web 1.0,set the Publish directory, specify the web-server alias and the Service Manager Port number. Click Next.

      The publish directory must be available to clients. You can designate the path of the publish directory. Perform the following steps:

      1. Specify an alias for the directory, default is zieweb.
      2. Specify the Service Manager port, through which Z and I Emulator for Web clients communicate with the Service Manager. This communication is necessary for the following deployment options:
        • Using the configuration server to maintain session configuration information as in the configuration server-based and combined deployment models, described in Planning for deployment.
        • HCL recommends designating port 8999 for these purposes. Check your server documentation to see if this port is being used. If it is in use, you can change the port during the installation or later. For more information about changing the Service Manager port, see Changing the Service Manager's configuration port in the online help.
    2. On Web server panel under Z and I Emulator for Web 1.0, select the web-server option that is appropriate for your requirement:
      • Select No Web Server when web server is configured manually by the user. This is recommended for web servers like IPlanet and Lotus Domino. The user is advised to contact their web server administrator or refer to the web server documentation for details.
      • Select the option 'Select from list of detected web server' and then select the web-server from the list if more than one detected.
      • Select the option Manually select specific web server, in case a IBM HTTP Server or Apache web-server is installed but not detected.
        • Select the type of web server that is installed on your system.
        • Click on the Browse button and navigate to the configuration file (httpd.conf) for the web server installed in your system. You can alternatively type into the field the complete path of the httpd.conf file in the web server installation directory.
    3. On the Application server panel under Z and I Emulator for Web, if the installation program detects IBM WebSphere Application Server on your system, you can configure the Configuration Servlet. The next panel from Application Server tab asks if you want to configure the ZIEWeb Configuration Servlet in WebSphere Application Server. See Installing the configuration servlet for more information.

      Uncheck the check box if you do not plan to use Configuration Servlet.

      If you plan to use Configuration Servlet, select the application server from the list detected. The installation program automatically deploys the configuration servlet on the Web application server you designate, and it configures your clients to access the Service Manager through the servlet.

      Note:
      • The Websphere application server is detected if it is installed by the same IBM Installation Manager program on the system. The versions that can be detected are Websphere Application Server V8.0 and V8.5.2.
      • An Application Server with administrative security enabled is not supported for servlet configuration during the installation.
    4. Once the panels are appropriately updated, click Next.
  17. Review the summary information, and click Install.
  18. Once the installation completes, a summary page is displayed. Review the messages.
  19. To ensure the install is completed successfully, you can take the following additional actions:
    1. Restart the web server.
    2. Ensure that ZIEWeb pages are accessible over the browser. If not, check the web server configuration and ensure that files in the Z and I Emulator for Web publish directory are accessible. Refer to your web server documentation for the configuring details.

Deployment Wizard

The Deployment Wizard is automatically installed as part of the Windows Z and I Emulator for Web server installation. It is also available separately for those customers who do not wish to install the entire Windows Z and I Emulator for Web server.

For z/OS and iSeries, the Deployment Wizard install package can be found on the ZIE server in the <install directory>/ZIEWeb/depwiz directory called DW.zip. This file can be downloaded to a Windows workstation and installed as a separate package.

Installing the Deployment Wizard

On Windows platforms, the Deployment Wizard is installed automatically when Z and I Emulator for Web is installed.

To install and run the Deployment Wizard, perform the following tasks:

  1. Open Installation Manager.
  2. Add the Z and I Emulator for Web repository location to the Installation Manager:
    1. On the Start page of Installation Manager, click File > Preferences, and then click Repositories. The Repositories page opens, showing any available repositories, locations and connection status of them.
    2. On the Repositories page, click Add Repository.
    3. In the Add Repository dialog box, click Browse.
    4. Navigate to the location of Z and I Emulator for Web disk 1 and select the diskTag.inf file, and then click OK. The new repository location is listed.
    5. Click Test Connections to ensure that the Repository URL is available.
    6. From the Start page, click Install. The Installation Manager searches the defined repositories for available packages.
    7. Repeat the above steps for the 2nd disk. If you proceed without configuring the second disk, Installation Manager confirms with user for it during the installation process.
  3. Select the Z and I Emulator for Web Deployment Wizard package.
  4. Ensure that Version 1.0 is also selected under it. Click Next.
  5. On the Install Packages panel, select Create a new package and HCL Z and I Emulator for Web Deployment Wizard as the Package group name.
  6. In case the Architecture selection is set to 64-bit, change the selection to 32-bit if necessary. Click Next.
  7. On the Install Packages panel, select the feature Z and I Emulator for Web Deployment Wizard 14.0. The disk information in the lower area of the panel gives information about the available disk space and required disk space. Click Next.
  8. Select the tab for Deployment Wizard Z and I Emulator for Web Wizard Location panel under the heading Z and I Emulator for Web Wizard 1.0 in the left tab. The Z and I Emulator for Web server location indicates the link to the Z and I Emulator for Web server. Ensure that a valid and working link to the ZIE server is entered in the field. Click Next.
  9. In the summary panel, review the selected packages and installation selections. Click Install to proceed with installation.

Downloading the Deployment Wizard installation image from a Z and I Emulator for Web server

The Deployment Wizard image is shipped on all Z and I Emulator for Web server platforms, and it can be downloaded from the server and installed on any Windows machine.

There are two ways to download the Deployment Wizard from a Z and I Emulator for Web server, access via dashboard_xx.html page, where xx is your two-letter language suffix or ftp directly from the server. Downloading via dashboard_xx.html downloads through the web server. Here are the steps:

  1. From your Windows machine, start your browser and point to the dashboard_xx.html file on your Z and I Emulator for Web server, where xx is your two letter language suffix.
  2. Click the Administrators tab 3.
  3. Click the Deployment Wizard link to download the Deployment Wizard installation image to your Windows machine.
  4. Run the Installation Manager to install the Deployment Wizard.
  5. Once the installation is complete, you can start the Deployment Wizard from the Start > Programs desktop menu.

To download via ftp, follow these steps:

  1. From your Windows machine, ftp to your ZIE server machine.
  2. When prompted, log into the server.
  3. Enter bin to set the mode to binary.
  4. Enter cd to the directory the Deployment Wizard file exist. The location will be <install-directory>/ZIEWeb/depwiz.
  5. Enter get DW.zip to get the file.
  6. Extract the zip file on the Windows machine.
  7. Run the Installation Manager to install the Deployment Wizard.
  8. Start the Deployment Wizard from the Start > Programs desktop menu.

Host Access Toolkit

The Host Access Toolkit is installed separately for those customers who want to write their own Z and I Emulator for Web application.

Installing the Host Access Toolkit

Perform the following basic steps to install the Host Access Toolkit on a Windows system:

  1. Open Installation Manager.
  2. Add the Z and I Emulator for Web repository location to the Installation Manager.
    1. On the Start page of Installation Manager, click File > Preferences, and then click Repositories. The Repositories page opens, showing any available repositories, the locations and connection status of them.
    2. On the Repositories page, click Add Repository.
    3. In the Add Repository dialog box, click Browse. Navigate to the location of your Z and I Emulator for Web disk1 and select the diskTag.inf file. Then click OK. The new repository location is listed.
    4. Click Test Connections to ensure that the Repository URL is available.
    5. From the Start page, click Install. The Installation Manager searches its defined repositories for available packages.
    6. Repeat the above steps for the 2nd disk. If you proceed without configuring the second disk, Installation Manager confirms with you for it during the installation process.
  3. Select the Host Access Toolkit package.
  4. Ensure that Version 1.0 is also selected under it. Click Next.
  5. On the Install Packages panel, select Create a new package and select HCL ZIE Host Access Toolkit as the package group name.
  6. In case the Architecture selection is set to 64-bit, change the selection to 32-bit because it is the recommended. Click Next.
  7. Select the languages you want to install. The default is English. Click Next.
  8. On the Install Packages panel, select the feature Host Access Toolkit 1.0 . The disk information in the lower area of the panel gives information about the available disk space and required disk space. Click Next.
  9. Select the tab for Host Access Toolkit 1.0 panel under the heading Host Access Toolkit 1.0 in the left tab.
  10. In the summary panel, review the selected packages and installation selections. Click Install to proceed with the installation.

Installing in the Console Mode

This chapter contains instructions of using Installation Manager console mode to install Z and I Emulator for Web on platforms that do not support a Graphical User Interface.

Note:
if you are installing for IBM iSeries, you are suggested reading Before installing ZIEWeb on IBM iSeries.

About installing in the Console Mode

Linux, UNIX, and z/OS systems that do not support a graphical user interface (GUI), administrators can use the console-based interface of Installation Manager to install Z and I Emulator for Web.

Using console mode of IBM Installation Manager, you can work on the installation packages to complete the following tasks:

To start Installation Manager console mode, use the imcl utility available in the Installation Manager tools directory.

These installation steps cover a typical installation scenario by using console mode. During the installation session, console mode prompts are displayed specific to the package being installed. You can follow the options as they appear on the console screen to proceed with the installation.

The Installation Manager console mode interface uses these conventions:

The Installation Manager can be installed using the information given in the Installation Manager documentation Installing or updating Installation Manager.

In order to install Z and I Emulator for Web, the Installation Manager must be installed in Administrator mode. For more information about downloading Installation Manager see System Requirements for IBM Installation Manager and Packaging Utility, minimum level is 1.8.3 in order to install Z and I Emulator for Web.

For more information about using Installation Manager, refer to the IBM Installation Manager Knowledge Center.

Before installing ZIEWeb on IBM iSeries

Installation of Z and I Emulator for Web on IBM iSeries platforms is supported through the console mode of Installation Manager. The GUI mode of installation is not available on IBM iSeries.

Additional notes before Z and I Emulator for Web installation on IBM iSeries are listed below:

To begin the installation, you need to perform the following tasks:

  1. Copy the Z and I Emulator for Web ESD zip files to the IBM i from FTP (File Transfer Protocol) or by any regular means and Extract the zip file.
  2. Open the Installation Manager and configure a repository by providing the complete path to the diskTag.inf file that is in the Z and I Emulator for Web disk.
  3. Proceed with the remaining steps, as provided in the console mode installation.

Installation procedure

To install ZIEWeb in the Console Mode, perform the following tasks:

  1. Start IBM Installation Manager in console mode. Open a command prompt with administrator's privileges and change to the tools folder within the IBM Installation Manager Installation directory.
  2. Run the following command in the tools directory
    imcl -c
    .

    On different operating systems, for example:

  3. In the console window, specify the HCL Z and I Emulator for Web repository:
    1. Type P, and then press Enter to edit preferences.
    2. Type 1, and then press Enter to specify repositories.
    3. Type D, and then press Enter to add a repository.
    4. Type the repository path for HCL Z and I Emulator for Web 1.0. For example, <path>\ZIEWeb\disk1\diskTag.inf.
    5. Type A, then press Enter to save the repository information.
    6. Type R, and then type press Enter to return to the main menu.
  4. Select 1 to install from the main menu. If you have repositories that require credentials, you are informed to enter your ID and then password. You can also save the credentials when you are asked. See Saving credentials in console mode in the Installation Manager Knowledge Center.
  5. On the panel to select packages to install, type the appropriate number to select the Z and I Emulator for Web 1.0 package.
  6. On the subsequent panel type the appropriate number to choose Version 1.0 for installation and type press Enter.
  7. Enter N to proceed.
  8. Review the license agreement by typing the appropriate number to view license information. To accept the license agreement, type A, and then click Enter. Type N and press Enter to proceed.
  9. Select the Installation Manager Shared Resources Directory. Refer to Overview of package groups and the shared resources directory for further information. To change the directory, enter M, and then Enter. Enter the correct path, then type N to proceed.
  10. The Location panel allows you to specify the location of the HCL Z and I Emulator for Web 1.0 installation directory. Type M to change location of the installation directory. Enter the correct path, and enter N to proceed.
  11. The architecture of the package shows when installing on a 64-bit operating system. For new package groups, you can change the bit mode by entering T: Change to bit-architecture. For example, if the Selected Architecture is displayed as 64-bit and option T is displayed to Change to 32-bit architecture, type T to change to 32-bit architecture.
  12. To accept the default values or to continue after entering a different value, type N to proceed.
  13. On the language panel, enter the number to the left of the language to add or remove the language from the list of languages for installation. You can select only one language at a time or S to select all languages. English is selected by default and it is mandatory. Your language choices apply to all packages installed in the package group. Type N to proceed.
  14. The next panel displays the Configurations menu, for the configuration details required by Z and I Emulator for Web installation:

    Typically, the Z and I Emulator for Web configuration menu has the following entries:

    • Publish Information
    • Web server
    1. Enter the appropriate number to the left of Publish Information entry to review the settings. The Publish Information panel displays the following information:
      • Publish Destination Directory is the location where the Z and I Emulator for Web files that users access from the web are installed. A default value is shown in the panel. Type 1 to change the location if needed.
      • Z and I Emulator for Web Publish Alias is the web-server alias setting for the Z and I Emulator for Web publish directory. Type A to change the location if needed.
      • Service manager port is the port number on which the Z and I Emulator for Web service manager listens. Specify Service Manager port, through which Z and I Emulator for Web clients communicate with the Service Manager. This communication is necessary for the following deployment options:
        • Using the configuration server to maintain session configuration information (as in the configuration server-based and combined deployment models, described in Planning for deployment).

        Port 8999 is the default port for Z and I Emulator for Web. Check with your system administrator to see if this port is occupied. If it is in use, you can change the port during the installation or later. For more information about changing the Service Manager port, see Changing the Service Manager's configuration port in the online help.

        Enter the number associated with any of these options to change the respective settings. Refer to the remaining options on the screen to navigate.

    2. Enter the appropriate number to the left of Web server to review its settings.
      1. The web server panel displays the following options. You need to select the web-server option that is appropriate for your requirement:
        • No Web Server: Select it when you configure the web server manually or when there is no web server. This is recommended for web servers like IPlanet, Lotus Domino. Contact your web server administrator or refer the web-server documentation for details.
          Note:
          Select No Web Server for z/OS installations because the web server cannot be detected and must be configured manually.
        • Select from list of detected web servers: To select a detected web server, select this option and then select the web server that has been detected.
        • Manually select specific web server: Select this option when an IBM HTTP Server 8.5 or Apache web server 2.2 is installed but not detected. You need to enter the complete path to the httpd.conf file in the web server installation directory.
      2. Enter the number associated with the required option to change the respective settings. Refer to the options on the screen to navigate. Enter N to proceed.
    3. If the installation program detects IBM WebSphere Application Server on your system, the next panel accessed using Application Server tab asks if you want to configure the Z and I Emulator for Web configuration servlet in WebSphere Application Server. If users run Z and I Emulator for Web through a firewall, this eliminates the need to open an extra port for client communications with the Z and I Emulator for Web Service Manager. See Installing the configuration servlet for more information.
      • If you type number or alphabet that appears to the left of the question, IBM Installation Manager displays a list of the versions of the application servers, their profiles and servers detected, prompting users to choose from them. The installation program automatically deploys the configuration servlet on the Web application server you designate, and it configures your clients to access the Service Manager through that servlet.
      • If you proceed without choosing to configure the servlet, the install does not configure the configuration servlet. Clients can access the Service Manager directly on port 8999 (or an alternative port you had specified).
      Note:
      • The Websphere application server is detected if it has been installed by the same IBM Installation Manager program on the system. The versions that can be detected are Websphere Application Server V8.0 and Websphere Application Server V8.5.
      • A server with administrative security enabled is not supported for servlet configuration during the installation.
  15. The next panel is the summary panel. Review your selections before continuing with the installation.
  16. To generate a response file, enter G: to generate an installation response file.
  17. Enter the name of the response file and use .xml as the file extension. Response files are XML files.
  18. Include a directory location when you enter the response file name to save the file to a different location.
  19. Enter I to start the installation.
  20. When the installation completes, enter F: to finish.
  21. Enter X to exit Installation Manager.

Installing Deployment wizard in Console mode

The Deployment Wizard is automatically installed as part of the Windows Z and I Emulator for Web server installation. It is also available separately for those customers who do not wish to install the entire Windows Z and I Emulator for Web server. Users can select only Deployment Wizard Option during Installation.

Refer to Installing in the Console Mode for more details.

Installing Host Access Toolkit in console mode

The Host Access Toolkit is automatically installed as part of the Windows Z and I Emulator for Web server installation. It is also available separately for those customers who do not wish to install the entire Windows Z and I Emulator for Web server. Users can select only Host Access Toolkit option during Installation.

Refer to Installing in the Console Mode for more details.

Installing in Silent Mode

Installing Z and I Emulator for Web in silent mode enables you to use a script for the installation. You need to create a response file first before starting the Installation Manager using the response file.

For information about installing packages silently using Installation Manager version V1.8.3, refer to the following topics in the Installation Manager Information Center:

Installation procedure

This section contains instructions of installing ZIEWeb in Silent Mode.

Perform the following tasks to install ZIEWeb in Silent Mode:

  1. To create a response file, record a response file using the IBM Installation Manager in wizard mode on a machine where GUI is available with the -record option. For more details, see Record a response file with Installation Manager. For example, on Windows the record of a response file displays like this:
    C:\Program Files (x86)\HCL\Installation Manager\eclipse>IBMIM.exe -record e:\recordResponse.xml 
  2. If needed, open the generated XML file in to view and edit preferences. For details on the file, refer to Installation Manager silent response file commands.
  3. To perform silent installation using the generated response file, use the imcl command-line utility provided by IBM Installation Manager. Examples on different operating systems are listed below:
    • Windows:
      imcl.exe input response_file -log log_file
    • Linux, UNIX, IBM i, IBM z/OS®, and OS X
    ./imcl input response_file -log log_file
    For more details, see Installing a package silently by using a response file.
Note:
  • It is recommended to avoid using the -skipInstall parameter when recording a response file for Z and I Emulator for Web installation.
  • If a web server, an application server, or both are configured by Z and I Emulator for Web during the silent installation, you need to record the response file in a similar software setup so that the user preferences and software parameters are recorded in the response file accordingly. For example, if HTTP Server V8.5 is going to be configured, it is recommended that the following parameters match for better results:
    • The HTTP server version
    • The HTTP server installation location path
    • The httpd.conf file location path in the HTTP server

    Similarly, for silent installation in an environment where Websphere Application Server is located, record the response file on a system where a similar Websphere Application Server setup is available.

    If a response file recorded in an environment where Websphere Application Server is not installed, it is recommended to be used in environments where Websphere Application Server is not installed.

  • It is recommended and helpful to maintain separate response files for different deployment scenarios.
  • You need to record the response file on the same operating system platform that Z and I Emulator for Web is to be installed on. For example, for silent installation on linux, record the response file on Linux. It is useful to maintain separate response files for different operating systems.
  • The pre-requisites for the console or the GUI mode of the installation (as applicable) are relevant in silent install mode as well. These include (but not limited to) the following :
    • The logged in user must have the administrator privileges.
    • The Installation Manager must have been installed in Administrator mode.
    • Installation Manager V1.8.3 or higher is installed to install Z and I Emulator for Web. In case where administrative security is enabled on Websphere Application Server, configuration of the Z and I Emulator for Web Configuration Servlet is not supported during installation. You need to configure it manually.

Installing the configuration servlet

During the Z and I Emulator for Web installation, you can choose to have the configuration servlet installed and configured on i/OS, OS/400, Windows, AIX, Linux, and Solaris for IBM Application Server.

Graphic Image
All Web servers and servlet engines are configured differently. Check your Web server and servlet engine documentation for servlet configuration details on your operating system.

Installing the configuration servlet is necessary only if both of the following statements are true for your Z and I Emulator for Web deployment:

By default, the Z and I Emulator for Web clients use port 8999 to access configuration information from the Service Manager. If any of your clients are outside the firewall, the firewall administrator needs to open port 8999 both internally and externally. However, you can avoid opening this port by customizing your clients to use the configuration servlet to access configuration information.

Deploying the servlet on WebSphere Application Server

During Z and I Emulator for Web installation on Windows, AIX, Linux, and Solaris, the install utility searches your system for an instance of WebSphere Application Server. If it detects an instance, the install utility can automatically install and configure the configuration servlet on WebSphere Application Server Versions 5.1, 6.0, 6.1 and 7.0.

For platforms that do provide an installation program such as System z and others, you will need to manually install the configuration servlet. Refer to your WebSphere Application Server documentation for steps on installing enterprise applications. You can also go to http://www.ibm.com/software/webservers/ and navigate to the WebSphere Application Server support page, where you can find a link to the documentation of your version.

The Z and I Emulator for Web configuration servlet EAR file, cfgservlet.ear, is located in the lib directory of your Z and I Emulator for Web installation.

Graphic Image
For WebSphere Application Server 5: After you save your deployment settings in the administrative console, you need to start the Z and I Emulator for Web configuration servlet in the Enterprise Applications window of WebSphere Application Server. Then go to the Environment window and select Update Web Server Plug-in.

After the configuration servlet is installed, you can configure your clients to use the configuration servlet instead of directly accessing the Service Manager. You can use the Deployment Wizard to build customized HTML client pages. The wizard sets the applet parameters in the HTML based on your input, so you do not have to learn the syntax and valid parameter values. HCL recommends that you use the Deployment Wizard to set the ConfigServerURL parameter in the client HTML to ZIEConfig/ZIEConfig/zieweb.

For more information regarding configuration servlet parameters, configuration and examples, see Configuring the configuration servlet in the online help.

Uninstalling the Z and I Emulator for Web server

You can use the Installation Manager GUI to uninstall the Z and I Emulator for Web Version 1.0. Follow the steps below for the uninstallation:

  1. Stop all Z and I Emulator for Web related applications (For example, Deployment Wizard and HCL Z and I Emulator for Web Service Manager).
  2. Start Installation Manager. Click Uninstall.
  3. Select HCL Z and I Emulator for Web and the appropriate version and click Next.
  4. Review the summary information. Click Uninstall.
    • If the uninstall is successful, the program displays a message that indicates success.
    • If the uninstall is not successful, click View log to troubleshoot the problem.
  5. Click Finish.
  6. Click File > Exit to close Installation Manager.

Uninstalling Z and I Emulator for Web using Installation Manager Console mode

You can use console mode to uninstall packages. To uninstall, the user must be the administrator or log in with the administrator privilege.

Perform the following tasks to uninstall ZIEWeb in the Installation Manager Console Mode:

  1. Close all programs that are associated with Z and I Emulator for Web installation. For example, Deployment Wizard and HCL Z and I Emulator for Web Service Manager.
  2. Enter the command
    : imcl -c
    and press Enter
  3. Enter 5 to proceed the uninstallation.
  4. Type the number that appears to the left of the Z and I Emulator for Web 1.0 package group. Press Enter.
  5. Review the details of the Z and I Emulator for Web 1.0 package group that is to be uninstalled. Type N for Next or press Enter. N is the default selection.
  6. Select the Z and I Emulator for Web package by typing the number that appears to the left of Z and I Emulator for Web 14.0 package. Press Enter. Enter N for Next.
  7. Confirm the package to be uninstalled. Type U for Uninstall, and press Enter. This panel also provides an option to create a response file. Press G and Enter to proceed with creating a response file. This starts uninstallation.
  8. At the next prompt, press F to Finish.

Configuring Z and I Emulator for Web

Configuring Z and I Emulator for Web emulator clients

After installing Z and I Emulator for Web, you need to create HTML files and configure Z and I Emulator for Web sessions for your users.

Graphic Image
Z and I Emulator for Web provides a sample HTML file of ready-to-use 3270, 5250, VT, and FTP emulator sessions pre-configured with download client and Java auto-detection components. These sessions use the HTML-based configuration model and are provided to allow you to get Z and I Emulator for Web up and running and access your host systems quickly. To use these emulator sessions, take the following steps:
  1. Locate the clients.zip file in the your_publish_directory\samples\html directory, where your_publish_directory is the name of your Z and I Emulator for Web publish directory.
  2. Verify that the clients.zip file created by the Deployment Wizard is located in the directory in which you want to unzip the files (either in the Z and I Emulator for Web publish directory or in a special-purpose publish directory). If not, copy the .zip file to that directory.
  3. Use the DWunzip tool to unzip the contents of clients.zip to your publish directory. Refer to Using DWunzip for more information about how to use this tool.
  4. Use your browser to point to clients.html on your Web server, for example, http://host/alias/clients.html.
  5. Right-click the appropriate session icon and then select Properties to open session properties. Fill in the correct destination address, port, and any other connection properties of your host system. Click OK.
  6. Double click the session icon to start the session.
You can use the Deployment Wizard to customize the HTML file. For more information, refer to Using the Deployment Wizard.

Creating Z and I Emulator for Web HTML files

The best way to create and set up your HTML files for Z and I Emulator for Web is to use the Deployment Wizard. The Deployment Wizard allows you to easily create custom HTML files that contain all of the Z and I Emulator for Web features tailored for your environment. The following is a list of some of the many features that can be configured using the Deployment Wizard:

Graphic Image
To use the Web Start client, you need to use the Deployment Wizard. Predefined files for this client type are not provided.

Configuring Z and I Emulator for Web sessions

In addition to setting up your HTML files, you need to define sessions for your users. If you are using the HTML-based model, then you configure your sessions in the Deployment Wizard at the same time that you create the HTML files. Otherwise, if you are using the configuration server-based model or the combined model, or using one of the predefined clients, you will need to create groups, users, and sessions in the configuration server using one of the administration clients.

There is a full range of options available to you when you are configuring your sessions, regardless of whether you need to use the Deployment Wizard or one of the administration clients:

Using the Deployment Wizard

The Deployment Wizard runs on Windows and Linux platforms. To start the Deployment Wizard, select one of the following ways:

The Deployment Wizard Welcome window appears.

The Deployment Wizard guides you through configuration choices and provides comprehensive help for the features. When you have finished selecting features, the Deployment Wizard creates the HTML and supporting files for you. These files need to be placed on the Z and I Emulator for Web server in a directory known to your Web server; usually, this directory is your Z and I Emulator for Web server's publish directory.

Distributing the Deployment Wizard output to your Z and I Emulator for Web server

If your Z and I Emulator for Web server is on a Windows or IBM System i platform, you might be able to write your Deployment Wizard HTML and configuration files directly to your Z and I Emulator for Web server's publish directory. On the final screen of the Deployment Wizard, you can select where to write the generated files. You may select any local or network drive accessible by the machine where your Deployment Wizard is running. In this case, you would direct the Deployment Wizard output to a publish directory on the Z and I Emulator for Web server and specify an output format of HTML. Assuming that you have already defined your sessions, the HTML page is then ready to be accessed by your users.

Otherwise, if your Deployment Wizard cannot directly write to your Z and I Emulator for Web server, then you should select to have the Deployment Wizard generate a zip file for the output format. The Deployment Wizard will then produce a single zip file containing all of the HTML and supporting files. You will need to move the zip file to the Z and I Emulator for Web server and use DWunzip to explode the zip file into the desired publish directory. Assuming that you have already defined your sessions, the HTML page is then ready to be accessed by your users.

Using Z and I Emulator for Web administration and new user clients

Z and I Emulator for Web supplies several predefined clients for administering Z and I Emulator for Web and creating new user accounts. Before accessing an emulator client or a Database On-Demand client that uses the configuration server-based or combined deployment models, you need to add users and configure sessions for them with one of the administration or full administration clients.

Loading administration and new user clients

To load an administration or new user client, do one of the following:

Administration clients

Administration clients enable you to perform the following tasks for data stored on the configuration server:

Administration clients run on all Z and I Emulator for Web client platforms except the Macinstosh operating system. If you are creating HTML files in the Deployment Wizard using either the configuration server-based or combined models, you need to configure sessions on the configuration server using an administration client. Refer to Basic Configuration Steps in the online help for more detailed information about configuring the Z and I Emulator for Web configuration server.

Z and I Emulator for Web supplies the following predefined administration and full administration clients:

Administration client (admin.html)
Loads the download version of the administration client.
Full Administration client (adminfull.html)2
Loads the download version of the full Administration client. The full administration client gives the administrator the additional ability of starting sessions to configure runtime properties. However, the download size of the full administration client is larger than the download size of administration client.
Notes:
  1. Use the problem determination clients only if you are working with Support to resolve a problem with your Z and I Emulator for Web installation.
  2. The full Administration client is the Administration client with Start Session enabled.
  3. If you use a Java-enabled browser, you need to use the Java Control Panel to remove the Administration cached client. For instructions, refer to Using the Java plug-in in the online help.

Directory Utility

The Directory Utility is a Java application the administrator can use to manage user, group or session configuration information. This information is stored either in the Z and I Emulator for Web default data store, or in an LDAP directory. This utility is only useful in the environment where the Configuration Server-based model is in use. The Directory Utility enables you to add, delete, or update large numbers of users, groups, or sessions in a batch mode environment instead of using the Administration client. The Directory Utility reads an XML ASCII file that contains the following actions to be performed on users, groups, or sessions defined to the Configuration Server:

Graphic Image
Searches performed with the list action are either user-based (returning user-specific information) or group-based (returning group-specific information). LDAP environments, however, support only user-based searches.

For more information, see Using the Directory Utility in the online help.

New user clients

If the administrator has enabled Allow users to create accounts in the Users/Groups window, users can use the predefined new user clients to create new accounts. See the Enabling users to create accounts topic in the online help for more information about this client.

The following new user clients are supplied with Z and I Emulator for Web:

New user client (NewUser.html)
Loads the download version of the New user client.
New user client cached (NewUserCached.html)
Loads the New User client in a cached environment.
New user client with problem determination (NewUserCachedDebug.html)1
Loads the New User client in a cached environment with problem determination (session logging and tracing).
Note:
Use the problem determination clients only if you are working with HCLto resolve a problem with your Z and I Emulator for Web installation.

Using Z and I Emulator for Web emulator clients

This chapter discusses issues that you need to be aware of when configuring and using Z and I Emulator for Web terminal emulator clients.

Loading emulator clients

Graphic Image
Z and I Emulator for Web provides a sample HTML file of ready-to-use 3270, 5250, VT, and FTP emulator sessions pre-configured with download client and Java auto-detection components. These sessions use the HTML-based configuration model and are provided to allow you to get Z and I Emulator for Web up and running and access your host systems quickly. For more information, refer to Configuring Z and I Emulator for Web emulator clients.

To load a Z and I Emulator for Web emulator client, a user starts a Web browser and enters in the Address field the URL of a Z and I Emulator for Web HTML file. The Z and I Emulator for Web HTML file must be one of the following:

HCL recommends the first option. For more information on the Deployment Wizard, see the Deployment Wizard topic in the online help.

Graphic Image
If your emulator client is deployed with the configuration server-based or combined deployment model, you need to add users and configure sessions with the administration client before you can use the emulator client.

To launch HTML files generated by the Deployment Wizard, specify the full URL of the HTML file in your browser:

http://server_name/zie_alias/client_name.html

where server_name is the host name or IP address of the Z and I Emulator for Web server, zie_alias is the alias (or path) of the publish directory, and client_name is the HTML file name of the client. For example, if you created an HTML file in the Deployment Wizard called 3270sessions.html, you can load it by specifying a URL such as the following:

http://host.yourcompany.com/zieweb/3270sessions.html

To launch a predefined HTML file included with Z and I Emulator for Web, point your browser to dashboard_xx.html file, where xx is your two-letter language suffix, to view links to all the available predefined clients. dashboard_xx.html is located in the publish directory.

When you access a client, a security warning appears to notify you that Z and I Emulator for Web was created by International Business Machines. Users must grant Java security privileges for this session or any future sessions by clicking the appropriate buttons in order for Z and I Emulator for Web to work properly.

Note:
Pop-up blockers might prevent the Java security windows and other response windows from appearing.

Selecting the appropriate client

The types of Z and I Emulator for Web clients that you use depend on your computing environment and your personal preferences.

Web Start clients are stored locally and load faster than download clients (unless an updated version of the client is being downloaded from the Web server). You can use them equally well over network and dial-up connections. Web Start clients take up more local disk space than download clients, but on most machines this is not a problem.

The Web Start client allows users to run Z and I Emulator for Web sessions without a browser. Users start Z and I Emulator for Web sessions from the Java Web Start Application Manager. If a user closes the Z and I Emulator for Web desktop and there are active sessions running, the user is prompted to make sure he wants to close all sessions.

Download clients are generally used in LAN-connected environments because high-speed network connections reduce the time it takes to download them from the Web server. They are not recommended for use over low-speed dialup connections because they need to be downloaded every time they are used, which takes more time on dialup connections. The small disk footprint of download clients is especially well-suited for client machines that do not have a lot of local disk space, such as NetStation machines.

You can use Web Start in the same Z and I Emulator for Web environment.

If you plan to use the Web Start client, you need to use the Deployment Wizard to generate your HTML file.

Web Start client

The Java Web Start client allows users to start Z and I Emulator for Web without a browser. You need to use the Deployment Wizard to generate a HTML file for the Web Start client. The HTML file generated by the Deployment Wizard points to a Java Network Launch Protocol (JNLP) file. The JNLP file defines a Java Application, including parameters passed to the application and the archives that contains class files used by the application. The JNLP file and the associated archives are stored on a Web server.

When a user points to the JNLP file, the browser launches the Web Start application on the client computer. It downloads the associated archives, checks to insure that the minimum required JRE is present (if specified), stores the archives on the user's machine, sets up icons to represent the application, and launches the application.

Users can start Z and I Emulator for Web sessions from the Java Web Start Application Manager. By using the Java Web Start Application Manager, Z and I Emulator for Web sessions do not depend on a browser. Therefore, closing a browser does not end a Z and I Emulator for Web session. If the user attempts to close the Z and I Emulator for Web desktop and there are active sessions running, the user is prompted to make sure he wants to close all sessions. If so, the sessions are terminated cleanly to prevent problems that occur when there are sessions running in the browser and the browser is abruptly closed.

After the initial launch of the application, you can either point the Web browser at the JNLP file again, or click the mouse on the icons created on the client machine. After Web Start is restarted, it checks the Web server for updates to the archives and downloads any updated files.

Java Web Start is bundled with JRE 1.4.0 or higher versions of the Java Runtime Environment. If you use JRE 1.3, then you should upgrade to JRE 1.4. For more information about Java Web Start, refer to http://www.javasoft.com. Z and I Emulator for Web Version 1.0 recommends Java 1.5 or higher.

The Z and I Emulator for Web Web Start client has the following requirements:

Installing the Web Start client

There are two ways to install the Web Start client. Typically, users install it from a Z and I Emulator for Web server over the network, either with or without using a Web browser. Alternatively, users can install it from a LAN or DVD drive, although this requires a small additional download over the network. Regardless of how users install the Web Start client, once it is installed and in the Java Web Start Application Manager, they can start it by clicking the appropriate icon in the Application Manager.

Installing the Web Start client from the Z and I Emulator for Web server

Users can install the Web Start client from the Z and I Emulator for Web server either with or without using a browser.

Using a Web browser

To install the Web Start client using a Web browser, users can perform the following steps:

  1. Specify the full URL of the HTML file in your browser, as described in Loading emulator clients.

    The Web Start client begins installing immediately. A window shows the progress of the installation. The upper progress bar of this window shows the status of individual files as they download, while the lower progress bar shows the status of the overall installation.

  2. When the installation completes, the installation code immediately launches the Web Start client. You do not have to restart the browser.
Without using a Web browser

For Windows users, distribute the JNLP file that was generated from the Deployment Wizard (for example, myhod.jnlp) to your end users. Once the file is distributed, users can type start myhod.jnlp to start the Web Start application and begin installing the Z and I Emulator for Web client. Since the file extension '.jnlp' will be registered to the Web Start application, the Web Start application will start, read the file, and download all the appropriate archive files from the Z and I Emulator for Web server that was specified in the Deployment Wizard-generated JNLP file. The Z and I Emulator for Web Web Start client will start when the download completes.

If you have not distributed the JNLP file to Windows users or your clients are running platforms other than Windows, users can still download the Web Start client without a Web browser by starting the Java Web Start Application Manager directly and pointing to the JNLP file on the Web server.

For Windows clients, users can perform the following steps:

  1. Open the Java Web Start Application Manager by double-clicking the javaws.exe file, typically located in the C:\Program Files\Java Web Start directory.
  2. Point to the JNLP file on the Web server at http://ZIEServer/ZIEAlias/myzieweb.jnlp.

For Linux clients, a user can type /javaws http://ZIEServer/ZIEAlias/myzieweb.jnlp to install and run the Z and I Emulator for Web session. A Z and I Emulator for Web icon appears in the Java Web Start Application Manager. Users can double-click this icon to launch Z and I Emulator for Web.

Installing the Web Start client from a LAN or DVD

In order to reduce network traffic and minimize download times, some companies wish for users to install the Web Start client from a LAN or DVD. Since the Web Start client share the same cached archives, users can install the majority of the Web Start client using the same installation procedure as the cached client. However, the Web Start client requires an additional component that must be installed directly from the Z and I Emulator for Web server over a network.

Installing the Web Start client involves two steps for the administrator followed by two steps for the end user.

First, the administrator should perform the following two steps:

  1. Use the Deployment Wizard to generate a Cached Client HTML file.
  2. Use the Deployment Wizard a second time to edit the HTML file that you created in the previous step, changing the client type from Cached Client to Web Start client. (Be sure not to make any other changes so that the defined sessions and the preload component list stay the same.) This second HTML page is the one that you should publish for users to access.

Second, once you have published your HTML file, users should perform the following two steps:

  1. Install the cached client that the administrator set up on the LAN or DVD.
  2. Install the additional component for the Web Start client by following the steps for Installing the Web Start client from the Z and I Emulator for Web Server: Using a Web browser. The Web Start client code will determine that the Z and I Emulator for Web archive files have already been downloaded and will not download them again. The remaining component should download quickly, and the Z and I Emulator for Web Web Start client will start.

Configuring your Web server for Web Start

The administrator must register the JNLP extension as a mimetype with the Web server so the browser knows to launch the Web Start application. For example, the following sections describe how to configure Apache HTTP Server, IBM HTTP Server, and Microsoft IIS.

Apache HTTP Server or IBM HTTP Server

To configure the Apache HTTP Server or IBM HTTP Server for Web Start, add the following line to mime.types:

AddType Application/x-java-jnlp-file    .jnlp

Microsoft IIS 7.0

To configure Microsoft IIS for Web Start, complete the following steps:

  1. From Control Panel > Administrative Tools > Internet Information Services, click Default Web Site.
  2. Click the HTTP Headers tab on the Properties.
  3. Under MIME Map, click the File Types tab and select New Type.
  4. In the Extension field, type .jnlp.
  5. In the Content Type field, type application/x-java-jnlp-file.
  6. Click OK.

Upgrading the Web Start client

After the initial install of the Web Start client, if users point their browsers to the HTML file generated by the Deployment Wizard and updates are available on the Z and I Emulator for Web server, Z and I Emulator for Web prompts users to update. If users want to update, Java Web Start downloads the updated archive files and launches Z and I Emulator for Web. If users decline to upgrade, Z and I Emulator for Web prompts them again the next time they launch the HTML file.

Adding Web Start components after the initial install

If users request a function that is not installed on the Java Web Start client, Z and I Emulator for Web prompts them to install the additional components required for that function. If they choose to install the additional components, they must restart the Z and I Emulator for Web client to use them.

Web Start and Windows Restricted Users

Windows Restricted Users with Java Web Start 1.0.1 should remove the JRE and Java Web Start and reinstall a newer JRE with Java Web Start 1.2.

Bookmarking sessions with Web Start

Since the Web Start client runs outside of a browser, bookmarking is disabled since bookmarking is a browser feature. Administrators can create Web Start clients that give users the same look as running an embedded bookmarked session by doing the following:

  1. On the Advanced Options window of the Deployment Wizard, add the HideDesktop parameter with a value of true.
  2. Configure a single session to autostart.
  3. Configure the session to not start in a separate window.

Using Web Start with HTTPS

If you want to use HTTPS with the Web Start client, the certificate authority used for your secure HTTP connection should come from a well known root authority. When you use Z and I Emulator for Web as an applet and use an HTTPS connection, you are given the opportunity to trust the certificate used for the HTTPS connection if the root authority is not known by the browser. Since Java Web Start runs as an application, this browser facility is not available. The Java Virtual Machine used by Java Web Start contains several root authorities that it trusts. If the certificate that comes from the HTTPS connection has a root authority of one of these authorities known by the JVM, the secure connection can be established. If you want to use a certificate authority other than ones known by the JVM by default, for example, a self-signed certificate, you need to import the certificate into the keystore of the JVM for each of the clients accessing this Java Web Start client. This is required to establish the secure HTTP connection.

Removing the Web Start client

To remove the Web Start client, complete both of the following steps:

  1. In the Java Web Start Application Manager, highlight your application and click Remove.
  2. Launch lcremove.html in your browser.

Deploying customer-supplied Java archives and classes

Customer-supplied Java classes and archives are Java class files and archive files that are not included either as part of the Z and I Emulator for Web client or as part of the Java Runtime Environment. Examples of such files are Java classes or archives that you yourself have implemented or that you have obtained from third parties.

You would want to deploy such classes or archives for use with the emulator client in the following situations:

Although several methods are available for deploying these files, each method works only under certain circumstances. The possible methods are:

The deployment method you choose depends on:

The three methods available for deploying customer-supplied Java archives and classes are described in the following sections. In addition, Hints and tips for archive files provides more information about using archive files.

Using the AdditionalArchives HTML parameter

You can use this method when you want to deploy Java archives to a Z and I Emulator for Web server. This method works for the cached emulator client, the download emulator client, and for the Web Start client.

Java archives must be Java .JAR files.

The advantage of using the AdditionalArchives HTML parameter is that it causes your Java archives to be downloaded to the user's workstation automatically when one of your users connects with the cached client or download client HTML file on your Z and I Emulator for Web server.

The disadvantage of this method is that these Java archives or class files will be downloaded again every time a user connects to that HTML file regardless of whether you are using a cached client or downloaded client. The reason for downloading the archives every time your user connects is to ensure that the Z and I Emulator for Web client has the latest versions of your archives or class files. As a result, this method works best when the Java archives or class files are relatively few and relatively small, so that your users do not have to wait a long time for these files to be downloaded, and so that downloading these files to your users does not place a heavy load on your Web server.

To use this method, perform the following steps:

  1. Place the archives in your Z and I Emulator for Web publish directory. The default publish directory is the subdirectory ZIEWeb in your Z and I Emulator for Web server's install directory, such as c:\Program Files\HCL\ZIEForWeb\ZIEWeb\.
  2. Edit the HTML file with the Deployment Wizard. Then:
    1. On the Advanced Options panel, click HTML Parameters.
    2. In the Name field, enter AdditionalArchives.
    3. In the Values field, enter the names of your Java archives, separated by commas, without file extensions (.jar). For example:
      myCustomA,myCustomB,MyCustomC

For more information, see AdditionalArchives in the online help.

Deploying from the Publish directory

This method works in the following situation:

To use this method, place the archives in your Z and I Emulator for Web publish directory. The default publish directory is the subdirectory ZIEWeb in your Z and I Emulator for Web server's install directory, such as c:\Program Files\HCL\ZIEForWeb\ZIEWeb\.

Hints and tips for archive files

The following hints and tips might provide helpful information about using archive files:

Using Database On-Demand clients

The Database On-Demand client is a Java applet that allows an end user to build SQL statements and File Upload statements, to send these SQL statements and File Upload statements to a remote database server, and to retrieve the results of SQL queries (SQL Select statements) from the remote database server.

The user can communicate with a database server running on an IBM System i server or other platform, so long as the proper Java Database Connectivity (JDBC) driver is installed on the Database On-Demand client workstation. For more information refer to Obtaining and installing a JDBC driver in this manual.

Features of Database On-Demand include:

The Database On-Demand client is available only through one of three predefined client HTML files (see Database On-Demand predefined clients). You cannot use the Deployment Wizard to create a Database On-Demand client.

However, as an alternative to the Database On-Demand client, you can now use database functions in Z and I Emulator for Web emulation clients and in macros (see Database functions in Display Emulation clients and in macros).

For more information see Overview of database access in the Z and I Emulator for Web online help.

The Database On-Demand client exists in a Java version. Therefore:

This Database On-Demand client can take advantage of the advanced capabilities of the Java plug-in.

Database functions in Display Emulation clients and in macros

As an alternative to the Database On-Demand client, almost all of the functions that are available in the Database On-Demand client are now also available in the display emulation client, including the following session types:

You can also use SQL statements and File Upload statements in macros in display emulation client sessions (see the SQLQuery action and the File Upload action in the Macro Programming Guide).

For example, while you are connected to a remote host in a 3270 Display session, you can launch a macro that automatically reads data from the 3270 Display session window and writes the data into a table in a database that is located on another remote host. Similarly, you can launch a macro that automatically reads data from a table in a remote database and writes the data into the 3270 Display session window.

For more information see Overview of database access in the Z and I Emulator for Web online help.

Starting a Database On-Demand client

To start a Database On-Demand client on the client workstation, use one of the following two methods:

Database On-Demand predefined clients

The Database On-Demand client is available through any one of three predefined client HTML files. You cannot use the Deployment Wizard to create a Database On-Demand client HTML file. The predefined clients are described below.

Database On-Demand client (database.html)

This is the download client. "Download" means that all the client code is downloaded to the client workstation each time the end user starts the Database On-Demand client.

Graphic Image
Use the problem determination client only if you are working with HCLto resolve a problem with your Z and I Emulator for Web installation.

Configuring Database On-Demand for users

To configure Database On-Demand for users, follow these steps:

  1. Use the Administration Utility to define groups and users (see Managing users and groups in the Z and I Emulator for Web online help).
  2. Specify the database functions that you want groups and users to be able to perform, and specify default values for some of the database parameters in new SQL statements and File Upload statements (see Database On-Demand Group/User Options in the Z and I Emulator for Web online help).

If you want to create predefined SQL statements and File Upload statements for users and groups, follow these steps:

  1. Run the Database On-Demand client as an end user, and create SQL statements and File Upload statements (see Getting started with Database On-Demand in the Z and I Emulator for Web online help).
  2. Launch the Administration Utility and copy the SQL statements and File Upload statements to other users or to groups (see Database On-Demand Group/User Statements in the Z and I Emulator for Web online help).

Obtaining and installing a JDBC driver

To connect to a database server running on a remote host, the end user needs a Java Database Connectivity (JDBC) driver installed on the client workstation.

The Z and I Emulator for Web client and the Database On-Demand client already include a JDBC driver from the IBM AS/400 Toolbox for Java. This driver allows a client to access a DB2/400 database on a properly configured IBM System i or AS/400 host system. You do not need to register or deploy this driver.

If you need a different JDBC driver:

  1. Contact the vendor or the administrator of the remote database to obtain the JDBC driver.
  2. Register the JDBC driver with Z and I Emulator for Web or Database On-Demand. See Registering a JDBC driver in the Z and I Emulator for Web online help.
  3. Deploy the JDBC driver to the workstations of your end users. See Deploying a JDBC driver in the Z and I Emulator for Web online help.

File formats for database access

The end user selects a file type for an SQL statement or a File Upload statement on the Output tab of the SQL Wizard window or on the File tab of the File Upload window.

For information on file formats, see File formats for database access in the Z and I Emulator for Web online help.

Using multiple code pages with Database On-Demand

If you wish to use multiple code pages with Database On-Demand, you need to add jar or cab files to your HTML file. Only those code pages that correspond to the language of the HTML file are automatically loaded. For example, if you are running from a French computer, but you want to access a Dutch host, you need to make these modifications.

Edit the CommonJars.js file. If you are using a download client, look for the line that starts "dbaDownloadJars =" and add the appropriate file names from the table below. Use jar file names, even if your clients will be using Internet Explorer (the names will be converted to cab file names later). If you are using a cached client, look for the line that starts "dbaCachedComps =" and add the appropriate component name from the table below.

Supported Database On-Demand code pages

The following table lists the supported Database On-Demand client code page languages, the corresponding .jar file names, and the cached component names:

Code page language .JAR file name Component name
Arabic hacpar.jar HACPAR
Czech, Hungarian, Polish, Slovenian hacpce.jar HACPCE
Danish, Finnish, Dutch, Norwegian, Swedish hacp1b.jar HACP1B
German, Spanish, French, Italian, Portuguese, Brazilian Portuguese hacp1a.jar HACP1A
Greek hacpgr.jar HACPGR
Hebrew hacphe.jar HACPHE
Japanese hacpja.jar HACPJA
Korean hacpko.jar HACPKO
Russian hacpru.jar HACPRU
Simplified Chinese hacpzh.jar HACPZH
Thai hacpth.jar HACPTH
Turkish hacptr.jar HACPTR
Traditional Chinese hacptw.jar HACPTW

Creating and deploying server macro libraries

Server macro libraries are available for the HTML model pages and Config model users. For the HTML page, users can use Deployment wizard to customize the server macro library; for the Config model, users can use the Z and I Emulator for Web admin console. GUI based configuration allows the administrator to configure for each session. For the administrator to configure for all the sessions defined, use the HTML parameter SetServerMacroLibraryPath.

The value of SetServerMacroLibraryPath is share path or relative path. You can use the values to create and maintain a central repository of macros for users to access from their Z and I Emulator for Web sessions. These macros are downloaded to the user's machine only when it is needed. When you make changes to a server macro, users automatically get your updates the next time when they access the macro.

Server macro libraries have several benefits:

Server macro libraries can reside on a Web server or on a shared network drive. For both types of libraries, you can control which macros are available to particular Z and I Emulator for Web sessions. If you use a Web-based macro library, you need to create a text file that identifies the specific macros that you want to be available for the session that you are configuring. If you use a shared drive-based macro library, then all the files in the specified directory will be available to the session. Users will not be allowed to write to a Web-based macro library, but they may update a shared drive-based macro library if they have write-access.

Deploying a server macro library to a Web server

  1. Put your macros in a place that users can access through a Web server. This does not need to be the Z and I Emulator for Web publish directory.
  2. For each session that requires a separate set of macros, create a text file that contains the list of the macro file names. The text file format can only have one macro file name per line, for example:
    macro1.mac
    macro2.mac
    macro3.mac
    Be sure to note the following rules:
    • The macro name must be the first element on the line, since everything after the first element is ignored.
    • If the first element on the line starts with //, the line is considered to be a comment and is ignored.
    • Each macro that you list in the text file must have a .mac extension.
  3. Put this text file in the same location as the macros that it references.
  4. In the Deployment Wizard, click the Configure menu on the Host Sessions window and select Server macro library... Check the 'Use a server macro library for this session' box and select Web server macro library.
  5. Specify the fully qualified URL of the macro list that you created in Step 2, for example, http://servername/zieweb/macrolist.txt. Click OK.

When users open their sessions, they can use the Play Macro or Available Macros windows to see the macros specified in the list that you created for their session. These macros are available when users select Server library as their macro location. The Server library location is only available if you have configured the session to use a server macro library.

Note:
Server Macro Library can also be configured in Admin Client.

Deploying a server macro library to a shared drive

  1. Put your macros in a shared directory on your network.
  2. In the Deployment Wizard Host Sessions window, select the session you wish to configure, click the Configure menu, and select Server macro library. Check the 'Use a server macro library for this session' box and select Shared drive macro library.
  3. Specify the directory path. Examples of valid directory paths include the following:
    • Absolute paths. Mapped network drive letters can also be used in the absolute path. Note that a server macro library should never point to a local drive.
    • Remote computer names or IP addresses are allowed as long as the user's computer is already remotely connected and authenticated to the computer that is sharing the directory. The following are two examples of paths to shared drive macro libraries:
      • \\your_host\macro_library, where your_host is the host name and macro_library is the macro directory.
      • \\123.45.67.89\macro_library, where 123.45.67.89 is the IP address of the host and macro_library is the macro directory.
    If you are configuring a macro library for more than one session, and each session uses its own set of macros, you will need to create a separate directory for each session.
  4. Click OK.

When users open their sessions, they can use the Play Macro or the Available Macros windows to see a list of the macros in the directory. These macros are available when users select Server library as their macro location. The Server library location is only available if you have configured the session to use a server macro library.

Modifying session properties dynamically

Z and I Emulator for Web sessions are defined by the administrator and retrieved by the Z and I Emulator for Web client when a user accesses a Z and I Emulator for Web HTML file. The session properties a user sees are fixed values and consist of a combination of the administrator's initial configuration and any user updates. However, there may be times when it would be useful with some HTML files, or with certain session properties, to dynamically set a value at the time that the HTML is accessed. This type of control allows you to set particular session property values based on information such as the IP address of the client or the time of day.

In order to dynamically set session properties at the time the HTML is accessed, the administrator must write a program that runs on the Web server and effectively modifies the HTML just before it is sent to the client. Even though the initial session properties are not defined in the HTML, Z and I Emulator for Web provides the capability to override many of the session properties in the HTML. These override values are always used by the client and take precedence over both the initial session properties setup by the administrator, as well as any updates for the property made by the user. The HTML override value is never stored, so the client will return to using prior settings for the property whenever the administrator removes the override. Also, the overridden property is locked so a user cannot change it.

There are many ways in which an administrator could write a program to dynamically set one or more session properties using the HTML overrides, such as using Java Server Pages (JSP), servlets, Perl, REXX, or Active Server Pages (ASP). This chapter takes you through a couple of examples that focus on common administrator issues. These examples are meant to demonstrate the syntax and technique of overriding particular properties. These mechanisms apply to whichever programming approach the administrator may choose.

Setting up the initial HTML file

The initial HTML file should be created using the Deployment Wizard, which will allow you to set up the features that are important to you, such as the size of the downloaded code and the functions available to your users. The following sections describe the HTML parameters you will need to include. However, keep in mind that the exact format required for these parameters will vary depending on the format of the HTML. Note that in Z and I Emulator for Web 7 and later, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements. Also, the format of the HTML varies according to the client (cached or download client) selected.

Setting the Code base

To set the code base when creating an HTML using the Deployment Wizard, do the following:

  1. On the Additional Options window, click Advanced Options and go to the Other branch in the tree view.
  2. Type the relative path /zieweb/ in the Code base field.
  3. Save the HTML file to the default Z and I Emulator for Web publish directory your_install_directory\ZIEWeb.

The HTML file is now located in the same directory with the Z and I Emulator for Web's archive files.

Code base refers to the installed Z and I Emulator for Web publish directory and not the directory where Deployment Wizard files are published. Although you can enter a fully qualified URL in the Code base field, we strongly recommend that you enter the relative path /zieweb/ for the default publish directory when modifying session properties dynamically. If you enter a fully qualified URL, any users who specify the host name in a different manner than you specified as the Code base will not be able to access the files, even if the DNS entries resolve to the same IP address.

Add the ConfigBase Parameter

Add a parameter to the HTML file called ConfigBase. Similar to defining /zieweb/ as the Codebase in Setting the Code base, the ConfigBase parameter is necessary because you will eventually deploy your JSP file to a location that is different than the default publish directory, and the Z and I Emulator for Web applet needs to know how to find the session configuration files located in the zieforweb/ZIEWeb/ZIEWebData directory. These files are created at the same time you save your Deployment Wizard HTML file to the publish directory. Unlike Codebase, the ConfigBase parameter requires a fully qualified URL. ConfigBase is a term that is specific to Z and I Emulator for Web.

Graphic Image
For more information, refer to Developing JavaServer Pages files with WebSphere extensions.

Overriding HTML parameters

There are several steps you need to follow in order to dynamically set session properties (the examples shown later in this chapter will help clarify how some of these parameters should be specified):

  1. Enable HTML overrides. By default, the client will ignore HTML overrides. To enable overrides, you will need to include an HTML parameter called EnableHTMLOverrides and set it to a value of true.
  2. List the sessions to be overridden. Because there may be multiple sessions associated with an HTML, you will need to list which ones will be overridden. You will need to include an HTML parameter called TargetedSessionList, having a value of the exact names of the sessions that should accept overrides. The value should be a comma-separated list of session names, such as "Session1Name, Session2Name".
  3. Specify the override itself. For each session property to be overridden, you will need to include an HTML parameter called the property name, with the value being the desired override. The value you specify will then apply to all sessions listed in your TargetedSessionList parameter. If you wish to only override a subset of the sessions in your TargetedSessionList, you can specify a value in the format of "Session1Name=value1, Session2Name=value2", for example.

Specific session properties that can be overridden

The following table describes the session properties that can be overridden and gives the acceptable values for each parameter:

Table 10. Session properties that can be overridden
Parameter name Description Valid values
Host Host name or IP address of the target server. Appears as "Destination address" on property panels. Applies to all session types. Host name or IP address.
HostBackup1 Host name or IP address of the backup1 server. Appears as "Destination address" of backup1on property panels. Applies to all session types. Host name or IP address.
HostBackup2 Host name or IP address of the backup2 server. Appears as "Destination address" of backup2on property panels. Applies to all session types. Host name or IP address.
Port The port number on which the target server is listening. Appears as "Destination port" on property panels. Applies to all session types. Any valid TCP/IP port number.
PortBackup1 The port number on which the backup1 server is listening. Appears as "Destination port" of backup1 on property panels. Applies to all session types. Any valid TCP/IP port number.
PortBackup2 The port number on which the backup2 server is listening. Appears as "Destination port" of backup2 on property panels. Applies to all session types. Any valid TCP/IP port number.
CodePage The codepage of the server to which the session will connect. Appears as "Host Code-Page" on property panels. Applies to all session types except FTP. The numeric portion (for example, 037) of the supported host codepage listed in the session property panel.
SessionID The short name you want to assign to this session (appears in the OIA). It must be unique to this configuration. Appears as "Session ID" on property panels. Applies to all session types. One character: A-Z.
LUName The name of the LU or LU Pool, defined at the target server, to which you want this session to connect. Appears as "LU or Pool Name" on property panels. Applies to 3270 Display and 3270 Printer session types. The name of an LU or LU Pool.
LUNameBackup1 The name of the LU or LU Pool, defined at the backup1 server, to which you want this session to connect. Appears as "LU or Pool Name" of backup1 on property panels. Applies to 3270 Display and 3270 Printer session types. The name of an LU or LU Pool.
LUNameBackup2 The name of the LU or LU Pool, defined at the backup2 server, to which you want this session to connect. Appears as "LU or Pool Name" of backup2 on property panels. Applies to 3270 Display and 3270 Printer session types. The name of an LU or LU Pool.
WorkstationID The name of this workstation. Appears as "Workstation ID" on property panels. Applies to 5250 Display and 5250 Print session types. A unique name for this workstation.
ScreenSize Defines the number of rows and columns on the screen. Appears as "Screen Size" on property panels. Applies to 3270 Display, 5250 Display, and VT Display session types.
  • value=rows x columns
  • 2=24x80 (3270, 5250, VT)
  • 3=32x80 (3270)
  • 4=43x80 (3270)
  • 5=27x132 (3270, 5250)
  • 6=24x132 (VT)
  • 7=36x80 (VT)
  • 8=36x132 (VT)
  • 9=48x80 (VT)
  • 10=48x132 (VT)
  • 11=72x80 (VT)
  • 12=72x132 (VT)
  • 13=144x80 (VT)
  • 14=144x132 (VT)
  • 15=25x80 (VT)
  • 16=25x132 (VT)
SLPScope Service Location Protocol (SLP) Scope. Appears as "Scope" under "SLP Options" on property panels. Applies to 3270 Display, 3270 Printer, 5250 Display, and 5250 Printer session types. Contact your administrator to get the correct value for this field.
SLPAS400Name Connects a session to a specific IBM System i. Appears as "iSeries Name (SLP)" on property panels. Applies to 5250 Display and 5250 Printer session types. The fully-qualified SNA CP name (for example, USIBMNM.RAS400B).
FTPUser Specifies the user ID the session uses when connecting to the FTP server. Appears as "User ID" on property panels. Applies to FTP session types. A valid user ID.
FTPPassword Specifies the password the session uses when connecting to the FTP server. Appears as "Password" on property panels. Applies to FTP session types. A valid password.
UseFTPAnonymousLogon Enables the session to log in to an FTP server using anonymous as the user ID. Appears as "Anonymous Login" on property panels. Applies to FTP session types. Yes or No.
FTPEmailAddress Specifies the e-mail address to use when connecting to the FTP server while using Anonymous Login. Appears as "E-mail Address" on property panels. Applies to FTP session types. A valid e-mail address.
PromptForDestinationAddress Specifies whether to prompt the user for the destination address to use when connecting to the FTP server. Appears as "Destination Address" on property panels. Applies to FTP session types. yes or no
CICSInitialTransEnabled Enables an initial transaction to be started when a CICS Gateway session is established. true or false
CICSInitialTrans Specifies the name of the initial transaction to be started upon connection to a CICS host. Applies to CICS Gateway sessions only. The CICSInitialTransEnabled parameter must be set to true for the specified transaction to be started. Valid transaction identifiers are strings of between 1 and 128 characters. The string identifies the initial transaction and any parameters to be run upon connection to the server. The first four characters, or the characters up to the first blank in the string are taken as the transaction. The remaining data is passed to the transaction on its invocation.
Netname The name of the terminal resource to be installed or reserved. If this field is blank, the selected terminal type is not predictable. Applies to CICS sessions only. A valid terminal resource name.

Any errors encountered in processing the HTML parameters are displayed in the Java Console.

Example #1: Overriding the LU name based on the client's IP address

Administrators may want to avoid specifying LU names directly in session definitions. This example shows a simple way of using the IP address of the client to look up an LU name listed in a text file and use it as an override value in a session.

This example is written using JSP. The Deployment Wizard was used to create an HTML file that contains two sessions named 3270 Display and 5250 Display. Note that in Z and I Emulator for Web 7 and later, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements. Also, the format of the HTML varies according to the client(cached or download client) selected.

This example uses a cached Java page to start from with the needed changes for HTML overrides in bold. When the Deployment Wizard is used to generate a cached Java2 page it generates the following files:

A Macintosh client makes use of the Example_J2.html page.

A file (c:\luname.table) is read that contains IP address/LU name pairs. The IP address of the client is used to look up the proper LU name, which is overridden in the "3270 Display" session. See the comments in the example for more detail. The lines added to the Deployment Wizard output are displayed in bold.

<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN">
<%
//  Read the luname.table file into a properties variable.
//  The luname.table file contains lines in the following format:
//    ipaddress=luname
Properties lunames = new Properties();
lunames.load(new FileInputStream("c:\\luname.table"));
%>
<HTML>
<HEAD>
<META http-equiv="content-type" content="text/html; charset=UTF-8">
<!-- TITLE Begin -->
<TITLE>Example1 page title</TITLE>
<!-- TITLE End -->
<!-- SUMMARY Begin -->
<!--
Configuration Model
	What configuration model would you like to use?
	-HTML-based model
Host Sessions 
	-3270 Display
	-5250 Display
Additional Options
	-Cached = Cached client
	-Java Type = java2
Disable Functions
Preload Options
	-5250 Sessions = True
	-Change Session Properties = True
	-3270 Sessions = True
Cached Client/Web Start Options
	Basic Options
	-Debug = False
	-Height (in pixels) = 250
	-Width  (in pixels) = 550
	Upgrade Options
	-Percent of users who can upgrade by default = 100
	-Prompt user (user decides foreground or background)
Advanced Options
	HTML parameters
	-None
	Code base
	- /zieweb/
	HTML templates
	-Default
	Problem determination
	-Debug = False
	User updates
	-Persist user updates? = True
	Appearance
	-Standard Z and I Emulator for Web Client
	Applet size
	-Autosize to browser
	Session Manager API
	-Enable Session Manager JavaScript API = False
	Server connection
	Language
	-Locale = Use the system Locale
	Maximum sessions
	- 26
-->
<!-- SUMMARY End -->
</HEAD>

<CENTER>
<P>


<SCRIPT LANGUAGE="JavaScript">
function writeAppletParameters()
{
   return "";
}
</SCRIPT>


<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/ziewebversion.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/CommonJars.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/CommonParms.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/CommonJ2Parms.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript">
var db = parent.location;
var hod_Locale = '';
var hod_AppName ='';
var hod_AppHgt = '340';
var hod_AppWid = '550';
var hod_CodeBase = '/zieweb/';
var hod_Comps = 'HABASE;HODBASE;HODIMG;HACP;HAFNTIB;HAFNTAP;HA3270;HODCFG;HA5250';
var hod_Archs = 'habasen.jar,hodbasen.jar,hodimg.jar,hacp.jar,hafntib.jar,hafntap.jar,
                 ha3270n.jar,hodcfgn.jar,ha5250n.jar';

var hod_URL = new String(window.location);
var hod_DebugOn = false;

var hHod_AppletParams = new Array;
hHod_AppletParams[1] = '<PARAM NAME="ShowDocument"      VALUE="_parent">';
hHod_AppletParams[3] = '<PARAM NAME="ParameterFile"     VALUE="HODData\\Example1\\params.txt">';
hHod_AppletParams[4] = '<PARAM NAME="JavaScriptAPI"     VALUE="false">';
hHod_AppletParams[5] = '<PARAM NAME="BookmarkPage"      VALUE="Example1.html">';

// The next 2 lines are required in order to override session properties.
//  The first line turns on the processing for this function and does not 
//  need to be modified.  The second line identifies the sessions that you
//  want to change.  In this example, there are 2 sessions identified 
//  named: "3270 Display" and "5250 Display".
 
hHod_AppletParams[6]='<PARAM NAME="EnableHTMLOverrides" VALUE="true">';
hHod_AppletParams[7]='<PARAM NAME="TargetedSessionList" VALUE="3270 Display,5250 Display">';
 
// The following line changes the LUName session parameter for the session named
//  "3270 Display".  In this example, the LUName is being set to the value   
//  contained in the c:\luname.table for the IP address of the client.
//  When you are initially testing your changes, you may want to use a constant
//  value to verify that the syntax is correct before you insert your 
//  calculations.
hHod_AppletParams[8]='<PARAM NAME="Luname" VALUE="3270 
                       Display=<%=lunames.get(request.getRemoteAddr())%>">';

//hHod_AppletParams[x] = '<PARAM NAME="DebugCode"              VALUE="65535">';


var pg = buildJ2Page(db);
pg += writeAppletParameters();
pg += '</APPLET>';
if(hod_DebugOn) alert('J2 page complete, result = \n' + pg);
document.write(pg);
</SCRIPT>

</CENTER>
</BODY>
</HTML>

Example #2: Allowing the user to specify the host to connect to using an HTML form

Administrators may also want to use HTML forms to specify override values rather than calculating them. The following example displays a simple form for entry of a host name. The form posts to a JSP program which uses the host name specified in the form to override the host name in the 3270 Session.

This example is written using JSP. The Deployment Wizard was used to create an HTML file that contains two sessions named "3270 Display" and "5250 Display." Note that in Z and I Emulator for Web 1.0, some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements.

When using forms, the form data needs to be retained across requests to the program. This is because Z and I Emulator for Web HTML files reload themselves for Java detection and for bookmarking support when using configuration server-based model pages. If Java 1 is selected and bookmarking support is disabled if using the configuration server-based model, the page will not need to reload and there is no need to retain the form data. This example uses a JSP session to store the form data across reloads.

Here is a simple HTML form that allows for entry of a host name. The form posts to the JSP program (example2.jsp):

<form method="POST"  action="zieweb/example2.jsp">
Hostname <input name="form.hostname"><br>
<input type="submit">
</form>

Here is the modified output from the Deployment Wizard. See the comments in the example for more detail. The lines added to the Deployment Wizard output are displayed in bold.

<HTML>
<%
// Get a session or create if necessary and store the hostname
// entered in the form in the session.
HttpSession session = request.getSession(true);
String hostname = request.getParameter("form.hostname");
if (hostname!=null) {
session.putValue("session.hostname", hostname);
}
%>
<!-- ZIEWeb WIZARD HTML -->
<!-- Deployment Wizard Build : 8.0.0-B20030605 -->
<HEAD>
<META http-equiv="content-type" content="text/html; charset=UTF-8">
<TITLE>Example 2 page title</TITLE>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/CommonJars.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/HODJavaDetect.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript" SRC="/zieweb/CommonParms.js"></SCRIPT>
<SCRIPT LANGUAGE="JavaScript">

//---- Start JavaScript variable declarations ----//
var hod_Locale = '';
var hod_jsapi=false;
var hod_AppName ='';
var hod_AppHgt = '80%';
var hod_AppWid = '80%';
var hod_CodeBase = '/zieweb/';
var hod_FinalFile = 'z_example2.html';
var hod_JavaType = 'java2';
var hod_Obplet = '';
var hod_jars = 'habasen.jar,hodbasen.jar,hodimg.jar,hacp.jar,hodsignn.jar,ha3270n.jar,
                hodcfgn.jar,ha5250n.jar';

var hod_URL = new String(window.location);
var hod_DebugOn = false;
var hod_SearchArg = window.location.search.substring(1);

var hod_AppletParams = new Array;
hod_AppletParams[0] = '<PARAM NAME="ParameterFile" VALUE="ZIEWebData\\example2\\params.txt">';
hod_AppletParams[1] = '<PARAM NAME="ShowDocument"  VALUE="_parent">';
hod_AppletParams[2] = '<PARAM NAME="JavaScriptAPI" VALUE="' + hod_jsapi + '">';
hod_AppletParams[3] = '<PARAM NAME="PreloadComponentList" VALUE="HABASE;HODBASE;HODIMG;
                                                                    HACP;HAFNTIB;HAFNTAP;
                                                                    HA3270;HODCFG;HA5250">';

// The next 2 lines are required in order to override session properties.
// The first line turns on the processing for this function and does not
// need to be modified. The second line identifies the sessions that you
// want to change. In this example, there are 2 sessions identified
// named: "3270 Display" and "5250 Display".
// Be careful to increment the array index correctly.

hod_AppletParams[4] = <PARAM NAME="EnableHTMLOverrides" VALUE="true">;
hod_AppletParams[5] = <PARAM NAME="TargetedSessionList" VALUE="3270 Display,5250 Display">;

// The following line changes the Host or Destination Address session parameter
// for the session named "3270 Display". In this example, the Host is being set
// to the value saved in the JSP session from the HTML form.
// When you are initially testing your changes, you may want to use a constant
// value to verify that the syntax is correct before you insert your
// calculations.
// Here we override the host for the 3270 session to the value saved in the
// jsp session from the html form.

hod_AppletParams[6] = <PARAM NAME="Host" VALUE="3270 
                       Display=<%=session.getValue("session.hostname")%>">;

//hod_AppletParams[x] = '<PARAM NAME="DebugCode"     VALUE="65535">';

//---- End JavaScript variable declarations ----//

function getHODMsg(msgNum) {
  return HODFrame.hodMsgs[msgNum];
}

function getHODFrame() {
  return HODFrame;
}

var lang = detectLanguage(hod_Locale);
document.writeln('<FRAMESET cols="*,10" border=0 FRAMEBORDER="0">');
document.writeln('<FRAME    src="/zieweb/hoddetect_' + lang + '.html" name="HODFrame">');
document.writeln('</FRAMESET>');

</SCRIPT>
</HEAD>
</HTML>

Configuring Z and I Emulator for Web on zSeries

This chapter describes how to set up separate read/write private and publish directories for configuring Z and I Emulator for Web on a zSeries system.

The purpose of this configuration scenario is to provide instructions for common zSeries configuration tasks.

Setting up separate read/write private and publish directories

Set up a separate File System for the Z and I Emulator for Web private directory

When Z and I Emulator for Web is installed, files in the /usr/lpp/ZIEWeb/zieforweb/private directory are updated in an execution environment, not just by manufacturing refresh releases. Because this directory is now updated during the Z and I Emulator for Web software's execution, you are recommended to mount a separate (non-service) File System. You can do this in one of the following ways:

If you are using LDAP and native authentication, manually copy the HODrapd and the /keys directory to the system-specific /private directory.

When the system-specific /private directory is mounted, it overlays but does not destroy the master /private directory. When maintenance releases are applied, use the master /private directory. If these files are changed, copy them to the system-specific /private directory.

Set up a separate user publish directory

Files generated from the Deployment Wizard can be placed in a user-defined directory that is separate from the Z and I Emulator for Web publish directory. This makes it easier to apply future Z and I Emulator for Web upgrades. This solution keeps the Z and I Emulator for Web publish directory read only and provides a separate writeable location for deploying Deployment Wizard files.

For instructions on deploying Deployment Wizard files in a separate user publish directory and for information on other user-modified files that can be placed outside the publish directory, refer to migration instruction of deployment wizard.

You can create and mount a separate file system for the user-defined publish directory. The generated Deployment Wizard zip file are to be transferred to this directory and unzipped by the DWUnzip utility. The Web server needs to include an alias statement specific to the user-defined publish directory.

You can access the page through the URL that specifies the alias of the user-defined publish location. For example, if the publish directory is /usr/lpp/ZIEWeb/publish, and the alias is userpublish, then the URL to access the client page would be http://<servername>/userpublish/<pagename>.html.

Installing the Development Wizard from the z/OS server

The Deployment Wizard normally locates on a Windows machine during the installation of the product. On z/OS, a download is provided for you to install the Deployment Wizard on Windows so you can generate client pages for the z/OS ZIE server. Refer to the following steps for installing the Development Wizard from the z/OS server:

  1. Use FTP in binary to relocate this file of a Windows workstation: /usr/lpp/ZIEWeb/zieforweb/ZIEWeb/depwiz/DW.zip.
  2. Extract the zip file into a folder.
  3. To start the install, go to <folder>\DeploymentWizard\disk1 in Explore.
  4. Double click imLauncherWindows.bat to launch Installation Manager User Interface.
  5. Follow the instructions to finish the installation.

Once the Development Wizard is installed, you can launch it. Go to Start > All Programs > HCL Z and I Emulator for Web Deployment Wizard.

Configuring Z and I Emulator for Web on IBM System i

After you install Z and I Emulator for Web on the IBM System i platform, configure the software as follows:

Configuring, starting, and stopping the Z and I Emulator for Web Service Manager on IBM System i

The following commands can be used from the IBM iv7r1 or OS/400 command line.

Configure

You can use the NCServiceManager-OS400.sh script file to configure Service Manager. NCServiceManager-OS400.sh is located in the following directory on the IBM System i:

ZIE_install_directory>/lib/samples/NCServiceManager/. 

To configure the Service manager settings, perform the following tasks:

  1. Access the directory /<ZIEWeb install directory>/lib/samples/ NCServiceManager/. Here, <ZIEWeb install directory> is the location or path where Z and I Emulator for Web has been installed. For example, /QHCL/ProdData/ZIEForWeb/.
  2. Open the NCServiceManager-OS400.sh file.
  3. Verify that the runtime variables are correct and correspond with your environment. Change the default values of the runtime variables if they do not correspond with your environment. These include the following:
    • Location of the JRE: JAVA_ENGINE

      Update the value of the JAVA_ENGINE to the complete path or location of the jre installed on the system. It must be Java V6 or higher. It must point to <java_installation>/bin/java in the Java installation directory.

    • Location of the Z and I Emulator for Web publish directory on the server: MY_ZIEWeb_DIRECTORY

      Verify, and update if necessary, the value of MY_ZIEWeb_DIRECTORY to the complete path of the Z and I Emulator for Web installation directory. It must be the installation directory of Z and I Emulator for Web and the directory contains /bin, /lib and other folders of Z and I Emulator for Web. Generally, this value is updated once at the time of installation. For example, /QHCL/ProdData/ZIEForWeb.

    • Target paths specified within the command file: MY_PUBLISHED_DIRECTORY

      Verify, and update if necessary, the value of MY_PUBLISHED_DIRECTORY to the complete path of the Z and I Emulator for Web Publish directory. Generally, it is the <ZIEWeb_Installation>/ZIEWeb directory, where <ZIEWeb_Installation> is the Z and I Emulator for Web installation directory.

  4. Confirm that NCServiceManager-OS400.sh has the necessary execute permissions and authorized to write to directories in the Z and I Emulator for Web installation on the server.

Start

To start the Z and I Emulator for Web Service Manager, run NCServiceManager-OS400.sh so that it starts and continues to run in the background.

One way to achieve this on IBM i Series is to submit a job by invoking the IBM PASE for System i to run the script. Contact your IBM i Series administrator for the details on best ways to submit a job suitable to your i Series setup and requirements.

An example command that submits a job:

sbmjob cmd(call pgm(qp2shell) parm('/QOpenSys/usr/bin/-sh' '/QHCL/ProdData/Z and I Emulator for Web/lib/samples/NCServiceManager/NCServiceManager-OS400.sh'))

Stop

To stop the service manager, end the job on Iseries. Contact your Iseries administrator for details on a suitable method for stopping the service.

One way to do this is with the following example steps:

  1. Type WRKACTJOB to open a list of active jobs.
  2. In the Work with Active Jobs menu, the Z and I Emulator for Web service manager job gets listed with function name JVM-NCServiceM. Scroll down the menu to this job entry and select the Work With.. option, typically option 5.
  3. Select the End job option. For this, type 41 to end the job, and press the Enter button. This ends the service manager job and stop the service manager.

Work with ZIE Server status

To determine whether the Service Manager is running, it needs to be checked whether the Java program NCServiceManager , which is started by the script NCServiceManager-OS400.sh, is running or not. Therefore, the method to check the server status might vary according to the method used to start the service manager.

In the example above, the Service Manager is started by submitting a job to run the NCServiceManager-OS400.sh script. Hence, the you can perform following two ways to check the status:

  1. Use the WRKACTJOB command to review the status :
    1. Enter the command:
      WRKACTJOB
      This provides a list of active jobs.
    2. In the Work with Active Jobs menu, the Z and I Emulator for Web service manager job gets listed with the function name JVM-NCServiceM. Use the PageDown or PageUp button to scroll down the menu to this job entry and enter the appropriate option number to Work with.. the job, typically option 5.
    3. Utilize the menu options to review the job status.
  2. Query the process status in the command line.

In the example of Start, the script NCServiceManager-OS400.sh is executed by invoking the IBM PASE for System i (qp2shell) in the SBMJOB command. Hence, in this case, the following steps can also help to check the status :

  1. On the IBM System i, sign on to a green screen command line.
  2. b) Enter the PASE shell environment. On the green screen command line, enter the following command:
    call qp2term
    .
  3. On the PASE shell, type the following command:
    ps -ef | grep NCServ
    .
    Note:
    NCServiceManager is the name of the Java program that runs the service manager.

If the command detects that the Service manager is running, it will provide an output that would look like the following :

   $                                                                            
		> ps -ef | grep NCServ                                                         
		  kushald 3146    1   0 15:23:30      -  0:00 /QHCL/ProdData/OS400/Java400/jFr
		  omPASE java -classpath .:sm.zip:ibmjndi.jar:jndi.jar:jsdk.jar:ods.jar:jt400.j
		  ar -Djava.net.preferIPv4Stack=true -DFIPS=on com.ibm.eNetwork.HODUtil.service
		  s.admin.NCServiceManager /QHCL/ProdData/Z and I Emulator for Web                         
		  $  
Note:
The PASE shell is case-sensitive. Hence, it is important to maintain the correct case of alphabets in command (step c).

Certificate Management

Certificate Management functions can be performed using the P12Keyring utility provided by Z and I Emulator for Web. This provides an easy way to create and deploy an SSL keyring database. Use this option to work with SSL certificates in one of the Z and I Emulator for Web keyrings. Refer to Planning for security for general information on SSL related sessions.

Information on P12Keyring and its usage is available in Appendix C. P12 Keyring utility.

Some sample commands can be viewed at the link How to create, add or convert certificates to CustomizedCAs.p12 file on z/OS for Z and I Emulator for Web.

Start Information Bundler

In the event that you need to contact the HCL Center for assistance, the already available Information Bundler script file can be used to gather information about your Z and I Emulator for Web configuration.

For usage information, refer the section Running the Information Bundler of the ZIEWeb V1 document.

Create ZIEWeb Printer Definition Table

Create a custom printer definition table for Z and I Emulator for Web 3270 printer sessions. In order to use this function, please refer the section under Compiling a PDT on an iSeries server section.

A custom printer definition might be necessary if you have a special paper form or if the printer is not supported. The following options are not available on ZIEWeb V1.0:

Using the Deployment Wizard with IBM System i

To use the Deployment Wizard to deploy screens to an IBM System i-based Z and I Emulator for Web server, do the following:

  1. From a Windows workstation, map a network drive to /qhcl directory on the IBM System i system that is Z and I Emulator for Web server. Refer to the IBM System i Web site for more information.
  2. Download Deployment Wizard installation image from an already installed Z and I Emulator for Web v1.0 server. Access dashboard.html (for example http://zieserver.name.com/zieweb/dashboard.html, and click on Deployment Wizard Installation Image for Windows.
  3. Refer to the installation instructions for installing Deployment Wizard. You can run this without having to install the entire Z and I Emulator for Web server.
  4. Design the custom features and selections.
  5. Save the customized HTML file to the mapped network drive (For example, y:\ProdData\zieforweb\zieweb\myweb).
  6. Use a browser to test out the file (For example, http://iSeries.name.com/zieweb/myweb.html).

Configuring IBM System i servers for secure connection

If you are using self-signed certificates or certificates from a signing agency that is not in the well-known list, use the P12Keyring utility to configure the CustomizedCAs keyring. For more details, refer to Appendix C. P12 Keyring utility.

Follow the steps below to configure a CustomizedCAs keyring:

  1. Ensure that java is installed in the system.
  2. Open a unix/AIX-based command line. For example, QSHELL or IBM I PASE shell.
  3. Navigate to the Z and I Emulator for Web publish folder in the Z and I Emulator for Web installation directory. Generally, it is /QHCL/ProdData/ZIEForWeb/ZIEWeb/.
  4. Enter the command
    java -classpath .:your_install_dir/lib/sm.zip com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs connect myServer.raleigh.ibm.com:702
    . This command can take a few minutes to complete. If you are asked for a password, type zieweb and press Enter.
  5. Select the certificate number that corresponds to the Certificate Authority (CA) that you want to add to the keyring. Be sure to add the CA certificate and not the site certificate. If the port is not responding, refer to Configuring IBM i 7.1 servers for secure connection.
  6. Repeat steps 3to 5for each target server.

To view the contents of the CustomizedCAs keyring, perform the following steps:

  1. Ensure that java is installed in the system.
  2. Open a linux-based shell, for example, QSHELL or IBM i PASE shell.
  3. Navigate to the Z and I Emulator for Web publish folder in the Z and I Emulator for Web installation directory. Generally, it is /QHCL/ProdData/ZIEForWeb/ZIEWeb/.
  4. Enter the command
    java -classpath .: your_install_dir/lib/sm.zip com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs list
    .

Installing and configuring Z and I Emulator for Web with TLS on i/OS and OS/400

The following list provides a high-level overview of the steps needed to install and configure Z and I Emulator for Web with TLS:

  1. Verify all software and hardware requirements are met.
  2. Install all necessary IBM System i software products. Refer to your IBM System i documentation for details.
  3. Install all required PTFs. The latest PTFs are located on at the IBM eServer System i support portal.
  4. Install and configure the IBM HTTP Server or IBM Application Server. Refer to the product documentation for details.
  5. Create a Certificate Authority (CA) from the Digital Certificate Manager on the IBM Administrative Server or purchase a public CA. Refer to your IBM System i documentation for details.
  6. Configure TLS on the IBM HTTP Server or IBM Application Server. Refer to the product documentation for details.
  7. Configure Z and I Emulator for Web with TLS. Refer to Configuring TLS in the online help for details.

Configuring a Telnet server for secure connection

Visit IBM System i Knowledge Center and search on TLS to learn the steps you need to take to enable TLS. You might need to repeat the steps for each IBM System i7 system that you want to use secure connections with.

Configuring the Z and I Emulator for Web CustomizedCAs keyring

If you are using self-signed certificates or certificates from a signing agency that is not in the well-known list, use the P12Keyring utility to configure the CustomizedCAs keyring. For more details, refer to Appendix C. P12 Keyring utility.

Perform the following steps to configure a CustomizedCAs keyring:

  1. Ensure that java is installed in the system.
  2. Open a linux-based shell, for example, QSHELL or IBM I PASE shell.
  3. Navigate to the Z and I Emulator for Web publish folder in the Z and I Emulator for Web installation directory. Generally, it is /QHCL/ProdData/ZIEForWeb/ZIEWeb/.
  4. Enter the command
    java -classpath .:your_install_dir/lib/sm.zip com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs connect myServer.raleigh.ibm.com:702
    This command can take a few minutes to complete. If you are prompted for a password, type zieweb and press Enter.
  5. Select the certificate number that corresponds to the Certificate Authority (CA) that you want to add to the keyring. Be sure to add the CA certificate and not the site certificate. If the port is not responding, refer to Configuring IBM System I servers for secure connection.
  6. Repeat steps 3to 5 for each target server.

To view the contents of the CustomizedCAs keyring, do the following:

  1. Ensure that java is installed in the system.
  2. Open a linux-based shell, for example, QSHELL or IBM I PASE shell.
  3. Navigate to the Z and I Emulator for Web publish folder in the Z and I Emulator for Web installation directory. Generally, it is /QHCL/ProdData/ZIEForWeb/ZIEWeb/.
  4. Enter the command
    java -classpath .: your_install_dir/lib/sm.zip com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs list
    .
Graphic Image
If you have multiple IBM System i machines and would like to create a single certificate that all the machines can use, consider cross certification. Refer to Managing Security, Cryptographic Services APIs, and Application System/400 Cryptographic Support/400 Version 3 for additional information about cross certification.

Client authentication

For additional security, consider TLS with client authentication to tightly control who can Telnet to your system over the Internet. For example, you can configure the Telnet server to only allow authentication if the client certificate was issued by your IBM System i (through Digital Certificate Manager).

The client certificates have a limited validity period (for example, 90 days). When the certificate expires, the user must perform the Client Certificate Download process in order to continue. This process requires a valid IBM System i user ID and password.

Graphic Image
Not all Telnet client software is capable of client authentication. When enabled, all TLS-enabled Telnet connections to the IBM System i require a user certificate.

Refer to the IBM System i Web site for more information.

Configuring the Z and I Emulator for Web OS/400 proxy for secure connections

The OS/400 proxy can be configured to encrypt file transfer and Database On-Demand connections. To do this, the following additional software must be installed on each target IBM System i:

Set up TLS user authorizations

You need to control authorization of the users to the files. To help you to meet the TLS legal responsibilities, you need to change the authority of the directory that contains the TLS files to control user access to the files. In order to change the authority, do the following:

  1. Enter the command wrklnk '/QHCL/ProdData/HTTP/Public/jt400/*'.
  2. Select option 9 in the directory.
    1. Ensure *PUBLIC has *EXCLUDE authority.
    2. Give users who need access to the TLS files *RX authority to the directory. You can authorize individual users or groups of users. Remember that users with *ALLOBJ special authority cannot be denied access to the TLS files.

Secure Web serving

The Z and I Emulator for Web server uses the Web server to download program objects to the browser. This information can be encrypted, but with a considerable performance impact.

The default port for secure web serving is 443. If that port is not enabled, port 80 is used. To enable secure web serving, perform the following steps:

  1. From a Web browser, enter: http://<server.name>:2001 (where <server.name> is the TCP/IP host name of your IBM System i). If you are unable to connect, start the HTTP server with the following i/OS and OS/400 command:
    STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
  2. Enter the i/OS or OS/400 user profile and password (when prompted). you need to have *ALLOBJ and *SECADM authorities to complete the remaining configuration activities.
  3. Click IBM HTTP Server for AS/400.
  4. Click Configuration and Administration.
  5. Click Configurations.
  6. Select the CONFIG configuration from the list.
  7. Click Security Configuration.
  8. For the Allow HTTP connections and Allow TLS connections selections:
    • Port number (443)
    • Select TLS Client authentication None.
    • Select Apply.
  9. Click AS/400 Tasks button on the lower left side of the screen.
  10. Click Digital Certificate Manager.
  11. Click System Certificates.
  12. Click Work with Secure Applications.
  13. Click QIBM_HTTP_SERVER_CONFIG; then click Work with System Certificate.
  14. Click Assign New Certificate.
  15. End the administration HTTP server instance with the following i/OS and OS/400 command:
    ENDTCPSVR SERVER(*HTTP) HTTPSVR(DEFAULT)
  16. Wait 10 seconds for the HTTP instance to shut down.
  17. Start the administration HTTP server instance with the following i/OS and OS/400 command:
    STRTCPSVR SERVER(*HTTP) HTTPSVR(DEFAULT)
  18. From a Web browser, enter https://server.name/zieweb/dashboard.html (where server.name is the TCP/IP host name of your IBM System i).

For more information on a wide variety of IBM System i topics, see IBM i PDF files and manuals.

Unicode Support for i/OS and OS/400

General information

In a 5250 Display session, Z and I Emulator for Web supports the display of Unicode data located in fields tagged with Coded Character Set Identifiers (CCSIDs). For more information see Unicode support for i/OS and OS/400 using Coded Character Set Identifiers.

Host programming information

For host programming information, refer to the IBM System i Website.

Deploying Z and I Emulator for Web with WebSphere Portal

As an alternative to accessing Z and I Emulator for Web through an HTML file, users can access it through Portal Server, which is a component of WebSphere Portal. Portal Server provides a framework for plugging content extensions known as portlets into a Web site. Portlets are applications that run within Portal Server. They organize content from different sources (such as Web sites, e-mail, and business applications) and display it on a single HTML file in a browser window. The WAR files generated by the Deployment Wizard used to launch Z and I Emulator for Web sessions can be deployed as portlets, enabling users to access Z and I Emulator for Web through the portal interface. If you are planning to use Z and I Emulator for Web and Portal Server in conjunction with a firewall, refer to Using Z and I Emulator for Web with a firewall. Also, if you are planning to use security features of WebSphere Portal, such as the user's Portal ID or the Portal Server Credential Vault, refer to the Web Express Logon Reference.

Both Z and I Emulator for Web and Portal Server must be installed to run a Z and I Emulator for Web portlet.

Eclipse-Plugin support

This chapter describes how to set up Z and I Emulator for Web for the IBM Eclipse-Plugin.

Note:
Z and I Emulator for Web currently supports Eclipse-Plugin on Windows platform only. Please check the README for additional support as that will be updated if additional platforms are added.

Eclipse-Plugin is the foundation for next-generation, network-centric computing. Built on the Eclipse rich client platform, it provides additional features for managing and deploying applications easily to end users.

On Eclipse-Plugin, all applications are packaged as Eclipse "features", which consist of "plugins" and "fragments". Eclipse features are usually installed from an "update site", which is a directory on a machine that is web-accessible.

To build the Z and I Emulator for Web plugin for Eclipse-Plugin, Z and I Emulator for Web provides a Java applet called "Update Site Utility". The Update Site Utility converts Z and I Emulator for Web jar files into Eclipse plugins and fragments and places them in a new or an existing update site directory.

Procedures to install features from an update site are different depending on Eclipse-Plugin platforms, such as Workplace Managed Client (WMC) or WebSphere Everyplace Deployment (WED). When WMC is used, extra configuration steps are required on its server counterpart, Workplace Collaboration Service (WCS). The Update Site Utility generates an XML file, which eases the configuration steps on WCS.

Creating Z and I Emulator for Web plug-ins

To create and deploy these Z and I Emulator for Web plugins to run in Eclipse-Plugin, do the following:

  1. Ensure that you have an HTML-model Deployment Wizard page that defines the sessions for your plugin. You can use any existing HTML-model page or create a new one.
    Note:
    Only HTML-model pages are supported for the Eclipse-Plugin feature.
    Once your page is completed, put the unzipped Deployment Wizard output files into the Z and I Emulator for Web publish directory.
  2. Create a directory, for example c:\update, that will be used as the Eclipse update site for your plugin(s), if you do not already have one defined. Next,
  3. Define an alias to that directory in the Web server configuration and restart the Web server.
  4. You are now ready to create the Z and I Emulator for Web plugin. On the Eclipse update site machine, open a browser, running Java JRE (1.6 or higher) and point it to the Z and I Emulator for Web URL: http://<hostname>/<alias>/WCTConfig.html .
    Note:
    On Linux, you need to set the LD_LIBRARY_PATH environment variable when using the IBM 1.4.2 Java plugin Service Release 2 and later.

    For example, if you want to use the Java plugin that is shipped by Z and I Emulator for Web server for Linux, use export command to set the LD_LIBRARY_PATH environment variable as follows:

    export LD_LIBRARY_PATH=/opt/hcl/Z and I Emulator for Web/zieweb_jre/jre/bin:
      $LD_LIBRARY_PATH   
  5. This URL will run a special Update Site Utility applet to assist in building the plugin.
  6. Fill in the Basic Information panel of the Update Site Utility as follows:
    • Update Site Destination Directory (Required) Specify the Eclipse update site directory created in Step 2, for example c:\updates.
    • ZIEWeb Code Base (Required) This field should already be correctly filled in, if you pointed to WCTConfig.html as described in Step 3. This field needs to specify the location of the Z and I Emulator for Web publish directory in the form: http://<hostname>/<alias> The Z and I Emulator for Web server name must be fully-qualified. It cannot be a relative URL name or one like "localhost" or "127.0.0.1".
    • Deployment Wizard Output File (Required) Specify the name of the HTML-model Deployment Wizard page created in Step 1.
    • Feature Version (Required) Specify the version string used in the generated feature in the format major.minor.service, like 1.0.0.
    • User JAR File Path (Optional) Specify the path of a jar file containing customer code used for solutions that require custom code to interact with the Z and I Emulator for Web sessions. You can specify multiple files separated by commas (,).
      Note:
      If you need to use the Run Applet feature, you need to package your applets in a jar file and specify the file path here.
  7. You can reduce the size of the Eclipse plugin to be created by unchecking any unnecessary features or host code pages on the Runtime Codes and the Code Pages panels of the Update Site Utility panel.
  8. When you have completed all the fields, select Generate and Deploy Plugin. The applet creates the Z and I Emulator for Web plugin, and places it in the update site you have specified.
  9. Following files are created or modified in the directory specified as Update Site Destination Directory:
    • Site map file (site.xml): This file lists the features that are installable from this update site.
    • XMLAccess script file: This file is an input of WebSphere Portal XMLAccess utility for installing Z and I Emulator for Web feature on WCS. The file names are given in the form: (deployment wizard output file name)_DeployScript.xml . On XMLAccess, refer to IBM Accelerators for WebSphere Portal family.
    • features subdirectory: This subdirectory contains the Z and I Emulator for Web feature archives.
    • plugins subdirectory: This subdirectory contains:
      Z and I Emulator for Web plugin Plugin itself. File name is given in the form: com.ibm.eNetwork.HOD.wct_(plugin version).jar
      Z and I Emulator for Web code fragment Z and I Emulator for Web runtime code. File name is given in the form: com.ibm.eNetwork.HOD.wct.(function name)_(plugin version).jar
      Config fragment Fragment that stores configuration information. File name is given in the form: com.ibm.eNetwork.HOD.wct.configs.(deployment wizard output file name)_(feature version).jar
    • images subdirectory: This subdirectory contains an image file used on WMC/WCS.

    For information about installing the plugin on the client, refer to documents that come with your Eclipse-Plugin platforms.

Setting Session Properties Dynamically

On the Eclipse-Plugin platform, HTML overrides cannot be used in order to dynamically set session properties because no HTML files are used for running the Z and I Emulator for Web plugin. If you need to have the similar functionality, do the following steps:

  1. Implement a Java class that implements the com.ibm.eNetwork.HOD.wct.IHODConfigFactory interface, which is stored in the wct.jar file. The wct.jar file is installed in the Z and I Emulator for Web publish directory. The interface has two public methods:
    public String setHodHtmlFileName()   
    public Properties getHodHtmlParameters()       

    Following is an example of such Java classes:

    Figure 8. Example of Java classes
    package com.ibm.eNetwork.HOD.wct.samples;
    
    import java.util.Properties;
    
    import com.ibm.eNetwork.HOD.wct.IHODConfigFactory;
    
    public class ConfigOverride implements IHODConfigFactory {
        /* (non-Javadoc)
         * @see com.ibm.eNetwork.HOD.wct.IHODConfigFactory#getHodHtmlFileName()
         */
        public String getHodHtmlFileName() {
            return "hodwmc";
        }
    
        /* (non-Javadoc)
         * @see com.ibm.eNetwork.HOD.wct.IHODConfigFactory#getHodHtmlParameters()
         */
        public Properties getHodHtmlParameters() {
            Properties p = new Properties();
            p.put("EnableHTMLOverrides", "true");
            p.put("TargetedSessionList", "3270 Display");
            p.put("host", "3270 Display=hostname");
            return p;
        }
  2. Package the Java class in a jar file.
  3. Edit the Update Site Utility HTML file (WCTConfig.html) in the Z and I Emulator for Web publish directory and set the showUserClass parameter to true:
    var showUserClass="true";  
  4. Run the Update Site Utility and specify additional parameters as follows: User JAR File Path: The file path of the jar file created on the step 2. User Configuration Factory Class: The name of the Java class implemented on the step 1.
  5. Generate a Z and I Emulator for Web plugin and deploy it to your Eclipse-Plugin platform.

Using a separate user publishing directory

When you are using a separate user publishing directory other than the Z and I Emulator for Web publish directory, you need to specify the directory on Update Site Utility with the following procedure:

  1. Edit the Update Site Utility HTML file (WCTConfig.html) in Z and I Emulator for Web publish directory and set the showAlternatePublishDirectory parameter to true:
    var showAlternatePublishDirectory ="true";  
  2. Run the Update Site Utility and specify your separate user publishing directory in the Alternate Publish Directory entry field.

View IDs used in Z and I Emulator for Web plugin

Following is the list of view IDs used by Z and I Emulator for Web plugin. You are suggested knowing them when you configure page layout on WCS manually.

ID Description
com.ibm.eNetwork.HOD.wct.SessionsView Configured Sessions
com.ibm.eNetwork.HOD.wct.SessionLabelsView Active Sessions
com.ibm.eNetwork.HOD.wct.TerminalView Terminal (Display, Printer, FTP, etc.)

Limitations on using Z and I Emulator for Web in a Eclipse-Plugin environment

Following are limitations not mentioned above on using Z and I Emulator for Web in an Eclipse-Plugin environment:

  1. Sometimes a Z and I Emulator for Web modal dialog can get behind the Eclipse-Plugin shell window. This will happen if Z and I Emulator for Web has a dialog open and the user switches to another application outside of Eclipse-Plugin. User will have to do ALT-TAB to find the ZIEWeb dialog that needs to be acknowledged.
  2. "Confirm On Exit" does not work. The "Confirm On Exit" setting is ignored in the Eclipse-Plugin environment. Since it is not supported, the option has been removed from the session properties.
  3. If a session is launched and a destination address is not configured, the Z and I Emulator for Web applet is able to launch the session properties dialog. In the Eclipse-Plugin environment, users receive a message that a destination address is required but the properties dialog does not open.
  4. GUI elements like Macro Manager, Keypad, and Toolbar can not be added dynamically to a running session. Instead, these items must be enabled using the existing properties in the Preferences section of the session properties.
  5. Option to "Start in a Separate Window" has no meaning in this environment since the session is always in an editor pane. This option is removed from the session properties.
  6. Only a client with debug capabilities is available. Reducing the preload components using the Deployment Wizard Preload Options to make the footprint smaller (with the exception of host codepages and 5250 File Transfer) is not possible.
  7. Unlike the Z and I Emulator for Web cached client, client does not automatically update to the new code level. The Administrator needs to re-configure Update Site so that the Eclipse-Plugin platform can install the new plugin/fragments.
  8. Run Applet works only when the applet is packaged in a JAR file and installed on client machines.
  9. IPMON tracing is supported only in the "normal" mode. The "automatic" mode is not supported. On the execution modes of IPMON, refer to the "Overview of IPMON tracing" topic in the online help.
  10. When multiple Z and I Emulator for Web features are installed, the Z and I Emulator for Web plugin displays the list of installed Z and I Emulator for Web features in the configured sessions view to let the user select one feature among them. After one feature is once selected, the user needs to restart WED to select a different feature.
  11. Pressing and releasing the Alt-key throws an exception on the Java console. This is a known problem with the IBM 1.4.2 JRE and has been resolved in IBM 1.4.2 Service Release 4.1 and later.

Configuring Z and I Emulator for Web Server to use LDAP

The Z and I Emulator for Web Server is used to manage configuration data for the configuration server-based and combined models. For the default operational mode of the Z and I Emulator for Web Server, this data is saved in a non-shared private data store. Some enterprise customers need to manage their configuration information between multiple Z and I Emulator for Web servers. If these customers use the non-shared private data store, then their administrators must manage the data for each Z and I Emulator for Web Server separately. A Lightweight Directory Access Protocol (LDAP) server directory provides the ability to share user and group configuration information over different instances of the Z and I Emulator for Web configuration server.

Using an LDAP directory server to manage and share your definitions across multiple Z and I Emulator for Web servers is an option that must be carefully planned and executed. Migration from the private data store, in particular, has implications on the configuration data. LDAP enables the customer to manage the configuration information by arranging users into a hierarchical tree of groups. If existing users are members of more than one group, then some information will be lost. Note that the configuration data in the private data store is not changed when a migration to LDAP occurs. Refer to implications of migrating to LDAP in the Z and I Emulator for Web online help for more detailed information.

Setting up LDAP support

  1. Decide which LDAP Directory server you are going to use and, if necessary, install it.
  2. If you are running a version of LDAP that does not support the schema for Z and I Emulator for Web , install the Z and I Emulator for Web schema extension files as described in Installing the schema extensions. (The schema extension files are not required for IBM LDAP Version 3.x or later.)
  3. Ask your LDAP administrator for a suffix which Z and I Emulator for Web will use to store configuration information. Make a note of the distinguished name (DN) of this suffix; you will need this information to complete the LDAP setup.
  4. Ask your LDAP administrator for an administrator DN and password for Z and I Emulator for Web; these will be used to authenticate to the LDAP server. The administrator DN must have create, modify and delete privileges for the suffix mentioned in the previous step. Make a note of the DN and password; you will need this information to complete the LDAP setup.
  5. Enable LDAP on the Directory Service window in the administration utility. Also, optionally, migrate the private data store configuration information to the LDAP directory server. For more information, refer to Configuring Z and I Emulator for Web Server to use LDAP.
    Graphic Image
    Users and groups that are already defined in LDAP for other purposes are not used by Z and I Emulator for Web. Users and groups for Z and I Emulator for Web must be defined separately by either migrating the configuration information from the private data store or by setting up the users and groups in Z and I Emulator for Web after enabling LDAP.
    Graphic Image
    If you are using the IBM LDAP server on Windows and AIX platforms, and you are creating a large number of users, make sure that DB2 is configured with the proper value for APP_CTL_HEAP_SZ. While the value for this variable is dependent on individual installations, setting APP_CTL_HEAP_SZ to 512 is a good starting value.

    To configure DB2 heap size in a Windows or AIX environment, issue these commands:

    1. set DB2INSTANCE=ldapdb2
    2. db2 connect to ldapdb2
    3. db2 update db cfg for ldapdb2 using APP_CTL_HEAP_SZ 512
    4. db2 force application all
    5. db2 terminate
    6. db2stop
    7. db2start

    Also, be sure that STMTHEAP is large enough. The size for these parameters are dependent solely on individual customer configurations and the number of Z and I Emulator for Web users that are being migrated to LDAP.

Installing the schema extensions

The Z and I Emulator for Web extensions to the LDAP directory schema are provided in several files that are located in the LDAP subdirectory of the publish directory (for example, your_install_directory\ZIEWeb\ldap, where your_install_directory is your Z and I Emulator for Web installation directory). These files contain extensions to the LDAP schema and are stored in the standard slapd format. The schema extensions must be in effect before Z and I Emulator for Web can store configuration information in an LDAP server. Contact your LDAP administrator to have these schema extensions installed.

Refer to the Program Directory for instructions on installing the schema extensions for the zSeries.

Graphic Image
Your LDAP administrator may have already installed these schema extensions for use by another IBM product. If so, skip these steps. If you are using the IBM Directory Server Version 3.1.1 or later, the schema is pre-installed, so you can skip these steps also.

To install the Z and I Emulator for Web schema extensions on a Netscape LDAP Directory server:

  1. Copy the following slapd files from the <Z and I Emulator for Web publish directory>/ldap directory to the Netscape LDAP config directory on the LDAP server :
    Netscape.IBM.at
    Netscape.IBM.oc
  2. Stop the LDAP server.
  3. Edit the <Netscape LDAP config directory>/slapd.conf file and add the following statements:
    userat "<Netscape LDAP config directory>/Netscape.IBM.at"
    useroc "<Netscape LDAP config directory>/Netscape.IBM.oc"
  4. Restart the LDAP Server.

To install the Z and I Emulator for Web schema extensions on an IBM LDAP Directory server:

  1. Copy the following slapd files from the Z and I Emulator for Web publish directory/ldap directory to the <installation directory>/etc directory on your LDAP server:
    V2.1.IBM.at
    V2.1.IBM.oc
  2. Stop the LDAP server.
  3. Edit the <installation directory>/etc/slapd.at.conf file and add the following statement to the end of the file:
    include /etc/V2.1.IBM.at
  4. Edit the <installation directory>/etc/slapd.oc.conf file and add the following statement to the end of the file:
    include /etc/V2.1.IBM.oc
  5. Restart the LDAP server.

Configuring the Z and I Emulator for Web server to use LDAP as a data store

  1. Open the Administration window and logon to Z and I Emulator for Web.
  2. Click Services > Directory Service
  3. Click the Use Directory Service (LDAP) box and then enter the LDAP server information.
    Destination Address
    Type the IP address of the LDAP directory. Use either the host name or dotted decimal format. The default is the host name of the Z and I Emulator for Web server.
    Destination Port
    Type the TCP/IP port on which the LDAP server will accept a connection from an LDAP client. The default port is 389.
    Administrator Distinguished Name
    Type the distinguished name (DN) of the directory administrator that allows Z and I Emulator for Web to update information. you need to use the LDAP string representation for distinguished names (for example, cn=Chris Smith,o=HCL,c=US ).
    Administrator Password
    Type the directory administrator's password.
    Distinguished Name Suffix
    Type the distinguished name (DN) of the highest entry in the directory information tree (DIT) for which information will be saved. Z and I Emulator for Web will store all of its configuration information below this suffix in the DIT. you need to use the LDAP string representation for distinguished names (for example, cn=ZIEWeb,o=HCL,c=US ).
    Migrate Configuration to Directory Service
    To migrate users and groups from the private data store to the LDAP directory, click the check box. Migrating to LDAP has significant implications for your group and user configuration information. Refer to LDAP Migration Implications in the online help for more information. You can check this box either when you switch to the directory server, or after you have made the switch.
    Graphic Image
    The Redirector configuration is not migrated to the directory server.
    Graphic Image
    If you have a problem connecting to LDAP and migrating, try to connect to LDAP first. Then, after successfully connecting, try to migrate.
  4. Click Apply.

    When you are asked to authenticate with the LDAP directory for the first time, specify a user ID of "admin" and a password of "password". You can change this password after the first log on. Even though you might have changed your password for the private data store, that ID and password continues to be valid for the private data store only. For the LDAP directory, a separate user ID and password are required. To avoid confusion, you can change your LDAP directory password to be the same as your private data store password.

Changes made on this panel are effective immediately. Once you have switched to the LDAP server, subsequent user-related changes will be made only on the LDAP server, including administrative changes to groups, users, or sessions, and changes such as new passwords, macros, keyboard changes, etc., by either the administrator or a user.

Appendixes

Appendix A. Using locally installed clients

The locally installed client installs to a local disk. The client applet is loaded directly into the default system browser, so there is no download from a server. The most common reason to configure a local client is for users who connect remotely over slow telephone lines, where download time can be an issue and connectivity is unpredictable. You can also use the locally installed client to test host access capabilities without installing the full Z and I Emulator for Web product.

Operating systems that support the locally installed client

Z and I Emulator for Web can be installed as a client on the following operating systems:

The locally-installed client requires approximately 320 MB of disk space.

Installing the local client

To install the Z and I Emulator for Web local client on a Windows workstation, you need to be a member of the Administrators group.

  1. Insert the DVD and run hodinstallwin.exe -lc from the \HODINST directory of the DVD.
  2. Click Install.
  3. Proceed through the rest of the windows.
  4. If you have not already done so, read the Readme available in the last window.

At the end of installation, the Z and I Emulator for Web Service Manager is configured and started automatically. On Windows 7, Windows 8, and Windows 10, the Service Manager is installed as a Service.

Starting the local client

To start Z and I Emulator for Web as a client, click Start > Programs> HCL Z and I Emulator for Web> Z and I Emulator for Web.

Removing the local client

To remove the local client, use Add/Remove Programs from the Control Panel.

Appendix B. Using the IKEYCMD command-line interface

IKEYCMD is a command-line tool, in addition to the Z and I Emulator for Web Certificate Management Utility, that can be used to manage keys, certificates, and certificate requests. It is functionally similar to Certificate Management and is meant to be run from the command line without a graphical interface. It can be called from native shell scripts and programs to be used when applications prefer to add custom interfaces to certificate and key management tasks. It can create key database files for all of the types that the Certificate Management utility currently supports. It can create certificate requests, import CA-signed certificates and manage self-signed certificates. It is Java-based and is available only on Windows, AIX, Linux Intel and Linux zSeries platforms.

Use IKEYCMD for configuration tasks related to public-private key creation and management. You cannot use IKEYCMD for configuration options that update the server configuration file, httpd.conf. For options that update the server configuration file, you need to use the IBM Administration Server.

Environment set-up for IKEYCMD command-line interface

Set up the environment variables to use the IKEYCMD command-line interface as follows:

For Windows platforms, do the following:

For AIX platforms:

First ensure that your xlC files (which constitute the run-time library for the standard AIX C++ compiler) meet one of the following requirements:

Use the following command to confirm your version:

lslpp -ha "xlC.aix*.rte"

(If your xlC fileset is outdated and you start the Z and I Emulator for Web ServiceManager with Certificate Management active, errors occur.)

Next make the following specifications:

Once you have completed these steps, IKEYCMD should run from any directory. To run an IKEYCMD command, use the following syntax:

java com.ibm.gsk.ikeyman.ikeycmd <command>

IKEYCMD command-line syntax

The syntax of the Java CLI is

java [-Dikeycmd.properties=<properties_file>]

com.ibm.gsk.ikeyman.ikeycmd <object> <action> [options]

where

Action is the specific action to be taken on the object, and options are the options, both required and optional, specified for the object and action pair.

Graphic Image
The object and action keywords are positional and must be specified in the selected order. However, options are not positional and can be specified in any order, provided that they are specified as an option and operand pair.

IKEYCMD list of tasks for Z and I Emulator for Web

IKEYCMD command-line interface tasks required for Z and I Emulator for Web are summarized in the following sections of this appendix:

Creating a new key database

A key database is a file that the server uses to store one or more key pairs and certificates. This is required to enable secure connections between the Z and I Emulator for Web server and clients. Before configuring TLS communication, you need to create the ServerKeyStore.jks java keystore file in your_install_directory\bin for Windows and your_install_directory/bin for AIX. This file is not shipped with Z and I Emulator for Web, so you need to create it after the first install.

For Windows platforms, for example, to create a new key database using the IKEYCMD command-line interface, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -keydb -create

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -type cms -expire <days> -stash

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Graphic Image
Whenever you create or make changes to the ServerKeyStore.jks file, you need to stop and restart the Z and I Emulator for Web Service Manager.

Setting the database password

When you create a new key database, you specify a key database password. This password protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key. Changing the key database password frequently is a good practice.

Use the following guidelines when specifying the password:

Graphic Image
Keep track of expiration dates for the password. If the password expires, a message is written to the error log. The server will start, but there will not be a secure network connection if the password has expired.

Changing the database password

To change the database password, do the following:

For Windows platforms, for example, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -keydb -changepw

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -new_pw <new_password> -expire <days> -stash

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Listing CAs

To display a list of trusted CAs in the ServerKeyStore.jks database, do the following:

For Windows platforms, for example, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -list CA 

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -type cms

where your_install_directory is your Z and I Emulator for Web installation directory.

By default, ServerKeyStore.jks comes with the CA certificates of the following well-known trusted CAs:

Creating a new key pair and certificate request

To create a public-private key pair and certificate request, do the following:

  1. For Windows platforms, for example, enter the following command:
    java com.ibm.gsk.ikeyman.ikeycmd -certreq -create
    -db your_install_directory\bin\ServerKeyStore.jks
    -pw <password> -size <1024 | 512> -dn <distinguished_name>
    -file <filename> -label <label>
    where your_install_directory is your Z and I Emulator for Web installation directory.

    Note the following descriptions:

    • -size: key size of 512 or 1024
    • -label: label attached to certificate or certificate request
    • -dn: X.500 distinguished name. This is input as a quoted string of the following format: (Only CN, O, and C are required; CN=common_name, O=organization, OU=organization_unit, L=location, ST=state/province, C=country.)
      "CN=weblinux.raleigh.ibm.com,O=ibm,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"
    • -file: name of file where the certificate request will be stored. By default, Z and I Emulator for Web uses the name certreq.arm and it should be stored in your_install_directory\bin (where your_install_directory is your Z and I Emulator for Web installation directory), where ServerKeyStore.jks is located.
  2. Verify that the certificate was successfully created.

    a. View the contents of the certificate request file you created.

    b. Make sure the key database recorded the certificate request:

    java com.ibm.gsk.ikeyman.ikeycmd -certreq -list
    -db <filename> -pw <password>

    You should see the label listed that you just created.

  3. Send the newly created file to a certificate authority.

Storing the server certificate

Receiving a CA-signed certificate

Use this procedure to receive an electronically mailed certificate from a certificate authority (CA), designated as a trusted CA on your server. By default, the following CA certificates are stored in the ServerKeyStore.jks key database and marked as trusted CA certificates:

The Certificate Authority may send more than one certificate. In addition to the certificate for your server, the CA may also send additional Signing certificates or Intermediate CA Certificates. For example, Verisign includes an Intermediate CA Certificate when sending a Global Server ID certificate. Before receiving the server certificate, receive any additional Intermediate CA certificates. Follow the instructions in Storing a CA certificate to receive Intermediate CA Certificates.

Graphic Image
If the CA who issues your CA-signed certificate is not a trusted CA in the key database, you need to first store the CA certificate and designate the CA as a trusted CA. Then you can receive your CA-signed certificate into the database. You cannot receive a CA-signed certificate from a CA who is not a trusted CA. For instructions, see Storing a CA certificate

For Windows platforms, for example, to receive the CA-signed certificate into a key database, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -receive -file <filename>

-db your_install_directory\bin\ServerKeyStore.jks -pw <password>

-format <ascii | binary> -default_cert <yes | no>

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Storing a CA certificate

For Windows platforms, for example, to store a certificate from a CA who is not a trusted CA, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -add

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -label <label> -format <ascii | binary>

-trust <enable |disable> -file <file>

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Graphic Image
You need to stop and restart the Z and I Emulator for Web Service Manager after doing this.

Creating a self-signed certificate

It usually takes two to three weeks to get a certificate from a well-known CA. While waiting for an issued certificate, use IKEYCMD to create a self-signed server certificate to enable TLS sessions between clients and the server. Use this procedure if you are acting as your own CA for a private Web network.

For Windows platforms, for example, to create a self-signed certificate, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -create

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -size <1024 | 512> -dn <distinguished name>

-label <label> -default_cert <yes or no>

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Making server certificates available to clients

All the certificates in the ServerKeyStore.jks are available to the Z and I Emulator for Web server. However, in some of the configurations, one of these certificates must also be made available to the clients that access the server. In the cases where your server uses a certificate from an unknown CA, the root of that certificate must be made available to the client. If your server uses a self-signed certificate, then a copy of that certificate must be made available to the clients.

For Z and I Emulator for Web downloaded and cached clients, this is done by extracting the certificate to a temporary file and creating or updating a file named CustomizedCAs.p12, which should be present in the Z and I Emulator for Web publish directory.

To create the CustomizedCAs.p12 file for downloaded or cached clients, enter the following command:

java com.ibm.gsk.ikeyman -keydb -create -db

CustomizedCAs.p12 -pw zieweb -type pkcs12

The default password is zieweb.

Adding the root of an unknown CA to CustomizedCAs.p12

First, extract the CA's root certificate or a self-signed certificate from the ServerKeyStore.jks key database file. To do this for Windows, for example, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -extract

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -label <label> -target cert.arm -format ascii

where your_install_directory is your Z and I Emulator for Web installation directory.

Note the following descriptions:

Now, add this CA root certificate to the CustomizedCAs.p12 file. To add a CA root certificate or a self-signed certificate to the list of signers in CustomizedCAs.p12, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -add

-db CustomizedCAs.p12 -pw zieweb -label <label>

-file cert.arm -format ascii -trust <enable | disable>

For older clients, to add this CA root certificate to the CustomizedCAs.class file, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -add

-db CustomizedCAs.class -label <label>

-file cert.arm -format ascii -trust <enable | disable>

Note the following descriptions:

Graphic Image
Stop and restart the Z and I Emulator for Web Service Manager after completing this task.

For older clients, you need to convert the CustomizedCAs.p12 file to CustomizedCAs.class file for download or cached clients by entering the following command. The command appears on three lines, but you should type it on one line.

..\zieweb_jre\jre\bin\java -cp ..\lib\sm.zip; 
com.ibm.eNetwork.HOD.convert.CVT2SSLIGHT
CustomizedCAs.p12 zieweb CustomizedCAs.class 

Exporting keys

To export keys to another key database or to export keys to a PKCS12 file, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -export -db <filename>

-pw <password> -label <label> -type <cms | jks | jceks | pks12>

-target <filename> -target_pw <password>

-target_type <cms | jks | jceks | pkcs12> -encryption <strong | weak>

Note the following descriptions:

Importing keys

To import keys from another key database, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -import -db <filename>

-pw <password> -label <label> -type <cms | jks | jceks | pks12> -target

<filename> -target_pw <password> -target_type <cms | jks | jceks | pks12>

To import keys from a PKCS12 file,enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -import -file <filename>

-pw <password> -type pkcs12 -target <filename>

-target_pw <password> -target_type <cms | jks | jceks | pks12>

Note the following descriptions:

Showing the default key in a key database

For Windows platforms, for example, to display the default key entry, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -cert -getdefault

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password>

where your_install_directory is your Z and I Emulator for Web installation directory.

Storing the encrypted database in a stash file

For a secure network connection, store the encrypted database password in a stash file. For Windows platforms, for example, to store the password while a database is created, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -keydb -create

-db your_install_directory\bin\ServerKeyStore.jks

-pw <password> -type cms -expire <days> -stash

where your_install_directory is your Z and I Emulator for Web installation directory.

For Windows platforms, for example, to store the password after a database has been created, enter the following command:

java com.ibm.gsk.ikeyman.ikeycmd -keydb -stashpw

-db your_install_directory\bin\ServerKeyStore.jks -pw <password>

where your_install_directory is your Z and I Emulator for Web installation directory.

IKEYCMD command-line parameter overview

The following table describes each action that can be performed on a specified object.

Object Action Description
-keydb -changepw Change the password for a key database
-convert Convert the key database from one format to another
-create Create a key database
-delete Delete the key database
-stashpw Stash the password of a key database into a file
-cert -add Add a CA certificate from a file into a key database
-create Create a self-signed certificate
-delete Delete a CA certificate
details List the detailed information for a specific certificate
-export Export a personal certificate and its associated private key from a key database into a PKCS#12 file, or to another key database
-extract Extract a certificate from a key database
-getdefault Get the default personal certificate
-import Import a certificate from a key database or PKCS#12 file
-list List all certificates
-modify Modify a certificate (NOTE: Currently, the only field that can be modified is the Certificate Trust field)
-receive Receive a certificate from a file into a key database
-setdefault Set the default personal certificate
-sign Sign a certificate stored in a file with a certificate stored in a key database and store the resulting signed certificate in a file
-certreg -create Create a certificate request
-delete Delete a certificate request from a certificate request database
-details List the detailed information of a specific certificate request
extract Extract a certificate request from a certificate request database into a file
-list List all certificate requests in the certificate request database
-recreate Recreate a certificate request
-help Display help information for the IKEYCMD command
-version Display IKEYCMD version information

IKEYCMD command-line options overview

The following table shows each option that can be present on the command line. The options are listed as a complete group; however, their use is dependent on the object and action specified on the command line.

Option Description
-db Fully qualified path name of a key database
-default_cert Sets a certificate to be used as the default certificate for client authentication (yes or no). The default is no.
-dn X.500 distinguished name. Input as a quoted string of the following format (only CN, O, and C are required):

"CN=Jane Doe,O=HCL,OU=Java Development,L=Endicott, ST=NY,ZIP=13760,C=country"

-encryption Strength of encryption used in certificate export command (strong or weak). The default is strong.
-expire Expiration time of either a certificate or a database password (in days). Defaults are 365 days for a certificate and 60 days for a database password.
-file File name of a certificate or certificate request (depending on specified object)
-format Format of a certificate (either ascii for Base64_encoded ASCII or binary for Binary DER data). The default is ascii.
-label Label attached to a certificate or certificate request
-new_format New format of key database
-new_pw New database password
-old_format Old format of key database
-pw Password for the key database or PKCS#12 file. See Creating a new key database.
-size Key size (512 or 1024). The default is 1024.
-stash Indicator to stash the key database password to a file. If specified, the password will be stashed in a file.
-target Destination file or database.
-target_pw Password for the key database if -target specifies a key database. See Creating a new key database.
-target_type Type of database specified by -target operand (see -type).
-trust Trust status of a CA certificate (enable or disable). The default is enable.
-type Type of database. Allowable values are cms (indicates a CMS key database), jce (indicates Sun's proprietary Java Cryptography Extension), jceks (indicates Sun's proprietary Java Cryptography Extension Key Store), or pkcs12 (indicates a PKCS#12 file).
-x509version Version of X.509 certificate to create (1, 2 or 3). The default is 3.

Command-line invocation

The following is a list of each of the command line-invocations, with the optional parameters specified in italics.

For simplicity, the actual Java invocation, java com.ibm.gsk.ikeyman.ikeycmd, is omitted from each of the command invocations.

-keydb -changepw -db <filename> -pw <password> 
-new_pw <new_password> -stash -expire <days>

-keydb -convert -db <filename> -pw <password> 
-old_format <cms | webdb> -new_format <cms>

-keydb -create -db <filename> -pw <password> -type <cms | jks | jceks | pks12>
-expire <days> -stash

-keydb -delete -db <filename> -pw <password>

-keydb -stashpw -db <filename> -pw <password>

-cert -add -db <filename> -pw <password> -label <label> 
-file <filename> -format <ascii | binary> -trust <enable | disable>

-cert -create -db <filename> -pw <password> -label <label> 
-dn <distinguished_name> -size <1024 | 512> -x509version <3 | 1 | 2>
-default_cert <no | yes>

-cert -delete -db <filename> -pw <password> -label <label>

-cert -details -db <filename> -pw <password> -label <label>

-cert -export -db <filename> -pw <password> -label <label> 
-type <cms | jks | jceks | pks12> -target <filename> -target_pw <password>
-target_type <cms | jks | jceks | pkcs12> -encryption <strong | weak>

-cert -extract -db <filename> -pw <password> -label <label> 
-target <filename> -format <ascii | binary>

-cert -getdefault -db <filename> -pw <password>

-cert -import -db <filename> -pw <password> -label <label> 
-type <cms | jks | jceks | pks12> -target <filename> -target_pw <password> 
-target_type <cms | jks | jceks | pks12>

-cert -import -file <filename> -type <pkcs12> -target <filename>
-target_pw <password> -target_type <cms | jks | jceks | pks12>

-cert -list <all | personal | CA | site> -db <filename> 
-pw <password> -type <cms | jks | jceks | pks12>

-cert -modify -db <filename> -pw <password> -label <label> 
-trust <enable | disable>

-cert -receive -file <filename> -db <filename> -pw <password>
-format <ascii | binary> -default _cert <no | yes>

-cert -setdefault -db <filename> -pw <password> -label <label>

-cert -sign -file <filename> -db <filename> -pw <password> 
-label <label> -target <filename> -format <ascii | binary> 
-expire <days>

-certreq -create -db <filename> -pw <password> -label <label> 
-dn <distinguished_name> -size <1024 | 512> -file <filename>

-certreq -delete -db <filename> -pw <password> -label <label>

-certreq -details -db <filename> -pw <password> -label <label>

-certreq -extract -db <filename> -pw <password> -label <label> 
-target <filename>

-certreq -list -db <filename> -pw <password>

-certreq -recreate -db <filename> -pw <password> -label <label> 
-target <filename>

-help

-version

User properties file

In order to eliminate some of the typing on the Java CLI invocations, user properties can be specified in a properties file. The properties file can be specified on the Java command-line invocation via the -Dikeycmd.properties Java option. For Windows platforms, a sample properties file, ikminit_hod.properties, is supplied in your_install_directory\bin, where your_install_directory is your Z and I Emulator for Web installation directory. For AIX platforms, this file is supplied in your_install_directory/bin. These installation directories contain the default setting for Z and I Emulator for Web.

Appendix C. P12 Keyring utility

A graphical Certificate Management utility (available on Windows and AIX platforms) is provided to allow you to create certificate requests, receive and store certificates, and create self-signed certificates. The P12 Keyring utility is provided mainly for platforms that do not have the Certificate Management Utility to create a keyring database with root certificates of self-signed and unknown Certificate Authority certificates. However, it can be used on any Z and I Emulator for Web platform. This utility provides system administrators with an easy way to create and deploy an TLS keyring database.

The P12 Keyring utility is written in Java. It obtains a server certificate from a Telnet or an FTP server (or a Redirector) that is configured for TLS. An TLS connection is made to the specified server and TLS port. If the port is not provided, the well-known secure Telnet or FTP port is used. The server's certificate will be extracted and added to the specified p12 file.

Access to the keyring database is password-protected. A password prompt will be given before any of the commands are performed. If the specified keyring file does not exist, it will be created and the password will be stored in the file.

Graphic Image
The Z and I Emulator for Web TLS support requires the password to be zieweb. If you are adding a private certificate to the keyring database, another password prompt will be given for the second p12 file.

Usage

P12Keyring p12FileName connect ipaddr[:port] [ftp]        	
P12Keyring p12FileName add p12FileName2        	
P12Keyring p12FileName list  

Options

connect - establishes an TLS connection to the specified ipaddr and port. The port number and ftp keyword are optional. If the port number is not specified, the default secure Telnet port 443 or the default secure FTP port 990 will be used.

If the ftp keyword is specified, the connection is to be made to a secure FTP server that is configured for security. There are two types of security options for FTP servers:

If the ftp keyword is specified but the port number is not specified or it is 990, implicit security negotiations are performed. If the ftp keyword is specified and the port number is not 990, explicit security negotiations are done by issuing AUTH TLS command first.

add - adds a private client certificate to the specified keyring database.

list - displays a list of certificates stored in the specified keyring database.

Examples

Windows:

C:\your_install_dir\lib\P12Keyring c:\your_install_dir\ZIEWeb\CustomizedCAs 
connect myServer.raleigh.ibm.com:702  

C:\your_install_dir\lib\P12Keyring c:\your_install_dir\ZIEWeb\CustomizedCAs 
connect myFTPServer.raleigh.ibm.com:5031 ftp 

where your_install_dir is your Z and I Emulator for Web installation directory.

Unix:

cd your_install_directory/ZIEWeb
Java -classpath .;your_install_dir/lib/sm.zip \
com.ibm.hod5sslight.tools.P12Keyring CustomizedCAs connect 
myServer.raleigh.ibm.com:702 	 

where your_install_dir is your Z and I Emulator for Web installation directory.

Appendix D. Native platform launcher command line options

When you enter the following command line options with your native platform launcher, the launcher passes them to the Z and I Emulator for Web install as installation parameters. Options that suppress the GUI wizard are marked accordingly.

Table 11. Command line options
Option Purpose Example usage
-console

(Suppresses the GUI wizard)

Installs Z and I Emulator for Web in console mode. install.exe
-log #!filename

where # echoes the display to standard output and !filename is the name of the log file. If you specify ! without a file name, the default log file name is used.

Generates an installation file log with the name specified. hodinstallwin.exe -log #!\mydirectory\logfile
-options filename Installs Z and I Emulator for Web with command line options that set specified properties for the installation. hodinstallwin.exe -silent -options c:\mydirectory\responseFile
-options-record filename Generates an options text file recording your responses to the Z and I Emulator for Web install wizard, establishing them as default values for installation variables. hodinstallwin.exe -options-record responses.txt
-options-template filename Generates an options text file containing the default installation values. hodinstallwin.exe -options-template template.txt
-silent

(Suppresses the GUI wizard)

Installs Z and I Emulator for Web in silent mode, accepting all default installation values. hodinstallwin.exe -silent

The following additional command line options apply only to the process of calling and running the installation program. Enter them at the command line with the native platform launcher.

Table 12. Launch-specific command line options
Option Purpose Example usage
-is:logfilename Generates a log file for the native launcher's JVM searches. hodinstallwin.exe -is:log myLogFile.txt
-is:silent Prevents the display of the launcher user interface (UI) while JVM searches and other initializations are taking place. (Commonly used with the command line option silent.) hodinstallwin.exe -is:silent
-is:tempdirdirectory Sets the temporary directory used by the Z and I Emulator for Web install. hodinstallwin.exe -is:tempdir "c:\temp"

Appendix E. Notices

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

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

HCL may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

HCL
330 Potrero Ave.
Sunnyvale, CA 94085
USA
Attention: Office of the General Counsel 

HCL TECHNOLOGIES LTD. PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

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

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

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

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

HCL
330 Potrero Ave.
Sunnyvale, CA 94085
USA
Attention: Office of the General Counsel 

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by HCL under terms of the HCL Customer Agreement, HCL International Program License Agreement or any equivalent agreement between us.

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

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Appendix F. Trademarks

HCL, the HCL logo, and hcl.com are trademarks or registered trademarks of HCL Technologies Ltd., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM® or other companies.