Minimum Requirements

How to Install BlueZone Web-to-Host

Miscellaneous

How BlueZone Web-to-Host Works

BlueZone Web-to-Host Logic Flow Diagram

Introduction

BlueZone Web-to-Host is a state-of-the-art secure IBM host access solution that utilizes the convenience of a web browser to install, configure, update and maintain the end user's host emulation software.

This is accomplished by simply copying the necessary BlueZone Web-to-Host files to a web server that can be accessed from the end user's browser. A customizable web page is provided which contains links to all the BlueZone Web-to-Host emulation clients.

These emulation clients include:

• BlueZone 3270 Display Emulator
• BlueZone 3270 Printer Emulator
• BlueZone 5250 Display Emulator
• BlueZone 5250 Printer Emulator
• BlueZone FTP Client
• BlueZone VT - VT100, VT220, VT320, VT420 Emulator

Scope

The scope of this QuickStart Guide is to provide the necessary steps to perform a basic web server installation and to configure BlueZone Web-to-Host to launch a display session that connects to an IBM host of your choice.

This QuickStart Guide assumes that you are familiar with the web server that you are installing this product on and have the knowledge and the resources necessary to install, configure and access the web pages that are supplied with BlueZone Web-to-Host.

This Quick Start Guide is not intended to address the more in-depth features of BlueZone Web-to-Host, nor is it intended to replace the BlueZone Web-to-Host Administrator's Guide.

The BlueZone Web-to-Host Administrator's Guide is a comprehensive guide for the installation configuration and maintenance of BlueZone Web-to Host.  It can be found on the BlueZone CD in the following location:

BlueZone Web-to-Host/docs/admin.chm

The BlueZone Web-to-Host Administrator's Guide is written in the standard Microsoft HTML Help format.

To launch the BlueZone Web-to-Host Administrator's Guide , click here.
(when prompted to Save or Open, choose Open)

BlueZone Web-to-Host Deployment Options

One of the most powerful features of BlueZone Web-to-Host is its unique ability to provide several deployment options.  BlueZone Web-to-Host offers three different options to deploy the BlueZone clients.  They are:

• Standard Web-to-Host Client
• Embedded Web-to-Host Client
• Served Desktop Client

All three options are installed on the web server and initiated by the end user in the exact same manner. The end user simply clicks on a web link to start the process.

Standard Web-to-Host Client - This deployment method is the standard default mode for BlueZone Web-to-Host.  The end user launches a web browser, clicks on a link, and BlueZone is automatically installed and launched.  This method also provides for "automatic" updates of the BlueZone emulation clients.

When launched as a Standard Web-to-Host Client, the BlueZone emulation client "floats" over the browser and the desktop.

Embedded Web-to-Host Client - This deployment option brings the power of the HTML web page into the equation. The Embedded Web-to-Host Client option works essentially the same way as the Standard Web-to-Host Client except that the BlueZone emulation client launches inside the browser window, and is embedded either full screen or at a fixed position within the web page. The exact position of the BlueZone emulator is completely configurable by the BlueZone administrator.  This method also provides for "automatic" updates of the BlueZone emulation clients.

With this option, you can design web pages that include frames, scripts, text, links, buttons or graphics right on the HTML page in harmony with the embedded BlueZone emulation client.

When launched as an Embedded Web-to-Host Client, the BlueZone emulation client is part of the web page.

Served Desktop Client - This deployment option is the only one of its kind in the industry.  It brings the benefits and familiarity of a BlueZone Desktop client with the convenience and advantages of a web-to-host client install.  This is a great option when you can't depend on the 100% availability of your web server. The BlueZone emulator is initially deployed by the web server but can be launched from the desktop thereafter.  BlueZone updates are also delivered via the web server. We call the Served Desktop Client our "best of both worlds" option.

When launched as a Served Desktop Client, the BlueZone emulation client is installed and launched just like any standard Windows desktop application but which can be updated upon visiting the web server.

NOTE It is strongly recommended that when installing BlueZone Web-to-Host for the first time, that you install it as a Standard Web-to-Host Client first regardless of which deployment option you ultimately desire. It's best to master the basic installation first then make your delivery option changes to a known working version of the Standard Web-to-Host Client Option.

