IBM Books

Open Host Interface Objects for Java


Migrating from EHLLAPI

Applications currently written to the Emulator High Level Language API (EHLLAPI) can be modified to use the Open Host Interface Objects (OHIO) API. In general it requires significant source code changes or application restructuring to migrate from EHLLAPI to OHIO. OHIO presents a different programming model than EHLLAPI and generally requires a different application structure to be effective.

The following sections will help a programmer who is familiar with EHLLAPI to understand how OHIO is similar and how OHIO is different than EHLLAPI. Using this information, you can understand how a particular application can be modified to use OHIO.

Execution/Language Interface

At the most fundamental level, EHLLAPI and OHIO differ in the mechanics of how the API is called by an application program.

EHLLAPI is implemented as a single call-point interface with multiple-use parameters. A single entry point (hllapi) in a DLL provides all the functions based on a fixed set of four parameters. Three of the parameters take on different meanings depending on the value of the first command parameter. This simple interface makes is easier to call the API from a variety of programming environments and languages. The disadvantage is a lot of complexity packed into one function and four parameters.

OHIO is an object-oriented interface that provides a set of programming objects instead of explicit entry points or functions. The objects have properties and methods that can be used to manipulate a host connection. You do not have to be concerned with details of structure packing and parameter command codes, but can focus on the application functions.

Features

At a high level, OHIO provides a number of features not available at the EHLLAPI level. There are also a few features of EHLLAPI not currently implemented in any OHIO class.

OHIO features include:

EHLLAPI features not currently implemented in OHIO include:

Session IDs

The OHIO architecture is not limited to 26 sessions. Therefore, a single character session ID such as that used in EHLLAPI is not appropriate. OHIO uses the concept of a session name, which is simply a string that identifies a session. The session name is provided by the application when an instance of iOhioSession is created.

Virtual Screen Models

The OHIO virtual screen model is easier to use than that of EHLLAPI. The OHIO virtual screen consists of a number of planes, each of which contains one type of data. The planes are:

The planes are all the same size and contain one character (Java native type) for each character position in the host virtual screen. An application can obtain any plane of interest using the iOhioScreen.getData method.

This model is different from EHLLAPI, in which text and non-text presentation space data is often interleaved in a buffer. An application must set the EHLLAPI session parameter to specify what type of data to retrieve, then make another call to copy the data to a buffer. The OHIO model allows the application to get the data of interest in a single call. Different data types are never mixed in a single buffer.

SendKey Interface

The OHIO method for sending keystrokes to the host (iOhioScreen.sendKeys) is similar to the EHLLAPI SendKey function. However, EHLLAPI uses cryptic escape codes to represent non-text keys such as ENTER, PF1 and BACKTAB. The iOhioScreen object has a method, sendAid, which is used to send these non-text keys.

Events

EHLLAPI provides multiple ways to receive asynchronous notifications, including use of semaphores, window messages, and polling. OHIO provides only one consistent method of event notification for all event types and takes care of threading internally.

However, you must be aware that the event procedures are called on a separate thread of execution. Access to dynamic application data must be synchronized when accessed from an event procedure.

Addressing (Rows, Columns, Positions)

In EHLLAPI, a linear positional addressing method (with position 1 in the upper left corner, progressing from left to right, top to bottom) is used. The positional method presents the virtual screen as a single array of data elements. To use positional addresses with OHIO, you must convert the positional address to a pair of row and column coordinates. There are some static utility methods provided by the HACL API that assist with this task:

PS Connect/Disconnect and Multithreading

An EHLLAPI application must manage a connection to different sessions by calling ConnectPS and DisconnectPS EHLLAPI functions. The application must be carefully coded to avoid being connected to a session indefinitely because sessions have to be shared by all EHLLAPI applications. You must also ensure that an application is connected to a session before using certain other EHLLAPI functions.

OHIO does not require any explicit session connect or disconnect by the application. Each OHIO object is associated with a particular host session when it is constructed. To access multiple, different hosts, the application need only create different instances of iOhioSession for each one. For applications that interact with multiple connections (sessions), this can greatly simplify the code needed to manage multiple connections. However, OHIO applications need to provide their own synchronization when more than one application interacts with the same session.

OHIO does not impose any particular multithreading restrictions on applications. An application can interact with any number of sessions on any number of threads concurrently.


[ Top of Page | Previous Page | Next Page | Table of Contents ]