The Com-plete 3270 Bridge

#### Search Results

Search

# The Com-plete 3270 Bridge

This document covers the following topics:

- Introduction – Invoking 3270 Terminal Oriented Applications from a Web Browser or an XML Client

- Browser Requirements and Limitations

- Parameters for Invoking the 3270 Bridge

- Customizations

- XML Processing of HTML Output

- Advanced Features with the XML Option

## Introduction – Invoking 3270 Terminal Oriented Applications from a Web Browser or an XML Client

Through a special CGI program which is part of the HTTP server, it is possible to invoke any 3270 terminal oriented applications that can run in Com-plete directly from an HTTP client. The 3270 output data stream from the application is converted to XHTML “on the fly”, without the need to make any changes to the existing application programs or terminal maps. User input data entered into the HTML form is send back to the server and converted into a 3270 input data stream as expected by the application program.

There are two major fields of application for this feature:

1. Access to terminal oriented applications from a standard web browser, without a terminal emulation. This makes it possible to integrate terminal oriented applications into web pages.

2. Access to and communication with terminal oriented transactions in Com-plete from any XML client program anywhere in the network. Instead of a 3270 screen, you get an XML document and can process it as such.

The look-and-feel of the presentation in the web browser is controlled using Cascading Style Sheets (CSS) and can be customized.

For applications using Com-plete terminal maps the output can be produced in XML format, using the original field names from the map. The XML data can be made visible in a web browser using a customizable XSLT style sheet, allowing for maximum flexibility in the presentation. For this kind of applications, it is also possible to add JavaScript code in the XSLT style sheet for client-side execution, e.g. for validation of user input, providing field-specific help texts, etc.

## Browser Requirements and Limitations

In general, the 3270 bridge works with the current versions of all major web browsers (Internet Explorer 6, Gecko-based browsers like Mozilla and Netscape 6, Opera 6, etc.). The basic requirements are:

- The browser must support DOM (Document Object Model).

- JavaScript and cookies must be enabled.

Recommended browser cache settings (“Temporary Internet files” in the Internet Explorer):

- Cache size: non-zero

- Check for new version of page: Automatically

If a style sheet changes, e.g., at a Com-plete version upgrade or because you customized it, then this setting should ensure that the browser finds out that it has changed, and loads the new version.

Avoid setting “Check for new version of page: at every visit”, because this would cause the browser to load style sheets and JavaScript files again and again with every 3270 transaction! The Com-plete 3270 bridge instructs the browser not to cache the actual transaction data, so it is guaranteed that the browser does submit the data to Com-plete when you press a key.

Note that not all features work equally well with all browsers. Known limitations are:

- XML / XSLT works only with Internet Explorer and Gecko-based browsers.

- Detecting the position of the caret (cursor) within a protected field (as opposed to input fields) works only with Internet Explorer and Gecko-based browsers.

- Many users prefer using the keyboard F1-F12 keys to emulate the mainframe PF1-PF12 keys. This requires the cancellation of keyboard events, a feature that is supported only by Internet Explorer.

## Parameters for Invoking the 3270 Bridge

The Com-plete 3270 bridge has been implemented as a CGI program named haen3270, hence all the rules for invoking CGI programs apply. In general, the URL for invoking a 3270 program via haen3270 looks like this:

    http://ip-addr:port/cgi/haen3270?command=command&format=format&model=model&window=window

#### Parameters

Keyword | Value
--- | ---
command | Any valid Com-plete terminal command of the format “program parmstring”. The value (the Com-plete command) must be URL-encoded, meaning spaces replaced by “+” signs, and special characters replaced by their %-notation. Default: If no command is supplied, the 3270 bridge sends to the browser a HTML form (“the command prompt”) that allows the user to type a command and select the other parameters.
format | HTML (or just H) XML (or just X) Default: HTML
model | The 3270 terminal model number: 2, 3, 4, or 5. Default: 2
window | The name of the browser window if (and only if) the conversation is being opened in a new browser window. The window name is used to close all 3270 bridge windows when the user logs out. Default: none

#### Examples

    http://complete/cgi/haen3270?command=uctrl+cm
    http://complete/cgi/haen3270?command=nat31+du%3Dforce&model=5&window=screen2

Hint: In order to see the URL for a specific command, type it at the command prompt, and uncheck “open conversation in new window”. When you get the first screen (not on subsequent screens!), the address bar displays the full URL. Alternatively, at the first screen in a new window, select View -> Toolbars -> Address_Bar from the browser menu.

