Host Access Class Library C++

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. The class libraries support Microsoft Visual C++ compilers.

The Host Access Class Library C++ layer consists of a number of C++ classes arranged in a class hierarchy. Figure 1 illustrates the C++ inheritance hierarchy of the Host Access Class Library C++ layer. Each object inherits from the class immediately above it in the diagram.

Figure 1. Host Access Class Objects
Displays the Host Access Class Library class library objects structure.

Figure 1 also shows all the member functions of each class. Note that in addition to the functions shown for each class, classes inherit all the functions of the parent class. For example, the function IsReady() is available on ECLSession, ECLPS, ECLOIA, ECLWinMetrics, and ECLXfer classes.

Each class is described briefly in the following sections. See the individual class descriptions in this chapter for more details.

All the examples shown in this chapter are supplied in the ECLSAMPS.CPP file. This file can be used to compile and execute any of the examples using any supported compiler.

The following is a brief overview of the Host Access Class Library C++ classes. Each class name begins with ECL, which is the common prefix for the Host Access Class Library.

  • ECLBase, on page ECLBase Class, is the base class for all ECL objects. It provides some basic utility methods such as the conversion of connection names and handles. Because all ECL objects inherit from this class, these methods can be used on any ECL object.
  • ECLConnection, on page ECLConnection Class, represents a single Z and I Emulator for Windows connection and contains connection information such as the connection status, the type of connection (for example, 3270 or 5250), and the name and handle of the connection. This class is also the base class for all the connection-specific ECL objects such as ECLPS and ECLOIA.
  • ECLConnList, on page ECLConnList Class, contains a list of all the Z and I Emulator for Windows connections that were in existence at the time the object was created or the last time the Refresh method was called. Each connection is represented by an ECLConnection object.
  • ECLConnMgr, on page ECLConnMgr Class, enumerates all the currently running Z and I Emulator for Windows connections (windows) using the ECLConnList object. Is also provides methods for starting new connections and stopping connections.
  • ECLCommNotify, on page ECLCommNotify Class, is a notification class that an application can use to be notified whenever a connection is disconnected from or connected to a host. It can be used to monitor the status of a connection and take action when a connection is disconnected unexpectedly.
  • ECLErr, on page ECLErr Class, provides a method for returning run-time error information from Host Access Class Library classes.
  • ECLField, on page ECLField Class, contains information about a single field on the screen, such as the field attributes, field color, position on the screen or length. A method is also supplied to update input fields.
  • ECLFieldList, on page ECLFieldList Class, contains a collection of ECLField objects. When the Refresh method is called, the current host screen is examined, and the list of fields is extracted and used to build the list of ECLField objects. An application can use this collection to manage fields without having to build the list itself.
  • ECLKeyNotify, on page ECLKeyNotify Class, is a notification class that an application can use to be notified of keystroke events. The application can filter (remove) keystrokes, replace them with other keystrokes or discard them.
  • ECLListener, on page ECLListener Class, is the base class for all new HACL event listener objects. It provides common functions for all listener objects.
  • ECLOIA, on page ECLOIA Class, provides access to operator status information such as shift indicators, input inhibited conditions and communications errors.
  • ECLOIANotify, on page ECLOIANotify Class, is an abstract base class. Applications create objects derived from this class to receive notification of OIA changes.
  • ECLPS, on page ECLPS Class, represents the presentation space (screen) of a single connection. It contains methods for obtaining a copy of the screen contents in the form of data planes. Each plane represents a specific aspect of the presentation space, such as the text, field attributes and color attributes. Methods are provided for searching for strings in the presentation space, sending keystrokes to the host, getting and setting the host cursor position, and many other functions. Also provided is an ECLFieldList object that can be used to enumerate the list of fields on the screen.
  • ECLPSEvent, on page ECLPSEvent Class, is an event object which is passed to PS event listeners when the presentation space has been updated. It contains information about the event including what caused the update and the portion of the screen which has been updated.
  • ECLPSListener, on page ECLPSListener Class, is an abstract base class. Applications create objects derived from this class to receive presentation space update events with all the information provided by the ECLPSEvent object.
  • ECLPSNotify, on page ECLPSNotify Class, is an abstract base class. Applications create objects derived from this class to receive notification of presentation space updates with minimal information.
  • ECLRecoNotify, on page ECLRecoNotify Class, is an abstract base class. Applications create objects derived from this class to receive notifications of screen recognitions.
  • ECLScreenDesc, on page ECLScreenDesc Class, is a class used to describe a single host screen. Screen description class objects are then used to trigger events when the described host screen appears, or to synchronously wait for a particular host screen.
  • ECLScreenReco, on page ECLScreenReco Class, is a class used to collect a set of screen description objects and generate asynchronous events when any of the screens in the collection appear in the presentation space.
  • ECLSession, on page ECLSession Class, contains a collection of all the connection-specific objects. ECLSession can be used to easily create a complete set of objects for a particular connection.
  • ECLStartNotify, on page ECLStartNotify Class,is a notification class that an application can use to be notified whenever a connection is started or stopped. It can be used to monitor the status of the system and take action when a connection is closed unexpectedly.
  • ECLUpdateNotify, on page ECLUpdateNotify Class, is a notification class that an application can use to be notified whenever the host screen or OIA is updated.
  • ECLWinMetrics, on page ECLWinMetrics Class, represents the physical window in which the emulation is running. Methods are provided for getting and setting the window state (min, max, restored), window size and visibility.
  • ECLXfer, on page ECLXfer Class, initiates file transfers to or from the host over the connection.
  • ECLPageSettings, on page ECLPageSettings Class, control and retrieve the settings of the emulator session File > Page Setup dialog.
  • ECLPrinterSettings, on page ECLPrinterSettings Class, control and retrieve the settings of the emulator session File > Printer Setup dialogs.