Host Access Class Library for Java

Concepts

The following sections describe several essential concepts of the Host Access Class Library (HACL). Understanding these concepts will aid you in making effective use of the library.

Sessions

In the context of HACL, a session object (ECLSession) encapsulates the connection to the host and the characteristics of that connection. A session object also serves as a container for the other session-specific objects: ECLPS (presentation space), ECLOIA (operator information area), and ECLXfer (file transfer).  A host print session object (ECLHostPrintSession) is derived from a session object and encapsulates a print connection with a host.

A session object has no associated graphical user interface (GUI). In other words, creating an instance of ECLSession does not display an emulator screen.

SSL

Using SSL, Host On-Demand sessions can be encrypted to provide security. Use the SESSION_SSL parameter to enable secure sessions.

Container Objects

Several HACL classes contain other objects. For example, the ECLSession object contains an instance of the ECLPS, ECLOIA, and ECLXfer objects. Containers provide methods to return a reference 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.

List Objects

Several HACL classes provide list iteration capabilities. For example, the ECLFieldList class manages the list of fields. HACL 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 might change during the iteration.

Events

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 the status of a connection to a host changes. Currently HACL supports notification for the following events:

Event notification is defined by the respective HACL Notify interfaces. A separate interface exists for each event type. To be notified of an event, the application must define and create an object which implements the interface for the type of events for which notification is required. 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 an event occurs.

Note: The application's NotifyEvent method is called asynchronously on a separate thread of execution. Therefore, the NotifyEvent method should be re-entrant, and if it accesses application resources, appropriate locking or synchronization should be used.

Error Handling

In general, HACL indicates errors to the application by the throwing ECLErr objects. To catch errors, the application should enclose calls to the HACL methods in a try/catch block such as:

    try {
        pos = ps.ConvertRowColToPos(row, col);
    } catch (ECLErr err) {
        System.out.println("HACL Error! " + err.GetMsgText());
    }

When a HACL error is caught, the application can call methods on the ECLErr object to determine the exact cause of the error. ECLErr methods can also be called to construct a complete language-sensitive error message.

Addressing (Rows, Columns, Positions)

HACL provides two ways of addressing positions in the host presentation space. The application can address characters by row and column coordinates or by a single linear position value. Presentation space addressing is always 1-based (not zero-based) no matter which addressing scheme is used.

The row and 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.

In general, 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 ways:

ps.SetCursorPos(81);
ps.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.

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