Host Access Class Library (HACL) API in IBM PCOMM. Part 1: Automation Objects

In continuation with my previous blogs about Automation using PCSAPI and Automation using EHLLAPI API’s, this blog provides a brief about the strongest set of PCOMM API’s, the HACL (Host Access Class Library) API.

​Host Access Class Library (HACL) is a set of objects that allows application programmers to access host applications easily and quickly. IBM Personal Communications supports different HACL Layers:

Figure 1 HACL Layers

Automation Objects (Visual Basic, Word, Excel, etc):
The Host Access Class Library Automation Objects allow Personal Communications to support 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 features.
Note: Automation Objects provided by IBM Personal Communications are 32-bit in nature. These can be used only with 32-bit Microsoft Office programs.
At present, the following types of automation objects are supported.
•       C++ objects:
         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.
•       Java Objects:
         Java objects provides Java wrappers for all HACL functions. Details on HACL Java classes           will be covered in another blog in the near future.
•       LotusScript Extension:
        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.
 
ECL Concept - Connections, Handles and Names
In the context of the ECL, a Connection is a single, and is unique to a Personal Communications emulator window.

Connections are distinguished by their connection handle or 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 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.SetConnectionByHandle("B")
 
The HACL Automation Objects
Below is a graphical representation of most commonly used autECL Objects.

Figure 2 autECL Object representation

Several automation servers are implemented as real-world, intuitive objects with methods and properties that control Personal Communications operability. Each object begins with autECL, for automation Host Access Class Library. These objects and a brief description of each are as follows:

• autECLConnList, Connection List contains a list of Personal Communications connections for a given system. This is contained by autECLConnMgr, but may be created independently of autECLConnMgr.
• autECLConnMgr, Connection Manager provides methods and properties to manage Personal Communications connections for a given system. A connection in this context is a Personal Communications window.
• autECLFieldList, Field List performs operations on fields in an emulator presentation space.
• autECLOIA, Operator Information Area provides methods and properties to query and manipulate the Operator Information Area. This is contained by autECLSession, but may be created independently of autECLSession.
• autECLPS, Presentation Space provides methods and properties to query and manipulate the presentation space for the related Personal Communications connection. This contains a list of all the fields in the presentation space. It is contained by autECLSession, but may be created independently of autECLSession.
• autECLScreenDesc, Screen Description provides methods and properties to describe a screen. This may be used to wait for screens on the autECLPS object or the autECLScreenReco object.
• autECLScreenReco, Screen Recognition provides the engine of the HACL screen recognition system.
• autECLScreenReco, Screen Recognition provides the engine of the HACL screen recognition system.
• autECLSession, Session provides general session-related functionality and information. For convenience, it contains the autECLPS, autECLOIA, autECLXfer, autECLWinMetrics, autECLPageSettings, and autECLPrinterSettings objects.
• autECLWinMetrics, Window Metrics provides methods to query the window metrics of the Personal Communications session associated with this object. For example, use this object to minimize or maximize a Personal Communications window. This is contained by autECLSession, but may be created independently of autECLSession.
• autECLXfer, File Transfer provides methods and properties to transfer files between the host and the workstation over the Personal Communications connection associated with this file transfer object. This is contained by autECLSession, but may be created independently of autECLsession.
• autECLPageSettings, Page Settings provides methods and properties to query and manipulate commonly used settings such as CPI, LPI, and Face Name of the session Page Setup dialog. This is contained by autECLSession, but may be created independently of autECLSession.
• autECLPrinterSettings, Printer Settings provides methods and properties to query and manipulate settings such as the Printer and PDT modes of the session Printer Setup dialog. This is contained by autECLSession, but may be created independently of autECLSession.

 
Essentially every class provides properties, methods and (optionally) Events with it. These can be used in conjunction or separately to interact with and control operations in PCOMM window.

More information about the mentioned Classes and sample code can be found in PCOMM online documentation.

​Sample code below demonstrates usage of most common ECL objects and methods.

1.       Object Declaration

2.       Initialize session object by Handle or by Name

3.       Sendkey (String, Row, Col)
          ' sends the text on mentioned row and col location
            autECLPSObj.SendKeys "PCOMM API’s are very Powerful", 3, 1
 
4.       Sendkey (KeyStroke)
         ' Send keystroke (Enter) on the green screen
          autECLPSObj.SendKeys “[Enter]”
 
5.       GetText (Row, Col, Length)
          ' Gets the text of 10 bytes from row and col
          PSText = GetText (1,1,10)
 
6.       SetCursorPos (Row, Col)
          ' sets the cursor position at row and col location
          autECLPSObj.SetCursorPos 2, 1
 
7.       StartMacro (MacroName)
          ' Executes the PCOMM recorded .mac macro
          autECLPSObj.StartMacro "MacroName"
 
8.       WaitforInputReady (time in millsec)
          ' waits for specified number of milliseconds
           autECLOIAObj.WaitForInputReady(10000)
 
9.       Properties
          ' Number of rows and cols properties in green screen autECLPS class Object
           Rows = autECLPSObj.NumRows
           Cols = autECLPSObj.NumCols
 
10.     GetCursorRow and GetCursorCol
           ' fetch rows and cols properties position
           CurPosRow = autECLPSObj.CursorPosRow
           CurPosCol = autECLPSObj.CursorPosCol
 
11.      RegisterPSEvent/ RegisterCommEvent, RegisterKeyEvent
            ‘Refer the attached example Excel application

Download the sample code:

pcomm_hacl_sample.zip
File Size:	39 kb
File Type:	zip

Download File

---

Contact:
For further information on automation, and services offerings please email zServices@hcl.com  or HCL-HI-LabServices@hcl.com.

Avinash Sable
Lead - Lab Services, IBM HACP & HATS
avinash.sable@hcl.com