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 ZIE Host Access Toolkit in console mode

The ZIE 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 ZIE 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:

• Silent installation road maps
• Installation Manager command-line arguments for silent mode

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.

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.

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:

• You plan to configure Z and I Emulator for Web so that client communication with the Service Manager is necessary (as in the configuration server-based and combined deployment models, if you enable License-Use Counting, or if you use the Redirector).
• A firewall protects the server(s) on which you plan to maintain session configuration information, and you do not want to open a port in that firewall to give outside clients access to the Service Manager.

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.

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 2.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 2.0 package group. Press Enter.
5. Review the details of the Z and I Emulator for Web 2.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.

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 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: 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. 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. 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. Use your browser to point to clients.html on your Web server, for example, http://host/alias/clients.html. 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. 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:

• Configuration models. Configuration models define the high-level approach you wish to follow with regard to where you define your sessions and where any user preferences are kept. For more information about configuration models, refer to Planning for deployment.
• Preloads. Z and I Emulator for Web runs as an applet or application and must download code to the users' machines. By default, the Z and I Emulator for Web client downloads all of the components, but you may reduce the download size by removing those components that are not needed.
• Web Start client. The Web Start client caches the client code and additionally allows you to run Z and I Emulator for Web without a browser.
• Web page appearance (custom HTML templates). You can easily set up a template that the Deployment Wizard will use to generate your HTML files. This feature makes it easy to add your own background, banners, etc.
• Web Start options. When running the Web Start client, the code must be upgraded when newer versions of the client are available. You can use a number of Deployment Wizard options to control the upgrades.
• Location of the Z and I Emulator for Web install (code base). Usually, Deployment Wizard files are placed in the Z and I Emulator for Web server's publish directory. However, sometimes it may be useful to put these files in a location that is independent of the Z and I Emulator for Web server so that they can be granted different security controls or make Z and I Emulator for Web server upgrades easier, for example.
• WebSphere Portal. WebSphere Portal provides a framework for plugging content extensions known as portlets into a Web site. Portlets are applications that organize content from various sources and display it on a single HTML file in a browser window. The HTML files that are used to launch Z and I Emulator for Web sessions can be deployed as portlets, allowing users to access Z and I Emulator for Web through a portal interface.
• Windows Domain logon. If your users are logged on to a Windows domain, this option automatically logs users on to Z and I Emulator for Web using their Windows user name. This option is available only when using the configuration server-based model in the Deployment Wizard.

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:

• Session properties. All of the session properties can be configured, including connection information, security, etc. Each of the fields may be locked to prevent users from updating them.
• Runtime options. When configuring a session, you can launch the session and configure features such as session size and placement, colors, toolbar customization, and macros. You can configure runtime options in the Deployment Wizard and the Full administration client.
• Disabling user functions. You can disable almost any of the functions that users normally receive as part of their Z and I Emulator for Web session, such as bookmarking, creating or running macros, etc.

Using the Deployment Wizard

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

• If you automatically installed the Deployment Wizard as part of the Windows Z and I Emulator for Web server, go to Start > Programs > HCL Z and I Emulator for Web > Administration > Deployment Wizard.

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:

• 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 administration or new user client.

  To log on as the administrator the first time after the initial installation:

  1. Type the default user ID: admin.
  2. Type the default password: password.
  3. Click Log On.
• Load the dashboard_xx.html file, where xx is your two-letter language suffix, into your browser to view links to all the available administration and new user clients, plus other predefined clients. dashboard_xx.html is located in the publish directory.

Administration clients

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

• Manage users, groups, and sessions
• Configure, manage and trace the Redirector service
• Configure Database On-Demand
• Enable security
• View trace and message logs
• Disable functions to end users

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)²

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.

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:

• Add, update, and delete groups
• Add, update, and delete users from groups
• Add, update, and delete sessions from users or groups
• List existing users and groups in output files, as products of unique searches
• List existing users and groups in output files that can be reused as input

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)¹

Loads the New User client in a cached environment with problem determination (session logging and tracing).

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 describes how to access Z and I Emulator for Web emulator clients.
• Selecting the appropriate client discusses how to decide which client is best for your needs.
• Web Start client discusses how to use the Web Start client, including installing and removing it, configuring your Web browser, using Web Start with Windows restricted users, and upgrading.
• Deploying customer-supplied Java archives and classes describes how to deploy Java archives and class files to your clients.

Loading emulator clients

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 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:

• An HTML file that you create with the Deployment Wizard.
• One of several generic predefined HTML files included with Z and I Emulator for Web.

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

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 HCL Technologies Ltd. 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.

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 (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 , 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.

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

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.8 or higher versions of the Java Runtime Environment. For more information about Java Web Start, refer to http://www.javasoft.com. Z and I Emulator for Web Version 2.0 recommends Java 1.8 or higher.

The ZIEWeb Web Start client has the following requirements:

• JRE 1.8 or later is required to use HTTPS to access files from the Web server.
• JRE 1.8 or later is required to use an HTTP proxy with Web Start.
• Session properties that say use Browser settings (like proxy server or TLS) cannot be used with Web Start.

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, myzieweb.jnlp) to your end users. Once the file is distributed, users can type start myzieweb.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. 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 new HTML file.
2. Use the Deployment Wizard a second time to edit the HTML file that you created in the previous step. (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 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.

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:

• You want your users to run macros that call customer-supplied Java methods.
• You want your users to run a customer-supplied applet with the session (either started automatically with the session or launched using the Actions > Run Applet... selection on the menu of the session window).

  For Java limitations on running customer-supplied applets, see Limitations with customer-supplied applets and Java.

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

• Using the AdditionalArchives HTML parameter in the Deployment Wizard. See Using the AdditionalArchives HTML parameter.
• Copying the files to the Z and I Emulator for Web server's publish directory. See Deploying from the Publish directory.

The deployment method you choose depends on:

• The type of file deployed (Java classes and Java archives)
• Where the files will be deployed (Z and I Emulator for Web server or client workstation)
• The type of client platform and the type of browser.

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 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 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 . 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:

• When you want to deploy Java class files to a Z and I Emulator for Web server. The Java class files must not belong to any Z and I Emulator for Web package.

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:

• When you create your archive (.jar), verify that the path of each class file is correct. For example, the path for com.mycompany.MyClass should be com\mycompany\. It should not be C:\MyTestDirectory\com\mycompany\, and it should not be blank (since the class file is part of a package).
• Verify that the proper permissions are set for your archive files. That is, in operating systems that use file permissions, such as Linux, AIX, Unix, and z/OS, the file permissions for the archive files should be set to 755 (that is, rwxr-xr-x).
• If you have two different client pages that specify different AdditionalArchives parameters, you need to close and restart the browser when switching from one page to another. Otherwise, when you switch from one page to another, the client is not reloaded and, as a result, the AdditionalArchives parameter is not checked.

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:

• Text and graphical interfaces for constructing SQL statements and File Upload statements.
• The ability to save and reuse SQL statements and File Upload statements.
• For SQL statements:
  • The ability to run an SQL statement and display the results.
  • The ability to save the results of an SQL statement into a file in various file formats, including XML (see File formats for database access in this manual).
• For File Upload statements:
  • The ability to use the following File Upload types: create, replace, append, and update.
  • The ability to read data files in various file formats, including XML (see File formats for database access in this manual).

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:

• An end user running a Java-enabled browser automatically runs the Java version of the Database On-Demand client.

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:

• 3270 Display session
• 5250 Display session
• VT Display session

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:

• Connect your browser to a predefined Database On-Demand HTML file, by typing the URL of the HTML file into the address field of your browser (or by clicking a link that directs the browser to that URL). The format for the URL is:

  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 of the publish directory, and client_name is the name of the HTML file. For example, assuming that www.myZIEServer.com is your Z and I Emulator for Web server and that zieweb is the alias of the publish directory, then the URL for the download version of the Database On-Demand client is:

  http://www.myZIEServer.com/zieweb/database.html

• Connect your browser to the HCL Z and I Emulator for Web Clients HTML file, and then click the link for the Database On-Demand client that you want to run. The URL of the Clients HTML file is:

  http://server_name/zie_alias/dashboard_xx.html

  where server_name and zie_alias have the same meanings as above. In the name of the file dashboard_xx, the xx is a two-letter mnemonic for the language that you want to use. For example, for English, the file is named dashboard_en.html, and the full URL is (assuming the same server and alias as above):

  http://www.myZIEServer.com/zieweb/dashboard_en.html

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)

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

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. Use jar file names, even if your clients will be using Internet Explorer (the names will be converted to cab file names later).

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 component names:

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:

• They provide a convenient way to store, edit, and administer macros, all from one easy-to-access location.
• They allow easy sharing of macros among multiple users and across any number of sessions.
• They eliminate the need to import macros into the Z and I Emulator for Web session, and can therefore reduce the size of the session. The macros are only downloaded to the user's machine if and when the user accesses them.
• You can edit macros and replace the files in the server macro library at any time without regenerating Z and I Emulator for Web sessions or modifying the HTML files. Any changes you make are automatically available the next time a user requests that macro.

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.

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 , some of the HTML is generated using JavaScript, and HTML parameters are specified within a JavaScript array or using JavaScript document.write statements.

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.

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:

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 .

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:

• Example1.html
• z_Example1.html
• Example_J2.html

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
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
	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 zie_Locale = '';
