Host Access Class Library for Java
Getting started with the Host Access Class Library (HACL) is easy because the object model is so simple. There
are five or six primary classes which will provide most of the function for any HACL applet. These classes are
all associated with a session to a particular host computer and can be obtained from an instance of ECLSession.
To develop the sample application:
- Define a session with a host using the ECLSession class. The session is constructed with a java.util.Properties
object populated with keyword and value pairs which make up the session configuration. A session has a variety
of configuration parameters including type (3270, 5250, VT), host, port, ID, presentation space dimensions (for
example, 24 rows by 80 columns), code page, and others specific to the session type. All parameters, except host,
have default values for 3270 emulation sessions.
The following sample code defines a session to the specified host or TN3270/5250 server, but does not initiate communications:
ECLSession s = null;
Properties p = new Properties();
// This is the name of the host or TN server
p.put(ECLSession.SESSION_HOST, new String("myHost"));
// Set the SESSION_CODEBASE parameter when running from a Web page.
// The use of 'this' assumes that the current class extends
// java.applet.Applet
// p.put(ECLSession.SESSION_APPLET, this);
try {
s = new ECLSession(p);
} catch (ECLErr e) { System.out.println(e.GetMsgText()); }
- Gain access to the presentation space and interact with
it. The presentation space is encapsulated in the ECLPS class, and an instance of it can be obtained using the
GetPS() method on ECLSession. ECLPS provides methods that manipulate text, perform searches, send keystrokes to
the host, and work with the cursor.
The following sample code gets an instance of ECLPS from the session established above:
ECLPS ps = s.GetPS()
- Register to receive notification of presentation space changes.
Registered objects are notified whenever the presentation space is changed. This event notification model is the
primary mechanism used by an application to drive interactions with the presentation space.
The following sample code registers the current class with the instance of ECLPS and starts communications with
the target host. Notice that the sample waits to start the session with the host [the call to StartCommunication()]
until after it has registered with ECLPS. This is done to ensure that no presentation space events are missed which
could cause incorrect behavior in the applet.
try {
ps.RegisterPSEvent(this);
} catch(ECLErr e) { System.out.println(e.GetMsgText()); }
// Start the session after registration so we don't
// miss any presentation space events.
s.StartCommunication()
- Implement methods that allow your class
to receive the events. These methods are defined by the ECLPSListener
interface, and the class you want to register must implement this interface.
The ECLPSListener interface is comprised of three methods which will handle different kinds of events occurring
within the presentation space. The PSNotifyEvent() method handles normal, non-error events and is the main method
for receiving and handling events. The PSNotifyStop() method handles stop events, and the PSNotifyError() method
handles errors which occur during event generation.
The following sample defines a simple PSNotifyEvent() method which recognizes screens and takes action on those
different screens.
public void PSNotifyEvent(ECLPSEvent evt) {
if (ps.SearchText("some text on the login screen", ps.SEARCH_FORWARD)) {
ps.SendKeys("myUserID"+ps.FWDTAB_STR+"myPW"+ps.ENTER_STR);
}
return;
}
This sample recognizes a particular host screen, such as a login prompt, then sends a user ID and password
to the host starting at the current cursor location. Note that the sample does not show the other two methods,
PSNotifyStop() and PSNotifyError(), which must be implemented to conform to the ECLPSListener interface.
Host On-Demand provides the ability
to load and run user-defined applets. You can launch a user applet from the Run Applet dialog or as a Startup
Applet. You can display the Run Applet dialog from either the button bar or the Assist pull-down menu. The
dialog prompts for the name of a user-defined class (without the .class extension), constructs an instance of the
class using the default constructor, and gives the class access to the current session. You can specify the Startup Applet in the session configuration window on the Advanced tab.
Personal Communications provides
only the Run Java Applet feature which is similar to the Run Applet feature of Host On-Demand.
The methods called when an applet is loaded are defined in an interface called ECLAppletInterface
and another called
CustomInterface.
These interfaces must be implemented by the main class of an applet which will be run using the feature.
ECLAppletInterface
To enable an applet to run within an active emulator window:
- Implement a default constructor. The default constructor has no parameters and is called when a class is dynamically loaded. The default
constructor does not have to contain any code.
The following sample code defines a default constructor for an applet class called MyClass.
public MyClass() { }
- Define the init() method, which is required for the implementation of ECLAppletInterface.
This is the only method (besides the constructor) which is called when the applet is loaded, so you must make sure
that the init() method gets the applet off and running. To do this, register with ECLPS to begin receiving
PS notification events.
Simply registering for PS events may not trigger the applet to start because it is probably waiting for the
first PS event, and there may not be any pending events when the applet is started. To work around this situation,
either attempt to recognize the current presentation space right away, or generate your own PS
event and let your PSNotifyEvent() method handle it.
The following sample code defines the init() method and shows one way of handling the initial presentation space
state. The sample assumes that MyClass implements ECLPSListener, in addition to ECLAppletInterface.
public void init(ECLSession session) {
ps = session.GetPS();
// Register with ECLPS to receive updates and new screens
try {
ps.RegisterPSEvent(this);
} catch(Exception e) { System.out.println("Registration Exception"); }
// Call our PSNotifyEvent() method to handle the initial state of the PS
PSNotifyEvent(new ECLPSEvent(ps));
}
-
Define the PSNotifyEvent(), PSNotifyStop(), and PSNotifyError() methods as required
by the ECLPSListener interface. In addition, MyClass must define that it implements ECLAppletInterface in its class
declaration.
To compile the user applets implementing ECLAppletInterface, the habeans.jar needs to be included in your CLASSPATH.
To run the applet, the compiled applet class must be placed in a directory at the HOD server where the main HOD files (HOD.html and HODAdmin.html) are stored. Then the client can connect to the HOD server and run the applet.
CustomInterface
Writing a HACL applet implementing a CustomInterface
is very similar to writing a HACL applet implementing an ECLAppletInterface.
To write a CustomInterface HACL applet, your applet must implement a CustomInterface
which requires an init() method and an update() method. A HIFramework
instance is passed for both init() and update() methods. This HIFramework
instance can be used to gain access to other class objects such as HostTerminal,
Applet, and Frame. From these object instances, you can then gain
access to other class objects. This is demonstrated in a sample
program provided below.
Below is a complete set of sample code for a user applet
implementing CustomInterface. This sample also implements ECLRecoNotify
interface for screen recognition notification. NotifyError(), NotifyEvent(),
and NotifyStop() methods are required to implement the ECLRecoNotify interface.
This sample program assumes that you are already
connected to a host login screen. You should change the User ID, password, strings to recognize,
and the commands to reflect the host you are connected
to. The sample program:
-
Registers and recognizes a login screen, and enters a user ID and password.
-
Registers and recognizes the next screen and enters a command.
-
Registers and recognizes the next screen and types a "logoff"
command to logoff from the host.
-
Registers and recognizes the next screen (back to login
screen) and closes the active emulator window.
// RunAppSam.java
import com.ibm.eNetwork.HOD.*;
import com.ibm.eNetwork.ECL.*;
import com.ibm.eNetwork.beans.HOD.*;
import com.ibm.eNetwork.beans.HOD.intf.*;
import java.awt.*;
import java.net.URL;
public class RunAppSam implements
CustomInterface, ECLRecoNotify
{
com.ibm.eNetwork.beans.HOD.HostTerminal
hostTerm = null;
java.awt.Frame fr = null;
java.applet.Applet applet
= null;
com.ibm.eNetwork.beans.HOD.Terminal
terminal = null;
com.ibm.eNetwork.ECL.ECLSession
eclSess = null;
com.ibm.eNetwork.ECL.ECLScreenDesc
sdLogonOff = null;
com.ibm.eNetwork.ECL.ECLScreenDesc
sdData1 = null;
com.ibm.eNetwork.ECL.ECLScreenDesc
sdData2 = null;
com.ibm.eNetwork.ECL.ECLScreenReco
eclSR = null;
com.ibm.eNetwork.HOD.HIFramework
framework = null;
boolean bLogon = true;
public RunAppSam()
{}
public void init(HIFramework
framework)
{
printTrace ("RunAppSam.init()
- Entry");
this.framework =
framework;
hostTerm = framework.getHostTerminal();
terminal = (Terminal)hostTerm;
applet = framework.getApplet();
fr = framework.getFrame();
eclSess = terminal.getECLSession();
if (applet != null)
{
printTrace
("got applet");
java.net.URL
docBase = applet.getDocumentBase();
java.net.URL
codeBase = applet.getCodeBase();
printTrace
("docBase = "+docBase);
printTrace
("codeBase = "+codeBase);
}
try
{
// define
screen descriptors to recognize
sdLogonOff
= new ECLScreenDesc();
sdLogonOff.AddString("USERID",
20, 2, true);
sdLogonOff.AddString("PASSWORD",
21, 2, true);
sdData1 = new
ECLScreenDesc();
sdData1.AddStringInRect("LOGON",
1, 1, -1, -1, true);
sdData1.AddString("MORE...",
24, 61);
sdData2 = new
ECLScreenDesc();
sdData2.AddStringInRect("Ready;",
1, 1, -1, -1, true);
sdData2.AddString("RUNNING",
24, 61, true);
bLogon = true;
// logon/logoff screen flag
if (hostTerm
!= null)
{
printTrace("hostTerm
!= null");
eclSR
= new ECLScreenReco();
eclSR.AddPS(eclSess.GetPS());
eclSR.RegisterScreen(sdLogonOff,
this);
}
}
catch (Exception
e){
printTrace
("Exception: "+e);
e.printStackTrace();
}
printTrace ("RunAppSam.init()
- Exit");
}
public void update(HIFramework
framework)
{
printTrace ("RunAppSam.update()");
}
// ECLRecoNotify interface
method
// Called whenever any
screen in the PS is matched to an ECLScreenDesc object in ECLScreenReco
public void NotifyEvent(ECLPS
ps, ECLScreenDesc sd)
{
if (sd == sdLogonOff
&& bLogon)
{ // Enter login
ID/PW
bLogon = false;
printTrace
("NotifyEvent(): Logon screen");
try
{
eclSR.UnregisterScreen
(sdLogonOff, this);
ps.SendKeys("userID[tab]password[enter]");
eclSR.RegisterScreen
(sdData1, this);
sleep(500);
}
catch (ECLErr
err)
{
printTrace
("ECLErr = "+err.toString());
}
}
else if (sd == sdData1)
{ // More screen
printTrace
("NotifyEvent(): More screen");
try
{
eclSR.UnregisterScreen
(sdData1, this);
ps.SendKeys("aCommand[enter]");
eclSR.RegisterScreen
(sdData2, this);
sleep(500);
}
catch (ECLErr
err)
{
printTrace
("ECLErr = "+err.toString());
}
}
else if (sd == sdData2)
{ // Logoff
printTrace
("NotifyEvent(): Data screen");
try
{
eclSR.UnregisterScreen
(sdData2, this);
ps.SendKeys("logoff[enter]");
eclSR.RegisterScreen
(sdLogonOff, this);
sleep(500);
}
catch (ECLErr
err)
{
printTrace
("ECLErr = "+err.toString());
}
}
else if (sd == sdLogonOff
&& !bLogon)
{ // close frame
and kill everything
printTrace
("NotifyEvent(): Logoff screen");
eclSR.UnregisterScreen
(sdLogonOff, this);
framework.close();
//closes session frame
}
}
// ECLRecoNotify interface
method
// Called when event generation
is stopped for any reason.
public void NotifyStop
(ECLScreenDesc sd, int reason)
{
printTrace ("RunAppSam.NotifyStop()");
}
// ECLRecoNotify interface
method
// Called whenever ECLScreenReco
object detects an error during event generation.
public void NotifyError
(ECLPS ps, ECLScreenDesc sd, ECLErr err)
{
printTrace ("RunAppSam.NotifyError()");
}
// sleep for mSec millisecond
private void sleep( long
mSec )
{
printTrace ("RunAppSam.sleep()");
try
{
java.lang.Thread.sleep(mSec);
}
catch (java.lang.InterruptedException
ie)
{
printTrace("Exception
= "+ie);
}
}
// Print a trace message
public void printTrace(String
msg)
{
System.out.println(msg);
}
}
To compile the user applets implementing CustomInterface, the habeans.jar needs to be included in your CLASSPATH.
To run the applet, the compiled applet class must be placed in a directory at the HOD server where the main HOD files (HOD.html and HODAdmin.html) are stored. Then the client can connect to the HOD server and run the applet.
[ Top of Page | Previous Page
| Next Page | Table of Contents
]