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:

Figure 3 is a graphical representation of the autECL objects:

Figure 3. Host Access Class Library Automation Objects

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.

Note for 64 Bit PCOMM:

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.

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 or 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
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
  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

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

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

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

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

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:

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

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

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

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

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

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

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")
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
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
Dim TextStr 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
 
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...

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

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 or 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 or 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
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

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

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

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

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.

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()
 
'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
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 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 or 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.

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
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)
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)
void CopyText([optional] Long Row, [optional] Long Col, [optional] Long LenToGet)
void PasteText([optional] Long Row, [optional] Long Col, [optional] Long LenToGet)
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

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

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 or 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 or 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

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.

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

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

CopyText

This method copies the text from a given location in presentation space of a specified length to clipboard. The length of the text copied will be the length specified, if no length is specified the text till the end of presentation space is copied. If the location is not specified, the text copied is from the current cursor position in presentation space. In case of no parameters, whole presentation space is copied to clipboard.

Prototype

void CopyText([optional] Long Row, [optional] Long Col, [optional] Long LenToGet)

Parameters

Long LenToGet
Number of characters to copy from the presentation space. This parameter is optional. The default is the length of the array passed in as BuffLen.
Long Row
The row at which to begin the copy 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 copy from the presentation space. This parameter is optional. The default is the current cursor column.

Return Value

None

Example

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

Dim autECLPSObj as Object
'Initialize the connection

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")
autECLPSObj.CopyText 6, 53, 10

PasteText

This method pastes the text of specified length from clipboard to a given location in presentation space. The length of the text pasted is the length specified, if no length is specified the whole text in clipboard is pasted until it reaches the end of presentation space. If the location is not specified, the text is pasted at the current cursor position in presentation space.

Prototype

void PasteText([optional] Long Row, [optional] Long Col, [optional] Long LenToGet)

Parameters

Long LenToGet
Number of characters to paste from clipboard to the presentation space. This parameter is optional. The default is the length of the text in clipboard.
Long Row
The row at which to begin the paste from clipboard to 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 paste from clipboard to 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 paste text from clipboard to presentation space the connection associated with the autECLPS object.

Dim autECLPSObj as Object
'Initialize the connection

Set autECLPSObj = CreateObject("PCOMM.autECLPS")

autECLPSObj.SetConnectionByName("A")
autECLPSObj.PasteText 8, 53, 10

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

SetTextRect

The SetTextRect method sets characters to a rectangular area in the presentation space for the connection associated with the autECLPS object. No wrapping takes place in the text setting; only the rectangular area is set.

Prototype

SetTextRect(String Text, Long StartRow, Long StartCol, Long EndRow, Long EndCol)

Parameters

String Text
Character array to set on presentation space.
Long StartRow
Row at which to begin the setting in the presentation space.
Long StartCol
Column at which to begin the setting in the presentation space.
Long EndRow
Row at which to end the setting in the presentation space.
Long EndCol
Column at which to end the setting in the presentation space.

Return Value

None

Example

The following example shows how to set characters to 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") 

SetTextRect "IBM is great company to collaborate with", 1, 1, 4, 8

If we want to use parentheses then we can use SetTextRect as

call SetTextRect("IBM is great company to collaborate with", 1, 1, 4, 8)

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

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

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

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

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

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

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

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

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
 
'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
 
'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

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:

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
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
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
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
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:

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

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

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
 
  ' 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, 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 or 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

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

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

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 or 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 or 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
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

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.

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

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

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

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

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

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 or 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 or 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")
' 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
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
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.

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()
 
   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
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 or 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

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

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 or 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 or 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

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.

Refer to Emulator Programming for the list of supported hosts and associated file transfer options.

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:

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.

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

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

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
 
'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"
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 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.

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:

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.

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

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

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

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

Printer is a String data type and is read-only.

The value must have the following format:

<Printer name> on <Port Name>

For example:

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:

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:

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

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

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"
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 Settings -> 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)

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:
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:

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.

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:

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

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:

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>

For example:

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

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

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