Note that you do not have to have end users invoke applications from the command prompt. Instead, you can use hyperlinks from anywhere directly to the desired application, specifying the URL as described above.

## Customizations

Generally, the following characteristics of the Com-plete 3270 bridge can be customized.

### The Command Prompt Page

The command prompt page is a HTML file named hhanprmt.html that resides in the HTTP server home directory. You can edit or replace this file. For example, if you do not wish to allow users to type in commands, you can simply replace it with a warning page, or redirect users to any other URL.

### Fonts and Colors

All fonts and colors used for the presentation of 3270 screens in the browser are controlled using the Cascading Style Sheet styl3270.css in the HTTP server home directory. You can edit this file in order to change the default look and feel. Some browsers support individual style sheets, allowing each user to set his own preferences.

The Com-plete 3270 bridge maps the extended 3270 color attributes to CSS classes as per the following table:

oB | ordinary blue
oR | ordinary red
oP | ordinary pink
oG | ordinary green
oT | ordinary turquoise
oY | ordinary yellow
b | bold
bB | bold blue
bR | bold red
bP | bold pink
bG | bold green
bT | bold turquoise
bY | bold yellow
r | reverse video (3270 extended highlighting attribute, used, e.g., by Natural pop-up frames)

You can change all colors by using color names or #RGB values.

If you prefer a black background, there are a few obvious dependencies:

- Add "color:white" where you set background-color:black

- Invert color and background-color for class "r".

- Chose a brighter blue for classes "oB", "bB", and "b".

## XML Processing of HTML Output

The output data of an application invoked via the Com-plete 3270 bridge is presented in HTML by default, and the XML option (see below) does not work, e.g., for Natural applications, as these do not use Com-plete terminal maps. However, the HTML version used here is in fact XHTML, an XML compliant dialect of HTML. This makes it possible to process the output using any XML software.

Each field of the 3270 screen is represented by a tag with a unique ID. The ID consists of the letter “C” followed by a five-digit decimal number representing the position (screen offset) of the field, e.g., C00000 or C01082.

Each protected (non-input) field is represented by a <span> tag, with the field value located between the <span> and the </span> tags.

Each unprotected (input) field is represented by an <input> tag of the following structure: <input id="Cnnnnn" value="…" … /> with the field value specified in the “value” attribute.

## Advanced Features with the XML Option

For applications that use Com-plete terminal maps (and only for these applications), the Com-plete 3270 bridge provides some advanced features. In order to make use of these, specify the haen3270 parameter `format=XML`.

### Better Performance, Less Network Traffic

The XML data is generated directly from the terminal map and the application program data area, saving the CPU-consuming intermediate step of building the 3270 data stream and then converting it to HTML in Com-plete. The conversion from XML to HTML is done at the client, which is the more appropriate place for it. All information related to the format of the HTML page is contained in the XSLT style sheet, which is transferred only once, provided that the browser cache settings have been set properly. This allows then at each transaction to transfer only the actual transaction related data.

### Using the Original Field Names from the Map

The output can be produced in XML format, using the original field names from the map. This makes it easier to write XML processing applications that are independent from the layout of the 3270 terminal map. Even if the map changes, moving fields to different locations on the screen, this does not affect the XML application. Or if you have multiple maps with common field naming conventions, then this can be used for processing them using a single XML application.

### Extented Formatting and Control

With the XML option, you can do virtually anything with the 3270 output data, as you have full control over the generated HTML. On a per-map basis, you can specify your own XSLT style sheet using an environment variable:

    SAG_COM_MAPXSL_mapname=/path/file.xsl

where mapname is the load module name of the map, and path/file is the location (library and member name) of the XSLT style sheet in URL notation. This style sheet will then be used for the appropriate maps instead of the standard 3270 bridge style sheet mapxslt.xsl.

Using these XSLT style sheets, you can easily present the 3270 data in any way you like, and it doesn’t have to resemble a 3270 screen at all.

Once you control the XSLT style sheet, you can also imbed CSS style elements and JavaScript code in it. This can be used, for example, for client-side validation of user input, providing field-specific help texts, etc..

### On this page

- Introduction – Invoking 3270 Terminal Oriented Applications from a Web Browser or an XML Client
- Browser Requirements and Limitations
- Parameters for Invoking the 3270 Bridge
- Customizations
- XML Processing of HTML Output
- Advanced Features with the XML Option