In fact, the installation portion of this QuickStart Guide is written for the Standard Web-to-Host Client option only.  The Embedded Web-to-Host Client and the Served Desktop Client options are discussed in the BlueZone Web-to-Host Administrator's Guide.

Getting Started

What's Provided

The BlueZone CD that you have been provided, contains the entire BlueZone family of emulation products including the files necessary to install BlueZone Web-to-Host.  The BlueZone Web-to-Host files are specifically located in the BlueZone Web-to-Host folder of this CD.

The BlueZone Web-to-Host Emulation Clients on this CD, are by default pre-configured to connect to various host systems.  You will of course, change the default configurations to connect to your host or hosts. See Table 1 for a list of default pre-configured hosts.

Table 1 : Pre-configured Host Settings BlueZone 3270 Library of Congress BlueZone 5250 Seagull iSeries BlueZone FTP Microsoft FTP Site BlueZone VT Library of Congress

How to Install BlueZone Web-to-Host on Your Web Server

Copying the BlueZone Web-to-Host files to your web server:

Choose one of the following web servers for instructions on how to copy the BlueZone Web-to-Host files to your web server.

• Microsoft Servers running IIS
• IBM Mainframe HTTP Web Servers
• IBM iSeries HTTP Web Servers
• Other Web Servers

NOTE After completing the steps necessary to install BlueZone Web-to-Host on your web server, you will be returned here to continue with the installation procedure.

Installation Continued...

Installing the SEAGULL Activation File: Very Important

This procedure applies to both Evaluations and Licensed installations.

Installing the SEAGULL Activation File (SAF) is very simple. It's simply a matter of copying the SAF file to the correct directory on the web server. By default, BlueZone comes with an "non-working" SAF file as a placeholder.

NOTE BlueZone emulators will launch but will not be able to connect to a host without a valid Software Activation File (SAF).

How to Install the SEAGULL Activation File:

1. Locate your SEAGULL Activation File (the file name is seagull.saf) which was sent as an email attachment to you, or the person who ordered BlueZone.  This email would have been sent from "SEAGULL Software Activation".

HELP! I can't locate my SEAGULL Activation File.  Click here, to send an email to Seagull Software's Order Administration Department.

2. Copy the SAF file to the directory on the web server, that contains BlueZone Web to Host files, overwriting the existing SAF file.

NOTE If you don't have your SAF file at this time, you may continue with the installation, just be aware that when you test the connection, BlueZone sessions will launch, but you will receive the following error:

This error will go away once you have installed a valid SAF file.

Setting "The Path" for Netscape Browsers

In order for BlueZone Web-to-Host to work properly with Netscape browsers, it is necessary to set the "path" which is located in the default.htm page.  This "path" statement lets the JavaScript know the location of the Java Plug-in files.

1. On the web server, edit the default.htm page with Notepad. The "path" statement is located at the top of the page inside an Administrators Note. It looks like this.
   
   thePath = "http://bluezone.seagullsw.com/bluezone/"
    
2. Edit thePath = value with a fully qualified URL that matches your web server.
   
   thePath = "http://www.yourhost.com/bluezone/"
    
3. Save the file and exit notepad.

CAUTION! Be sure to include the slash at the end of the path statement or else the SEAGULL Web-to-Host Control Module will not download.

Testing the Default Connections

1. From a Windows Workstation, launch your browser.
    
2. Type in the URL of your web server, followed by /bluezone (or whatever you called the folder where BlueZone Web-to-Host is installed).

Example: http://63.69.143.23/bluezone  or  http://www.myhost.com/bluezone

If your web server is set up properly, the default.htm page will launch.

3. Click the Mainframe Display link (or the iSeries Display link), and launch a display session. These sessions are pre-configured to connect to either the Library of Congress Mainframe or the Seagull iSeries.

CAUTION! It is recommended that you use a workstation other than your web server for testing.  If you use the web server as a workstation, you run the risk of creating problems with file permissions.

4. If you have both Internet Explorer users and Netscape users, be sure to test with both browsers.

NOTE When conducting browser tests, it's okay to run IE and Netscape at the same time however, you can not launch a BlueZone display session from one browser then launch the same BlueZone display session from the other.  The second session will not launch. You must close down the first BlueZone session (not the browser) before launching the same BlueZone session with the other browser.

Modifying and Saving the Display Configuration File