var zie_AppName ='';
var zie_AppHgt = '340';
var zie_AppWid = '550';
var zie_CodeBase = '/zieweb/';
var zie_Comps = 'HABASE;ZIEBASE;ZIEIMG;HACP;HAFNTIB;HAFNTAP;HA3270;ZIECFG;HA5250';
var zie_Archs = 'habasen.jar,ziebasen.jar,zieimg.jar,hacp.jar,hafntib.jar,hafntap.jar,
                 ha3270n.jar,ziecfgn.jar,ha5250n.jar';

var zie_URL = new String(window.location);
var zie_DebugOn = false;

var hZie_AppletParams = new Array;
hZie_AppletParams[1] = '<PARAM NAME="ShowDocument"      VALUE="_parent">';
hZie_AppletParams[3] = '<PARAM NAME="ParameterFile"     VALUE="ZIEWebData\\Example1\\params.txt">';
hZie_AppletParams[4] = '<PARAM NAME="JavaScriptAPI"     VALUE="false">';
hZie_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".
 
hZie_AppletParams[6]='<PARAM NAME="EnableHTMLOverrides" VALUE="true">';
hZie_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.
hZIe_AppletParams[8]='<PARAM NAME="Luname" VALUE="3270 
                       Display=<%=lunames.get(request.getRemoteAddr())%>">';

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


var pg = buildJ2Page(db);
pg += writeAppletParameters();
pg += '</APPLET>';
if(zie_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 2.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 zie_Locale = '';
var zie_jsapi=false;
var zie_AppName ='';
var zie_AppHgt = '80%';
var zie_AppWid = '80%';
var zie_CodeBase = '/zieweb/';
var zie_FinalFile = 'z_example2.html';
var zie_JavaType = 'java2';
var zie_Obplet = '';
var zie_jars = 'habasen.jar,ziebasen.jar,zieimg.jar,hacp.jar,ziesignn.jar,ha3270n.jar,
                ziecfgn.jar,ha5250n.jar';

var zie_URL = new String(window.location);
var zie_DebugOn = false;
var zie_SearchArg = window.location.search.substring(1);

var zie_AppletParams = new Array;
zie_AppletParams[0] = '<PARAM NAME="ParameterFile" VALUE="ZIEWebData\\example2\\params.txt">';
zie_AppletParams[1] = '<PARAM NAME="ShowDocument"  VALUE="_parent">';
zie_AppletParams[2] = '<PARAM NAME="JavaScriptAPI" VALUE="' + zie_jsapi + '">';
zie_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.

zie_AppletParams[4] = <PARAM NAME="EnableHTMLOverrides" VALUE="true">;
zie_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.

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

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

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

function getZIEMsg(msgNum) {
  return ZIEFrame.zieMsgs[msgNum];
}

function getZIEFrame() {
  return ZIEFrame;
}

var lang = detectLanguage(zie_Locale);
document.writeln('<FRAMESET cols="*,10" border=0 FRAMEBORDER="0">');
document.writeln('<FRAME    src="/zieweb/ziedetect_' + lang + '.html" name="ZIEFrame">');
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:

• MOUNT the separate File System on the current private directory location, such as /usr/lpp/ZIEWeb/zieforweb/private.
• Create a symbolic link to the private directory location as follows:
  1. Do a TSO MKDIR to create a different mount point, such as /etc/ZIEWeb/private.
  2. Rename, or back up and delete, your original private directory.
  3. Create a symbolic link from the expected location, /usr/lpp/ZIEWeb/zieforweb/private, to point to the real location, /etc/ZIEWeb/private. Use the following link command:

     ln -s /etc/ZIEWeb/private /usr/lpp/ZIEWeb/zieforweb/private 

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:

• To set up the Service Manager, follow the instructions in Configuring, starting, and stopping the Z and I Emulator for Web Service Manager on IBM System i.
• To use the Deployment Wizard with an IBM System i system, follow the instructions in Using the Deployment Wizard with IBM System i.
• To configure security, follow the instructions in Configuring IBM System i servers for secure connection.
• To understand the requirements for Unicode support using Coded Character Set Identifiers see Unicode Support for i/OS and OS/400.

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                         
		  $  

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 V2.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 v2.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

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.hcl.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 3 to 5 for 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

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.hcl.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

   .

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.

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:

• IBM Cryptographic Access Provider
• IBM Client Encryption
• Host Servers
• Digital Certificate Manager

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 QHCL_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.

Eclipse-Plugin support

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

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 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 Java plugin.

   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.

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. 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 JRE and has been resolved in IBM 1.8 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.

   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.

   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: set DB2INSTANCE=ldapdb2 db2 connect to ldapdb2 db2 update db cfg for ldapdb2 using APP_CTL_HEAP_SZ 512 db2 force application all db2 terminate db2stop 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.

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.

   The Redirector configuration is not migrated to the directory server.

   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. 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 HCL 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.

Appendix B. 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.