Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Host Access Class Library

Host Access Class Library Automation Objects

The Host Access Class Library Automation Objects allow the Personal Communications product to support Microsoft
COM-based automation technology (formerly known as OLE automation). The ECL Automation Objects are a series of
automation servers that allow automation controllers, for example, Microsoft Visual Basic, to programmatically access
Personal Communications data and functionality.

An example of this would be sending keys to Personal Communications presentation space. This can be accomplished by
manually typing keys in the Personal Communications window, but it can also be automated through the appropriate Personal
Communications automation server (autECLPS in this case). Using Visual Basic you can create the autECLPS object and
then call the SendKeys method in that object with the string that is to be placed in the presentation space.

In other words, applications that are enabled for controlling the automation protocol (automation controller) can control some
Personal Communications operations (automation server). Personal Communications supports Visual Basic Script, which
uses ECL Automation objects. Refer to the Personal Communications Macro/Script support for more details.

Personal Communications offers several automation servers to accomplish this. These 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. The objects are as follows:

autECLConnList, Connection List, on page "autECLConnList Class", 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, on page "autECLConnMgr Class", 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, on page "autECLFieldList Class", performs operations on fields in an emulator
presentation space.
autECLOIA, Operator Information Area, on page "autECLOIA Class", 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, on page "autECLPS Class", 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, on page "autECLScreenDesc Class", 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, on page "autECLScreenReco Class", provides the engine of the HACL
screen recognition system.
autECLSession, Session, on page "autECLSession Class", provides general session-related functionality and
information. For convenience, it contains the autECLPS, autECLOIA, autECLXfer, autECLWinMetrics,
autECLPageSettings, and autECLPrinterSettings objects.
autECLWinMetrics, Window Metrics, on page "autECLWinMetrics Class", 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, on page "autECLXfer Class", 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, on page "autECLPageSettings Class", 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, on page "autECLPrinterSettings Class", 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.

Figure 3 is a graphical representation of the autECL objects:

Figure 3. Host Access Class Library Automation Objects

1 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This chapter describes each object's methods and properties in detail and is intended to cover all potential users of the
automation object. Because the most common way to use the object is through a scripting application such as Visual Basic,
all examples are shown using a Visual Basic format.

autSystem Class
The autSystem Class provides two utility functions that may be useful for use with some programming languages. See
autSystem Class for more information.

2 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLConnList Class
autECLConnList contains information about all started connections. Its name in the registry is PCOMM.autECLConnList.

The autECLConnList object contains a collection of information about connections to a host. Each element of the collection
represents a single connection (emulator window). A connection in this list may be in any state (for example, stopped or
disconnected). All started connections appear in this list. The list element contains the state of the connection.

An autECLConnList object provides a static snapshot of current connections. The list is not dynamically updated as
connections are started and stopped. The Refresh method is automatically called upon construction of the autECLConnList
object. If you use the autECLConnList object right after its construction, your list of connections is current. However, you
should call the Refresh method in the autECLConnList object before accessing its other methods if some time has passed
since its construction to ensure that you have current data. Once you have called Refresh you may begin walking through the
collection

Properties

This section describes the properties for the autECLConnList object.

Type Name Attributes

Long Count Read-only

Count

This is the number of connections present in the autECLConnList collection for the last call to the Refresh method. The Count
property is a Long data type and is read-only. The following example uses the Count property.

Dim autECLConnList as Object

Dim Num as Long

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh
Num = autECLConnList.Count

The following table shows Collection Element Properties, which are valid for each item in the list.

Type Name Attributes

String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

Name

This collection element property is the connection name string of the connection. Personal Communications only returns the
short character ID (A-Z) in the string. There can be only one Personal Communications connection open with a given name.
For example, there can be only one connection "A" open at a time. Name is a String data type and is read-only. The following
example uses the Name collection element property.

Dim Str as String

Dim autECLConnList as Object
Dim Num as Long

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh

3 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Str = autECLConnList(1).Name

Handle

This collection element property is the handle of the connection. There can be only one Personal Communications
connection open with a given handle. Handle is a Long data type and is read-only. The following example uses the Handle
property.

Dim autECLConnList as Object

Dim Hand as Long

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh
Hand = autECLConnList(1).Handle

ConnType

This collection element property is the connection type. This type may change over time. ConnType is a String data type and
is read-only. The following example shows the ConnType property.

Dim Type as String

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh
Type = autECLConnList(1).ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

CodePage

This collection element property is the code page of the connection. This code page may change over time. CodePage is a
Long data type and is read-only. The following example shows the CodePage property.

Dim CodePage as Long

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh
CodePage = autECLConnList(1).CodePage

Started

This collection element property indicates whether the emulator window is started. The value is True if the window is open;
otherwise, it is False. Started is a Boolean data type and is read-only. The following example shows the Started property.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh

' This code segment checks to see if is started.

' The results are sent to a text box called Result.
If Not autECLConnList(1).Started Then

4 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This collection element property indicates the status of the connection to the host. The value is True if the host is connected;
otherwise, it is False. CommStarted is a Boolean data type and is read-only. The following example shows the CommStarted
property.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh

' This code segment checks to see if communications are connected

' The results are sent to a text box called CommConn.
If Not autECLConnList(1).CommStarted Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This collection element property indicates whether the emulator is API-enabled. A connection may be enabled or disabled
depending on the state of its API settings (in a Personal Communications window, choose File -> API Settings). The value is
True if the emulator is enabled; otherwise, it is False. APIEnabled is a Boolean data type and is read-only. The following
example shows the APIEnabled property.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh

' This code segment checks to see if API is enabled.

' The results are sent to a text box called Result.
If Not autECLConnList(1).APIEnabled Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This collection element property indicates whether the emulator window is started, API-enabled, and connected. This property
checks for all three properties. The value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type
and is read-only. The following example shows the Ready property.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

autECLConnList.Refresh

' This code segment checks to see if X is ready.

' The results are sent to a text box called Result.
If Not autECLConnList(1).Ready Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLConnList Methods

5 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The following section describes the methods that are valid for the autECLConnList object.
void Refresh()
Object FindConnectionByHandle(Long Hand)
Object FindConnectionByName(String Name)

Collection Element Methods

The following collection element methods are valid for each item in the list.
void StartCommunication()
void StopCommunication()

Refresh

The Refresh method gets a snapshot of all the started connections.

Note:
You should call this method before accessing the autECLConnList collection to ensure that you have current data.

Prototype

void Refresh()

Parameters

None

Return Value

None

Example

The following example shows how to use the Refresh method to get a snapshot of all the started connections.

Dim autECLPSObj as Object

Dim autECLConnList as Object

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

FindConnectionByHandle

This method finds an element in the autECLConnList object for the handle passed in the Hand parameter. This method is
commonly used to see if a given connection is alive in the system.

Prototype

Object FindConnectionByHandle(Long Hand)

Parameters

Long Hand
Handle to search for in the list.

Return Value

Object
Collection element dispatch object.

Example

6 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The following example shows how to find an element by the connection handle.

Dim Hand as Long

Dim autECLConnList as Object
Dim ConnObj as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the collection

autECLConnList.Refresh
' Assume Hand obtained earlier
Set ConnObj = autECLConnList.FindConnectionByHandle(Hand)
Hand = ConnObj.Handle

FindConnectionByName

This method finds an element in the autECLConnList object for the name passed in the Name parameter. This method is
commonly used to see if a given connection is alive in the system.

Prototype

Object FindConnectionByName(String Name)

Parameters

String Name
Name to search for in the list.

Return Value

Object
Collection element dispatch object.

Example

The following example shows how to find an element in the autECLConnList object by the connection name.

Dim Hand as Long

Dim autECLConnList as Object
Dim ConnObj as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the collection

autECLConnList.Refresh
' Assume Hand obtained earlier
Set ConnObj = autECLConnList.FindConnectionByName("A")
Hand = ConnObj.Handle

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

7 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

'Start the first session

autECLConnList.Refresh
autECLConnList(1).StartCommunication()

StopCommunication

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to disconnect a PCOMM emulator session from the host.

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

'Start the first session

autECLConnList.Refresh
autECLConnList(1).StartCommunication()
'
'Interact programmatically with host
'
autECLConnList.Refresh
'Stop the first session
autECLConnList(1).StartCommunication()

autECLConnMgr Class
autECLConnMgr manages all Personal Communications connections on a given machine. It contains methods relating to the
connection management such as starting and stopping connections. It also creates an autECLConnList object to enumerate
the list of all known connections on the system (see autECLConnList Class). Its name in the registry is
PCOMM.autECLConnMgr.

Properties

This section describes the properties for the autECLConnMgr object.

Type Name Attributes

autECLConnList Object autECLConnList Read-only

8 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLConnList

The autECLConnMgr object contains an autECLConnList object. See autECLConnList Class for details on its methods and
properties. The property has a value of autECLConnList, which is an autECLConnList dispatch object. The following example
shows this property.

Dim Mgr as Object

Dim Num as Long

Set Mgr = CreateObject("PCOMM.autECLConnMgr ")

Mgr.autECLConnList.Refresh
Num = Mgr.autECLConnList.Count

autECLConnMgr Methods
The following section describes the methods that are valid for autECLConnMgr.
void RegisterStartEvent()
void UnregisterStartEvent()
void StartConnection(String ConfigParms)
void StopConnection(Variant Connection, [optional] String StopParms)

RegisterStartEvent

This method registers an autECLConnMgr object to receive notification of start events in sessions.

Prototype

void RegisterStartEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterStartEvent

Ends Start Event Processing

Prototype

void UnregisterStartEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

StartConnection

9 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This member function starts a new Personal Communications emulator window. The ConfigParms string contains connection
configuration information as explained under Usage Notes.

Prototype

void StartConnection(String ConfigParms)

Parameters

String ConfigParms
Configuration string.

Return Value

None

Usage Notes

The configuration string is implementation-specific. Different implementations of the autECL objects may require different
formats or information in the configuration string. The new emulator is started upon return from this call, but it may or may not
be connected to the host.

For Personal Communications, the configuration string has the following format:

PROFILE=[']<filename>['] [CONNNAME=<c>] [WINSTATE=<MAX|MIN|RESTORE|HIDE>]

Optional parameters are enclosed in square brackets []. The parameters are separated by at least one blank. Parameters may
be in upper, lower, or mixed case and may appear in any order. The meaning of each parameter is as follows:

PROFILE=<filename>: Names the Personal Communications workstation profile (.WS file), which contains the
configuration information. This parameter is not optional; a profile name must be supplied. If the file name contains
blanks the name must be enclosed in single quotation marks. The <filename> value may be either the profile name
with no extension, the profile name with the .WS extension, or the fully qualified profile name path.
CONNNAME=<c> specifies the short ID of the new connection. This value must be a single, alphabetic character
(A-Z). If this value is not specified, the next available connection ID is assigned automatically.
WINSTATE=<MAX|MIN|RESTORE|HIDE> specifies the initial state of the emulator window. The default if this
parameter is not specified is RESTORE.

Example

The following example shows how to start a new Personal Communications emulator window.

Dim Mgr as Object

Dim Obj as Object
Dim Hand as Long

Set Mgr = CreateObject("PCOMM.autECLConnMgr ")

Mgr.StartConnection("profile=coax connname=e")

StopConnection

The StopConnection method stops (terminates) the emulator window identified by the connection handle. See Usage Notes
for contents of the StopParms string.

Prototype

void StopConnection(Variant Connection, [optional] String StopParms)

Parameters

Variant Connection
Connection name or handle. Legal types for this variant are short, long, BSTR, short by reference, long by reference, and
BSTR by reference.

10 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

String StopParms
Stop parameters string. See usage notes for format of string. This parameter is optional.

Return Value

None

Usage Notes

The stop parameter string is implementation-specific. Different implementations of the autECL objects may require a different
format and contents of the parameter string. For Personal Communications, the string has the following format:

[SAVEPROFILE=<YES|NO|DEFAULT>]

Optional parameters are enclosed in square brackets []. The parameters are separated by at least one blank. Parameters may
be in upper, lower, or mixed case and may appear in any order. The meaning of each parameter is as follows:

SAVEPROFILE=<YES|NO|DEFAULT> controls the saving of the current configuration back to the workstation profile
(.WS file). This causes the profile to be updated with any configuration changes you may have made. If NO is
specified, the connection is stopped and the profile is not updated. If YES is specified, the connection is stopped and
the profile is updated with the current (possibly changed) configuration. If DEFAULT is specified, the update option is
controlled by the File->Save On Exit emulator menu option. If this parameter is not specified, DEFAULT is used.

Example

The following example shows how to stop the emulator window identified by the connection handle.

Dim Mgr as Object

Dim Hand as Long

Set Mgr = CreateObject("PCOMM.autECLConnMgr ")

' Assume we've got connections open and the Hand parm was obtained earlier
Mgr.StopConnection Hand, "saveprofile=no"
'or
Mgr.StopConnection "B", "saveprofile=no"

autECLConnMgr Events
The following events are valid for autECLConnMgr:
void NotifyStartEvent(By Val Handle As Variant, By Val Started As Boolean)
NotifyStartError(By Val ConnHandle As Variant)
void NotifyStartStop(Long Reason)

NotifyStartEvent

A Session has started or stopped.

Prototype

void NotifyStartEvent(By Val Handle As Variant, By Val Started As Boolean)

Note:
Visual Basic will create this subroutine correctly.

Parameters

By Val Handle As Variant

Handle of the Session that started or stopped.

By Val Started As Boolean

11 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

True if the Session is started, False otherwise.

Example

See Event Processing Example for an example.

NotifyStartError

This event occurs when an error occurs in Event Processing.

Prototype

NotifyStartError(By Val ConnHandle As Variant)

Note:
Visual Basic will create this subroutine correctly.

Parameters

None

Example

See Event Processing Example for an example.

NotifyStartStop

This event occurs when event processing stops.

Prototype

void NotifyStartStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently, this will always be 0.

Event Processing Example

The following is a short example of how to implement Start Events:

Option Explicit

Private WithEvents mCmgr As autECLConnMgr 'AutConnMgr added as reference

dim mSess as object

sub main()

'Create Objects

Set mCmgr = New autECLConnMgr

Set mSess = CreateObject("PCOMM.autECLSession")

mCmgr.RegisterStartEvent 'register for PS Updates

12 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

mCmgr.UnregisterStartEvent

set mCmgr = Nothing

set mSess = Nothing

End Sub

'This sub will get called when a session is started or stopped

Private Sub mCmgr_NotifyStartEvent(Handle as long, bStarted as Boolean)

' do your processing here

if (bStarted) then

mSess.SetConnectionByHandle Handle

end if

End Sub

'This event occurs if an error happens

Private Sub mCmgr_NotifyStartError()

'Do any error processing here

End Sub

Private Sub mCmgr_NotifyStartStop(Reason As Long)

'Do any stop processing here

End Sub

autECLFieldList Class
autECLFieldList performs operations on fields in an emulator presentation space. This object does not stand on its own. It is
contained by autECLPS, and can only be accessed through an autECLPS object. autECLPS can stand alone or be contained
by autECLSession.

autECLFieldList contains a collection of all the fields on a given presentation space. Each element of the collection contains
the elements shown in Collection Element Properties.

An autECLFieldList object provides a static snapshot of what the presentation space contained when the Refresh method
was called.

Note:
You should call the Refresh method in the autECLFieldList object before accessing its elements to ensure that you have
current field data. Once you have called Refresh, you may begin walking through the collection.

Properties

This section describes the properties and the collection element properties for the autECLFieldList object.

13 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Type Name Attributes

Long Count Read-only

Count

This property is the number of fields present in the autECLFieldList collection for the last call to the Refresh method. Count is
a Long data type and is read-only. The following example shows this property.

Dim NumFields as long

Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
NumFields = autECLPSObj.autECLFieldList.Count

The following properties are collection element properties and are valid for each item in the list.

Type Name Attributes

Long StartRow Read-only
Long StartCol Read-only
Long EndRow Read-only
Long EndCol Read-only
Long Length Read-only
Boolean Modified Read-only
Boolean Protected Read-only
Boolean Numeric Read-only
Boolean HighIntensity Read-only
Boolean PenDetectable Read-only
Boolean Display Read-only

StartRow

This collection element property is the row position of the first character in a given field in the autECLFieldList collection.
StartRow is a Long data type and is read-only. The following example shows this property.

Dim StartRow as Long

Dim StartCol as Long
Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
StartRow = autECLPSObj.autECLFieldList(1).StartRow
StartCol = autECLPSObj.autECLFieldList(1).StartCol
Endif

StartCol

14 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This collection element property is the column position of the first character in a given field in the autECLFieldList collection.
StartCol is a Long data type and is read-only. The following example shows this property.

Dim StartRow as Long

Dim StartCol as Long
Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
StartRow = autECLPSObj.autECLFieldList(1).StartRow
StartCol = autECLPSObj.autECLFieldList(1).StartCol
Endif