Once BlueZone has successfully launched with the default settings, all the components can be considered to be working and configured properly.  The next task is to customize the configuration for the specific connectivity and emulation requirements of your users.

1. Go to the default web page and launch a BlueZone mainframe or iSeries display session.
    
2. On the tool bar, click Session:Disconnect to disconnect the session.
    
3. On the tool bar, click Session:Configure which will display the Session Configuration dialog box.  as shown here:

4. Select the Connection Type (the default is TN3270E/TN5250E) and click the Configure button. You will see the TN3270E Properties dialog box.  As shown here:

5. Click the Edit button and you will see the Edit Connection dialog box. As shown here:

6. Replace the information you see with your host's information.  Connection Name can be any name you wish.  The key fields are Host Address and TCP Port. The Host Address can also be a DNS name. These two items must be correct in order for the connection to work.
    
7. If you are running TN3270E be sure to click the Enable TN3270E check box.
    
8. Click the OK button. You will now be brought back to the TN3270E Properties dialog box as shown below. It should now contain your host's information.

9. Click the OK button twice.
    
10. Go to the toolbar and click on Session:Connect.  You should now be connected to your host.
    
    Now would be a good time to make any additional configuration changes to the look and size of the display emulator. In the next step, you will be creating a new BlueZone Display Configuration File.
     
11. Go to the toolbar and select File:Save As. The following dialog box will appear:

Choose a new file name like "myhost" and click the Save button.  The file will automatically be saved with the appropriate file extension to a temporary BlueZone folder on your PC.  This temporary folder is automatically created by BlueZone the first time you launch a BlueZone session. The following is a screen shot of the temporary folder on a Windows 98 PC.

The location of this temporary BlueZone folder will vary depending on the Windows Operating System that you are using. BlueZone determines your Windows "TEMP" variable, then creates the BlueZone folder accordingly.

TIP If you are not sure of where the temporary files are stored on your PC, you can easily find out by opening the drop down box inside of the Save Configuration As dialog box as shown in the following example:

There's the path - C:\WINDOWS\TEMP\Bluezone

Copying the Configuration File and Modifying the Distribution File

1. Find the BlueZone temporary folder on your PC and copy the file that you saved in step 11 from this folder to the appropriate bluezone folder that you created on your web server.

Please refer to the following table for the correct Configuration File extension and location:

Table 2 : Configuration File Extension References BlueZone Component File Extension Web Server Folder 3270 Display Emulator .zmd \bluezone\bz3270 3270 Printer Emulator .zmp \bluezone\bz3270 5250 Display Emulator .zad \bluezone\bz5250 5250 Printer Emulator .zap \bluezone\bz5250 FTP Emulator .zft \bluezone\bzftp VT Display Emulator .zvt \bluezone\bzvt

2. Modify the BlueZone Distribution File so that the BlueZone Configuration File that you just created is served up to your users. Refer to the following table for the correct Distribution File extension and location:

Table 3 : Distribution File Extension References BlueZone Component File Extension Web Server Folder 3270 Display Emulator .e3d \bluezone\bz3270 3270 Printer Emulator .e3p \bluezone\bz3270 5250 Display Emulator .e5d \bluezone\bz5250 5250 Printer Emulator .e5p \bluezone\bz5250 FTP Emulator .eft \bluezone\bzftp VT Display Emulator .evt \bluezone\bzvt

The default BlueZone Mainframe Display Distribution File is called "display.e3d".  On the web server, open the "display.e3d" file with notepad. It should look like this:

bzmd32C4.cab,1
mfdisp1.zmd,1
seaglapl.ttf,1
../seagull.saf,1

3. Replace "mfdisp1.zmd,1" with the name of the display configuration file that you created above. The file should look like this:

bzmd32C4.cab,1
myhost.zmd,1
seaglapl.ttf,1
../seagull.saf,1

4. Save the file and exit Notepad.

Modifying the Object Tags

Object Tags are the "engine" that power BlueZone Web-to-Host.  By modifying the Object Tags, you can control exactly how BlueZone Web-to-Host is deployed. You can choose to launch a single emulator with a single session or launch several emulators with multiple sessions each, all with a single "click".  You also control the optional features of BlueZone Web-to-Host from within the Object Tag.

There are two Object Tags, one for Internet Explorer and one for Netscape Navigator. When editing Object Tags you must make your changes to both Object Tags.

