IBM Books

Host Access Class Library for Java


Migrating from EHLLAPI

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

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

Note: EHLLAPI uses the term session to mean the same thing as an ECL connection. The terms are used interchangeably in this section.

Execution/Language Interface

At the most fundamental level, EHLLAPI and ECL 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 fourth 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.

ECL 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, ECL provides a number of features not available at the EHLLAPI level. There are also a few features of EHLLAPI not currently implemented in any ECL class.

ECL unique features include:

EHLLAPI features not currently implemented in the ECL include:

Session IDs

The ECL architecture is not limited to 26 sessions. Therefore, a single character session ID such as that used in EHLLAPI is not appropriate. The ECL 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 ECLSession is created.

Presentation Space Models

The ECL presentation space model is easier to use than that of EHLLAPI. The ECL presentation space 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 char (Java native type) for each character position in the host presentation space. An application can obtain any plane of interest using the ECLPS::GetScreen 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 ECL model allows the application to get the data of interest in a single call and different data types are never mixed in a single buffer.

SendKey Interface

The ECL method for sending keystrokes to the host (ECLPS::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 ECLPS object uses bracketed keywords called mnemonics to represent these keystrokes. For example, the following sample would type the characters "ABC" at the current cursor position, followed by an ENTER key:

ps.SendKeys("ABC[enter]"); // Send keystrokes

See Appendix A. Sendkeys Mnemonic Keywords for more information.


Events

EHLLAPI provides some means for an application to receive asynchronous notification of certain events. However, the event models are not consistent (some events use semaphores, others use window system messages), and the application is responsible for setting up and managing the event threads. The ECL simplifies all the event handling and makes it consistent for all event types. The application does not have to explicitly create multiple threads of execution, the ECL takes care of the 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. The event thread is spawned when the application registers for the event, and is terminated when the event is unregistered.

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.

The ECL does not require any explicit session connect or disconnect by the application. Each ECL 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 ECLSession for each one. For applications that interact with multiple connections (sessions), this can greatly simplify the code needed to manage the multiple connections.

In addition to the single working session, EHLLAPI also places constraints on the multithreaded nature of the application. Connecting to the presentation space and disconnecting from the presentation space has to be managed carefully when the application has more than one thread calling the EHLLAPI interface, and even with multiple threads, the application can interact with only one session at a time.

The ECLPS 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 ]