EndRow

This collection element property is the row position of the last character in a given field in the autECLFieldList collection.
EndRow is a Long data type and is read-only. The following example shows this property.

Dim EndRow as Long

Dim EndCol as Long
Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
EndRow = autECLPSObj.autECLFieldList(1).EndRow
EndCol = autECLPSObj.autECLFieldList(1).EndCol
Endif

EndCol

This collection element property is the column position of the last character in a given field in the autECLFieldList collection.
EndCol is a Long data type and is read-only. The following example shows this property.

Dim EndRow as Long

Dim EndCol as Long
Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
EndRow = autECLPSObj.autECLFieldList(1).EndRow
EndCol = autECLPSObj.autECLFieldList(1).EndCol
Endif

15 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Length

This collection element property is the length of a given field in the autECLFieldList collection. Length is a Long data type and
is read-only. The following example shows this property.

Dim Len as Long

Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
Len = autECLPSObj.autECLFieldList(1).Length
Endif

Modified

This collection element property indicates if a given field in the autECLFieldList collection has a modified attribute. Modified is
a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).Modified ) Then
' do whatever
Endif
Endif

Protected

This collection element property indicates if a given field in the autECLFieldList collection has a protected attribute. Protected
is a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).Protected ) Then
' do whatever
Endif
Endif

Numeric

16 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This collection element property indicates if a given field in the autECLFieldList collection has a numeric input only attribute.
Numeric is a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).Numeric ) Then
' do whatever
Endif
Endif

HighIntensity

This collection element property indicates if a given field in the autECLFieldList collection has a high intensity attribute.
HighIntensity is a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).HighIntensity ) Then
' do whatever
Endif
Endif

PenDetectable

This collection element property indicates if a given field in the autECLFieldList collection has a pen detectable attribute.
PenDetectable is a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).PenDetectable ) Then
' do whatever
Endif
Endif

Display

17 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This collection element property indicates whether a given field in the autECLFieldList collection has a display attribute.
Display is a Boolean data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh(1)
If (Not autECLPSObj.autECLFieldList.Count = 0 ) Then
If ( autECLPSObj.autECLFieldList(1).Display ) Then
' do whatever
Endif
Endif

autECLFieldList Methods
The following section describes the methods that are valid for the autECLFieldList object.

void Refresh()
Object FindFieldByRowCol(Long Row, Long Col)
Object FindFieldByText(String text, [optional] Long Direction, [optional] Long StartRow,
[optional] Long StartCol)

Collection Element Methods

The following collection element methods are valid for each item in the list.
String GetText()
void SetText(String Text)

Refresh

The Refresh method gets a snapshot of all the fields.

Note:
You should call the Refresh method before accessing the field collection to ensure that you have current field data.

Prototype

void Refresh()

Parameters

None

Return Value

None

Example

The following example shows how to get a snapshot of all the fields for a given presentation space.

Dim NumFields as long

Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")

18 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and get the number of fields

autECLPSObj.autECLFieldList.Refresh()
NumFields = autECLPSObj.autECLFieldList.Count

FindFieldByRowCol

This method searches the autECLFieldList object for a field containing the given row and column coordinates. The value
returned is a collection element object in the autECLFieldList collection.

Prototype

Object FindFieldByRowCol(Long Row, Long Col)

Parameters

Long Row
Field row to search for.

Long Col
Field column to search for.

Return Value

Object
Dispatch object for the autECLFieldList collection item.

Example

The following example shows how to search the autECLFieldList object for a field containing the given row and column
coordinates.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim FieldElement as Object

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

Set autECLConnList = CreateObject("PCOMM.autECLConnList)

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and search for field at row 2 col 1
autECLPSObj.autECLFieldList.Refresh(1)
Set FieldElement = autECLPSObj.autECLFieldList.FindFieldByRowCol( 2, 1 )
FieldElement.SetText("IBM")

FindFieldByText

This method searches the autECLFieldList object for a field containing the string passed in as Text. The value returned is a
collection element object in the autECLFieldList collection.

Prototype

Object FindFieldByText(String Text, [optional] Long Direction, [optional] Long StartRow, [optional] Long StartCol)

Parameters

String Text

19 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The text string to search for.

Long StartRow
Row position in the presentation space at which to begin the search.

Long StartCol
Column position in the presentation space at which to begin the search.

Long Direction
Direction in which to search. Values are 1 for search forward, 2 for search backward

Return Value

Object
Dispatch object for the autECLFieldList collection item.

Example

The following example shows how to search the autECLFieldList object for a field containing the string passed in as text.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim FieldElement as Object

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and search for field with text
autECLPSObj.autECLFieldList.Refresh(1)
set FieldElement = autECLPSObj.autECLFieldList.FindFieldByText "IBM"

' Or... search starting at row 2 col 1

set FieldElement = autECLPSObj.autECLFieldList.FindFieldByText "IBM", 2, 1
' Or... search starting at row 2 col 1 going backwards
set FieldElement = autECLPSObj.autECLFieldList.FindFieldByText "IBM", 2, 2, 1

FieldElement.SetText("Hello.")

GetText

The collection element method GetText retrieves the characters of a given field in an autECLFieldList item.

Prototype

String GetText()

Parameters

None

Return Value

String
Field text.

Example

The following example shows how to use the GetText method.

Dim autECLPSObj as Object

20 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim TestStr as String

' Initialize the connection

Set autECLPSObj = CreateObject("PCOMM.autECLPS")
autECLPSObj.SetConnectionByName("A")

autECLPSObj.autECLFieldList.Refresh()
TextStr = autECLPSObj.autECLFieldList(1).GetText()

SetText

This method populates a given field in an autECLFieldList item with the character string passed in as text. If the text exceeds
the length of the field, the text is truncated.

Prototype

void SetText(String Text)

Parameters

String text
String to set in field

Return Value

None

Example

The following example shows how to populate the field in an autECLFieldList item with the character string passed in as text.

Dim NumFields as Long

Dim autECLPSObj as Object
Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the list and set the first field with some text
autECLPSObj.autECLFieldList.Refresh(1)
autECLPSObj.autECLFieldList(1).SetText("IBM is a cool company")

autECLOIA Class
The autECLOIA object retrieves status from the Host Operator Information Area. Its name in the registry is
PCOMM.autECLOIA.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection may be set only once. After the connection is set, any further calls to the set connection
methods cause an exception. If you do not set the connection and try to access a property or method, an exception is also
raised.

Note:
The autECLOIA object in the autECLSession object is set by the autECLSession object.

The following example shows how to create and set the autECLOIA object in Visual Basic.

DIM autECLOIA as Object

21 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

autECLOIA.SetConnectionByName("A")

Properties

This section describes the properties for the autECLOIA object.

Type Name Attributes

Boolean Alphanumeric Read-only
Boolean APL Read-only
Boolean Katakana Read-only
Boolean Hiragana Read-only
Boolean DBCS Read-only
Boolean UpperShift Read-only
Boolean Numeric Read-only
Boolean CapsLock Read-only
Boolean InsertMode Read-only
Boolean CommErrorReminder Read-only
Boolean MessageWaiting Read-only
Long InputInhibited Read-only
String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only
Boolean NumLock Read-only

Alphanumeric

This property queries the operator information area to determine whether the field at the cursor location is alphanumeric.
Alphanumeric is a Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

If autECLOIA.Alphanumeric Then...

APL

This property queries the operator information area to determine whether the keyboard is in APL mode. APL is a Boolean
data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if the keyboard is in APL mode

if autECLOIA.APL Then...

22 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Katakana

This property queries the operator information area to determine whether Katakana characters are enabled. Katakana is a
Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if Katakana characters are available

if autECLOIA.Katakana Then...

Hiragana

This property queries the operator information area to determine whether Hiragana characters are enabled. Hiragana is a
Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if Hiragana characters are available

if autECLOIA.Hiragana Then...

DBCS

This property queries the operator information area to determine whether the field at the cursor location is DBCS. DBCS is a
Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if DBCS is available

if autECLOIA.DBCS Then...

UpperShift

This property queries the operator information area to determine whether the keyboard is in uppershift mode. Uppershift is a
Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

23 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if the keyboard is in uppershift mode

If autECLOIA.UpperShift then...

Numeric

This property queries the operator information area to determine whether the field at the cursor location is numeric. Numeric is
a Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if the cursor location is a numeric field

If autECLOIA.Numeric Then...

CapsLock

This property queries the operator information area to determine if the keyboard CapsLock key is on. CapsLock is a Boolean
data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if the caps lock

If autECLOIA.CapsLock Then...

InsertMode

This property queries the operator information area to determine whether if the keyboard is in insert mode. InsertMode is a
Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if in insert mode

If autECLOIA.InsertMode Then...

CommErrorReminder

This property queries the operator information area to determine whether a communications error reminder condition exists.
CommErrorReminder is a Boolean data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

24 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if comm error

If autECLOIA.CommErrorReminder Then...

MessageWaiting

This property queries the operator information area to determine whether the message waiting indicator is on. This can only
occur for 5250 connections. MessageWaiting is a Boolean data type and is read-only. The following example shows this
property.

DIM autECLOIA as Object

DIM autECLConnList as Object
Set autECLOIA = CreateObject("PCOMM.autECLOIA")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if message waiting

If autECLOIA.MessageWaiting Then...

InputInhibited

This property queries the operator information area to determine whether keyboard input is inhibited. InputInhibited is a Long
data type and is read-only. The following table shows valid values for InputInhibited.

Name Value
Not Inhibited 0
System Wait 1
Communication Check 2
Program Check 3
Machine Check 4
Other Inhibit 5

The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object
Set autECLOIA = CreateObject("PCOMM.autECLOIA")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)

' Check if input inhibited

If not autECLOIA.InputInhibited = 0 Then...

Name

This property is the connection name string of the connection for which autECLOIA was set. Personal Communications only
returns the short character ID (A-Z) in the string. There can be only one Personal Communications connection open with a
given name. For example, there can be only one connection "A" open at a time. Name is a String data type and is read-only.
The following example shows this property.

DIM Name as String

25 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the name

Name = Obj.Name

Handle

This is the handle of the connection for which the autECLOIA object was set. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.
Handle is a Long data type and is read-only. The following example shows this property.

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the handle

Hand = Obj.Handle

ConnType

This is the connection type for which autECLOIA was set. This type may change over time. ConnType is a String data type
and is read-only. The following example shows this property.

DIM Type as String

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the type
Type = Obj.ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

CodePage

This is the code page of the connection for which autECLOIA was set. This code page may change over time. CodePage is
a Long data type and is read-only. The following example shows this property.

DIM CodePage as Long

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the code page
CodePage = Obj.CodePage

Started

This indicates whether the emulator window is started. The value is True if the window is open; otherwise, it is False. Started

26 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If Obj.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This indicates the status of the connection to the host. The value is True if the host is connected; otherwise, it is False.
CommStarted is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If Obj.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This indicates whether the emulator is API-enabled. A connection may be enabled or disabled depending on the state of its
API settings (in a Personal Communications window, choose File -> API Settings). The value is True if the emulator is
enabled; otherwise, it is False. APIEnabled is a Boolean data type and is read-only. The following example shows this
property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is API enabled.

' The results are sent to a text box called Result.
If Obj.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This indicates whether the emulator window is started, API-enabled, and connected. This property checks for all three

27 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

properties. The value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type and is read-only.
The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If Obj.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

NumLock

This property queries the operator information area to determine if the keyboard NumLock key is on. NumLock is a Boolean
data type and is read-only. The following example shows this property.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject ("PCOMM.autECLOIA")

