Applications created using HLLAPI (High Level Language Application Programming Interface) can be modified to use the the PASSPORT Host Integration Objects (HIO). In general it requires significant source code changes or application restructuring to migrate from HLLAPI to PASSPORT HIO, but it is possible. PASSPORT HIO presents a different programming model than HLLAPI and generally requires a different application structure to be effective.
A fundamental difference is that HLLAPI applications must have a terminal emulation client application running to perform the actual communication with the host computer. PASSPORT HIO itself is a terminal emulation application without the user interface.
At the most fundamental level, HLLAPI and PASSPORT HIO differ in the mechanics of how the API is called by an application program.
HLLAPI 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.
PASSPORT HIO 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.
PASSPORT HIO features include:
Session start and stop functions
No architectural limit to the number of sessions
Event notification for host communications status
Comprehensive error trapping
Generation of error message text
Simplified model for presentation space
Automatic generation of presentation space field list and attributes
Keyword-based function key strings
HLLAPI features not implemented in PASSPORT HIO include:
Structured field support
OIA character images
File transfer.
Keyboard locking.
Keystroke interception.
Window manipulation
The PASSPORT HIO architecture is not limited to 26 sessions. Therefore, a single character session ID such as that used in HLLAPI is not appropriate. PASSPORT HIO uses the concept of a session name (session ID), which is simply a string that identifies a session. The session name is provided by the application when an instance of a Session is created.
The PASSPORT HIO virtual screen consists of a number of planes, each of which contains one type of data. The planes are:
Text
Field attributes
Color
Extended attributes
The planes are all the same size and contain one character for each character position in the host virtual screen. An application can obtain any plane of interest using the Screen.GetData method.
This model is different from HLLAPI, in which text and non-text presentation space data is often interleaved in a buffer. An application must set the HLLAPI session parameter to specify what type of data to retrieve, then make another call to copy the data to a buffer. The PASSPORT HIO model allows the application to get the data of interest in a single call. Different data types are never mixed in a single buffer.
The PASSPORT HIO method for sending keystrokes to the host, Screen.SendKeys, is similar to the HLLAPI SendKey function. However, HLLAPI uses escape codes to represent non-text keys such as ENTER, PF1, BACKTAB, etc. The PASSPORT HIO Screen object has a method, SendAID, which is used to send these non-text keys.
An HLLAPI application must manage a connection to different sessions by calling ConnectPS and DisconnectPS HLLAPI functions. The application must be carefully coded to avoid being connected to a session indefinitely because sessions have to be shared by all HLLAPI applications. You must also ensure that an application is connected to a session before using certain other HLLAPI functions.
PASSPORT HIO does not require any explicit session connect or disconnect by the application. Each PASSPORT HIO 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 Session for each one. For applications that interact with multiple connections (sessions), this can greatly simplify the code needed to manage multiple connections. However, PASSPORT HIO applications need to provide their own synchronization when more than one application interacts with the same session.
PASSPORT HIO does not impose any particular multi-threading restrictions on applications. An application can interact with any number of sessions on any number of threads concurrently.