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:
ECLPS *PSObject;
PSObject = new ECLPS(’B’);
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
' Declare the Objects to be used
DIM autECLPSObj as Object
DIM autECLConnList as Object
Dim autECLOIAObj as Object
Dim PSText String
2. Initialize session object by Handle or by Name
' Define the purpose of the object type
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")
Set autECLOIAObj = CreateObject("PCOMM.autECLOIA")
' Refresh must be called to get latest connection info
autECLConnList.Refresh
' Initialize the connection with the first in the list
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
' Initialize the connection with Session Name
autECLOIAObj.SetConnectionByName("A")
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
Contact:
For further information on Automation, Services Offerings or Technical details in IBM HACP/HATS please connect with HCL mainframe Lab Services.
Avinash Sable
Lead - Lab Services, IBM HACP & HATS