Set autECLConnList = CreateObject ("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByFHandle (autECLConnList (1) .Handle)

' Check if the num lock is on

If autECLOIA.NumLock Then . . .

autECLOIA Methods
The following section describes the methods that are valid for autECLOIA.
void RegisterOIAEvent()
void UnregisterOIAEvent()
void SetConnectionByName (String Name)
void SetConnectionByHandle (Long Handle)
void StartCommunication()
void StopCommunication()
Boolean WaitForInputReady([optional] Variant TimeOut)
Boolean WaitForSystemAvailable([optional] Variant TimeOut)
Boolean WaitForAppAvailable([optional] Variant TimeOut)
Boolean WaitForTransition([optional] Variant Index, [optional] Variant timeout)
void CancelWaits()

RegisterOIAEvent

This method registers an object to receive notification of all OIA events.

Prototype

void RegisterOIAEvent()

Parameters

28 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterOIAEvent

Ends OIA event processing.

Prototype

void UnregisterOIAEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

SetConnectionByName

The SetConnectionByName method uses the connection name to set the connection for a newly created autECLOIA object.
In Personal Communications this connection name is the short connection ID (character A-Z). There can be only one
Personal Communications connection open with a given name. For example, there can be only one connection "A" open at a
time.

Note:
Do not call this if using the autECLOIA object in autECLSession.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection (A-Z).

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created autECLOIA object.

DIM autECLOIA as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

' Initialize the connection

autECLOIA.SetConnectionByName("A")
' For example, see if its num lock is on

29 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

If ( autECLOIA.NumLock = True ) Then

'your logic here...
Endif

SetConnectionByHandle

The SetConnectionByHandle method uses the connection handle to set the connection for a newly created autECLOIA
object. In Personal Communications this connection handle is a Long integer. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLOIA object in autECLSession.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle
Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created autELCOIA object.

DIM autECLOIA as Object

DIM autECLConnList as Object

Set autECLOIA = CreateObject("PCOMM.autECLOIA")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLOIA.SetConnectionByHandle(autECLConnList(1).Handle)
' For example, see if its num lock is on
If ( autECLOIA.NumLock = True ) Then
'your logic here...
Endif

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

None

30 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim OIAObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set OIAObj = CreateObject("PCOMM.autECLOIA")

' Initialize the session

autECLConnList.Refresh
OIAObj.SetConnectionByHandle(autECLConnList(1).Handle)

OIAObj.StartCommunication()

StopCommunication

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim OIAObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set OIAObj = CreateObject("PCOMM.autECLOIA")

' Initialize the session

autECLConnList.Refresh
OIAObj.SetConnectionByHandle(autECLConnList(1).Handle)

OIAObj.StopCommunication()

WaitForInputReady

The WaitForInputReady method waits until the OIA of the connection associated with the autECLOIA object indicates that the
connection is able to accept keyboard input.

Prototype

Boolean WaitForInputReady([optional] Variant TimeOut)

Parameters

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

31 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim autECLOIAObj as Object

Set autECLOIAObj = CreateObject("PCOMM.autECLOIA")

autECLOIAObj.SetConnectionByName("A")

if (autECLOIAObj.WaitForInputReady(10000)) then

msgbox "Ready for input"

else

msgbox "Timeout Occurred"

end if

WaitForSystemAvailable

The WaitForSystemAvailable method waits until the OIA of the connection associated with the autECLOIA object indicates
that the connection is connected to a host system.

Prototype

Boolean WaitForSystemAvailable([optional] Variant TimeOut)

Parameters

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLOIAObj as Object

Set autECLOIAObj = CreateObject("PCOMM.autECLOIA")

autECLOIAObj.SetConnectionByName("A")

if (autECLOIAObj.WaitForSystemAvailable(10000)) then

msgbox "System Available"

else

msgbox "Timeout Occurred"

end if

WaitForAppAvailable

32 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The WaitForAppAvailable method waits while the OIA of the connection associated with the autECLOIA object indicates that
the application is being worked with.

Prototype

Boolean WaitForAppAvailable([optional] Variant TimeOut)

Parameters

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLOIAObj as Object

Set autECLOIAObj = CreateObject("PCOMM.autECLOIA")

autECLOIAObj.SetConnectionByName("A")

if (autECLOIAObj.WaitForAppAvailable (10000)) then

msgbox "Application is available"

else

msgbox "Timeout Occurred"

end if

WaitForTransition

The WaitForTransition method waits for the OIA position specified of the connection associated with the autECLOIA object to
change.

Prototype

Boolean WaitForTransition([optional] Variant Index, [optional] Variant timeout)

Parameters

Variant Index
The 1 byte Hex position of the OIA to monitor. This parameter is optional. The default is 3.

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

33 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim autECLOIAObj as Object

Dim Index

Index = 03h

Set autECLOIAObj = CreateObject("PCOMM.autECLOIA")

autECLOIAObj.SetConnectionByName("A")

if (autECLOIAObj.WaitForTransition(Index,10000)) then

msgbox "Position " " Index " " of the OIA Changed"

else

msgbox "Timeout Occurred"

end if

CancelWaits

Cancels any currently active wait methods.

Prototype

void CancelWaits()

Parameters

None

Return Value

None

autECLOIA Events
The following events are valid for autECLOIA:
void NotifyOIAEvent()
void NotifyOIAError()
void NotifyOIAStop(Long Reason)

NotifyOIAEvent

A given OIA has occurred.

Prototype

void NotifyOIAEvent()

Parameters

None

Example

See Event Processing Example for an example.

34 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

NotifyOIAError

This event occurs when an error occurs in the OIA.

Prototype

void NotifyOIAError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyOIAStop

This event occurs when event processing stops.

Prototype

void NotifyOIAStop(Long Reason)

Parameters

Long Reason
Long Reason code for the stop. Currently, this will always be 0.

Event Processing Example

The following is a short example of how to implement OIA Events

Option Explicit

Private WithEvents myOIA As autECLOIA 'AutOIA added as reference

sub main()

'Create Objects

Set myOIA = New AutOIA

Set myConnMgr = New AutConnMgr

myOIA.SetConnectionByName ("B") 'Monitor Session B for OIA Updates

myOIA.RegisterOIAEvent 'register for OIA Notifications

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

35 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

'Clean up

myOIA.UnregisterOIAEvent

Private Sub myOIA_NotifyOIAEvent()

' do your processing here

End Sub

Private Sub myOIA_NotifyOIAError()

' do your processing here

End Sub

'This event occurs when Communications Status Notification ends

Private Sub myOIA_NotifyOIAStop(Reason As Long)

'Do any stop processing here

End Sub

autECLPS Class
autECLPS performs operations on a presentation space. Its name in the registry is PCOMM.autECLPS.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection may be set only once. After the connection is set, any further calls to the SetConnection
methods cause an exception. If you do not set the connection and try to access a property or method, an exception is also
raised.

Notes:

1. In the presentation space, the first row coordinate is row 1 and the first column coordinate is column 1. Therefore, the
top, left position has a coordinate of row 1, column 1.

2. The autECLPS object in the autECLSession object is set by the autECLSession object.

The following is an example of how to create and set the autECLPS object in Visual Basic.

DIM autECLPSObj as Object

DIM NumRows as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
' Initialize the connection
autECLPSObj .SetConnectionByName("A")
' For example, get the number of rows in the PS
NumRows = autECLPSObj.NumRows

Properties

This section describes the properties of the autECLPS object.

Type Name Attributes

Object autECLFieldList Read-only
Long NumRows Read-only

36 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Long NumCols Read-only

Long CursorPosRow Read-only
Long CursorPosCol Read-only
String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

autECLFieldList

This is the field collection object for the connection associated with the autECLPS object. See autECLFieldList Class for
details. The following example shows this object.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

' Build the field list

CurPosCol = autECLPSObj.autECLFieldList.Refresh(1)

NumRows

This is the number of rows in the presentation space for the connection associated with the autECLPS object. NumRows is a
Long data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim Rows as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
Rows = autECLPSObj.NumRows

NumCols

This is the number of columns in the presentation space for the connection associated with the autECLPS object. NumCols is
a Long data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim Cols as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
Cols = autECLPSObj.NumCols

CursorPosRow

This is the current row position of the cursor in the presentation space for the connection associated with the autECLPS

37 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

object. CursorPosRow is a Long data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim CurPosRow as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
CurPosRow = autECLPSObj.CursorPosRow

CursorPosCol

This is the current column position of the cursor in the presentation space for the connection associated with the autECLPS
object. CursorPosCol is a Long data type and is read-only. The following example shows this property.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim CurPosCol as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
CurPosCol = autECLPSObj.CursorPosCol

Name

This is the connection name string of the connection for which autECLPS was set. Personal Communications only returns the
short character ID (A-Z) in the string. There can be only one Personal Communications connection open with a given name.
For example, there can be only one connection "A" open at a time. Name is a String data type and is read-only. The following
example shows this property.

DIM Name as String

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the name

Name = Obj.Name

Handle

This is the handle of the connection for which the autECLPS object was set. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.
Handle is a Long data type and is read-only. The following example shows this property.

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the connection handle

Hand = Obj.Handle

ConnType

This is the connection type for which autECLPS was set. This connection type may change over time. ConnType is a String
data type and is read-only. The following example shows this property.

38 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

DIM Type as String

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the type
Type = Obj.ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

CodePage

This is the code page of the connection for which autECLPS was set. This code page may change over time. CodePage is a
Long data type and is read-only. The following example shows this property.

DIM CodePage as Long

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the code page
CodePage = Obj.CodePage

Started

This indicates if the connection emulator window is started. The value is True if the window is open; otherwise, it is False.
Started is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If Obj.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This indicates the status of the connection to the host. The value is True if the host is connected; otherwise, it is False.
CommStarted is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

39 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Obj.SetConnectionByName("A")

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If Obj.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This indicates if the emulator is API-enabled. A connection may be enabled or disabled depending on the state of its API
settings (in a Personal Communications window, choose File -> API Settings). The value is True if API is enabled; otherwise,
it is False. APIEnabled is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is API enabled.

' The results are sent to a text box called Result.
If Obj.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This indicates whether the emulator window is started, API enabled and connected. This checks for all three properties. The
value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type and is read-only. The following
example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If Obj.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLPS Methods
The following section describes the methods that are valid for the autECLPS object.

void RegisterPSEvent()
void RegisterKeyEvent()
void RegisterCommEvent()
void UnregisterPSEvent()
void UnregisterKeyEvent()
void UnregisterCommEvent()
void SetConnectionByName (String Name)

40 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void SetConnectionByHandle (Long Handle)

void SetCursorPos(Long Row, Long Col)
void SendKeys(String text, [optional] Long row, [optional] Long col)
Boolean SearchText(String text, [optional] Long Dir, [optional] Long row,
[optional] Long col)
String GetText([optional] Long row, [optional] Long col, [optional] Long lenToGet)
void SetText(String Text, [optional] Long Row, [optional] Long Col)
String GetTextRect(Long StartRow, Long StartCol, Long EndRow, Long EndCol )
void StartCommunication()
void StopCommunication()
void StartMacro(String MacroName)
void Wait(milliseconds as Long)
Boolean WaitForCursor(Variant Row, Variant Col, [optional]Variant TimeOut,
[optional] Boolean bWaitForIr)
Boolean WaitWhileCursor(Variant Row, Variant Col, [optional]Variant TimeOut,
[optional] Boolean bWaitForIr)
Boolean WaitForString(Variant WaitString, [optional] Variant Row,
[optional] Variant Col, [optional] Variant TimeOut, [optional] Boolean bWaitForIr,
[optional] Boolean bCaseSens)
Boolean WaitWhileString(Variant WaitString, [optional] Variant Row,
[optional] Variant Col, [optional] Variant TimeOut, [optional] Boolean bWaitForIr,
[optional] Boolean bCaseSens)
Boolean WaitForStringInRect(Variant WaitString, Variant sRow, Variant sCol,
Variant eRow, Variant eCol, [optional] Variant nTimeOut,
[optional] Boolean bWaitForIr, [optional] Boolean bCaseSens)
Boolean WaitWhileStringInRect(Variant WaitString, Variant sRow, Variant sCol,
Variant eRow, Variant eCol, [optional] Variant nTimeOut,
[optional] Boolean bWaitForIr, [optional] Boolean bCaseSens)
Boolean WaitForAttrib(Variant Row, Variant Col, Variant WaitData,
[optional] Variant MaskData, [optional] Variant plane, [optional] Variant TimeOut,
[optional] Boolean bWaitForIr)
Boolean WaitWhileAttrib(Variant Row, Variant Col, Variant WaitData,
[optional] Variant MaskData, [optional] Variant plane,
[optional] Variant TimeOut, [optional] Boolean bWaitForIr)
Boolean WaitForScreen(Object screenDesc, [optional] Variant TimeOut)
Boolean WaitWhileScreen(Object screenDesc, [optional] Variant TimeOut)
void CancelWaits()

RegisterPSEvent

This method registers an autECLPS object to receive notification of all changes to the PS of the connected session.

Prototype

void RegisterPSEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

RegisterKeyEvent

Begins Keystroke Event Processing.

Prototype

void RegisterKeyEvent()

Parameters

None

Return Value

None

41 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

See Event Processing Example for an example.

RegisterCommEvent

This method registers an object to receive notification of all communication link connect/disconnect events.

Prototype

void RegisterCommEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterPSEvent

Ends PS Event Processing.

Prototype

void UnregisterPSEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterKeyEvent

Ends Keystroke Event Processing.

Prototype

void UnregisterKeyEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterCommEvent

42 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Ends Communications Link Event Processing.

Prototype

void UnregisterCommEvent()

Parameters

None

Return Value

None

SetConnectionByName

This method uses the connection name to set the connection for a newly created autECLPS object. In Personal
Communications this connection name is the short ID (character A-Z). There can be only one Personal Communications
connection open with a given name. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLPS object in autECLSession.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection (A-Z).

Return Value

None

Example

The following example shows how to set the connection for a newly created autECLPS object using the connection name.

DIM autECLPSObj as Object

DIM NumRows as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")

' Initialize the connection

autECLPSObj.SetConnectionByName("A")
' For example, get the number of rows in the PS
NumRows = autECLPSObj.NumRows

SetConnectionByHandle

This method uses the connection handle to set the connection for a newly created autECLPS object. In Personal
Communications this connection handle is a Long integer. There can be only one Personal Communications connection open
with a given handle. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLPS object in autECLSession.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

43 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Long Handle
Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to set the connection for a newly created autECLPS object using the connection handle.

DIM autECLPSObj as Object

DIM autECLConnList as Object
DIM NumRows as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection with the first in the list

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
' For example, get the number of rows in the PS
NumRows = autECLPSObj.NumRows

SetCursorPos

The SetCursorPos method sets the position of the cursor in the presentation space for the connection associated with the
autECLPS object. The position set is in row and column units.

Prototype

void SetCursorPos(Long Row, Long Col)

Parameters

Long Row
The row position of the cursor in the presentation space.

Long Col
The column position of the cursor in the presentation space.

Return Value

None

Example

The following example shows how to set the position of the cursor in the presentation space for the connection associated
with the autECLPS object.

DIM autECLPSObj as Object

DIM autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection with the first in the list

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
autECLPSObj.SetCursorPos 2, 1

SendKeys

The SendKeys method sends a string of keys to the presentation space for the connection associated with the autECLPS
object. This method allows you to send mnemonic keystrokes to the presentation space. See Appendix A, Sendkeys
Mnemonic Keywords for a list of these keystrokes.

44 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Prototype

void SendKeys(String text, [optional] Long row, [optional] Long col)

Parameters

String text
String of keys to send to the presentation space.

Long Row
Row position to send keys to the presentation space. This parameter is optional. The default is the current cursor row
position. If row is specified, col must also be specified.

Long Col
Column position to send keys to the presentation space. This parameter is optional. The default is the current cursor
column position. If col is specified, row must also be specified.

Return Value

None

Example

The following example shows how to use the SendKeys method to send a string of keys to the presentation space for the
connection associated with the autECLPS object.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)
autECLPSObj.SendKeys "IBM is a really cool company", 3, 1

SearchText

The SearchText method searches for the first occurrence of text in the presentation space for the connection associated with
the autECLPS object. The search is case-sensitive. If text is found, the method returns a TRUE value. It returns a FALSE
value if no text is found. If the optional row and column parameters are used, row and col are also returned, indicating the
position of the text if it was found.

Prototype

boolean SearchText(String text, [optional] Long Dir, [optional] Long Row, [optional] Long Col)

Parameters

String text
String to search for.

Long Dir
Direction in which to search. Must either be 1 for search forward or 2 for search backward. This parameter is optional. The
default is 1 for Forward.

Long Row
Row position at which to start the search in the presentation space. The row of found text is returned if the search is
successful. This parameter is optional. If row is specified, col must also be specified.

Long Col
Column position at which to start the search in the presentation space. The column of found text is returned if the search is

45 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

successful. This parameter is optional. If col is specified, row must also be specified.

Return Value

TRUE if text is found, FALSE if text is not found.

Example

The following example shows how to search for text in the presentation space for the connection associated with the
autECLPS object.

Dim autECLPSObj as Object

Dim autECLConnList as Object
Dim Row as Long
Dim Col as Long
Set autECLPSObj = CreateObject("PCOMM.autECLPS")
Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

// Search forward in the PS from the start of the PS. If found

// then call a hypothetical found routine, if not found, call a hypothetical

// not found routine.

row = 3
col = 1
If ( autECLPSObj.SearchText "IBM", 1, row, col) Then
Call FoundFunc (row, col)
Else
Call NotFoundFunc
Endif

GetText

The GetText method retrieves characters from the presentation space for the connection associated with the autECLPS
object.

Prototype

String GetText([optional] Long Row, [optional] Long Col, [optional] Long LenToGet)

Parameters

Long Row
Row position at which to start the retrieval in the presentation space. This parameter is optional.

Long Col
Column position at which to start the retrieval in the presentation space. This parameter is optional.

Long LenToGet
Number of characters to retrieve from the presentation space. This parameter is optional. The default is the length of the
array passed in as BuffLen.

Return Value

String
Text from the PS.

Example

The following example shows how to retrieve a string from the presentation space for the connection associated with the
autECLPS object.

46 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim autECLPSObj as Object

Dim PSText as String

' Initialize the connection

Set autECLPSObj = CreateObject("PCOMM.autECLPS")
autECLPSObj.SetConnectionByName("A")

PSText = autECLPSObj.GetText(2,1,50)

SetText

The SetText method sends a string to the presentation space for the connection associated with the autECLPS object.
Although this method is similar to the SendKeys method, this method does not send mnemonic keystrokes (for example,
[enter] or [pf1]).

Prototype

void SetText(String Text, [optional] Long Row, [optional] Long Col)

Parameters

String Text
Character array to send.

Long Row
The row at which to begin the retrieval from the presentation space. This parameter is optional. The default is the current
cursor row position.

Long Col
The column position at which to begin the retrieval from the presentation space. This parameter is optional. The default is
the current cursor column position.

Return Value

None

Example

The following example shows how to search for text in the presentation space for the connection associated with the
autECLPS object.

Dim autECLPSObj as Object

'Initialize the connection

Set autECLPSObj = CreateObject("PCOMM.autECLPS")
autECLPSObj.SetConnectionByName("A")
autECLPSObj.SetText"IBM is great", 2, 1

GetTextRect

The GetTextRect method retrieves characters from a rectangular area in the presentation space for the connection
associated with the autECLPS object. No wrapping takes place in the text retrieval; only the rectangular area is retrieved.

Prototype

String GetTextRect(Long StartRow, Long StartCol, Long EndRow, Long EndCol)

Parameters

Long StartRow
Row at which to begin the retrieval in the presentation space.

47 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Long StartCol
Column at which to begin the retrieval in the presentation space.

Long EndRow
Row at which to end the retrieval in the presentation space.

Long EndCol
Column at which to end the retrieval in the presentation space.

Return Value

String
PS Text.

Example

The following example shows how to retrieve characters from a rectangular area in the presentation space for the connection
associated with the autECLPS object.

Dim autECLPSObj as Object

Dim PSText String

' Initialize the connection

Set autECLPSObj = CreateObject ("PCOMM.autELCPS")
autECLPSObj.SetConnectionByName("A")

PSText = GetTextRect(1,1,2,80)

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim PSObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set PSObj = CreateObject("PCOMM.autECLPS")

' Initialize the session

autECLConnList.Refresh
PSObj.SetConnectionByHandle(autECLConnList(1).Handle)

PSObj.StartCommunication()

StopCommunication

48 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim PSObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set PSObj = CreateObject("PCOMM.autECLPS")

' Initialize the session

autECLConnList.Refresh
PSObj.SetConnectionByHandle(autECLConnList(1).Handle)

PSObj.StopCommunication()

StartMacro

The StartMacro method runs the Personal Communications macro file indicated by the MacroName parameter.

Prototype

void StartMacro(String MacroName)

Parameters

String MacroName
Name of macro file located in the Personal Communications user-class application data directory (specified at installation),
without the file extension. This method does not support long file names.

Return Value

None

Usage Notes

You must use the short file name for the macro name. This method does not support long file names.

Example

The following example shows how to start a macro.

Dim PS as Object

Set PS = CreateObject("PCOMM.autECLPS")
PS.StartMacro "mymacro"

Wait

49 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The Wait method waits for the number of milliseconds specified by the milliseconds parameter

Prototype

void Wait(milliseconds as Long)

Parameters

Long milliseconds
The number of milliseconds to wait.

Return Value

None

Example

Dim autECLPSObj as Object

