Host Access Class Library for java in pcomm

In continuation to the previous blog about Host Access Class Library(HACL) API in IBM Pcomm-part 1-Automation Objects, this blog covers Java Objects implementation using HACL API
HACL unique features include:

• Session start and stop functions
• No architectural limit to the number of sessions.
• Event notification for host communications status
• Comprehensive error trapping
• Generation of language-specific error message text
• Row and column addressing for host presentation space
• Simplified model for presentation space
• Automatic generation of presentation space field list and attributes
• Keyword-based function key strings

Source Code Preparation
Programs that use HACL classes must import the appropriate HACL packages to obtain class definitions and other compile-time information. The HACL packages can be imported into a Java source file using the following statements:

​import com.ibm.eNetwork.ECL.*;                  // Base HACL classes
 
To import the HACL listener interfaces and event classes (only needed when using HACL events):

import com.ibm.eNetwork.ECL.event.*;            // HACL event classes
Session
In the context of HACL, a session object (ECLSession) encapsulates the connection to the host and the characteristics of that connection.

It can be constructed with a Properties object which contains all the configuration information for the session.

ECLSession session = new ECLSession(prop);
session.StartCommunication();  // Starts the communication link to the host.
session.connect();

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).

ECLOIA eclOIA = session.GetOIA();
ECLPS ps = session.GetPS();
 
Properties prop = new Properties();
prop.put("SESSION_HOST", "iseriesd.ws");
 
For Personal Communications, the value of SESSION_HOST must be the name of an existing .WS session configuration file.
 
prop.put("SESSION_WIN_STATE", "MAX");
 
SESSION_WIN_STATE - Specifies the initial state of the Emulator window.
                                        The value can be one of the following strings:

String	Description
HIDE	Emulator window is hidden (default)
MAX	Emulator window starts maximized
MIN	Emulator window starts minimized
RESTORE	Emulator window starts restored

prop.put("SESSION_VT_KEYPAD ", "SESSION_VT_KEYPAD_APPL"); //

SESSION_VT_KEYPAD - Determines the behaviour of the keypad
 
Value can be one of the following:

Constant	Value	Description
SESSION_VT_KEYPAD_NORM	"false"	Normal (default)
SESSION_VT_KEYPAD_APPL	"true"	Application controls keypad behaviour

prop.put("SESSION_VT_LOCAL_ECHO", "SESSION_VT_LOCAL_ECHO_ON");
 
SESSION_VT_LOCAL_ECHO - Determines the behaviour of local keyboard echo
 
Value can be one of the following:
 

Constant	Value	Description
SESSION_VT_LOCAL_ECHO_OFF	"false"	Off (default)
SESSION_VT_LOCAL_ECHO_ON	"true"	On

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

Code Editor

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.

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); // Sets the cursor position to the specified linear position.
ps.SetCursorPos(2, 1); // Sets the cursor position to the specified row and column.

SendKey Interface
The HACL method for sending keystrokes to the host (ECLPS.SendKeys) is similar to the EHLLAPI SendKey function. However, EHLLAPI uses escape codes to represent non-text keys such as ENTER, PF1 and BACKTAB. The ECLPS object uses bracketed keywords called mnemonics to represent these keystrokes. For example, the following sample would type the characters "ABC" at the current cursor position, followed by an ENTER key:

ps.SendKeys("ABC[enter]"); // Send keystrokes

session.disconnect();
session.StopCommunication(); // Stops the communications link to the host.

​session.dispose(); // Frees resources associated with the session. The session should not be used after a call to dispose ().

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

Ashish Rajpoot
Member Technical Staff - Lab Services, IBM HACP & HATS
rajpoota@hcl.com