The Host Access Class Library (HACL) is a set of objects that allows application programmers to access host applications easily and quickly. IBM® Personal Communications provides support for a wide variety of programming languages and environments by supporting several different HACL layers: C++ objects, Java™ objects, Microsoft COM-based automation technology (OLE), and LotusScript Extension (LSX). Each layer provides the same basic functionality, but each layer has some differences due to the different syntax and capabilities of each environment. The most functional and flexible layer is the C++ layer, which provides the basis for all others.
This layering concept allows the basic HACL functions to be used with a wide variety of programming environments including Java, Microsoft Visual Basic, Visual Basic for Applications, Lotus® Notes®, Lotus WordPro and Visual C++. The following figure shows the HACL layers.
This C++ class library presents a complete object-oriented abstraction of a host connection that includes: reading and writing the host presentation space (screen), enumerating the fields on the screen, reading the Operator Indicator Area (OIA) for status information, accessing and updating information about the visual emulator window, transferring files, and performing asynchronous notification of significant events.
See Host Access Class Library C++ for details on C++ objects.
Personal Communications Version 12.0 supports Japanese code page 1390/1399 on a Unicode session for the following HACL C++ methods:
For more information about these methods, see their individual sections in Host Access Class Library C++.
Java objects provides Java wrapping for all HACL functions similar to Host-on-Demand Version 3. See Host Access Class Library for Java for details on HACL Java classes.
The Host Access Class Library Automation Objects allow Personal Communications to support the Microsoft COM-based automation technology (formerly known as OLE automation). The HACL Automation Objects are a series of automation servers that allow automation controllers, for example, Microsoft Visual Basic, to programmatically access Personal Communications’ data and functionality. In other words, applications that are enabled for controlling the automation protocol (automation controller) can control some of Personal Communications' operations (automation server).
See Host Access Class Library Automation Objects for details on the Automation Objects layer.
The Host Access Class Library LotusScript Extension (LSX) is a language extension module for LotusScript (the scripting and macro language of Lotus Notes and all the Lotus SmartSuite® products). This LSX gives users of Lotus products access to the HACL functions through easy-to-use scripting functions.
See Host Access Class Library LotusScript Extension for details on the LotusScript layer.
The following sections describe several essential concepts of the Emulator Class Library (ECL). Understanding these concepts will aid you in making effective use of the library.
In the context of the ECL, a connection is a single, unique Personal Communications emulator window. The emulator window may or may not be actually connected to a host and may or may not be visible on the screen. For instance, a Personal Communications window can be in a disconnected state. Connections are distinguished by their connection handle or by their connection name. Most HACL objects are associated with a specific connection. Typically, the object takes a connection handle or connection name as a parameter on the constructor of the object. For languages like Visual Basic that do not support parameters on constructors, a member function is supplied for making the association. Once constructed, the object cannot be associated with any other connection. For example, to create an ECLPS (Presentation Space) object associated with connection 'B', the following code would be used:
C++
ECLPS *PSObject;
PSObject = new ECLPS('B');Visual Basic
Dim PSObject as Object
Set PSObject = CreateObject("PCOMM.autECLPS")
PSObject.SetConnectionByName("B")LotusScript Extension
dim myPSObj as new lsxECLPS("B")An HACL connection name is a single character from A-Z or a-z. There are a maximum of 52 connection names, and Personal Communications is currently limited to 52 concurrent connections. A connection's name is the same as its EHLLAPI short session ID, and the session ID shown on the Personal Communications window title and OIA.
An HACL handle is a unique 32-bit number that represents a single connection. Unlike a connection name, a connection handle is not limited to 52 values, and the value itself has no significance to the application. You can use a connection handle across threads and processes to refer to the same connection.
For future expansion, applications should use the connection handle whenever possible. Most HACL objects accept a handle or a name when a connection needs to be identified. There are functions available in the base HACL class to convert a handle to a name, and a name to a handle. These functions are available from any HACL object.
In the context of the ECL, a session object (ECLSession) is only a container for all the other connection-specific objects. It provides a shortcut for an application to create a complete set of HACL objects for a particular connection. The term session should not be confused with the Personal Communications session concept. A Personal Communications session refers to a physical emulation window on the screen.
Creating or destroying ECLSession objects does not affect Personal Communications sessions (windows). An application can create any number of ECLSession objects that refer to the same or different connections.
Several of the HACL classes act as containers of other objects. For example, the ECLSession object contains an instance of the ECLPS, ECLOIA, ECLWinMetrics, and ECLXfer objects. Containers provide methods to return a pointer to the contained object. For example, the ECLSession object has a GetOIA method, which returns a pointer to an OIA object. Contained objects are not implemented as public members of the container’s class, but rather are accessed only through methods.
For performance or other reasons, the contained objects may or may not be created when the container object is created. The class implementation may choose to defer construction of the contained objects until the first time the application requests a pointer to them. The application should not assume that contained objects are created at the same time as the container. For example, an instance of the ECLPS object may not be constructed when an ECLSession object is constructed. Instead, the ECLSession class may delay the construction of the ECLPS object until the first time the GetPS method is called.
When a container class is destroyed, all the contained instances are also destroyed. Any pointers that have been returned to the application become invalid and must not be used.
Several HACL classes provide list iteration capabilities. For example, the ECLConnList class manages the list of connections. ECL list classes are not asynchronously updated to reflect changes in the list content. The application must explicitly call the Refresh method to update the contents of a list. This allows an application to iterate a list without concern that the list may change during the iteration.
The HACL provides the capability of asynchronous notification of certain events. An application can choose to be notified when specific events occur. For example, the application can be notified when a new Personal Communications connection starts. Currently the HACL supports notification for the following events:
Notification of events is implemented by the ECLNotify abstract base classes. A separate class exists for each event type. To be notified of an event, the application must define and create an object derived from one of the ECLNotify abstract base classes. That object must then be registered by calling the appropriate HACL registration function. Once an application object is registered, its NotifyEvent method is called whenever the event of interest occurs.
At the C++ layer, HACL uses C++ structured exception handling. In general, errors are indicated to the application by the throwing of a C++ exception with an ECLErr object. To catch errors, the application should enclose calls to the HACL objects in a try/catch block such as:
try {
PSObj = new ECLPS('A');
x = PSObj->GetSize();
//...more references to HACL objects...
} catch (ECLErr ErrObj) {
ErrNumber = ErrObj.GetMsgNumber();
MessageBox(NULL, ErrObj.GetMsgText(), "ECL Error");
}When a HACL error is caught, the application can call methods of the ECLErr object to determine the exact cause of the error. The ECLErr object can also be called to construct a complete language-sensitive error message.
In both the Automation Objects layer and the LotusScript Extension layer, runtime errors cause an appropriate scripting error to be created. An application can use an On Error handler to capture the error, query additional information about the error and take appropriate action.
The HACL provides two ways of addressing points (character positions) in the host presentation space. The application can address characters by row/column numbers, or by a single linear position value. Presentation space addressing is always 1-based (not zero-based) no matter what addressing scheme is used.
The row/column addressing scheme is useful for applications that relate directly to the physical screen presentation of the host data. The rectangular coordinate system (with row 1 column 1 in the upper left corner) is a natural way to address points on the screen. The linear positional addressing method (with position 1 in the upper left corner, progressing from left to right, top to bottom) is useful for applications that view the entire presentation space as a single array of data elements, or for applications ported from the EHLLAPI interface which uses this addressing scheme.
At the C++ layer, the different addressing schemes are chosen by calling different signatures for the same methods. For example, to move the host cursor to a given screen coordinate, the application can call the ECLPS::SetCursorPos method in one of two signatures:
PSObj->SetCusorPos(81);
PSObj->SetCursorPos(2, 1);These statements have the same effect if the host screen is configured for 80 columns per row. This example also points out a subtle difference in the addressing schemes -- the linear position method can yield unexpected results if the application makes assumptions about the number of characters per row of the presentation space. For example, the first line of code in the example would put the cursor at column 81 of row 1 in a presentation space configured for 132 columns. The second line of code would put the cursor at row 2 column 1 no matter what the configuration of the presentation space.
Applications currently written to the Emulator High Level Language API (EHLLAPI) can be modified to use the Host Access Class Library. In general it requires significant source code changes or application restructuring to migrate from EHLLAPI to HACL. HACL presents a different programming model than EHLLAPI and in general requires a different application structure to be effective.
The following sections will help a programmer familiar with EHLLAPI understand how HACL is similar and how HACL is different than EHLLAPI. Using this information you can understand how a particular application can be modified to use the HACL.
At the most fundamental level, EHLLAPI and HACL 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 forth 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.
HACL 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. HACL objects can only be used from one of the supported HACL layer environments (C++, Automation Objects, or LotusScript). These three layers are accessible to most modern programming environments such as Microsoft Visual C++, Visual Basic and Lotus SmartSuite applications.
At a high level, HACL provides a number of features not available at the EHLLAPI level. There are also a few features of EHLLAPI not currently implemented in any HACL class.
HACL unique features include:
EHLLAPI features not currently implemented in the HACL include:
The HACL architecture is not limited to 52 sessions. Therefore, a single character session ID such as that used in EHLLAPI is not appropriate. The HACL uses the concept of a connection handle, which is a simple 32-bit value that has no particular meaning to the application. A connection handle uniquely identifies a specific connection (session). You can use a connection handle across threads and processes to refer to the same connection.
All HACL objects and methods that need to reference a particular connection accept a connection handle. In addition, for backward compatibility and to allow a reference from the emulator user interface (which does not display the handle), some objects and methods also accept the traditional session ID. The application can obtain a connection handle by enumerating the connections with the ECLConnList object. Each connection is represented by an ECLConnection object. The ECLConnection::GetHandle method can be used to retrieve the handle associated with that specific connection.
It is highly recommended that applications use connection handles instead of connection names (EHLLAPI short session ID). Future implementations of the HACL may prevent applications that use connection names from accessing more than 52 sessions. In some cases it may be necessary to use the name, such as when the user is required to input the name of a specific session the application is to utilize. In the following C+ + example, you supply the name of a session. The application then finds the connection in the connection list and creates PS and OIA objects for that session:
ECLConnList ConnList; // Connection list
ECLConnection *ConnFound; // Ptr to found connection
ECLPS *PS; // Ptr to PS object
ECLOIA *OIA; // Ptr to OIA object
char UserRequestedID;
//... user inputs a session name (A-Z or a-z) and it is put
//... into the UserRequesteID variable. Then...
ConnList.Refresh(); // Update list of connections
ConnFound = ConnList.FindConnection(UserRequestedID);
if (ConnFound == NULL) {
// Session name given by user does not exist...
}
else {
// Create PS and OIA objects using handle of the
// connection just found:
PS = new ECLPS(ConnFound.GetHandle());
OIA= new ECLOIA(ConnFound.GetHandle());
// The following would also work, but is not the
// preferred method:
PS = new ECLPS(UserRequestedID);
OIA= new ECLOIA(UserRequestedID);
}The second way of creating the PS and OIA objects shown in the example is not preferred because is uses the session name instead of the handle. This creates an implicit 52-session limit in this section of the code. Using the first example shown allows that section of code to work for any number of sessions.
The HACL presentation space model is easier to use than that of EHLLAPI. The HACL 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 byte 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 the 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 HACL 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.
The HACL 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 to represent these keystrokes. For example, the following C++ sample would type the characters ABC at the current cursor position, followed by an Enter key:
ECLPS *PS;
PS = new ECLPS('A'); // Get PS object for "A"
PS->SendKeys("ABC[enter]"); // Send keystrokesEHLLAPI 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 HACL 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 HACL 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.
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 HACL does not require any explicit session connect or disconnect by the application. Each HACL object is associated with a particular connection (session) when it is constructed. To access different connections, the application only needs to create objects for each one. For example, the following example sends the keystrokes ABC to session A, then DEF to session B, and then the Enter key to session A. In an EHLLAPI program, the application would have to connect/disconnect each of the sessions since it can interact with only one at a time. An HACL application can just use the objects in any order needed:
ECLPS *PSA, *PSB;
PSA = new ECLPS('A');
PSB = new ECLPS('B');
PSA->Sendkeys("ABC");
PSB->Sendkeys("DEF");
PSA->Sendkeys("[enter]");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.