Set autECLPSObj = CreateObject ("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName ("A")

' Wait for 10 seconds

autECLPSObj.Wait(10000)

WaitForCursor

The WaitForCursor method waits for the cursor in the presentation space of the connection associated with the autECLPS
object to be located at a specified position.

Prototype

Boolean WaitForCursor(Variant Row, Variant Col, [optional]Variant TimeOut,

[optional] Boolean bWaitForIr)

Parameters

Variant Row
Row position of the cursor.

Variant Col
Column position of the cursor.

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim Row, Col

50 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

Row = 20

Col = 16

if (autECLPSObj.WaitForCursor(Row,Col,10000)) then

msgbox "Cursor is at " " Row " "," " Col

else

msgbox "Timeout Occurred"

end if

WaitWhileCursor

The WaitWhileCursor method waits while the cursor in the presentation space of the connection associated with the
autECLPS object is located at a specified position.

Prototype

Boolean WaitWhileCursor(Variant Row, Variant Col, [optional]Variant TimeOut,

[optional] Boolean bWaitForIr)

Parameters

Variant Row
Row position of the cursor.

Variant Col
Column position of the cursor.

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim Row, Col

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

51 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLPSObj.SetConnectionByName("A")

Row = 20

Col = 16

if (autECLPSObj.WaitWhileCursor(Row,Col,10000)) then

msgbox "Cursor is no longer at " " Row " "," " Col

else

msgbox "Timeout Occurred"

end if

WaitForString

The WaitForString method waits for the specified string to appear in the presentation space of the connection associated with
the autECLPS object. If the optional Row and Column parameters are used, the string must begin at the specified position. If
0,0 are passed for Row,Col the method searches the entire PS.

Prototype

Boolean WaitForString(Variant WaitString, [optional] Variant Row,

[optional] Variant Col, [optional] Variant TimeOut, [optional] Boolean bWaitForIr,
[optional] Boolean bCaseSens)

Parameters

Variant WaitString
The string for which to wait.

Variant Row
Row position that the string will begin. This parameter is optional. The default is 0.

Variant Col
Column position that the string will begin. This parameter is optional. The default is 0.

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Boolean bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

52 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim Row, Col, WaitString

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

WaitString = "Enter USERID"

Row = 20

Col = 16

if (autECLPSObj.WaitForString(WaitString,Row,Col,10000)) then

msgbox WaitString " " found at " " Row " "," " Col

else

msgbox "Timeout Occurred"

end if

WaitWhileString

The WaitWhileString method waits while the specified string appears in the presentation space of the connection associated
with the autECLPS object. If the optional Row and Column parameters are used, the string must begin at the specified
position. If 0,0 are passed for Row,Col the method searches the entire PS.

Prototype

Boolean WaitWhileString(Variant WaitString, [optional] Variant Row,

[optional] Variant Col, [optional] Variant TimeOut, [optional] Boolean bWaitForIr,
[optional] Boolean bCaseSens)

Parameters

Variant WaitString
The method waits while this string value exists.

Variant Row
Row position that the string will begin. This parameter is optional. The default is 0.

Variant Col
Column position that the string will begin. This parameter is optional. The default is 0.

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Boolean bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is False.

Return Value

53 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim Row, Col, WaitString

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

WaitString = "Enter USERID"

Row = 20

Col = 16

if (autECLPSObj.WaitWhileString(WaitString,Row,Col,10000)) then

msgbox WaitString " " was found at " " Row " "," " Col

else

msgbox "Timeout Occurred"

end if

WaitForStringInRect

The WaitForStringInRect method waits for the specified string to appear in the presentation space of the connection
associated with the autECLPS object in the specified rectangle.

Prototype

Boolean WaitForStringInRect(Variant WaitString, Variant sRow, Variant sCol,

Variant eRow, Variant eCol, [optional] Variant nTimeOut,
[optional] Boolean bWaitForIr, [optional] Boolean bCaseSens)

Parameters

Variant WaitString
The string for which to wait.

Variant sRow
Starting row position of the search rectangle.

Variant sCol
Starting column position of the search rectangle.

Variant eRow
Ending row position of the search rectangle.

Variant eCol

54 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Ending column position of the search rectangle

Variant nTimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Boolean bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim sRow, sCol, eRow, eCol, WaitString

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

WaitString = "Enter USERID"

sRow = 20

sCol = 16

eRow = 21

eCol = 31

if (autECLPSObj.WaitForStringInRect(WaitString,sRow,sCol,eRow,eCol,10000)) then

msgbox WaitString " " found in rectangle"

else

msgbox "Timeout Occurred"

end if

WaitWhileStringInRect

The WaitWhileStringInRect method waits while the specified string appears in the presentation space of the connection
associated with the autECLPS object in the specified rectangle.

Prototype

Boolean WaitWhileStringInRect(Variant WaitString, Variant sRow, Variant sCol,

Variant eRow, Variant eCol, [optional] Variant nTimeOut,
[optional] Boolean bWaitForIr, [optional] Boolean bCaseSens)

55 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Parameters

Variant WaitString
The method waits while this string value exists.

Variant sRow
Starting row position of the search rectangle.

Variant sCol
Starting column position of the search rectangle.

Variant eRow
Ending row position of the search rectangle.

Variant eCol
Ending column position of the search rectangle.

Variant nTimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Boolean bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim sRow, sCol, eRow, eCol, WaitString

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

WaitString = "Enter USERID"

sRow = 20

sCol = 16

eRow = 21

eCol = 31

if (autECLPSObj.WaitWhileStringInRect(WaitString,sRow,sCol,eRow,eCol,10000)) then

56 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

msgbox WaitString " " no longer in rectangle"

else

msgbox "Timeout Occurred"

end if

WaitForAttrib

The WaitForAttrib method will wait until the specified Attribute value appears in the presentation space of the connection
associated with the autECLPS object at the specified Row/Column position. The optional MaskData parameter can be used
to control which values of the attribute you are looking for. The optional plane parameter allows you to select any of the four
PS planes.

Prototype

Boolean WaitForAttrib(Variant Row, Variant Col, Variant WaitData,

[optional] Variant MaskData, [optional] Variant plane, [optional] Variant TimeOut,
[optional] Boolean bWaitForIr)

Parameters

Variant Row
Row position of the attribute.

Variant Col
Column position of the attribute.

Variant WaitData
The 1-byte HEX value of the attribute to wait for.

Variant MaskData
The 1-byte HEX value to use as a mask with the attribute. This parameter is optional. The default value is 0xFF.

Variant plane
The plane of the attribute to get. The plane can have the following values:

1
Text Plane

2
Color Plane

3
Field Plane (default)

4
Extended Field Plane

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Return Value

57 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim Row, Col, WaitData, MaskData, plane

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

Row = 20

Col = 16

WaitData = E8h

MaskData = FFh

plane = 3

if (autECLPSObj.WaitForAttrib(Row, Col, WaitData, MaskData, plane, 10000)) then

msgbox "Attribute " " WaitData " " found"

else

msgbox "Timeout Occurred"

end if

WaitWhileAttrib

The WaitWhileAttrib method waits while the specified Attribute value appears in the presentation space of the connection
associated with the autECLPS object at the specified Row/Column position. The optional MaskData parameter can be used
to control which values of the attribute you are looking for. The optional plane parameter allows you to select any of the four
PS planes.

Prototype

Boolean WaitWhileAttrib(Variant Row, Variant Col, Variant WaitData,

[optional] Variant MaskData, [optional] Variant plane, [optional] Variant TimeOut,
[optional] Boolean bWaitForIr)

Parameters

Variant Row
Row position of the attribute.

Variant Col
Column position of the attribute.

Variant WaitData
The 1 byte HEX value of the attribute to wait for.

58 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Variant MaskData
The 1 byte HEX value to use as a mask with the attribute. This parameter is optional. The default value is 0xFF.

Variant plane
The plane of the attribute to get. The plane can have the following values:

1
Text Plane

2
Color Plane

3
Field Plane (default)

4
Extended Field Plane

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Boolean bWaitForIr
If this value is true, after meeting the wait condition the function will wait until the OIA is ready to accept input. This
parameter is optional. The default is False.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim Row, Col, WaitData, MaskData, plane

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

Row = 20

Col = 16

WaitData = E8h

MaskData = FFh

plane = 3

if (autECLPSObj.WaitWhileAttrib(Row, Col, WaitData, MaskData, plane, 10000)) then

msgbox "Attribute " " WaitData " " No longer exists"

else

59 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

msgbox "Timeout Occurred"

end if

WaitForScreen

Synchronously waits for the screen described by the autECLScreenDesc parameter to appear in the Presentation Space.

Note:
The wait for OIA input flag is set on the autECLScreenDesc object, it is not passed as a parameter to the wait method.

Prototype

Boolean WaitForScreen(Object screenDesc, [optional] Variant TimeOut)

Parameters

Object screenDesc
autECLScreenDesc object that describes the screen (see autECLScreenDesc Class).

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

autECLScreenDesObj.AddCursorPos 23, 1

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen found"

else

msgbox "Timeout Occurred"

end if

WaitWhileScreen

Synchronously waits until the screen described by the autECLScreenDesc parameter is no longer in the Presentation Space.

Note:

60 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The wait for OIA input flag is set on the autECLScreenDesc object, it is not passed as a parameter to the wait method.

Prototype

Boolean WaitWhileScreen(Object screenDesc, [optional] Variant TimeOut)

Parameters

Object ScreenDesc
autECLScreenDesc object that describes the screen (see autECLScreenDesc Class).

Variant TimeOut
The maximum length of time in milliseconds to wait, this parameter is optional. The default is Infinite.

Return Value

The method returns True if the condition is met, or False if the Timeout value is exceeded.

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")

autECLScreenDesObj.AddCursorPos 23, 1

if (autECLPSObj.WaitWhileScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen exited"

else

msgbox "Timeout Occurred"

end if

CancelWaits

Cancels any currently active wait methods.

Prototype

void CancelWaits()

Parameters

None

Return Value

None

61 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLPS Events
The following events are valid for autECLPS:
void NotifyPSEvent()
void NotifyKeyEvent(string KeyType, string KeyString, PassItOn as Boolean)
void NotifyCommEvent(boolean bConnected)
void NotifyPSError()
void NotifyKeyError()
void NotifyCommError()
void NotifyPSStop(Long Reason)
void NotifyKeyStop(Long Reason)
void NotifyCommStop(Long Reason)

NotifyPSEvent

A given PS has been updated.

Prototype

void NotifyPSEvent()

Parameters

None

Example

See Event Processing Example for an example.

NotifyKeyEvent

A keystroke event has occurred and the key information has been supplied. This function can be used to intercept keystrokes
to a given PS. The Key information is passed to the event handler and can be passed on, or another action can be
performed.

Note:
Only one object can have keystroke event handling registered to a given PS at a time.

Prototype

void NotifyKeyEvent(string KeyType, string KeyString, PassItOn as Boolean)

Parameters

String KeyType
Type of key intercepted.

M
Mnemonic keystroke

A
ASCII

String KeyString
Intercepted keystroke

Boolean PassItOn
Flag to indicate if the keystroke should be echoed to the PS.

TRUE

62 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Allows the keystroke to be passed on to the PS.

FALSE
Prevents the keystroke from being passed to the PS.

Example

See Event Processing Example for an example.

NotifyCommEvent

A given communications link as been connected or disconnected.

Prototype

void NotifyCommEvent(boolean bConnected)

Parameters

boolean bConnected
True if Communications Link is currently Connected, False otherwise.

Example

See Event Processing Example for an example.

NotifyPSError

This event occurs when an error occurs in event processing.

Prototype

void NotifyPSError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyKeyError

This event occurs when an error occurs in event processing.

Prototype

void NotifyKeyError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyCommError

This event occurs when an error occurs in event processing.

Prototype

63 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void NotifyCommError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyPSStop

This event occurs when event processing stops.

Prototype

void NotifyPSStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently this will always be 0.

Example

See Event Processing Example for an example.

NotifyKeyStop

This event occurs when event processing stops.

Prototype

void NotifyKeyStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently this will always be 0.

Example

See Event Processing Example for an example.

NotifyCommStop

This event occurs when event processing stops.

Prototype

void NotifyCommStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently this will always be 0.

Event Processing Example

The following is a short example of how to implement PS Events

64 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Option Explicit

Private WithEvents mPS As autECLPS 'AutPS added as reference

Private WithEvents Mkey as autECLPS

sub main()

'Create Objects

Set mPS = New autECLPS

Set mkey = New autECLPS

mPS.SetConnectionByName "A" 'Monitor Session A for PS Updates

mPS.SetConnectionByName "B" 'Intercept Keystrokes intended for Session B

mPS.RegisterPSEvent 'register for PS Updates

mPS.RegisterCommEvent ' register for Communications Link updates for session A

mkey.RegisterKeyEvent 'register for Key stroke intercept

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

mPS.UnregisterPSEvent

mPS.UnregisterCommEvent

mkey.UnregisterKeyEvent

set mPS = Nothing

set mKey = Nothing

End Sub

'This sub will get called when the PS of the Session registered

'above changes

Private Sub mPS_NotifyPSEvent()

' do your processing here

End Sub

65 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

'This sub will get called when Keystrokes are entered into Session B

Private Sub mkey_NotifyKeyEvent(string KeyType, string KeyString, PassItOn as Boolean)

' do your keystroke filtering here

If (KeyType = "M") Then

'handle mnemonics here

if (KeyString = "[PF1]" then 'intercept PF1 and send PF2 instead

mkey.SendKeys "[PF2]"

set PassItOn = false

end if

end if

End Sub

'This event occurs if an error happens in PS event processing

Private Sub mPS_NotifyPSError()

'Do any error processing here

End Sub

'This event occurs when PS Event handling ends

Private Sub mPS_NotifyPSStop(Reason As Long)

'Do any stop processing here

End Sub

'This event occurs if an error happens in Keystroke processing

Private Sub mkey_NotifyKeyError()

'Do any error processing here

End Sub

'This event occurs when key stroke event handling ends

Private Sub mkey_NotifyKeyStop(Reason As Long)

'Do any stop processing here

End Sub

66 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

'This sub will get called when the Communication Link Status of the registered

'connection changes

Private Sub mPS_NotifyCommEvent()

' do your processing here

End Sub

'This event occurs if an error happens in Communications Link event processing

Private Sub mPS_NotifyCommError()

'Do any error processing here

End Sub

'This event occurs when Communications Status Notification ends

Private Sub mPS_NotifyCommStop()

'Do any stop processing here

End Sub

autECLScreenDesc Class
autECLScreenDesc is the class that is used to describe a screen for IBM's Host Access Class Library Screen Recognition
Technology. It uses all four major planes of the presentation space to describe it (text, field, extended field, and color planes),
as well as the cursor position.

Using the methods provided on this object, the programmer can set up a detailed description of what a given screen looks
like in a host side application. Once an autECLScreenDesc object is created and set, it may be passed to either the
synchronous WaitFor... methods provided on autECLPS, or it may be passed to autECLScreenReco, which fires an
asynchronous event if the screen matching the autECLScreenDesc object appears in the PS.

autECLScreenDesc Methods
The following section describes the methods that are valid for autECLScreenDesc.

void AddAttrib(Variant attrib, Variant row, Variant col, Variant plane)

void AddCursorPos(Variant row, Variant col)
void AddNumFields(Variant num)
void AddNumInputFields(Variant num)
void AddOIAInhibitStatus(Variant type)
void AddString(String str, Variant row, Variant col, [optional] Boolean caseSense)
void AddStringInRect(String str, Variant sRow, Variant sCol,
Variant eRow, Variant eCol, [optional] Variant caseSense)
void Clear()

AddAttrib

67 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Adds an attribute value at the given position to the screen description.

Prototype

void AddAttrib(Variant attrib, Variant row, Variant col, Variant plane)

Parameters

Variant attrib
The 1 byte HEX value of the attribute.

Variant row
Row position.

Variant col
Column position.

Variant plane
The plane of the attribute to get. The plane can have the following values:

0. All Planes

1. Text Plane

2. Color Plane

3. Field Plane

4. Extended Field Plane

5. DBCS Character Plane

6. DBCS Grid Line Plane

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

68 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddCursorPos

Sets the cursor position for the screen description to the given position.

Prototype

void AddCursorPos(Variant row, Variant col)

Parameters

Variant row
Row position.

Variant col
Column position.

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

69 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddNumFields

Adds the number of fields to the screen description.

Prototype

void AddNumFields(Variant num)

Parameters

Variant num
Number of fields.

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

70 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddNumInputFields

Adds the number of fields to the screen description.

Prototype

void AddNumInputFields(Variant num)

Parameters

Variant num
Number of input fields.

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

71 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddOIAInhibitStatus

Sets the type of OIA monitoring for the screen description.

Prototype

void AddOIAInhibitStatus(Variant type)

Parameters

Variant type
Type of OIA status. Valid values are as follows:

0. Don't Care

1. Not Inhibited

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

72 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddString

Adds a string at the given location to the screen description.

Prototype

void AddString(String str, Variant row, Variant col, [optional] Boolean caseSense)

Parameters

String str
String to add.

Variant row
Row position.

Variant col
Column position.

Boolean caseSense
If this value is True, the strings are added as case-sensitive. This parameter is optional. The default is True.

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

73 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

AddStringInRect

Adds a string in the given rectangle to the screen description.

Prototype

void AddStringInRect(String str, Variant sRow, Variant sCol,

Variant eRow, Variant eCol, [optional] Variant caseSense)

Parameters

String str
String to add

Variant sRow
Upper left row position.

Variant sCol
Upper left column position.

Variant eRow
Lower right row position.

Variant eCol
Lower right column position.

Variant caseSense
If this value is True, the strings are added as case-sensitive. This parameter is optional. The default is True.

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

74 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

Clear

Removes all description elements from the screen description.

Prototype

void Clear()

Parameters

None

Return Value

None

Example

Dim autECLPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

75 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName "A"

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddCursorPos 23,1

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLPSObj.WaitForScreen(autECLScreenDesObj, 10000)) then

msgbox "Screen reached"

else

msgbox "Timeout Occurred"

end if

autECLScreenDesObj.Clear // start over for a new screen

autECLScreenReco Class
The autECLScreenReco class is the engine for the Host Access Class Library screen recognition system. It contains the
methods for adding and removing descriptions of screens. It also contains the logic for recognizing those screens and for
asynchronously calling back to your event handler code for those screens.

Think of an object of the autECLScreenReco class as a unique recognition set. The object can have multiple autECLPS
objects that it watches for screens, and multiple screens to look for, and when it sees a registered screen in any of the added
autECLPS objects it will fire event handling code defined in your application.

All you need to do is set up your autECLScreenReco objects at the start of your application, and when any screen appears in
any autECLPS that you want to monitor, your event code will get called by autECLScreenReco. You do absolutely no legwork
in monitoring screens.

See Event Processing Example for an example.

autECLScreenReco Methods
The following section describes the methods that are valid for autECLScreenReco.
void AddPS(autECLPS ps)
Boolean IsMatch(autECLPS ps, AutECLScreenDesc sd)
void RegisterScreen(AutECLScreenDesc sd)

76 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void RemovePS(autECLPS ps)

void UnregisterScreen(AutECLScreenDesc sd)

AddPS

Adds an autECLPS object to monitor to the autECLScreenReco Object.

Prototype

void AddPS(autECLPS ps)

Parameters

autECLPS ps
PS object to monitor.

Return Value

None

Example

See Event Processing Example for an example.

IsMatch

Allows for passing an autECLPS object and an AutECLScreenDesc object and determining if the screen description matches
the current state of the PS. The screen recognition engine uses this logic, but is provided so any routine can call it.

Prototype

Boolean IsMatch(autECLPS ps, AutECLScreenDesc sd)

Parameters

autECLPS ps
autPS object to compare.

AutECLScreenDesc sd
autECLScreenDesc object to compare.

Return Value

True if the AutECLScreenDesc object matches the current screen in the PS, False otherwise.

Example

Dim autPSObj as Object

Dim autECLScreenDescObj as Object

Set autECLScreenDescObj = CreateObject("PCOMM.autECLScreenDesc")

Set autPSObj = CreateObject("PCOMM.autECLPS")

autPSObj.SetConnectionByName "A"

77 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLScreenDesObj.AddCursorPos 23, 1

autECLScreenDesObj.AddAttrib E8h, 1, 1, 2

autECLScreenDesObj.AddNumFields 45

autECLScreenDesObj.AddNumInputFields 17

autECLScreenDesObj.AddOIAInhibitStatus 1

autECLScreenDesObj.AddString "LOGON", 23, 11, True

autECLScreenDesObj.AddStringInRect "PASSWORD", 23, 1, 24, 80, False

if (autECLScreenReco.IsMatch(autPSObj, autECLScreenDesObj)) then

msgbox "matched"

else

msgbox "no match"

end if

RegisterScreen

Begins monitoring all autECLPS objects added to the screen recognition object for the given screen description. If the
screen appears in the PS, a NotifyRecoEvent will occur.

Prototype

void RegisterScreen(AutECLScreenDesc sd)

Parameters

AutECLScreenDesc sd
Screen description object to register.

Return Value

None

Example

See Event Processing Example for an example.

RemovePS

Removes the autECLPS object from screen recognition monitoring.

Prototype

void RemovePS(autECLPS ps)

Parameters

autECLPS ps
autECLPS object to remove.

Return Value

None

78 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

See Event Processing Example for an example.

UnregisterScreen

Removes the screen description from screen recognition monitoring.

Prototype

void UnregisterScreen(AutECLScreenDesc sd)

Parameters

AutECLScreenDesc sd
Screen description object to remove.

Return Value

None

Example

See Event Processing Example for an example.

autECLScreenReco Events
The following events are valid for autECLScreenReco:
void NotifyRecoEvent(AutECLScreenDesc sd, autECLPS ps)
void NotifyRecoError()
void NotifyRecoStop(Long Reason)

NotifyRecoEvent

This event occurs when a Registered Screen Description appears in a PS that was added to the autECLScreenReco object.

Prototype

void NotifyRecoEvent(AutECLScreenDesc sd, autECLPS ps)

Parameters

AutECLScreenDesc sd
Screen Description object that had its criteria met.

autECLPS ps
PS object in which the match occurred.

Example

See Event Processing Example for an example.

NotifyRecoError

This event occurs when an error occurs in Event Processing.

Prototype

void NotifyRecoError()

Parameters

79 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

None

Example

See Event Processing Example for an example.

NotifyRecoStop

This event occurs when event processing stops.

Prototype

void NotifyRecoStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently this will always be 0.

Event Processing Example

The following is a short example of how to implement Screen Recognition Events:

Dim myPS as Object

Dim myScreenDesc as Object

Dim WithEvents reco as autECLScreenReco 'autECLScreenReco added as reference

Sub Main()

' Create the objects

Set reco= new autECLScreenReco

myScreenDesc = CreateObject("PCOMM.autECLScreenDesc")

Set myPS = CreateObject("PCOMM.autECLPS")

myPS.SetConnectionByName "A"

' Set up the screen description

myScreenDesc.AddCursorPos 23, 1

myScreenDesc.AddString "LOGON"

myScreenDesc.AddNumFields 59

' Add the PS to the reco object (can add multiple PS's)

reco.addPS myPS

' Register the screen (can add multiple screen descriptions)

reco.RegisterScreen myScreenDesc

80 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

' Clean up

reco.UnregisterScreen myScreenDesc

reco.RemovePS myPS

set myPS = Nothing

set myScreenDesc = Nothing

set reco = Nothing

End Sub

'This sub will get called when the screen Description registered above appears in

'Session A. If multiple PS objects or screen descriptions were added, you can

'determine which screen and which PS via the parameters.

Sub reco_NotifyRecoEvent(autECLScreenDesc SD, autECLPS PS)

If (reco.IsMatch(PS,myScreenDesc)) Then

' do your processing for your screen here

End If

End Sub

Sub reco_NotifyRecoError

'do your error handling here

End sub

Sub reco_NotifyRecoStop(Reason as Long)

'Do any stop processing here

End sub

autECLSession Class
The autECLSession object provides general emulator related services and contains pointers to other key objects in the Host
Access Class Library. Its name in the registry is PCOMM.autECLSession.

Although the objects that autECLSession contains are capable of standing on their own, pointers to them exist in the
autECLSession class. When an autECLSession object is created, autECLPS, autECLOIA, autECLXfer,

81 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLWindowMetrics, autECLPageSettings, and autECLPrinterSettings objects are also created. Refer to them as you
would any other property.

Notes:

1. The current version of this object is 1.2. There are two versions of this object; their ProgIDs in the registry are
PCOMM.autECLSession.1 and PCOMM.autECLSession.2. The version-independent ProgID is
PCOMM.autECLSession. The PCOMM.autECLSession.1 object does not support the properties
autECLPageSettings and autECLPrinterSettings.

2. You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle
to initialize your object. The connection can be set only once. After the connection is set, any further calls to the
SetConnection methods cause an exception. If you do not set the connection and try to access an autECLSession
property or method, an exception is also raised.

The following example shows how to create and set the autECLSession object in Visual Basic.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example, set the host window to minimized
SessObj.autECLWinMetrics.Minimized = True

Properties

This section describes the properties for the autECLSession object.

Type Name Attributes

String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only
Object autECLPS Read-only
Object autECLOIA Read-only
Object autECLXfer Read-only
Object autECLWinMetrics Read-only
Object autECLPageSettings Read-only
Object autECLPrinterSettings Read-only

Name

This property is the connection name string of the connection for which autECLSession was set. Personal Communications
only returns the short character ID (A-Z) in the string. There can be only one Personal Communications connection open with
a given name. For example, there can be only one connection "A" open at a time. Name is a String data type and is read-only.
The following example shows this property.

DIM Name as String

DIM SessObj as Object
Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")

' Save the name

Name = SessObj.Name

Handle

82 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This is the handle of the connection for which the autECLSession object was set. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.
Handle is a Long data type and is read-only. The following example shows this property.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")

' Save the session handle

Hand = SessObj.Handle

ConnType

This is the connection type for which autECLXfer was set. This type may change over time. ConnType is a String data type
and is read-only. The following example shows this property.

DIM Type as String

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' Save the type
Type = SessObj.ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

CodePage

This is the code page of the connection for which autECLXfer was set. This code page may change over time. CodePage is
a Long data type and is read-only. The following example shows this property.

DIM CodePage as Long

DIM SessObj as Object
Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' Save the code page
CodePage = SessObj.CodePage

Started

This indicates whether the emulator window is started. The value is True if the window is open; otherwise, it is False. Started
is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' This code segment checks to see if A is started.

83 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

' The results are sent to a text box called Result.

If SessObj.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This indicates the status of the connection to the host. The value is True if the host is connected; otherwise, it is False.
CommStarted is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")

' This code segment checks to see if communications are connected

' for session A. The results are sent to a text box called
' CommConn.
If SessObj.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This indicates whether the emulator is API-enabled. A connection may be enabled or disabled depending on the state of its
API settings (in a Personal Communications window, choose File -> API Settings). The value is True if the emulator is
enabled; otherwise, it is False. APIEnabled is a Boolean data type and is read-only. The following example shows this
property.

DIM Hand as Long

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")

' This code segment checks to see if A is API enabled.

' The results are sent to a text box called Result.
If SessObj.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This indicates whether the emulator window is started, API-enabled, and connected. This property checks for all three
properties. The value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type and is read-only.
The following example shows this property.

DIM Hand as Long

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")

84 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If SessObj.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLPS object

The autECLPS object allows you to access the methods contained in the PCOMM.autECLPS class. See autECLPS Class for
more information. The following example shows this object.

DIM SessObj as Object

DIM PSSize as Long
Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example, get the PS size
PSSize = SessObj.autECLPS.GetSize()

autECLOIA object

The autECLOIA object allows you to access the methods contained in the PCOMM.autECLOIA class. See autECLOIA Class
for more information. The following example shows this object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example, set the host window to minimized
If (SessObj.autECLOIA.Katakana) Then
'whatever
Endif

autECLXfer object

The autECLXfer object allows you to access the methods contained in the PCOMM.autECLXfer class. See autECLXfer
Class for more information. The following example shows this object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example
SessObj.Xfer.Sendfile "c:\temp\filename.txt",
"filename text a0",
"CRLF ASCII"

autECLWinMetrics object

The autECLWinMetrics object allows you to access the methods contained in the PCOMM.autECLWinMetrics class. See
autECLWinMetrics Class for more information. The following example shows this object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example, set the host window to minimized
SessObj.autECLWinMetrics.Minimized = True

85 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLPageSettings object

The autECLPageSettings object enables you to access the methods contained in the PCOMM.autECLPageSettings class.
See autECLPageSettings Class for more information.

The following example shows the autECLPageSettings object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")
'Initialize the session
SessObj.SetConnectionByName("A")

'For example, set the FaceName

SessObj.autECLPageSettings.FaceName = "Courier New"

The autECLPageSettings object is also supported in VBSCRIPT. The following example shows how to use VBSCRIPT.

sub test_()
autECLSession.SetConnectionByName(ThisSessionName)
autECLSession.autECLPageSettings.FaceName="Courier"
end sub

autECLPrinterSettings object

The autECLPrinterSettings object enables you to access the methods contained in the PCOMM.autECLPrinterSettings class.
See autECLPageSettings Class for more information.

The following example shows the autECLPageSettings object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")
' Initialize the session
SessObj.SetConnectionByName("A")

'For example, set the Windows default printer

SessObj.autECLPrinterSettings.SetWinDefaultPrinter

The autECLPrinterSettings object is also supported in VBSCRIPT. The following example shows how to use VBSCRIPT.

sub test_()
autECLSession.SetConnectionByName(ThisSessionName)
autECLSession.autECLPrinterSettings.SetWinDefaultPrinter
end sub

autECLSession Methods
The following section describes the methods that are valid for the autECLSession object.
void RegisterSessionEvent(Long updateType)
void RegisterCommEvent()
void UnregisterSessionEvent()
void UnregisterCommEvent()
void SetConnectionByName (String Name)
void SetConnectionByHandle (Long Handle)
void StartCommunication()
void StopCommunication()

RegisterSessionEvent

This method registers an autECLSession object to receive notification of specified Session events.

Note:

86 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This method is not supported and is not recommended for use.

Prototype

void RegisterSessionEvent(Long updateType)

Parameters

Long updateType
Type of update to monitor for:
1. PS Update
2. OIA Update
3. PS or OIA Update

Return Value

None

Example

See Event Processing Example for an example.

RegisterCommEvent

This method registers an object to receive notification of all communication link connect/disconnect events.

Prototype

void RegisterCommEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterSessionEvent

Ends Session Event processing.

Note:
This method is not supported and is not recommended for use.

Prototype

void UnregisterSessionEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

87 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

UnregisterCommEvent

Ends Communications Link Event processing.

Prototype

void UnregisterCommEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

SetConnectionByName

This method uses the connection name to set the connection for a newly created autECLSession object. In Personal
Communications this connection name is the short ID (character A-Z). There can be only one Personal Communications
connection open with a given name. For example, there can be only one connection "A" open at a time.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection (A-Z).

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created autECLSession
object.

DIM SessObj as Object

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

SessObj.SetConnectionByName("A")
' For example, set the host window to minimized
SessObj.autECLWinMetrics.Minimized = True

SetConnectionByHandle

This method uses the connection handle to set the connection for a newly created autECLSession object. In Personal
Communications this connection handle is a long integer. There can be only one Personal Communications connection open
with a given handle. For example, there can be only one connection "A" open at a time.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle

88 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created autECLSession
object.

Dim SessObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

autECLConnList.Refresh
autECLPSObj.SetConnectionByHandle(autECLConnList(1).Handle)

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim SessObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

autECLConnList.Refresh
SessObj.SetConnectionByHandle(autECLConnList(1).Handle)

SessObj.StartCommunication()

StopCommunication

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

89 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim SessObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set SessObj = CreateObject("PCOMM.autECLSession")

' Initialize the session

autECLConnList.Refresh
SessObj.SetConnectionByHandle(autECLConnList(1).Handle)

SessObj.StopCommunication()

autECLSession Events
The following events are valid for autECLSession:
void NotifyCommEvent(boolean bConnected)
void NotifyCommError()
void NotifyCommStop(Long Reason)

NotifyCommEvent

A given communications link has been connected or disconnected.

Prototype

void NotifyCommEvent(boolean bConnected)

Parameters

boolean bConnected
TRUE if communications link is currently connected. FALSE otherwise.

Example

See Event Processing Example for an example.

NotifyCommError

This event occurs when an error occurs in event processing.

Prototype

void NotifyCommError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyCommStop

This event occurs when event processing stops.

90 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Prototype

void NotifyCommStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently, this will always be 0.

Event Processing Example

The following is a short example of how to implement Session Events

Option Explicit

Private WithEvents mSess As autECLSession 'AutSess added as reference

sub main()

'Create Objects

Set mSess = New autECLSession

mSess.SetConnectionByName "A"

mSess.RegisterCommEvent 'register for communication link notifications

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

mSess.UnregisterCommEvent

set mSess = Nothing

End Sub

'This sub will get called when the Communication Link Status of the registered

'connection changes

Private Sub mSess_NotifyCommEvent()

' do your processing here

End Sub

'This event occurs if an error happens in Communications Link event processing

Private Sub mSess_NotifyCommError()

'Do any error processing here

End Sub

'This event occurs when Communications Status Notification ends

91 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Private Sub mSess_NotifyCommStop()

'Do any stop processing here

End Sub

autECLWinMetrics Class
The autECLWinMetrics object performs operations on an emulator window. It allows you to perform window rectangle and
position manipulation (for example, SetWindowRect, Ypos and Width), as well as window state manipulation (for example,
Visible or Restored). Its name in the registry is PCOMM.autECLWinMetrics.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection may be set only once. After the connection is set, any further calls to the set connection
methods cause an exception. If you do not set the connection and try to access a property or method, an exception is also
raised.

Note:
The autECLSession object in the autECL object is set by the autECL object.

The following example shows how to create and set the autECLWinMetrics object in Visual Basic.

DIM autECLWinObj as Object

Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

autECLWinObj.SetConnectionByName("A")
' For example, set the host window to minimized
autECLWinObj.Minimized = True

Properties

This section describes the properties for the autECLWinMetrics object.

Type Name Attributes

String WindowTitle Read/Write
Long Xpos Read/Write
Long Ypos Read/Write
Long Width Read/Write
Long Height Read/Write
Boolean Visible Read/Write
Boolean Active Read/Write
Boolean Minimized Read/Write
Boolean Maximized Read/Write
Boolean Restored Read/Write
String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

WindowTitle

This is the title that is currently in the title bar for the connection associated with the autECLWinMetrics object. This property
may be both changed and retrieved. WindowTitle is a String data type and is read/write enabled. The following example
shows this process. The following example shows this property.

92 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim autECLWinObj as Object

Dim ConnList as Object
Dim WinTitle as String
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

WinTitle = autECLWinObj.WindowTitle 'get the window title

' or...

autECLWinObj.WindowTitle = "Flibberdeejibbet" 'set the window title

Usage Notes

If WindowTitle is set to blank, the window title of the connection is restored to its original setting.

Xpos

This is the x position of the upper left point of the emulator window rectangle. This property may be both changed and
retrieved. Xpos is a Long data type and is read/write enabled. However, if the connection you are attached to is an inplace,
embedded object, this property is read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Dim x as Long
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

x = autECLWinObj.Xpos 'get the x position

' or...

autECLWinObj.Xpos = 6081 'set the x position

Ypos

This is the y position of the upper left point of the emulator window rectangle. This property may be both changed and
retrieved. Ypos is a Long data type and is read/write enabled. However, if the connection you are attached to is an inplace,
embedded object, this property is read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Dim y as Long
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

y = autECLWinObj.Ypos 'get the y position

' or...

autECLWinObj.Ypos = 6081 'set the y position

Width

93 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This is the width of the emulator window rectangle. This property may be both changed and retrieved. Width is a Long data
type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this property is
read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Dim cx as Long
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

cx = autECLWinObj.Width 'get the width

' or...

autECLWinObj.Width = 6081 'set the width

Height

This is the height of the emulator window rectangle. This property may be both changed and retrieved. Height is a Long data
type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this property is
read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Dim cy as Long
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

cy = autECLWinObj.Height 'get the height

' or...

autECLWinObj.Height = 6081 'set the height

Visible

This is the visibility state of the emulator window. This property may be both changed and retrieved. Visible is a Boolean data
type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this property is
read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

' Set to Visible if not, and vice versa

If ( autECLWinObj.Visible) Then
autECLWinObj.Visible = False
Else
autECLWinObj.Visible = True
End If

Active

94 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This is the focus state of the emulator window. This property may be both changed and retrieved. Active is a Boolean data
type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this property is
read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

' Set to Active if not, and vice versa

If ( autECLWinObj.Active) Then
autECLWinObj.Active = False
Else
autECLWinObj.Active = True
End If

Minimized

This is the minimize state of the emulator window. This property may be both changed and retrieved. Minimized is a Boolean
data type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this
property is read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

' Set to minimized if not, if minimized set to maximized

If ( autECLWinObj.Minimized) Then
autECLWinObj.Maximized = True
Else
autECLWinObj.Minimized = True
End If

Maximized

This is the maximize state of the emulator window. This property may be both changed and retrieved. Maximized is a Boolean
data type and is read/write enabled. However, if the connection you are attached to is an inplace, embedded object, this
property is read-only. The following example shows this property.

Dim autECLWinObj as Object

Dim ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)