1. On the web server, edit the "object_d_3.htm" file located in the bz3270 folder, with notepad.  It's best to use notepad in the full screen mode with word wrap turned off.
   
   The Object Tag is located very near the top of the page. The Object Tag will look like this.  For clarity the IE Object Tag is shown in blue, and the Netscape Object Tag is shown in red.

<!-- Start IE Section -->

<OBJECT ID="Seagull Web-to-Host Control Module v3"
CLASSID="clsid:037790A6-1576-11D6-903D-00105AABADD3"
CODEBASE="../sglw2hcm.ocx#Version=3,2,4,329" HEIGHT=0 WIDTH=0>
<PARAM NAME="IniFile" VALUE="default.ini">
<PARAM NAME="Sessions" VALUE="MD_S1">
<PARAM NAME="MD_DistFile" VALUE="display.e3d">
<PARAM NAME="MD_S1" VALUE="mfdisp1.zmd">
<PARAM NAME="MD_S1_Save" VALUE="Yes">
</OBJECT>

<!-- End IE Section -->

<!-- Start Netscape Section -->

<OBJECT TYPE="application/x-sglw2hcm" HEIGHT=0 WIDTH=0>
<PARAM NAME="IniFile" VALUE="default.ini">
<PARAM NAME="Sessions" VALUE="MD_S1">
<PARAM NAME="MD_DistFile" VALUE="display.e3d">
<PARAM NAME="MD_S1" VALUE="mfdisp1.zmd">
<PARAM NAME="MD_S1_Save" VALUE="Yes">
</OBJECT>

<!-- End Netscape Section -->

2. Edit the line <PARAM NAME="MD_S1" VALUE="mfdisp1.zmd"> and replace "mfdisp1.zmd" with the name of the Configuration File you created above. Be sure to change it in both Object Tags.
    
3. Save the file and exit notepad.

CAUTION When editing the Object Tags, it is very important to pay close attention to exact syntax. You must maintain quotes, exact character spacing and case of the characters that are used in the PARAM NAME strings.  Very often when a problem occurs, it can be traced to a typo or incorrect case of a PARAM NAME value.

To learn more about Object Tags, please refer to the BlueZone Web-to-Host Administrator's Guide.

Testing Your Changes

1. From a PC, browse to the default.htm page, and run the eZClear utility by clicking on the "run or Get eZClear" link.

TIP You should download the eZClear utility and place it on your desktop for easy access.

2. Click the Mainframe Display link (or the iSeries Display link), and launch a display session. You should now be connected to your host.
    
3. If desired, repeat the above process for the BlueZone Printer emulator or any other BlueZone client product.

NOTE When testing, if you run eZClear,  or if you are testing BlueZone Web-to-Host on a PC for the very first time, and you launch a BlueZone Printer emulator session before you launch a BlueZone Display session, you will receive the following two errors.

The happens because the RTN3270E.DLL file is downloaded only with the Display emulator and not with the Printer emulator.  Since both the BlueZone Display and Printer emulators use this same file, we purposely designed BlueZone Web-to-Host to download the RTN3270E.DLL only with the Display emulator in order to eliminate the need to download the same file twice.

Optional Components

BlueZone Web-to-Host has several optional components that can be added to and made part of the distribution process so that these components can be available to the end user as part of a seamless BlueZone Web-to-Host solution.

Here is a list of BlueZone's Optional Components:

• BlueZone Secure FTP
• BlueZone Secure FTP Help File
• BlueZone Scripting Editor
• BlueZone Scripting Host
• BlueZone VT Graphics Font
• BlueZone Spoolfile Information Program
• HLLAPI API 32 bit
• HLLAPI API
• BlueZone Served Desktop Client Uninstall Program

 To learn more about Enabling Optional Components, please refer to the BlueZone Web-to-Host Administrator's Guide.

Congratulations! You have successfully installed and configured BlueZone Web-to-Host. For more detailed information please consult the BlueZone Administrator's Guide located in the "docs" folder of this CD.

NOTE If you have purchased BlueZone Web-to-Host and are installing a licensed version, you must install the Seagull License Manager software provided on this BlueZone CD.

 To learn more about the Seagull License Manager, please refer to the BlueZone Web-to-Host Administrator's Guide.