' Set to maximized if not, if maximized set to minimized

If ( autECLWinObj.Maximized) Then
autECLWinObj.Minimized = False
Else
autECLWinObj.Maximized = True
End If

Restored

95 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This is the restore state of the emulator window. Restored is a Boolean data type and is read/write enabled. However, if the
connection you are attached to is an inplace, embedded object, this property is read-only. The following example shows this
property.

Dim autECLWinObj as Object

Dim SessList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set SessList = CreateObject("PCOMM.autECLConnList")

' Initialize the session

SessList.Refresh
autECLWinObj.SetSessionByHandle(SessList(1).Handle)

' Set to restored if not, if restored set to minimized

If ( autECLWinObj.Restored) Then
autECLWinObj.Minimized = False
Else
autECLWinObj.Restored = True
End If

Name

This property is the connection name string of the connection for which autECLWinMetrics was set. Currently, Personal
Communications only returns the short character ID (A-Z) in the string. There can be only one Personal Communications
connection open with a given name. For example, there can be only one connection "A" open at a time. Name is a String data
type and is read-only. The following example shows this property.

DIM Name as String

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the name

Name = Obj.Name

Handle

This is the handle of the connection for which the autECLWinMetrics object was set. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.
Handle is a Long data type and is read-only. The following example shows this property.

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the handle

Hand = Obj.Handle

ConnType

This is the connection type for which autECLWinMetrics was set. This type may change over time. ConnType is a String data
type and is read-only. The following example shows this property.

DIM Type as String

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the type

96 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Type = Obj.ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

CodePage

This is the code page of the connection for which autECLWinMetrics was set. This code page may change over time.
CodePage is a Long data type and is read-only. The following example shows this property.

DIM CodePage as Long

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the code page
CodePage = Obj.CodePage

Started

This indicates whether the emulator window is started. The value is True if the window is open; otherwise, it is False. Started
is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If Obj.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This indicates the status of the connection to the host. The value is True if the host is connected; otherwise, it is False.
CommStarted is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If Obj.CommStarted = False Then
CommConn.Text = "No"
Else

97 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

CommConn.Text = "Yes"
End If

APIEnabled

This indicates whether the emulator is API-enabled. A connection may be enabled or disabled depending on the state of its
API settings (in a Personal Communications window, choose File ->API Settings). The value is True if the emulator is
enabled; otherwise, it is False. APIEnabled is a Boolean data type and is read-only. The following example shows this
property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is API enabled.

' The results are sent to a text box called Result.
If Obj.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This indicates whether the emulator window is started, API enabled, and connected. This property checks for all three
properties. The value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type and is read-only.
The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If Obj.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLWinMetrics Methods
The following section describes the methods that are valid for the autECLWinMetrics object.
void RegisterCommEvent()
void UnregisterCommEvent()
void SetConnectionByName(String Name)
void SetConnectionByHandle(Long Handle)
void GetWindowRect(Variant Left, Variant Top, Variant Right, Variant Bottom)
void SetWindowRect(Long Left, Long Top, Long Right, Long Bottom)
void StartCommunication()
void StopCommunication()

RegisterCommEvent

This method registers an object to receive notification of all communication link connect/disconnect events.

98 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Prototype

void RegisterCommEvent()

Parameters

None

Return Value

None

Example

See Event Processing Example for an example.

UnregisterCommEvent

Ends Communications Link Event Processing.

Prototype

void UnregisterCommEvent()

Parameters

None

Return Value

None

SetConnectionByName

This method uses the connection name to set the connection for a newly created autECLWinMetrics object. In Personal
Communications this connection name is the short ID (character A-Z). There can be only one Personal Communications
connection open with a given name. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLWinMetrics object in autECLSession.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection (A-Z).

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created autECLWinMetrics
object.

DIM autECLWinObj as Object

Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the connection

autECLWinObj.SetConnectionByName("A")

99 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

' For example, set the host window to minimized

autECLWinObj.Minimized = True

SetConnectionByHandle

This method uses the connection handle to set the connection for a newly created autECLWinMetrics object. In Personal
Communications this connection handle is a long integer. There can be only one Personal Communications connection open
with a given handle. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLWinMetrics object in autECLSession.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle
Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created autECLWinMetrics
object.

DIM autECLWinObj as Object

DIM ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)
' For example, set the host window to minimized
autECLWinObj.Minimized = True

GetWindowRect

The GetWindowRect method returns the bounding points of the emulator window rectangle.

Prototype

void GetWindowRect(Variant Left, Variant Top, Variant Right, Variant Bottom)

Parameters

Variant Left, Top, Right, Bottom

Bounding points of the emulator window.

Return Value

None

Example

The following example shows how to return the bounding points of the emulator window rectangle.

Dim autECLWinObj as Object

Dim ConnList as Object

100 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim left
Dim top
Dim right
Dim bottom
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)
autECLWinObj.GetWindowRect left, top, right, bottom

SetWindowRect

The SetWindowRect method sets the bounding points of the emulator window rectangle.

Prototype

void SetWindowRect(Long Left, Long Top, Long Right, Long Bottom)

Parameters

Long Left, Top, Right, Bottom

Bounding points of the emulator window.

Return Value

None

Example

The following example shows how to set the bounding points of the emulator window rectangle.

Dim autECLWinObj as Object

Dim ConnList as Object
Set autECLWinObj = CreateObject("PCOMM.autECLWinMetrics")
Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection

ConnList.Refresh
autECLWinObj.SetConnectionByHandle(ConnList(1).Handle)
autECLWinObj.SetWindowRect 0, 0, 6081, 6081

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim WinObj as Object

101 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set WinObj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the session

autECLConnList.Refresh
WinObj.SetConnectionByHandle(autECLConnList(1).Handle)

WinObj.StartCommunication()

StopCommunication

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim WinObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set WinObj = CreateObject("PCOMM.autECLWinMetrics")

' Initialize the session

autECLConnList.Refresh
WinObj.SetConnectionByHandle(autECLConnList(1).Handle)

WinObj.StopCommunication()

autECL WinMetrics Events

The following events are valid for autECL WinMetrics:
void NotifyCommEvent(boolean bConnected)
NotifyCommError()
void NotifyCommStop(Long Reason)

NotifyCommEvent

A given communications link as been connected or disconnected.

Prototype

void NotifyCommEvent(boolean bConnected)

Parameters

boolean bConnected
True if Communications Link is currently Connected, False otherwise.

102 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

See Event Processing Example for an example.

NotifyCommError

This event occurs when an error occurs in Event Processing.

Prototype

NotifyCommError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyCommStop

This event occurs when event processing stops.

Prototype

void NotifyCommStop(Long Reason)

Parameters

Long Reason
Reason code for the stop. Currently this will always be 0.

Event Processing Example

The following is a short example of how to implement WinMetrics Events.

Option Explicit

Private WithEvents mWmet As autECLWinMetrics 'AutWinMetrics added as reference

sub main()

'Create Objects

Set mWmet = New autECLWinMetrics

mWmet.SetConnectionByName "A" 'Monitor Session A

mWmet.RegisterCommEvent ' register for Communications Link updates for session A

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

103 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

mWmet.UnregisterCommEvent

set mWmet = Nothing

End Sub

'This sub will get called when the Communication Link Status of the registered

'connection changes

Private Sub mWmet _NotifyCommEvent()

' do your processing here

End Sub

'This event occurs if an error happens in Communications Link event processing

Private Sub mWmet _NotifyCommError()

'Do any error processing here

End Sub

'This event occurs when Communications Status Notification ends

Private Sub mWmet _NotifyCommStop()

'Do any stop processing here

End Sub

autECLXfer Class
The autECLXfer object provides file transfer services. Its name in the registry is PCOMM.autECLXfer.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection may be set only once. After the connection is set, any further calls to the SetConnection
methods cause an exception. If you do not set the connection and try to access an autECLXfer property or method, an
exception is also raised. The following shows how to create and set the autECLXfer object in Visual Basic.

DIM XferObj as Object

Set XferObj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

XferObj.SetConnectionByName("A")

Properties

This section describes the properties for the autECLXfer object.

Type Name Attribute

String Name Read-only
Long Handle Read-only

104 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

String ConnType Read-only

Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

Name

This property is the connection name string of the connection for which autECLXfer was set. Personal Communications only
returns the short character ID (A-Z) in the string. There can be only one Personal Communications connection open with a
given name. For example, there can be only one connection "A" open at a time. Name is a String data type and is read-only.
The following example shows this property.

DIM Name as String

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the name

Name = Obj.Name

Handle

This is the handle of the connection for which the autECLXfer object was set. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.
Handle is a Long data type and is read-only. The following example shows this property.

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' Save the handle

Hand = Obj.Handle

ConnType

This is the connection type for which autECLXfer was set. This type may change over time. Conntype is a String data type
and is read-only. The following example shows this property.

DIM Type as String

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the type
Type = Obj.ConnType

Connection types for the ConnType property are:

String Returned Meaning

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

105 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

CodePage

This is the code page of the connection for which autECLXfer was set. This code page may change over time. CodePage is
a Long data type and is read-only. The following example shows this property.

DIM CodePage as Long

DIM Obj as Object
Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")
' Save the code page
CodePage = Obj.CodePage

Started

This indicates whether the emulator window is started. The value is True if the window is open; otherwise, it is False. Started
is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If Obj.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This indicates the status of the connection to the host. The value is True if the host is connected; otherwise, it is False.
CommStarted is a Boolean data type and is read-only. The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If Obj.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This indicates whether the emulator is API-enabled. A connection may be enabled or disabled depending on the state of its
API settings (in a Personal Communications window, choose File -> API Settings). The value is True if the emulator is
enabled; otherwise, it is False. APIEnabled is a Boolean data type and is read-only. The following example shows this
property.

DIM Hand as Long

DIM Obj as Object

106 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is API enabled.

' The results are sent to a text box called Result.
If Obj.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This indicates whether the emulator window is started, API enabled, and connected. This property checks for all three
properties. The value is True if the emulator is ready; otherwise, it is False. Ready is a Boolean data type and is read-only.
The following example shows this property.

DIM Hand as Long

DIM Obj as Object

Set Obj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

Obj.SetConnectionByName("A")

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If Obj.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLXfer Methods
The following section describes the methods that are valid for the autECLXfer object.
void RegisterCommEvent()
void UnregisterCommEvent()
void SetConnectionByName(String Name)
void SetConnectionByHandle(Long Handle)
void SendFile(String PCFile, String HostFile, String Options)
void ReceiveFile(String PCFile, String HostFile, String Options)
void StartCommunication()
void StopCommunication()

RegisterCommEvent

This method registers an object to receive notification of all communication link connect/disconnect events.

Prototype

void RegisterCommEvent()

Parameters

None

Return Value

None

107 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

SeeEvent Processing Example for an example.

UnregisterCommEvent

Ends Communications Link Event Processing.

Prototype

void UnregisterCommEvent()

Parameters

None

Return Value

None

SetConnectionByName

The SetConnectionByName method uses the connection name to set the connection for a newly created autECLXfer object.
In Personal Communications this connection name is the short ID (character A-Z). There can be only one Personal
Communications connection open with a given name. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLXfer object in autECLSession.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection (A-Z).

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created autECLXfer object.

DIM XferObj as Object

Set XferObj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

XferObj.SetConnectionByName("A")

SetConnectionByHandle

The SetConnectionByHandle method uses the connection handle to set the connection for a newly created autECLXfer
object. In Personal Communications this connection handle is a Long integer. There can be only one Personal
Communications connection open with a given handle. For example, there can be only one connection "A" open at a time.

Note:
Do not call this if using the autECLXfer object in autECLSession.

Prototype

108 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle
Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created autECLXfer object.

DIM XferObj as Object

DIM autECLConnList as Object

Set XferObj = CreateObject("PCOMM.autECLXfer")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection with the first connection in the list
autECLConnList.Refresh
XferObj.SetConnectionByHandle(autECLConnList(1).Handle)

SendFile

The SendFile method sends a file from the workstation to the host for the connection associated with the autECLXfer object.

Prototype

void SendFile( String PCFile, String HostFile, String Options )

Parameters

String PCFile
Name of the file on the workstation.

String HostFile
Name of the file on the host.

String Options
Host-dependent transfer options. See Usage Notes for more information.

Return Value

None

Usage Notes

File transfer options are host-dependent. The following is a list of some of the valid host options for a VM/CMS host.

ASCII
CRLF
APPEND
LRECL
RECFM
CLEAR/NOCLEAR
PROGRESS
QUIET

Refer to Emulator Programming for the list of supported hosts and associated file transfer options.

109 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

The following example shows how to send a file from the workstation to the host for the connection associated with the
autECLXfer object.

DIM XferObj as Object

DIM autECLConnList as Object
DIM NumRows as Long

Set XferObj = CreateObject("PCOMM.autECLXfer")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection with the first connection in the autECLConnList
autECLConnList.Refresh
XferObj.SetConnectionByHandle(autECLConnList(1).Handle)

' For example, send the file to VM

XferObj.SendFile "c:\windows\temp\thefile.txt",
"THEFILE TEXT A0",
"CRLF ASCII"

ReceiveFile

The ReceiveFile method receives a file from the host to the workstation for the connection associated with the autECLXfer
object.

Prototype

void ReceiveFile( String PCFile, String HostFile, String Options )

Parameters

String PCFile
Name of the file on the workstation.

String HostFile
Name of the file on the host.

String Options
Host-dependent transfer options. See Usage Notes for more information.

Return Value

None

Usage Notes

File transfer options are host-dependent. The following is a list of some of the valid host options for a VM/CMS host:

ASCII
CRLF
APPEND
LRECL
RECFM
CLEAR/NOCLEAR
PROGRESS
QUIET

Refer to Emulator Programming manual for the list of supported hosts and associated file transfer options.

Example

The following example shows how to receive a file from the host and send it to the workstation for the connection associated
with the autECLXfer object.

110 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

DIM XferObj as Object

DIM autECLConnList as Object
DIM NumRows as Long

Set XferObj = CreateObject("PCOMM.autECLXfer")

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection with the first connection in the list
autECLConnList.Refresh
XferObj.SetConnectionByHandle(autECLConnList(1).Handle)
' For example, send the file to VM
XferObj.ReceiveFile "c:\windows\temp\thefile.txt",
"THEFILE TEXT A0",
"CRLF ASCII"

StartCommunication

The StartCommunication collection element method connects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

The following example shows how to connect a PCOMM emulator session to the host.

Dim XObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set XObj = CreateObject("PCOMM.autECLXfer")

' Initialize the session

autECLConnList.Refresh
XObj.SetConnectionByHandle(autECLConnList(1).Handle)

XObj.StartCommunication()

StopCommunication

The StopCommunication collection element method disconnects the PCOMM emulator to the host data stream. This has the
same effect as going to the PCOMM emulator Communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

111 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The following example shows how to connect a PCOMM emulator session to the host.

Dim XObj as Object

Dim autECLConnList as Object

Set autECLConnList = CreateObject("PCOMM.autECLConnList")

Set XObj = CreateObject("PCOMM.autECLXfer")

' Initialize the session

autECLConnList.Refresh
XObj.SetConnectionByHandle(autECLConnList(1).Handle)

SessObj.StopCommunication()

autECLXfer Events
The following events are valid for autECLXfer:
void NotifyCommEvent(boolean bConnected)
NotifyCommError()
void NotifyCommStop(Long Reason)

NotifyCommEvent

A given communications link as been connected or disconnected.

Prototype

void NotifyCommEvent(boolean bConnected)

Parameters

boolean bConnected
True if Communications Link is currently Connected, False otherwise.

Example

See Event Processing Example for an example.

NotifyCommError

This event occurs when an error occurs in event processing.

Prototype

NotifyCommError()

Parameters

None

Example

See Event Processing Example for an example.

NotifyCommStop

This event occurs when event processing stops.

Prototype

void NotifyCommStop(Long Reason)

Parameters

112 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Long Reason
Reason code for the stop. Currently this will always be 0.

Event Processing Example

The following is a short example of how to implement Xfer Events

Option Explicit

Private WithEvents mXfer As autECLXfer 'AutXfer added as reference

sub main()

'Create Objects

Set mXfer = New autECLXfer

mXfer.SetConnectionByName "A" 'Monitor Session A

mXfer.RegisterCommEvent ' register for Communications Link updates for session A

' Display your form or whatever here (this should be a blocking call, otherwise sub just ends

call DisplayGUI()

mXfer.UnregisterCommEvent

set mXfer= Nothing

End Sub

'This sub will get called when the Communication Link Status of the registered

'connection changes

Private Sub mXfer _NotifyCommEvent()

' do your processing here

End Sub

'This event occurs if an error happens in Communications Link event processing

Private Sub mXfer _NotifyCommError()

'Do any error processing here

End Sub

113 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

'This event occurs when Communications Status Notification ends

Private Sub mXfer _NotifyCommStop()

'Do any stop processing here

End Sub

autSystem Class
The autSystem class is used to perform utility operations that are not present in some programming languages.

autSystem Methods
The following section describes the methods that are valid for the autSystem object.
Long Shell(VARIANT ExeName, VARIANT Parameters, VARIANT WindowStyle)
String Inputnd()

Shell

The shell function runs any executable file.

Prototype

Long Shell(VARIANT ExeName, VARIANT Parameters, VARIANT WindowStyle)

Parameters

VARIANT ExeName
Full path and file name of the executable file.

VARIANT Parameters
Any parameters to pass to the executable file. This parameter is optional.

VARIANT WindowStyle
The initial window style to show as executable. This parameter is optional and can have the following values:
1. Normal with focus (default)
2. Minimized with focus
3. Maximized
4. Normal without focus
5. Minimized without focus

Return Value

The method returns the Process ID if it is successful, or zero if it fails.

Example

Example autSystem - Shell()

'This example starts notepad with the file c:\test.txt loaded

dim ProcessID
dim SysObj as object

set SysObj = CreateObject("PCOMM.autSystem")

ProcessID = SysObj.shell "Notepad.exe","C:\test.txt"
If ProcessID > 0 then
Msgbox "Notepad Started, ProcessID = " + ProcessID
Else
Msgbox "Notepad not started"

114 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

End if

Inputnd

The Inputnd method displays a popup input box to the user with a no-display text box so that when the user types in data only
asterisks(*) are displayed.

Prototype

String Inputnd()

Parameters

None

Return Value

The characters typed into the input box, or "" if nothing was typed in.

Example

DIM strPassWord
dim SysObj as Object
dim PSObj as Object

set SysObj = CreateObject("PCOMM.autSystem")

set PSObj = CreateObject("PCOMM.autPS")

PSObj.SetConnectionByName("A")
'Prompt user for password
strPassWord = SysObj.Inputnd()
PSObj.SetText(strPasssWord)
DIM XferObj as Object

Set XferObj = CreateObject("PCOMM.autECLXfer")

' Initialize the connection

XferObj.SetConnectionByName("A")

autECLPageSettings Class
The autECLPageSettings object controls the page settings of a Personal Communications connection. Its name in the
registry is Personal Communications.autECLPageSettings. This automation object can also be used in VB scripts.

The read-only property autECLPageSettings has been added to the autECLSession object. See autECLSession Class for
information about how to use this property.

Note:
The autECLPageSettings object in the autECLSession object is set by the autECLSession object.

The following example shows how to create and set the autECLPageSettings object in Visual Basic.

DIM PgSet as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")
PgSet.SetConnectionByName("A")

Usage Notes

This object is not supported for DBCS or bidirectional sessions.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection can be set only once. After the connection is set, any further calls to the set connection

115 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

methods cause an exception. If you do not set the connection and try to access a property or method, an exception is raised.

The properties CPI, LPI, and FontSize are dependent on the property FaceName. Therefore, if CPI, LPI, or FontSize are set
before the FaceName is set, and if they are not valid for the new FaceName, different CPI, LPI, or FontSize values might be
reconfigured in the connection. You should set the FaceName before setting the CPI, LPI, or FontSize. Otherwise, every time
you set FaceName, query CPI, LPI, and FontSize and make sure that they have the desired values.

Restrictions

The connection associated with each method must be in a particular state for the method to succeed. If the restrictions are
not met, an appropriate exception is raised.

The following restrictions must be satisfied while any property or method of the autECLPageSettings object is invoked.

The host session should not be printing when this API is invoked.
The File -> Page Setup and File -> Printer Setup dialogs must not be in use.
The associated connection must not be in PDT mode.

Additional restrictions might apply for each specific property or method.

Connection types

The following connection types are valid for the methods in the autECLPageSettings class:

3270 display
3270 printer
5250 display
VT (ASCII)

If a property or method is accessed or called on an unsupported connection, an exception is raised. Use the ConnType
property to determine the connection type.

Properties

This section describes the properties for the autECLPageSettings object.

Type Name Attributes

Long CPI Read/Write
Boolean FontCPI Read-only
Long LPI Read/Write
Boolean FontLPI Read-only
String FaceName Read/Write
Long FontSize Read/Write
Long MaxLinesPerPage Read/Write
Long MaxCharsPerLine Read/Write
String Name Read-only
Long Handle Read-only
String ConnType Read-only
Long CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

CPI

This property determines the number of characters printed per inch. This is a Long data type and is read/write enabled.

Set this property to the predefined constant pcFontCPI to select the Font CPI in Page Settings or set it to some specific CPI
value. If this property is queried when FontCPI is configured in the connection, the actual CPI value is returned and the
constant pcFontCPI is not returned.

To determine whether FontCPI is set in the connection, use the property FontCPI.

116 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Example

Dim PgSet as Object

Dim ConnList as Object
Dim CPI as Long

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

CPI = PgSet.CPI ' get the CPI value

' or...
PgSet.CPI = pcFontCPI 'set the connection to use Font CPI.

FontCPI

This determines whether Font CPI is set in the connection. FontCPI is a Boolean data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

'check if Font CPI is set

If PgSet.FontCPI Then
...

LPI

This property determines the number of lines printed per inch. This is a Long data type and is read/write enabled. Set it to the
predefined constant pcFontLPI to select the Font LPI in Page Settings or set it to some specific LPI value. If this property is
queried when FontLPI is configured in the connection, the actual LPI value is returned and the constant pcFontLPI is not
returned. To determine whether FontLPI is set in the connection, use the property FontLPI.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim LPI as Long

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

LPI = PgSet.LPI ' get the LPI value

' or...
PgSet.LPI = pcFontLPI 'set the connection to use Font LPI.

FontLPI

This property determines whether Font LPI is set in the connection. FontLPI is a Boolean data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object

117 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

'check if Font LPI is set

If PgSet.FontLPI Then
...

FaceName

This is the Font Face Name of the Page Settings of the connection. FaceName is a String data type and is read/write
enabled.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim FaceName as String

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)
FaceName = PgSet.FaceName ' get the FaceName
' or...
PgSet.FaceName = "Courier New" 'set the FaceName

FontSize

This is the size of the font in the Page Settings of the connection. FontSize is a Long data type and is read/write enabled.

Notes:

1. This property is for sessions that use a DBCS code page. Connections that use an SBCS host code page will raise an
exception.

2. Because FontSize is dependent on the FaceName of the connection, FaceName should be set before FontSize is
set.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim FontSize as Long
Set PgSet = CreateObject("PCOMM.autECLPageSettings")
Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)
FontSize = PgSet. FontSize ' get the FontSize
' or...
PgSet. FontSize = 14 'set the FontSize

MaxLinesPerPage

This property is the maximum number of lines that can be printed per page. This is also called maximum print lines or MPL.
Valid values are in the range 1-255. This is a Long data type and is read/write enabled.

Example

Dim PgSet as Object

118 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim ConnList as Object

Dim MPL as Long

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

MPL = PgSet.MaxLinesPerPage ' get the MaxLinesPerPage

' or...
PgSet.MaxLinesPerPage = 20 'set the MaxLinesPerPage

MaxCharsPerLine

This property is the maximum number of characters that can be printed per line. This is also called maximum print position or
MPP. Valid values are in the range 1-255. This is a Long data type and is read/write enabled.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim MPP as Long

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

MPP = PgSet.MaxCharsPerLine ' get the MaxCharsPerLine

' or...
PgSet.MaxCharsPerLine = 80 'set the MaxCharsPerLine

Name

This property is the connection name string of the connection for which autECLPageSettings was set. Personal
Communications returns only the short character ID (a single alphabetical character from A to Z) in the string. There can be
only one Personal Communications connection open with a given name. For example, there can be only one connection A
open at a time. Name is a String data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object
DIM Name as String

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

Name = PgSet.Name 'Save the name

Handle

This property is the handle of the connection for which the autECLPageSettings object was set. There can be only one
Personal Communications connection open with a given handle. For example, there can be only one connection A open at a
time. Handle is a Long data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim Hand as Long

119 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

Hand = PgSet.Handle ' save the handle

ConnType

This property is the connection type for which autECLPageSettings was set. This type might change over time. ConnType is a
String data type and is read-only.

String Value Connection Type

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

Example

Dim PgSet as Object

Dim ConnList as Object
Dim Type as String

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

Type = PgSet.ConnType ' save the type

CodePage

This property is the connection type for which autECLPageSettings was set. This type might change over time. ConnType is a
String data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object
Dim CodePage as Long

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

CodePage = PgSet.CodePage ' save the codepage

Started

This property indicates whether the emulator window is started. The value is TRUE if the window is open; otherwise, it is
FALSE. Started is a Boolean data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

120 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Set ConnList = CreateObject("PCOMM.autECLConnList")

' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If PgSet.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This property indicates the status of the connection to the host. The value is TRUE if the host is connected; otherwise, it is
FALSE. CommStarted is a Boolean data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If PgSet.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"
End If

APIEnabled

This property indicates whether the emulator is API-enabled. A connection can be API-enabled or disabled depending on the
state of its API settings (in a Personal Communications window, click Edit -> Preferences -> API). The value is TRUE if the
emulator is API-enabled; otherwise, it is FALSE. APIEnabled is a Boolean data type and is read-only.

Example

Dim PgSet as Object

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if A is API-enabled.

' The results are sent to a text box called Result.
If PgSet.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This property indicates whether the emulator window is started, API-enabled, and connected. This property checks for all

121 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

three properties. The value is TRUE if the emulator is ready; otherwise, it is FALSE. Ready is a Boolean data type and is
read-only.

Example

Dim PgSet as Object

Dim ConnList as Object
Set PgSet = CreateObject("PCOMM.autECLPageSettings")
Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)
' This code segment checks to see if A is ready.
' The results are sent to a text box called Result.
If PgSet.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLPageSettings Methods
The following section describes the methods that are valid for the autECLPageSettings object.

void RestoreTextDefaults()
void SetConnectionByName (String Name)
void SetConnectionByHandle (Long Handle)

RestoreTextDefaults

The RestoreTextDefaults method restores the system default values of the Text property page in the Page Setup dialog of
the connection. This is equivalent to pressing the Default button on the Text property page of the Page Setup Dialog of the
connection.

Prototype

void RestoreTextDefaults()

Parameters

None

Return Value

None

Example

The following example shows the RestoreTextDefaults method.

Dim PgSet as Object

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

PgSet.RestoreTextDefaults 'Restores Text Default Settings

SetConnectionByName

The SetConnectionByName method uses the connection name to set the connection for a newly created

122 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

autECLPageSettings object. This connection name is the short connection ID (a single alphabetical character from A to Z).
There can be only one Personal Communications connection open with a given name. For example, there can be only one
connection A open at a time.

Note:
Do not call this method if you are using the autECLPageSettings object contained in the autECLSession object.

Prototype

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection. Valid values are A-Z.

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created autECLPageSettings
object.

Dim PgSet as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")
' Initialize the connection
PgSet.SetConnectionByName("A")
' For example, see if Font CPI is set
If PgSet.FontCPI Then
'your logic here...
End If

SetConnectionByHandle

The SetConnectionByHandle method uses the connection handle to set the connection for a newly created
autECLPageSettings object. In Personal Communications, this connection handle is a Long integer. There can be only one
Personal Communications connection open with a given handle. For example, there can be only one connection A open at a
time.

Note:
Do not call this method if you are using the autECLPageSettings object contained in the autECLSession object.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle
Long integer value of the connection to be set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created
autECLPageSettings object.

Dim PgSet as Object

123 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Dim ConnList as Object

Set PgSet = CreateObject("PCOMM.autECLPageSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PgSet.SetConnectionByHandle(ConnList(1).Handle)

' For example, see if Font CPI is set

If PgSet.FontCPI Then
'your logic here...
End If

autECLPrinterSettings Class
The autECLPrinterSettings object controls the Printer Settings of a Personal Communications connection. Its name in the
registry is PCOMM.autECLPrinterSettings. This automation object can also be used in VB scripts.

The read-only property autECLPrinterSettings has been added to the autECLSession object. See autECLSession Class
for information about how to use this property.

Note:
The autECLPrinterSettings object in the autECLSession object is set by the autECLSession object.

The following example shows how to create and set the autECLPrinterSettings object in Visual Basic.

DIM PrSet as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")
PrSet.SetConnectionByName("A")

Usage Notes

This object is not supported for DBCS or bidirectional sessions.

You must initially set the connection for the object you create. Use SetConnectionByName or SetConnectionByHandle to
initialize your object. The connection can be set only once. After the connection is set, any further calls to the set connection
methods cause an exception. If you do not set the connection and try to access a property or method, an exception is raised.

The properties CPI, LPI, and FontSize are dependent on the property FaceName. Therefore, if CPI, LPI, or FontSize are set
before the FaceName is set, and if they are not valid for the new FaceName, different CPI, LPI, or FontSize values might be
reconfigured in the connection. You should set the FaceName before setting the CPI, LPI, or FontSize. Otherwise, every time
you set FaceName, query CPI, LPI, and FontSize and make sure that they have the desired values.

Restrictions

The connection associated with each method must be in a particular state for the method to succeed. If the restrictions are
not met, an appropriate exception is raised.

The following restrictions must be satisfied while any property or method of the autECLPageSettings object is invoked.

The host session should not be printing when this API is invoked.
The File -> Page Setup and File -> Printer Setup dialogs should not be in use.

Additional restrictions might apply for each specific property or method.

Properties

This section describes the properties for the autECLPrinterSettings object.

Type Name Attributes

Boolean PDTMode Read-only
String PDTFile Read-only
Long PrintMode Read-only

124 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

String Printer Read-only

String PrtToDskAppendFile Read-only
String PrtToDskSeparateFile Read-only
Boolean PrompDialogOption Read/Write
String Name Read-only
Long Handle Read-only
String ConnType Read-only
Boolean CodePage Read-only
Boolean Started Read-only
Boolean CommStarted Read-only
Boolean APIEnabled Read-only
Boolean Ready Read-only

PDTMode

This property determines whether the connection is in PDT mode or not. PDTMode is a Boolean data type and is read/write
enabled.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

'check if in PDT mode.

If PrSet.PDTMode Then
...

PDTFile

This property is the PDT file configured in the connection. This property gives a null string if the PDT file is not configured in
the connection. Otherwise, this property gives the fully qualified path name of the PDT file. PDTFile is a String data type and
is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

If PrSet. PDTFile = vbNullString Then ' get the

...
Else
...

PrintMode

This property indicates the print mode of the connection. PrintMode is a Long data type and is read-only. This property returns
one of the following four enumerated values:

Value Name of the enum constant Description

1 pcPrtToDskAppend Print to Disk-Append mode. This means the Print to Disk -> Append option is selected in the Printer
listbox in the Printer Setup dialog of the connection.

125 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

2 pcPrtToDskSeparate Print to Disk-Separate mode. This means the Print to Disk -> Separate option is selected in the
Printer listbox in the Printer Setup dialog of the connection.
3 pcSpecificPrinter Specific Printer mode. This means one of the printers is selected in the Printer listbox in the Printer
Setup dialog of the connection and the Use Windows Default Printer checkbox is clear.
4 pcWinDefaultPrinter Windows Default Printer mode. This means that the Use Windows Default Printer checkbox is
selected.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

If PrSet.PrintMode = pcPrtToDskAppend Then

...
ElseIf PrSet.PrintMode = pcPrtToDskSeparate Then
...
ElseIf PrSet.PrintMode = pcSpecificPrinter Then
...
ElseIf PrSet.PrintMode = pcWinDefaultPrinter Then
...

Printer

This property is the name of the printer. It contains one of the following:

The name of the specific printer if the PrintMode of the connection is pcSpecificPrinter.
The name of the Windows default printer if the PrintMode of the connection is pcWinDefaultPrinter.
A null string if a printer is not configured in the connection or if the PrintMode of the connection is pcPrtToDskAppend
or pcPrtToDskSeparate.

Printer is a String data type and is read-only.

The value must have the following format:

<Printer name> on <Port Name>

For example:

IBM InfoPrint 40 PS on Network Port

HP LaserJet 4050 Series PCL 6 on LPT1

Example

Dim PrSet as Object

Dim ConnList as Object
Dim Printer as String

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

Printer = PrSet.Printer ' get the Printer Name

PrtToDskAppendFile

This property is the name of the file set for the Print to Disk-Append mode. This file is called the Print to Disk-Append file.
This property contains one of the following:

126 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

The fully qualified path name of the Print to Disk-Append file of the connection.
A null string if the Print to Disk-Append file is not configured in the connection.

PrtToDskAppendFile is a String data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
Dim DskAppFile as String

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

DskAppFile = PrSet. PrtToDskAppendFile ' get the Disk append file.

PrtToDskSeparateFile

This property is the name of the file set for the Print to Disk-Separate mode. This file is called the Print to Disk-Separate
file. This property contains one of the following:

The fully qualified path name of the Print to Disk-Separate file of the connection.
A null string if the Print to Disk-Separate file is not configured in the connection.

PrtToDskSeparateFile is a String data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
Dim DskSepFile as String

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

DskSepFile = PrSet. PrtToDskSeparateFile ' get the Disk separate file.

PromptDialogOption

This property indicates whether the option to show the Printer Setup dialog before printing is set or not. PromptDialogOption
is a Boolean data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
Dim PromptDialog as Boolean

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

PromptDialog = PrSet.PromptDialogOption ' get the Prompt Dialog option

' or...
PrSet.PromptDialogOption = True 'set the Prompt Dialog option

Name

127 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

This property is the connection name string of the connection for which autECLPrinterSettings was set. Personal
Communications returns only the short character ID (a single alphabetical character from A to Z) in the string. There can be
only one Personal Communications connection open with a given name. For example, there can be only one connection A
open at a time. Name is a String data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
DIM Name as String

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

Name = PrSet.Name 'Save the name

Handle

This property is the handle of the connection for which the autECLPrinterSettings object was set. There can be only one
Personal Communications connection open with a given handle. For example, there can be only one connection A open at a
time. Handle is a Long data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
Dim Hand as Long

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

Hand = PrSet.Handle ' save the handle

ConnType

This property is the connection type for which autECLPrinterSettings was set. This type might change over time. ConnType is
a String data type and is read-only.

String Value Connection Type

DISP3270 3270 display
DISP5250 5250 display
PRNT3270 3270 printer
PRNT5250 5250 printer
ASCII VT emulation

Example

Dim PrSet as Object

Dim ConnList as Object
Dim Type as String

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

Type = PrSet.ConnType ' save the type

128 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

CodePage

This property is the code page of the connection for which autECLPrinterSettings was set. This code page might change over
time. CodePage is a Long data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object
Dim CodePage as Long

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

CodePage = PrSet.CodePage ' save the codepage

Started

This property indicates whether the emulator window is started. The value is TRUE if the window is open; otherwise, it is
FALSE. Started is a Boolean data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if A is started.

' The results are sent to a text box called Result.
If PrSet.Started = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

CommStarted

This property indicates the status of the connection to the host. The value is TRUE if the host is connected; otherwise, it is
FALSE. CommStarted is a Boolean data type and is read-only.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if communications are connected

' for A. The results are sent to a text box called
' CommConn.
If PrSet.CommStarted = False Then
CommConn.Text = "No"
Else
CommConn.Text = "Yes"

129 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

End If

APIEnabled

This property indicates whether the emulator is API-enabled. A connection is API-enabled or disabled depending on the state
of its API settings (in a Personal Communications window, click Edit -> Preferences -> API).

The value is TRUE if the emulator is API-enabled; otherwise, it is FALSE. APIEnabled is a Boolean data type and is
read-only.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if A is API-enabled.

' The results are sent to a text box called Result.
If PrSet.APIEnabled = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

Ready

This property indicates whether the emulator window is started, API-enabled, and connected. This property checks for all
three properties. The value is TRUE if the emulator is ready; otherwise, it is FALSE. Ready is a Boolean data type and is
read-only.

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

' This code segment checks to see if A is ready.

' The results are sent to a text box called Result.
If PrSet.Ready = False Then
Result.Text = "No"
Else
Result.Text = "Yes"
End If

autECLPrinterSettings Methods
The following sections describe the methods that are valid for the autECLPrinterSettings object.

void SetPDTMode(Boolean bPDTMode, [optional] String PDTFile)

void SetPrtToDskAppend( [optional] String FileName)
void SetPrtToDskSeparate([optional] String FileName)
void SetSpecificPrinter(String Printer)
void SetWinDefaultPrinter()
void SetConnectionByName (String Name)
void SetConnectionByHandle (Long Handle)

130 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

SetPDTMode

The SetPDTMode method sets the connection in PDT mode with the given PDT file or sets the connection in non-PDT mode
(also called GDI mode).

Restriction

If this method is called with bPDTMode set to FALSE, PrintMode of the associated connection must already be set to
SpecificPrinter or WinDefaultPrinter.

Prototype

void SetPDTMode(Boolean bPDTMode, [optional] String PDTFile)

Parameters

Boolean bPDTMode
Possible values are as follows:
TRUE to set the connection to PDT mode.
FALSE to set the connection to non-PDT mode (GDI mode).

String PDTFile
This optional parameter contains the PDT file name.

This parameter is used only if bPDTMode is TRUE. If this parameter is not specified and bPDTMode is set to TRUE, the
PDT file configured in the connection is used. If there is no PDT file already configured in the connection, this method fails
with an exception.

This parameter ignored if bPDTMode is FALSE.

Possible values are as follows:

File name without path

PDTFile in the PDFPDT subfolder in the Personal Communications installation path is used.

Fully qualified path name of the file

If PDTFile does not exist, this method fails with an exception.

Return Value

None

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

PrSet.SetPDTMode(True, "epson.pdt") 'Set PDT mode

PrSet.SetPDTMode(False) 'Set non-PDT mode (also called GDI mode)

SetPrtToDskAppend

This method sets the PrintMode of the connection to Print to Disk-Append mode. It also sets the appropriate file for this
mode.

131 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

Notes:

1. The folder where this file is to be set must have write access. Otherwise, this method fails with an exception.

2. The associated connection must be in PDT mode.

Prototype

void SetPrtToDskAppend( [optional] String FileName)

Parameters

String FileName
This optional parameter contains the name of the Print to Disk-Append file.

If the file exists, it is used. Otherwise, it is created when printing is complete.

Possible values are as follows:

File name, without the path

The user-class application data directory path will be used to locate the file.

Fully qualified path name of the file

The directory must exist in the path, or the method will fail with an exception. It is not necessary that the file exist in
the path.

If this parameter is not specified, the file configured for this PrintMode in the connection is used. If there is no file already
configured in the connection, this method fails with an exception.

Return Value

None

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

'If PDTMode, set PrintMode to pcPrtToDskAppend

If PrSet.PDTMode Then
PrSet.SetPrtToDskAppend("dskapp.txt")

SetPrtToDskSeparate

This method sets the PrintMode of the connection to Print to Disk-Separate mode. It also sets the appropriate file for this
mode.

Notes:

1. The folder where this file is to be set must have write access. Otherwise, this method fails with an exception.

2. The associated connection must be in PDT mode.

Prototype

132 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void SetPrtToDskSeparate([optional] String FileName)

Parameters

String FileName
This optional parameter contains the name of the Print to Disk-Separate file.

If this parameter is not specified, the file configured for this PrintMode in the connection is used.

Possible values are:

NULL (default)

The file that is currently configured for this PrintMode in the connection is used. If there is no file already configured
in the connection, the method fails with an exception.

File name, without the path

The user-class application data directory path will be used to locate the file.

Fully qualified path name of the file

The directory must exist in the path, or the method will fail with an exception. It is not necessary that the file exist in
the path.

Note:
The file name must not contain an extension. If it contains an extension, the method fails with an exception.

Return Value

None

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

'If PDTMode, set PrintMode to pcPrtToDskSeparate

If PrSet.PDTMode Then
PrSet.SetPrtToDskSeparate("dsksep")

SetSpecificPrinter

This method sets the PrintMode of the connection to Specific Printer mode with the printer specified by the Printer parameter.

Prototype

void SetSpecificPrinter(String Printer)

Parameters

String Printer
Contains the name of the printer. If the printer does not exist, this method fails with an exception.

The value must have the following format:

<Printer name> on <Port Name>

133 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

For example:

IBM InfoPrint 40 PS on Network Port

HP LaserJet 4050 Series PCL 6 on LPT1

Return Value

None

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

'Set PrintMode to pcSpecificPrinter

PrSet. SetSpecificPrinter("IBM InfoPrint 40 PS on Network Port")

SetWinDefaultPrinter

This method sets the PrintMode of the connection to Windows Default Printer mode (the connection will use the Windows
default printer). If no Windows default printer is configured, this method fails with an exception.

Prototype

void SetWinDefaultPrinter()

Parameters

None

Return Value

None

Example

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

'Set PrintMode to pcWinDefaultPrinter

PrSet. SetWinDefaultPrinter

SetConnectionByName

The SetConnectionByName method uses the connection name to set the connection for a newly created
autECLPrinterSettings object. In Personal Communications, this connection name is the short connection ID (a single
alphabetical character from A to Z). There can be only one Personal Communications connection open with a given name. For
example, there can be only one connection A open at a time.

Note:
Do not call this if you are using the autECLPrinterSettings object contained in the autECLSession object.

Prototype

134 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

void SetConnectionByName( String Name )

Parameters

String Name
One-character string short name of the connection. Valid values are A-Z.

Return Value

None

Example

The following example shows how to use the connection name to set the connection for a newly created
autECLPrinterSettings object.

Dim PrSet as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")
' Initialize the connection
PrSet.SetConnectionByName("A")
' For example, see if PDTMode
If PrSet.PDTMode Then
'your logic here...
End If

SetConnectionByHandle

The SetConnectionByHandle method uses the connection handle to set the connection for a newly created
autECLPrinterSettings object. In Personal Communications, this connection handle is a Long integer.

There can be only one Personal Communications connection open with a given handle. For example, there can be only one
connection A open at a time.

Note:
Do not call this method if you are using the autECLPrinterSettings object contained in the autECLSession object.

Prototype

void SetConnectionByHandle( Long Handle )

Parameters

Long Handle
The Long integer value of the connection to set for the object.

Return Value

None

Example

The following example shows how to use the connection handle to set the connection for a newly created
autECLPrinterSettings object.

Dim PrSet as Object

Dim ConnList as Object

Set PrSet = CreateObject("PCOMM.autECLPrinterSettings")

Set ConnList = CreateObject("PCOMM.autECLConnList")
' Initialize the connection
ConnList.Refresh
PrSet.SetConnectionByHandle(ConnList(1).Handle)

' For example, see if PDTMode

135 of 136 05/03/2011 4:01 PM

Host Access Class Library Automation Objects http://publib.boulder.ibm.com/infocenter/pcomhelp/v5r9/topic/com.ibm....

If PrSet.PDTMode Then
'your logic here...
End If

Support For Primary Interop Assemblies for Automation Objects

Automation objects exposed by IBM Personal Communications can be used by applications written in any language that
targets the .NET framework. Managed .NET applications can program Personal Communications by using the Primary Interop
Assemblies (PIA) that wrap the automation objects. Interop Assemblies are the mechanism with which managed (.NET)
applications use COM-compliant objects. Interop Assemblies contain binding and metadata information, which enables the
.NET framework (CLR) to load or marshall COM objects and wrap them for .NET applications. The PIA contains the official
description of the COM types as defined by the publisher of those COM types. The PIA is always digitally signed by the
publisher of the original COM type.

There are two ways a .NET application can reference an assembly.

If it is a simple application or the only application that uses the assembly, Microsoft recommends that the assembly be
copied in the same directory as the application.
If multiple applications are referencing the assembly, you can install them in the Global Assembly Cache (GAC) and
have all the solutions reference the assembly in the GAC.

The model for programming the types exposed by Interop Assemblies is very similar to COM. The methods, properties, and
events exposed by the COM object can be accessed by any .NET language, using the syntax of the language. A sample
application (ECLSamps.net) written in C# is provided in the \samples directory in the Personal Communications installation
image. The sample demonstrates the simple usage of various Interop Assembly types.

For Visual Basic 6.0, projects that use Personal Communications automation objects and have been migrated to Visual Basic
.NET using the conversion assistant wizard, you only need to replace the references that the conversion assistant wizard
implicitly generates with the corresponding Personal Communications Interop references (from the \Interops directory) and
recompile. The way to replace the references is to delete all the references generated by the conversion assistant and use
Visual Studio .NET to add the .NET interop references. If you have registered the assemblies in the GAC and want to use
them, add the references and set the Copy Local property for the Personal Communications Interop references to False.

The PIAs for the Personal Communications emulator automation objects are installed in the \Interops directory in the
Personal Communications installation image. If the Personal Communications product installer detects that the .NET
framework is present, it gives you the additional option to register the types in the GAC. While installing the assemblies in the
GAC, the PIAs will also be placed in the registry, under the registry key of the corresponding type library.

Table 2 lists the PIAs supplied for the Personal Communications automation objects

Table 2. Primary Interop Assemblies for Personal Communications Automation Objects

Automation Object Interop Assembly Dependency

autECLConnList Interop.AutConnListTypeLibrary.dll
autECLConnMgr Interop.AutConnMgrTypeLibrary.dll
autECLConnList Interop.AutPSTypeLibrary.dll
autECLOIA Interop.AutOIATypeLibrary.dll
autECLPS Interop.AutPSTypeLibrary.dll
autECLScreenDesc Interop.AutScreenDescTypeLibrary.dll
autECLScreenReco Interop.AutScreenRecoTypeLibrary.dll
autECLSession Interop.AutSessTypeLibrary.dll
autECLPageSettings Interop.AutSettingsTypeLibrary.dll
autECLPrinterSettings Interop.AutSettingsTypeLibrary.dll
autECLWinMetrics Interop.AutWinMetricsTypeLibrary.dll
autECLXfer Interop.AutXferTypeLibrary.dll
autSystem Interop.AutSystemTypeLibrary.dll

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

136 of 136 05/03/2011 4:01 PM