Host Access Class Library C++

This C++ class library presents a complete object-oriented abstraction of a host connection that includes: reading and writing the host presentation space (screen), enumerating the fields on the screen, reading the Operator Indicator Area (OIA) for status information, accessing and updating information about the visual emulator window, transferring files, and performing asynchronous notification of significant events. The class libraries support Microsoft Visual C++ compilers.

The Host Access Class Library C++ layer consists of a number of C++ classes arranged in a class hierarchy. Figure 2 illustrates the C++ inheritance hierarchy of the Host Access Class Library C++ layer. Each object inherits from the class immediately above it in the diagram.

Figure 2. Host Access Class Objects
Displays the Host Access Class Library class library objects structure.

Figure 2 also shows all the member functions of each class. Note that in addition to the functions shown for each class, classes inherit all the functions of the parent class. For example, the function IsReady() is available on ECLSession, ECLPS, ECLOIA, ECLWinMetrics, and ECLXfer classes.

Each class is described briefly in the following sections. See the individual class descriptions in this chapter for more details.

All the examples shown in this chapter are supplied in the ECLSAMPS.CPP file. This file can be used to compile and execute any of the examples using any supported compiler.

The following is a brief overview of the Host Access Class Library C++ classes. Each class name begins with ECL, which is the common prefix for the Host Access Class Library.

Building C++ ECL Programs

This section describes the mechanics of how to build a C++ program which uses the ECL. The source code preparation, compiling and linking requirements are described.

Microsoft Visual C++

The following sections describe how to prepare, compile, and link Microsoft Visual C++ applications that use the ECL. Z and I Emulator for Windows currently supports Microsoft Visual C++ compiler Version 4.2 and later.

Source Code Preparation

Programs that use ECL classes must include the ECL header files to obtain the class definitions and other compile-time information. Although it is possible to include only the subset of header files the application requires, for simplicity it is recommended that applications include all ECL header files using the ECLALL.HPP file.

Any C++ source file which contains references to ECL objects or definitions should have the following statement before the first reference:

	#include "eclall.hpp"   

Compiling

The compiler must be instructed to search the ZIEWin subdirectory containing the ECL header files. This is done using the /I compiler option, or the Developer Studio Project Setting dialog.

The application must be compiled for multithreaded execution by using the /MT (for executable files), or /MD (for DLLs) compiler options.

Linking

The linker must be instructed to include the ECL linkable library file (PCSECLVC.LIB). This is done by specifying the fully qualified name of the library file on the linker command line, or by using the Developer Studio Project Settings dialog.

Executing

When an application that uses the ECL is executed, the ZIEWin libraries must be found in the system path. By default, the ZIEWin directory is added to the system path during ZIEWin installation.

ECLBase Class

ECLBase is the base class for all ECL objects. It provides some basic utility methods such as the conversion of connection names and handles. Because all ECL objects inherit from this class, these methods can be used on any ECL object.

An application should not create objects of this class directly.

Derivation

None

ECLBase Methods

The following shows the methods that are valid for ECLBase classes.

int GetVersion(void)
char ConvertHandle2ShortName(long ConnHandle)
long ConvertShortName2Handle(char Name)
void ConvertTypeToString(int ConnType,char *Buff)
inline void ConvertPos(ULONG Pos, ULONG *Row, ULONG *Col, ULONG PSCols)

GetVersion

This method returns the version of the Host Access Class Library. The value returned is the decimal version number multiplied by 100. For example, version 1.02 would be returned as 102.

Prototype

int GetVersion(void)

Parameters

None

Return Value

int
The ECL version number multiplied by 100.

Example

//-----------------------------------------------------------------
// ECLBase::GetVersion
//
// Display major version number of ECL library.
//-----------------------------------------------------------------
void Sample2() {
 
if (ECLBase::GetVersion() >= 200) {
  printf("Running version 2.0 or later.\n");
}
else {
  printf("Running version 1.XX\n");
}
 
} // end sample

ConvertHandle2ShortName

This method returns the name (A-Z or a-z) of the ECL connection handle specified. Note that this function may return a name even if the specified connection does not exist.

Prototype

char ConvertHandle2ShortName(long ConnHandle)

Parameters

long ConnHandle
The handle of an ECL connection.

Return Value

char
The name of the ECL connection in the range A-Z or a-z.

Example

//-------------------------------------------------------------------
// ECLBase::ConvertHandle2ShortName
//
// Display name of first connection in the connection list.
//-------------------------------------------------------------------
void Sample3() {
 
ECLConnList  ConnList;
long Handle;
char Name;
 
if (ConnList.GetCount() > 0) {
  // Print connection name of first connection in the
  // connection list.
  Handle = ConnList.GetFirstConnection()->GetHandle();
  Name = ConnList.ConvertHandle2ShortName(Handle);
  printf("Name of first connection is: %c \n", Name);
}
else printf("There are no connections.\n");
 
} // end sample

ConvertShortName2Handle

This method returns the connection handle of the ECL connection with the specified name. The name must be in the range A-Z or a-z. Note that this function may return a handle even if the specified connection does not exist.

Prototype

char ConvertShortName2Handle(char Name)

Parameters

char Name
The name of an ECL connection in the range A-Z or a-z.

Return Value

char
The handle of the ECL connection.

Example

//-------------------------------------------------------------------
// ECLBase::ConvertShortName2Handle
//
// Display handle of connection 'A'.
//-------------------------------------------------------------------
void Sample4() {
 
ECLConnList  ConnList;
long Handle;
char Name;
 
Name = 'A';
Handle = ConnList.ConvertShortName2Handle(Name);
printf("Handle of connection A is: 0x%lx \n", Handle);
 
} // end sample
 

ConvertTypeToString

This method converts a connection type returned by ECLConnection::GetConnType() into a null terminated string. The string returned is not language sensitive.

Prototype

void ConvertTypeToString(int ConnType,char *Buff)

Parameters

int ConnType
The connection type and must be one of the HOSTTYPE_* constants defined in ECLBASE.HPP.
char *Buff
A buffer of size TYPE_MAXSTRLEN as defined in ECLBase.hpp in which the string will be returned.
ConnType Returned String
HOSTTYPE_3270DISPLAY "3270 DISPLAY"
HOSTTYPE_3270PRINTER "3270 PRINTER"
HOSTTYPE_5250 DISPLAY "5250 PRINTER"
HOSTTYPE_5250PRINTER "5250 PRINTER"
HOSTTYPE_VT "ASCII TERMINAL"
HOSTTYPE_PC "PC SESSION"
Any other value "UNKNOWN"

Return Value

None

Example

//-------------------------------------------------------------------
// ECLBase::ConvertTypeToString
//
// Display type of connection 'A'.
//-------------------------------------------------------------------
void Sample5() {
 
ECLConnection  *pConn;
char           TypeString[21];
 
pConn = new ECLConnection('A');
 
pConn->ConvertTypeToString(pConn->GetConnType(), TypeString);
// Could also use:
// ECLBase::ConvertTypeToString(pConn->GetConnType(), TypeString);
 
printf("Session A is a %s \n", TypeString);
 
delete pConn;
 
} // end sample

ConvertPos

This method is an inline function (macro) to convert an ECL position coordinate into a row/column coordinate given a position and the width of the presentation space. This function is faster than using ECLPS::ConvertPosToRowCol() for applications that already know (or assume) the width of the presentation space.

Prototype

inline void ConvertPos(ULONG Pos,ULONG *Row,ULONG *Col,ULONG PSCols).

Parameters

ULONG Pos
The linear positional coordinate to be converted (input).
ULONG *Row
The pointer to the returned row number of the given position (output).
ULONG *Col
The pointer to the returned column number of the given position (output).
ULONG *PSCols
The number of columns in the host presentation space (input).

Return Value

None

Example

//-------------------------------------------------------------------
// ECLBase::ConvertPos
//
// Display row/column coordinate of a given point.
//-------------------------------------------------------------------
void Sample6() {
 
ECLPS     *pPS;
ULONG     NumRows, NumCols, Row, Col;
 
try {
  pPS = new ECLPS('A');
 
  pPS->GetSize(&NumRows, &NumCols);  // Get height and width of PS
 
  // Get row/column coordinate of position 81
  ECLBase::ConvertPos(81, &Row, &Col, NumCols);
  printf("Position 81 is row %lu, column %lu \n", Row, Col);
 
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

ECLConnection Class

ECLConnection contains connection-related information for a given connection. This object can be created directly by an application, and is also created indirectly by the ECLConnList object or when creating any object that inherits from ECLConnection (for example, ECLSession).

The information returned by the methods of this object are current as of the time the method is called.

ECLConnection is inherited by ECLSession, ECLPS, ECLOIA, ECLWinMetrics, and ECLXfer.

Derivation

ECLBase > ECLConnection

ECLConnection Methods

The following shows the methods that are valid for ECLConnection classes.

ECLConnection(char ConnName)
ECLConnection(long ConnHandle)
~ECLConnection()
long GetHandle()
int GetConnType()
int GetEncryptionLevel()
char GetName()
BOOL IsStarted()
BOOL IsCommStarted()
BOOL IsAPIEnabled()
BOOL IsReady()

unsigned int GetCodePage()
void StartCommunication()
void StopCommunication()
void RegisterCommEvent(ECLCommNotify *NotifyObject, BOOL InitEvent = TRUE)
void UnregisterCommEvent(ECLCommNotify *NotifyObject)

ECLConnection Constructor

This method constructs an ECLConnection object from either a connection name or a handle.

Prototype

ECLConnection(long ConnHandle)

ECLConnection(char ConnName)

Parameters

long ConnHandle
Handle of connection to create a connection object.
char ConnName
Name (A-Z or a-z) of connection to create a connection object.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnection::ECLConnection    (Constructor)
//
// Create two connection objects for connection 'A', one created
// by name, the other by handle.
//-------------------------------------------------------------------
void Sample7() {
 
ECLConnection 		*pConn1, *pConn2;
long              Hand;
 
try {
  pConn1  = new ECLConnection('A');
  Hand    = pConn1->GetHandle();
  pConn2  = new ECLConnection(Hand);  // Another ECLConnection for 'A'
 
  printf("Conn1 is for connection %c, Conn2 is for connection %c.\n",
         pConn1->GetName(), pConn2->GetName());
 
  delete pConn1;  // Call destructors
  delete pConn2;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
  

ECLConnection Destructor

This method destroys an ECLConnection object.

Prototype

~ECLConnection()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnection::~ECLConnection    (Destructor)
//
// Create two connection objects, then delete both of them.
//-------------------------------------------------------------------
void Sample8() {
 
ECLConnection 		*pConn1, *pConn2;
long              Hand;
 
try {
  pConn1  = new ECLConnection('A');
  Hand    = pConn1->GetHandle();
  pConn2  = new ECLConnection(Hand);  // Another ECLConnection for 'A'
 
  printf("Conn1 is for connection %c, Conn2 is for connection %c.\n",
         pConn1->GetName(), pConn2->GetName());
 
  delete pConn1;  // Call destructors
  delete pConn2;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
  

GetCodePage

This method returns the host code page for which the connection is configured.

Prototype

unsigned int GetCodePage()

Parameters

None

Return Value

unsigned int
Host code page of the connection.

Example

//-------------------------------------------------------------------
// ECLConnection::GetCodePage
//
// Display host code page for each ready connection.
//-------------------------------------------------------------------
void Sample16() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (Info->IsReady())
    printf("Connection %c is configured for host code page %u.\n",
            Info->GetName(), Info->GetCodePage());
}
 
} // end sample
  

GetHandle

This method returns the handle of the connection. This handle uniquely identifies the connection and may be used in other ECL functions that require a connection handle.

Prototype

long GetHandle()

Parameters

None

Return Value

long
Connection handle of the ECLConnection object.

Example

The following example shows how to return the handle of the first connection in the connection list.

//-------------------------------------------------------------------
// ECLConnection::GetHandle
//
// Get the handle of connection 'A' and use it to create another
// connection object.
//-------------------------------------------------------------------
void Sample9() {
 
ECLConnection 		*pConn1, *pConn2;
long              Hand;
 
try {
  pConn1  = new ECLConnection('A');
  Hand    = pConn1->GetHandle();
  pConn2  = new ECLConnection(Hand);  // Another ECLConnection for 'A'
 
  printf("Conn1 is for connection %c, Conn2 is for connection %c.\n",
         pConn1->GetName(), pConn2->GetName());
 
  delete pConn1;  // Call destructors
  delete pConn2;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
  

GetConnType

This method returns the connection type. This connection type may change over time (for example, you may reconfigure the connection for a different host). The application should not assume the connection type is fixed. See below for connection types returned.

Note:
The ECLBase::ConvertTypeToString function converts the connection type to a null terminated string.

Prototype

int GetConn Type()

Parameters

None

Return Value

int
Connection type constant (HOSTTYPE_* from HOSTBASE.HPP). The following table shows the value returned and its meaning.
Value Returned Meaning
HOSTTYPE_3270DISPLAY 3270 display
HOSTTYPE_3270PRINTER 3270 printer
HOSTTYPE_5250DISPLAY 5250 display
HOSTTYPE_5250PRINTER 5250 printer
HOSTTYPE_VT ASCII VT display
HOSTTYPE_UNKNOWN Unknown connection type

Example

The following example shows how use the GetConnType method to return the connection type.

//-------------------------------------------------------------------
// ECLConnection::GetConnType
//
// Find the first 3270 display connection in the current list of
// all connections.
//-------------------------------------------------------------------
void Sample10() {
 
ULONG      i;             // Connection counter
ECLConnList ConnList;     // Connection list object
ECLConnection *Info=NULL; // Pointer to connection object
 
for (i=0; i<ConnList.GetCount(); i++) {
 
  Info = ConnList.GetNextConnection(Info);
  if (Info->GetConnType() == HOSTTYPE_3270DISPLAY) {
    // Found the first 3270 display connection
    printf("First 3270 display connection is '%c'.\n",
            Info->GetName());
    return;
  }
 
} // for
printf("Found no 3270 display connections.\n");
 
} // end sample
  

GetName

This method returns the connection name (a single, alphabetic character from A-Z or a-z) of the connection. This name also corresponds to the EHLLAPI session ID.

Prototype

char GetName()

Parameters

None

Return Value

char
Connection short name.

Example

The following example shows how to use the GetName method to return the connection name.

//-------------------------------------------------------------------
// ECLConnection::GetName
//
// Find the first 3270 display connection in the current list of
// all connections and display its name (session ID).
//-------------------------------------------------------------------
void Sample11() {
 
ULONG      i;             // Connection counter
ECLConnList ConnList;     // Connection list object
ECLConnection *Info=NULL; // Pointer to connection object
 
for (i=0; i<ConnList.GetCount(); i++) {
 
  Info = ConnList.GetNextConnection(Info);
  if (Info->GetConnType() == HOSTTYPE_3270DISPLAY) {
    // Found the first 3270 display connection, display the name
    printf("First 3270 display connection is '%c'.\n",
            Info->GetName());
    return;
  }
 
} // for
printf("Found no 3270 display connections.\n");
 
} // end sample
  

GetEncryptionLevel

This method returns the encryption level of the current connection.

Prototype

int GetEncryptionLevel()

Parameters

None

Return Value

int
Encryption level constant. The following table shows the value returned and its meaning.
Value Returned Meaning
ENCRYPTION_NONE No Encryption
ENCRYPTION_40BIT 40 bit encryption
ENCRYPTION_56BIT 56 bit encryption
ENCRYPTION_128BIT 128 bit encryption
ENCRYPTION_168BIT 168 bit encryption
ENCRYPTION_NOKEY Encrypted without a key

Example

The following example shows how use the GetEncryptionLevel method to return the encryption level.

//-------------------------------------------------------
// ECLConnection::GetEncryptionLevel
//
// Display the encryption level of session A
//
//-------------------------------------------------------
void SampleEL()
{
int EncryptionLevel = 0;			//Encryption Level
ECLConnection * Info = NULL;		//Pointer to connection object

Info = new ECLConnection('A');
If (Info != NULL)
{
	EncryptionLevel = Info->GetEncryptionLevel();
	switch (EncryptionLevel)
	{
	case ENCRYPTION_NONE:
		printf("Encryption Level = None");
		break;
	case ENCRYPTION_40BIT:
		printf("Encryption Level = 40 BIT");
		break;
	case ENCRYPTION_56BIT:
		printf("Encryption Level = 56 BIT");
		break;
	case ENCRYPTION_128BIT:
		printf("Encryption Level = 128 BIT");
		break;
	case ENCRYPTION_168BIT:
		printf("Encryption Level = 168 BIT");
		break;

    	default:
	}
}	
}

IsStarted

This method indicates if the connection is started. A started connection may or may not be connected to a host. Use the IsCommStarted function to determine if the connection is currently connected to a host.

Prototype

BOOL IsStarted()

Parameters

None

Return Value

BOOL
TRUE value if the connection is started; FALSE value if the connection is not started.

Example

//-------------------------------------------------------------------
// ECLConnection::IsStarted
//
// Display list of all started connections.  Note they may or may
// not be communications-connected to a host, and may or may not
// be visible on the screen.
//-------------------------------------------------------------------
void Sample12() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
// Print list of started connections
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (Info->IsStarted())
    printf("Connection %c is started.\n", Info->GetName());
}
 
} // end sample
  

IsCommStarted

This method indicates if the connection is currently connected to the host (for example, it indicates if host communications is active for the connection). This function returns a FALSE value if the connection is not started (see IsStarted).

Prototype

BOOL IsCommStarted()

Parameters

None

Return Value

BOOL
TRUE value if the connection is connected to the host; FALSE value if the connection is not connected to the host.

Example

//-------------------------------------------------------------------
// ECLConnection::IsCommStarted
//
// Display list of all started connections which are currently
// in communications with a host.
//-------------------------------------------------------------------
void Sample13() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (Info->IsCommStarted())
    printf("Connection %c is connected to a host.\n", Info->GetName());
}
 
} // end sample
  

IsAPIEnabled

This method indicates if the connection is API-enabled. A connection that does not have API enabled cannot be used with the Host Access Class Library. This function returns a FALSE value if the connection is not started.

Prototype

BOOL IsAPIEnabled()

Parameters

None

Return Value

BOOL
TRUE value if API is enabled; FALSE value if API is not enabled.

Example

//-------------------------------------------------------------------
// ECLConnection::IsAPIEnabled
//
// Display list of all started connections which have APIs enabled.
//-------------------------------------------------------------------
void Sample14() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (Info->IsAPIEnabled())
    printf("Connection %c has APIs enabled.\n", Info->GetName());
}
 
} // end sample
  

IsReady

This method indicates that the connection is ready, meaning the connection is started, connected, and API-enabled. This function is faster and easier than calling IsStarted, IsCommStarted, and IsAPIEnabled.

Prototype

BOOL IsReady()

Parameters

None

Return Value

BOOL
TRUE if the connection is started, CommStarted, and API-enabled; FALSE if otherwise.

Example

//-------------------------------------------------------------------
// ECLConnection::IsReady
//
// Display list of all connections which are started, comm-connected
// to a host, and have APIs enabled.
//-------------------------------------------------------------------
void Sample15() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
   if (Info->IsReady())
    printf("Connection %c is ready (started, comm-connected, API
          enabled).\n", Info->GetName());
}
 
} // end sample
  

StartCommunication

This method connects the ZIEWin emulator to the host data stream. This has the same effect as going to the ZIEWin emulator communication menu and choosing Connect.

Prototype

void StartCommunication()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnection::StartCommunication
//
// Start communications link for any connection which is currently
// not comm-connected to a host.
//-------------------------------------------------------------------
void Sample17() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (!(Info->IsCommStarted())) {
    printf("Starting comm-link for connection %c...\n", Info->GetName());
    Info->StartCommunication();
  }
}
 
} // end sample
  

StopCommunication

This methods disconnects the ZIEWin emulator from the host data stream. This has the same effect as going to the ZIEWin emulator communication menu and choosing Disconnect.

Prototype

void StopCommunication()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnection::StopCommunication
//
// Stop comm-link for any connection which is currently connected
// to a host.
//-------------------------------------------------------------------
void Sample18() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
 
for (Info = ConnList.GetFirstConnection();
     Info != NULL;
     Info = ConnList.GetNextConnection(Info)) {
 
  if (Info->IsCommStarted()) {
    printf("Stopping comm-link for connection %c...\n", Info->GetName());
    Info->StopCommunication();
  }
}
 
} // end sample
 

RegisterCommEvent

This member function registers an application object to receive notification of all communication link connect/disconnect events. To use this function, the application must create an object derived from the ECLCommNotify class. A pointer to that object is then passed to this registration function. Implementation Restriction: An application can register only one object for communication event notification.

After a notify object has been registered with this function, it will be called whenever the connections communication link with the host connects or disconnects. The object will receive notification for all communication events whether they are caused by the StartCommunication() function or explicitly by the user. This event should not be confused with the connection start/stop event which is triggered when a new ZIEWin connection starts or stops.

The optional InitEvent parameter causes an initial event to be generated when the object is registered. This can be useful to synchronize an event object with the current state of the communications link. If InitEvent is specified as FALSE, no initial event is generated when the object is registered. The default for this parameter is TRUE.

The application must call UnregisterCommEvent() before destroying the notification object. The object is automatically unregistered if the ECLConnection object where it is registered is destroyed.

See the description of ECLCommNotify Class for more information.

Prototype

void RegisterCommEvent(ECLCommNotify *NotifyObject, BOOL InitEvent = TRUE)

Parameters

ECLCommNotify *NotifyObject
Pointer to an object derived from ECLCommNotify class.
BOOL InitEvent
Generate an initial event with the current state.

Return Value

None

Example

See ECLCommNotify Class for an example of ECLConnection::RegisterCommEvent.

UnregisterCommEvent

This member function unregisters an application object previously registered for communication events with the RegisterCommEvent() function. A registered application notify object should not be destroyed without first calling this function to unregister it. If there is no notify object currently registered, or the registered object is not the NotifyObject passed in, this function does nothing (no error is thrown).

When a notify object is unregistered, its NotifyStop() member function will be called.

See the description of ECLCommNotify Class for more information.

Prototype

void UnregisterCommEvent(ECLCommNotify *NotifyObject)

Parameters

ECLCommNotify *NotifyObject
This is a currently registered application notification object.

Return Value

None

Example

See ECLCommNotify Class for an example of ECLConnection::UnregisterCommEvent.

ECLConnList Class

ECLConnList obtains information about all host connections on a given machine. An ECLConnList object contains a collection of all the connections that are currently known in the system.

The ECLConnList object contains a collection of ECLConnection objects. Each element of the collection contains information about a single connection. A connection in this list may be in any state (for example, stopped or disconnected). All started connections appear in this list. The ECLConnection object contains the state of the connection.

The list is a snapshot of the set of connections at the time this object is created, or the last time the Refresh method was called. The list is not dynamically updated as connections are started and stopped. An application can use the RegisterStartEvent member of the ECLConnMgr object to be notified of connection start and stop events.

An ELCConnList object may be created directly by the application or indirectly by the creation of an ECLConnMgr object.

Derivation

ECLBase > ECLConnList

Usage Notes

An ECLConnList object provides a static snapshot of current connections. The Refresh method is automatically called upon construction of the ECLConnList object. If you use the ECLConnList object right after construction it contains an accurate representation of the list of connections at that moment. However, you should call the Refresh method in the ECLConnList object before you start accessing it if some time has passed since its construction.

The application can iterate over the collection by using the GetFirstConnection and GetNextConnection methods. The object pointers returned by GetFirstConnection and GetNextConnection are valid only until the Refresh member is called, or the ECLConnList object is destroyed. The application can locate a specific connection of interest in the list using the FindConnection function. Like GetNextConnection, the returned pointer is valid only until the next Refresh or the ECLConnList object is destroyed.

The order of connections in the connection list is undefined. An application should not make any assumptions about the list order. The order of connections in the list does not change until the Refresh function is called.

An ECLConnList object is automatically created when an ECLConnMgr object is created. However, the ECLConnList object can be created without an ECLConnMgr object.

ECLConnList Methods

The following section describes the methods that are valid for the ECLConnList class.

ECLConnection * GetFirstConnection()
ECLConnection * GetNextConnection(ECLConnection *Prev)
ECLConnection * FindConnection(Long ConnHandle)
ECLConnection * FindConnection(char ConnName)
ULONG GetCount()
void Refresh()

ECLConnList Constructor

This method creates an ECLConnList object and initializes it with the current list of connections.

Prototype

ECLConnList();

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnList::ECLConnList        (Constructor)
//
// Dynamically construct a connection list object, display number
// of connections in the list, then delete the list.
//-------------------------------------------------------------------
void Sample19() {
 
ECLConnList *pConnList;  // Pointer to connection list object
 
try {
  pConnList = new ECLConnList();
  printf("There are %lu connections in the connection list.\n",
         pConnList->GetCount());
 
  delete pConnList;  // Call destructor
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

ECLConnList Destructor

This method destroys an ECLConnList object.

Prototype

~ECLConnList()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnList::~ECLConnList        (Destructor)
//
// Dynamically construct a connection list object, display number
// of connections in the list, then delete the list.
//-------------------------------------------------------------------
void Sample20() {
 
ECLConnList *pConnList;  // Pointer to connection list object
 
try {
  pConnList = new ECLConnList();
  printf("There are %lu connections in the connection list.\n",
         pConnList->GetCount());
 
  delete pConnList;  // Call destructor
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 
 

GetFirstConnection

The GetFirstConnection method returns a pointer to the first connection information object in the ECLConnList collection. See ECLConnection Class for details on its contents. The returned pointer becomes invalid when the ECLConnList Refresh member is called or the ECLConnList object is destroyed. The application should not delete the returned object. If there are no connections in the list, NULL is returned.

Prototype

ECLConnection *GetFirstConnection()

Parameters

None

Return Value

ECLConnection *
Pointer to the first ECLConnection object in the list. If there are no connections in the list, null is returned.

Example

//-------------------------------------------------------------------
// ECLConnection::GetFirstConnection
//
// Iterate over list of connections and display information about
// each one.
//-------------------------------------------------------------------
void Sample21() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
char TypeString[21];     // Type of connection
 
for (Info = ConnList.GetFirstConnection();       // Get first one
     Info != NULL;                               // While there is one
     Info = ConnList.GetNextConnection(Info)) {  // Get next one
 
  ECLBase::ConvertTypeToString(Info->GetConnType(), TypeString);
  printf("Connection %c is a %s type connection.\n",
         Info->GetName(), TypeString);
}
 
} // end sample
 
 
 

GetNextConnection

This method returns a pointer to the next connection information object in the ECLConnList collection given a connection in the list. The application supplies a pointer to a connection previously returned by this function or GetFirstConnection. See ECLConnection Class for details on its contents. The returned pointer is not valid after the next ECLConnList Refresh() call, or the ECLConnList object is destroyed. A NULL pointer is returned if there is an attempt to read past the end of the list. Successive calls to this method (supplying the prior pointer on each call) iterates over the list of connections. After the last connection is returned, subsequent calls return a NULL pointer. The first connection in the list can be obtained by supplying NULL for the previous connection.

Prototype

ECLConnection *GetNext Connection (ECLConnection *Prev)

Parameters

ECLConnection *Prev
Pointer returned by prior call to this function, GetFirstConnection(), or NULL.

Return Value

ECLConnection *
This is the pointer to the next ECLConnection object, or NULL if end of list.

Example

//-------------------------------------------------------------------
// ECLConnection::GetNextConnection
//
// Iterate over list of connections and display information about
// each one.
//-------------------------------------------------------------------
void Sample22() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
char TypeString[21];     // Type of connection
 
for (Info = ConnList.GetFirstConnection();       // Get first one
     Info != NULL;                               // While there is one
     Info = ConnList.GetNextConnection(Info)) {  // Get next one
 
  ECLBase::ConvertTypeToString(Info->GetConnType(), TypeString);
  printf("Connection %c is a %s type connection.\n",
         Info->GetName(), TypeString);
}
 
} // end sample
 
 

FindConnection

This method searches the current connection list for the connection specified. The desired connection can be specified by handle or by name. There are two signatures for the FindConnection method. If the specified connection is found, a pointer to the ECLConnection object is returned. If the specified connection is not in the list, NULL is returned. The list is not automatically refreshed by this function; if a new connection has started since the list was constructed or refreshed it is not found. The returned pointer is to an object in the connection list maintained by the ECLConnList object. The returned pointer is invalid after the next ECLConnList::Refresh call or the ECLConnList object is destroyed.

Prototype

ECLConnection *FindConnection(Long ConnHandle),

ECLConnection *FindConnection(char ConnName)

Parameters

Long ConnHandle
Handle of the connection to find in the list.
char ConnName
Name of the connection to find in the list.

Return Value

ECLConnection *
Pointer to the requested ECLConnection object. If the specified connection is not in the list, NULL is returned.

Example

//-------------------------------------------------------------------
// ECLConnection::FindConnection
//
// Find connection 'B' in the list of connections.  If found, display
// its type.
//-------------------------------------------------------------------
void Sample23() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
char TypeString[21];     // Type of connection
 
Info = ConnList.FindConnection('B');  // Find connection by name
if (Info != NULL) {
 
  ECLBase::ConvertTypeToString(Info->GetConnType(), TypeString);
  printf("Connection 'B' is a %s type connection.\n",
          TypeString);
}
else printf("Connection 'B' not found.\n");
 
} // end sample
 
 

GetCount

This method returns the number of connections currently in the ECLConnList collection.

Prototype

ULONG GetCount()

Parameters

None

Return Value

ULONG
Number of connections in the collection.

Example

//-------------------------------------------------------------------
// ECLConnList::GetCount
//
// Dynamically construct a connection list object, display number
// of connections in the list, then delete the list.
//-------------------------------------------------------------------
void Sample24() {
 
ECLConnList *pConnList;  // Pointer to connection list object
 
try {
  pConnList = new ECLConnList();
  printf("There are %lu connections in the connection list.\n",
         pConnList->GetCount());
 
  delete pConnList;  // Call destructor
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

Refresh

This method updates the ECLConnList collection with a list of all currently known connections in the system. All pointers previously returned by GetNextConnection, GetFirstConnection and FindConnection become invalid.

Prototype

void Refresh()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnection::Refresh
//
// Loop-and-wait until connection 'B' is started.
//-------------------------------------------------------------------
void Sample25() {
 
ECLConnection *Info;     // Pointer to connection object
ECLConnList ConnList;	   // Connection list object
int i;
 
printf("Waiting up to 60 seconds for connection B to start...\n");
for (i=0; i<60; i++) {   // Limit wait to 60 seconds
  ConnList.Refresh();    // Refresh the connection list
  Info = ConnList.FindConnection('B');
  if ((Info != NULL) && (Info->IsStarted())) {
    printf("Connection B is now started.\n");
    return;
  }
  Sleep(1000L);          // Wait 1 second and try again
}
 
printf("Connection 'B' not started after 60 seconds.\n");
 
} // end sample
 
 

ECLConnMgr Class

ECLConnMgr manages all Z and I Emulator for Windows connections on a given machine. It provides methods relating to the management of connections such as starting and stopping connections. It also creates an ECLConnList object to enumerate the list of all known connections on the system (see ECLConnList Class).

Derivation

ECLBase > ECLConnMgr

ECLConnMgr Methods

The following shows the methods that are valid with the ECLConnMgr class.

ECLConnMgr()
~ECLConnMgr()
ECLConnList * GetConnList()
void StartConnection(char *ConfigParms)
void StopConnection(Long ConnHandle, char *StopParms)
void RegisterStartEvent(ECLStartNotify *NotifyObject)
void UnregisterStartEvent(ECLStartNotify *NotifyObject)

ECLConnMgr Constructor

This method constructs an ECLConnMgr object.

Prototype

ECLConnMgr()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnMgr::ECLConnMgr          (Constructor)
//
// Create a connection mangager object, start a new connection,
// then delete the manager.
//-------------------------------------------------------------------
void Sample26() {
 
ECLConnMgr			*pCM; // Pointer to connection manager object
 
try {
  pCM = new ECLConnMgr();  // Create connection manager
  pCM->StartConnection("profile=coax connname=e");
  printf("Connection 'E' started with COAX profile.\n");
  delete pCM;              // Delete connection manager
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample

ECLConnMgr Deconstructor

This method destroys an ECLConnMgr object.

Prototype

~ECLConnMgr()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnMgr::~ECLConnMgr          (Destructor)
//
// Create a connection mangager object, start a new connection,
// then delete the manager.
//-------------------------------------------------------------------
void Sample27() {
 
ECLConnMgr			*pCM; // Pointer to connection manager object
 
try {
  pCM = new ECLConnMgr();  // Create connection manager
  pCM->StartConnection("profile=coax connname=e");
  printf("Connection 'E' started with COAX profile.\n");
  delete pCM;              // Delete connection manager
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetConnList

This method returns a pointer to an ECLConnList object. See ECLConnList Class for more information. The ECLConnList object is destroyed when the ECLConnMgr object is destroyed.

Prototype

ECLConnList * GetConnList()

Parameters

None

Return Value

ECLConnList *
Pointer to an ECLConnList object

Example

//-------------------------------------------------------------------
// ECLConnMgr::GetConnList
//
// Use connection manager's connection list object to display
// number of connections (see also ECLConnList::GetCount).
//-------------------------------------------------------------------
void Sample28() {
 
ECLConnMgr			CM; // Connection manager object
 
printf("There are %lu connections in the connection list.\n",
       CM.GetConnList()->GetCount());
 
} // end sample
 

StartConnection

This method starts a new Z and I Emulator for Windows emulator connection. The ConfigParms string contains connection configuration information as explained under Usage Notes.

Prototype

void StartConnection(char *ConfigParms)

Parameters

char *ConfigParms
Null terminated connection configuration string.

Return Value

None

Usage Notes

The connection configuration string is implementation-specific. Different implementations of the Host Access Class Library may require different formats or information in the configuration string. This call is asynchronous in nature; the new connection may not yet be started when this call returns. An application can use the RegisterStartEvent function to be notified when a connection starts.

For Z and I Emulator for Windows, the configuration string has the following format:

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

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

PROFILE=<filename>
Names the Z and I Emulator for Windows workstation profile (.WS file) that contains the connection configuration information. This parameter is not optional; a profile name must be supplied. If the file name contains blanks, the name must be enclosed in double quotation marks. The <filename> value may be either the profile name with no extension, the profile name with the .WS extension, or the fully-qualified profile name path.
CONNNAME=<c>
Specifies the connection name (EHLLAPI short session ID) of the new connection. This value must be a single, alphabetic character (A-Z or a-z). If this value is not specified, the next available connection name is assigned automatically. If a connection already exists with the specified name an error is thrown (ERRMAJ_INVALID_SESSION).
WINSTATE=<MAX|MIN|RESTORE|HIDE>
Specifies the initial state of the emulator window. The default if this parameter is not specified is RESTORE.
Note:
Due to the asynchronous nature of this call, it is possible for this function to return without error, but the connection fails to start. For example, if two connections are started in a short period of time with the same connection name the second StartConnection does not fail because the first connection has not yet started. However, when the second connection finally attempts to register its name it does fail to start because the name is already in use by the first connection. To minimize this possibility, connections should be started without specifying the CONNNAME parameter if possible.

Example

The following is an example of the StartConnection method.

ECLConnMgr	Manager;		// Connection manager object
 
// Start a host connection "E" and check for errors
 
try {
  Manager.StartConnection("profile=coax connname=e");
}
catch (ECLErr Error) {
  MessageBox(NULL, Error.GetMsgText(), "Session start error!", MB_OK);
}

StopConnection

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

Prototype

void StopConnection(Long ConnHandle, char *StopParms)

Parameters

Long ConnHandle
Handle of the connection to be stopped.
char * StopParms
Null terminated connection stop parameter string.

Return Value

None

Usage Notes

The connection stop parameter string is implementation-specific. Different implementations of the Host Access Class Library may require a different format and contents of the parameter string. For Z and I Emulator for Windows 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 the SAVEPROFILE parameter is as follows:

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

Example

//-------------------------------------------------------------------
// ECLConnMgr::StopConnection
//
// Stop the first connection in the connection list.
//-------------------------------------------------------------------
void Sample29() {
 
ECLConnMgr			CM; // Connection manager object
 
if (CM.GetConnList()->GetCount() > 0) {
 
  printf("Stopping connection %c.\n",
         CM.GetConnList()->GetFirstConnection()->GetName());
 
  CM.StopConnection(
    CM.GetConnList()->GetFirstConnection()->GetHandle(),
    "saveprofile=no");
}
else printf("No connections to stop.\n");
 
 
} // end sample
 

RegisterStartEvent

This method registers an application object to receive notification of all connection start and stop events. To use this function, the application must create an object derived from the ECLStartNotify class. A pointer to that object is then passed to this registration function. Implementation Restriction: An application can register only one object for connection start or stop notification.

After a notify object has been registered with this function, it is called whenever a Z and I Emulator for Windows connection is started or stopped. The object receives notification for all connections whether they are started by the StartConnection function or explicitly by you. This event should not be confused with the start/stop Communication event, which is triggered when a connection connects or disconnects from a host system.

See ECLStartNotify Class for more information.

Prototype

void RegisterStartEvent(ECLStartNotify *NotifyObject)

Parameters

ECLStartNotify *NotifyObject
Pointer to object derived from the ECLStartNotify class.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnMgr::RegisterStartEvent
//
// See ECLStartNotify Class for example of this method.
//---------------------------------------------------------
  

UnregisterStartEvent

This method unregisters an application object previously registered for connection start or stop events with the RegisterStartEvent function. A registered application notify object should not be destroyed without first calling this function to unregister it. If there is no notify object currently registered, or the registered object is not the NotifyObject passed in, this function does nothing (no error is thrown).

When a notify object is unregistered, its NotifyStop method is called.

See ECLStartNotify Class for more information.

Prototype

void UnregisterStartEvent(ECLStartNotify *NotifyObject)

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLConnMgr::UnregisterStartEvent
//
// See ECLStartNotify Class for example of this method.
//-------------------------------------------------------------------
  

ECLCommNotify Class

ECLCommNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLCommNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLCommNotify class is used to allow an application to be notified of communications connect/disconnect events on a ZIEWin connection. Connect/disconnect events are generated whenever a ZIEWin connection (window) is connected or disconnected from a host system.

To be notified of communications connect/disconnect events, the application must perform the following steps:

  1. Define a class derived from ECLCommNotify.
  2. Implement the derived class and implement the NotifyEvent() member function.
  3. Optionally implement the NotifyError() function, NotifyStop() function or both.
  4. Create an instance of the derived class.
  5. Register the instance with the ECLConnection::RegisterCommEvent() function.

The example shown demonstrates how this may be done. When the above steps are complete, each time a connection's communications link is connected or disconnected from a host, the applications NotifyEvent() member function will be called.

If an error is detected during event generation, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error, depending on the nature of the error. When event generation terminates (either due to an error, by calling the ECLConnection::UnregisterCommEvent, or by destruction of the ECLConnection object) the NotifyStop() member function is called. However event notification is terminated, the NotifyStop() member function is always called, and the application object is unregistered.

If the application does not provide an implementation of the NotifyError() member function, the default implementation is used (a simple message box is displayed to the user). The application can override the default behavior by implementing the NotifyError() function in the applications derived class. Likewise, the default NotifyStop() function is used if the application does not provide this function (the default behavior is to do nothing).

Note that the application can also choose to provide its own constructor and destructor for the derived class. This can be useful if the application wants to store some instance-specific data in the class and pass that information as a parameter on the constructor. For example, the application may want to post a message to an application window when a communications event occurs. Rather than define the window handle as a global variable (so it would be visible to the NotifyEvent() function), the application can define a constructor for the class which takes the window handle and stores it in the class member data area.

The application must not destroy the notification object while it is registered to receive events.

Implementation Restriction: Currently the ECLConnection object allows only one notification object to be registered for communications event notification. The ECLConnection::RegisterCommEvent will throw an error if a notify object is already registered for that ECLConnection object.

Derivation

ECLBase > ECLNotify > ECLCommNotify

Example

//-------------------------------------------------------------------
// ECLCommNotify class
//
// This sample demonstrates the use of:
//
// ECLCommNotify::NotifyEvent
// ECLCommNotify::NotifyError
// ECLCommNotify::NotifyStop
// ECLConnection::RegisterCommEvent
// ECLConnection::UnregisterCommEvent
//-------------------------------------------------------------------
 
 
 //...................................................................
// Define a class derived from ECLCommNotify
//...................................................................
class MyCommNotify: public ECLCommNotify
{
public:
  // Define my own constructor to store instance data
  MyCommNotify(HANDLE DataHandle);
 
  // We have to implement this function
  void	NotifyEvent(ECLConnection *ConnObj, BOOL Connected);
 
  // We choose to implement this function
  void NotifyStop (ECLConnection *ConnObj, int Reason);
 
  // We will take the default behaviour for this so we
  // don't implement it in our class:
  // void NotifyError (ECLConnection *ConnObj, ECLErr ErrObject);
 
private:
  // We will store our application data handle here
  HANDLE MyDataH;
};
 
 
//...................................................................
void MyCommNotify::NotifyEvent(ECLConnection *ConnObj,
                           BOOL Connected)
//
// This function is called whenever the communications link
// with the host connects or disconnects.
//
// For this example, we will just write a message.  Note that we
// have access the the MyDataH handle which could have application
// instance data if we needed it here.
//
// The ConnObj pointer is to the ECLConnection object upon which
// this event was registered.
//...................................................................
{
  if (Connected)
    printf("Connection %c is now connected.\n", ConnObj->GetName());
  else
    printf("Connection %c is now disconnected.\n", ConnObj->GetName());
 
  return;
}
 
 //...................................................................
MyCommNotify::MyCommNotify(HANDLE DataHandle)   // Constructor
//...................................................................
{
  MyDataH = DataHandle;  // Save data handle for later use
}
 
//...................................................................
void MyCommNotify::NotifyStop(ECLConnection *ConnObj,
                         int Reason)
//...................................................................
{
  // When notification ends, display message
  printf("Comm link monitoring for %c stopped.\n", ConnObj->GetName());
}
 
 //...................................................................
// Create the class and start notification on connection 'A'.
//...................................................................
void Sample30() {
 
ECLConnection *Conn;    // Ptr to connection object
MyCommNotify *Event;    // Ptr to my event handling object
HANDLE InstData;	    	// Handle to application data block (for example)
 
try {
  Conn = new ECLConnection('A');         // Create connection obj
  Event = new MyCommNotify(InstData);    // Create event handler
 
  Conn->RegisterCommEvent(Event);        // Register for comm events
 
  // At this point, any comm link event will cause the
  // MyCommEvent::NotifyEvent() function to execute.  For
  // this sample, we put this thread to sleep during this
  // time.
 
  printf("Monitoring comm link on 'A' for 60 seconds...\n");
  Sleep(60000);
 
 
  // Now stop event generation.  This will cause the NotifyStop
  // member to be called.
  Conn->UnregisterCommEvent(Event);
 
  delete Event;  // Don't delete until after unregister!
  delete Conn;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample 

ECLCommNotify Methods

The following section describes the methods that are valid for the ECLCommNotify class:

ECLCommNotify()
~ECLCommNotify()
virtual void NotifyEvent (ECLConnection *ConnObj, BOOL Connected) = 0
virtual void NotifyError (ECLConnection *ConnObj, ECLErr ErrObject)
virtual void NotifyStop  (ECLConnection *ConnObj, int Reason)

NotifyEvent

This method is a "pure virtual" member function (the application must implement this function in classes derived from ECLCommNotify). This function is called whenever a connection starts or stops and the object is registered for start/stop events. The Connected BOOL is TRUE if the communications link is connected, or FALSE if it is not connected to the host.

Prototype

virtual void NotifyEvent (ECLConnection *ConnObj, BOOL Connected)

Parameters

ECLConnection *ConnObj
This is the pointer to ECLConnection object where the event occurred.
BOOL Connected
This is TRUE if comm link is connected and FALSE if disconnected.

Return Value

None

NotifyError

This method is called whenever the ECLConnection object detects an error during event generation. The error object contains information about the error (see ECLErr Class). Events may continue to be generated after the error, depending on the nature of the error. If the event generation stops due to an error, the NotifyStop() function is called. An application can choose to implement this function or allow the ECLCommNotify base class to handle the error. The base class will display the error in a message box using the text supplied by the ECLErr::GetMsgText() function. If the application implements this function in its derived class, it will override the base class function.

Prototype

virtual void NotifyError (ECLConnection *ConnObj, ECLErr ErrObject)

Parameters

ECLConnection *ConnObj
This is the pointer to ECLConnection object in which the error occurred.
ECLErr ErrObject
This is the ECLErr object describing the error.

Return Value

None

NotifyStop

This method is called when event generation is stopped for any reason (for example, due to an error condition or a call to ECLConnection::UnregisterCommEvent, etc.).

Implementation Note: the reason code is currently unused and will be zero.

Prototype

virtual void NotifyStop (ECLConnection *ConnObj, int Reason)

Parameters

ECLConnection *ConnObj
This is the ptr to ECLConnection object that is stopping notification.
int Reason
This is unused (zero).

Return Value

None

ECLErr Class

The ECLErr class provides a method of returning run-time error information from Host Access Class Library classes. In error situations, ECLErr objects are created and populated with error and diagnostic information. The ECLErr objects are then thrown as C++ exceptions. The error and diagnostic information can then be queried from the caught ECLErr object.

Applications should not create or throw ECLErr objects directly.

Derivation

ECLBase > ECLErr

ECLErr Methods

The following section describes the methods that are valid for the ECLErr class.

const int GetMsgNumber()
const int GetReasonCode()
const char *GetMsgText()

GetMsgNumber

This method returns the message number that was set when this ECLErr object was created. Error message numbers are described in ERRORIDS.HPP.

Prototype

const int GetMsgNumber()

Parameters

None

Return Value

const int
The error message number.

Example

//-------------------------------------------------------------------
// ECLErr::GetMsgNumber
//
// Cause an 'invalid parameters' error and tryp the ECL exception.
// The extract the error number and language-sensative text.
//-------------------------------------------------------------------
void Sample31() {
 
ECLPS   *PS = NULL;
 
try {
  PS = new ECLPS('A');
  PS->SetCursorPos(999,999);  // Invalid parameters
}
catch (ECLErr ErrObj) {
  printf("The following ECL error was trapped:\n");
  printf("%s \nError number: %lu\nReason code: %lu\n",
    ErrObj.GetMsgText(),
    ErrObj.GetMsgNumber(),
    ErrObj.GetReasonCode());
}
 
if (PS != NULL)
  delete PS;
 
} // end sample
 

GetReasonCode

This method gets the reason code (sometimes referred to as the secondary or minor return code) from the ECLErr object. This code is generally used for debugging and diagnostic purposes. It is subject to change in future versions of the Host Access Class Library and should not be used programmatically. Descriptions of the reason codes can be found in ERRORIDS.HPP.

Prototype

const int GetReasonCode()

Parameters

None

Return Value

const int
The ECLErr reason code.

Example

//-------------------------------------------------------------------
// ECLErr::GetReasonCode
//
// Cause an 'invalid parameters' error and tryp the ECL exception.
// The extract the error number and language-sensative text.
//-------------------------------------------------------------------
void Sample32() {
 
ECLPS   *PS = NULL;
 
try {
  PS = new ECLPS('A');
  PS->SetCursorPos(999,999);  // Invalid parameters
}
catch (ECLErr ErrObj) {
  printf("The following ECL error was trapped:\n");
  printf("%s \nError number: %lu\nReason code: %lu\n",
    ErrObj.GetMsgText(),
    ErrObj.GetMsgNumber(),
    ErrObj.GetReasonCode());
}
 
if (PS != NULL)
  delete PS;
 
} // end sample
 

GetMsgText

This method returns the message text associated with the error code used to create this ECLErr object. The message text is returned in the language for which Z and I Emulator for Windows is currently installed.

Note:
The returned pointer is invalid after the ECLErr object is deleted.

Prototype

const char *GetMsgText()

Parameters

None

Return Value

char *
The message text associated with the error code that is part of this ECLErr object.

Example

//-------------------------------------------------------------------
// ECLErr::GetMsgText
//
// Cause an 'invalid parameters' error and tryp the ECL exception.
// The extract the error number and language-sensative text.
//-------------------------------------------------------------------
void Sample33() {
 
ECLPS   *PS = NULL;
 
try {
  PS = new ECLPS('A');
  PS->SetCursorPos(999,999);  // Invalid parameters
}
catch (ECLErr ErrObj) {
  printf("The following ECL error was trapped:\n");
  printf("%s \nError number: %lu\nReason code: %lu\n",
    ErrObj.GetMsgText(),
    ErrObj.GetMsgNumber(),
    ErrObj.GetReasonCode());
}
 
if (PS != NULL)
  delete PS;
 
} // end sample
 

Usage Notes

The message text is retrieved from the Z and I Emulator for Windows message facility.

ECLField Class

ECLField contains information for a given field in an ECLFieldList object contained by an ECLPS object. An application should not create an object of this type directly. ECLField objects are created indirectly by the ECLFieldList object.

An ECLField object describes a single field of the host presentation space. It has methods for querying various attributes of the field and for updating the text of the field (for example, modifying the field text). Field attributes cannot be modified.

Derivation

ECLBase > ECLField

Copy-Constructor and Assignment Operator

This object supports copy-construction and assignment. This is useful for an application that wants to easily capture fields on a host screen for later processing. Rather than allocate text buffers and copy the string contents of the field, the application can simply store the field in a private ECLField object. The stored copy retains all the function of an ECLField object including the field's text value, attributes, starting position, length, etc. For example, suppose an application wanted to capture the first input field of the screen. Table 1 shows two ways this could be accomplished.

Table 1. Copy-Construction and Assignment Examples
Save the field as a string Save the field as an ECLField object
#include "eclall.hpp"
 
{
   char *SavePtr;  // Ptr to saved string
   ECLPS Ps('A'); // PS object
   ECLFieldList *List;
   ECLField       *Fld;
 
   // Get fld list and rebuild it
   List = Ps->GetFieldList();
   List->Refresh();
 
   // See if there is an input field
   Fld = List->GetFirstField(GetUnmodified);
   if  (Fld !=NULL) {
      // Copy the field's text value
      SavePtr=malloc(Fld->Length() + 1);
      Fld->GetScreen(SavePtr, Fld->Length()+1);
  }
 
  // We now have captured the field text
 
#include "eclall.hpp"
 
{
   ECLField SaveFld;  // Saved field
   ECLPS Ps('A');      // PS object
   ECLFieldList *List;
   ECLField       *Fld;
 
   // Get fld list and rebuild it
   List = Ps->GetFieldList();
   List->Refresh();
 
   // See if there is an input field
   Fld = List->GetFirstField(GetUnmodified);
   if  (Fld !=NULL) {
      // Copy the field object
      SaveFld = *Fld;
  }
 
  // We now have captured the field text
  // including text, position, attrib
 

There are several advantages to using an ECLField object instead of a string to store a field:

Assignment operator overrides are also provided for character strings and long integer value types. These overrides make it easy to assign new string or numeric values to unprotected fields. For example, the following sets the first two input fields of the screen:

ECLField *Fld1; //Ptr to 1st unprotected field in field list
ECLField *Fld2; // PTR to 2nd unprotected field in field list
 
Fld1 = FieldList->GetFirstField(GetUnprotected);
Fld2 = FieldList->GetNextField(Fld1, GetUnprotected);
if ((Fld1 == NULL) || (Fld2 == NULL)) return;
 
*Fld1 = "Easy string assignment";
*Fld2 = 1087;
Notes:
  1. ECLField objects initialized by copy-construction or assignment are read-only copies of the original field object. The SetText() method is invalid for such an object and will cause an ECLErr exception to be thrown. Because the objects are copies, they are not updated or deleted when the original field object is updated or deleted. The application is responsible for deleting copies of field objects when they are no longer needed.
  2. Calling any method on an unitialized ECLField object will return undefined results.
  3. An ECLField object created by the application can be reassigned any number of times.
  4. Assignments can only be made from another ECLField object, a character string, or a long integer value. Assigning any other data type to an ECLField object is invalid.
  5. If an assignment is made to an ECLField object that currently is part of an ECLFieldList, the effect is to update only the field's text value. This is allowed only if the field object is an unprotected field. For example, the following will modify the 2nd input field of the screen by copying the value from the 1st input field:
    ECLField *Fld1;   // Ptr to 1st unprotected field in field list
    ECLField *Fld2;   // Ptr to 2nd unprotected field in field list
     
    Fld1 = FieldList->GetFirstField(GetUnprotected);
    Fld2 = FieldList->GetNextField(Fld1, GetUnprotected);
    if ((Fld1 == NULL) || (Fld2 == NULL)) return;
     
    // Update the 2nd input field using text from the first
    FLD2 = * Fld1;
     

    Because Fld2 is part of an ECLFieldList, the above assignment is identical to:

    { char temp[Fld1->GetLength()+1];
      Fld1->GetText(temp, Fld1->GetLength()+1);
      Fld2->SetText(temp);
      delete []temp;
    }
     

    Note that this will throw an ECLErr exception if Fld2 is protected. Also note that only the text of Fld2 is updated, not its attributes, position, or length.

  6. Assigning a string to a field object is equivalent to calling the SetText() method. You can also assign numeric values without first converting to strings:
    *Field = 1087;
    This is equivalent to converting the number to a string and then calling the SetText() method.

ECLField Methods

The following section describes the methods that are valid for the ECLField class.

ULONG GetStart()
void GetStart(ULONG *RowULONG *Col)
ULONG GetStartRow()
ULONG GetStartCol()
ULONG GetEnd()
void GetEnd(ULONG *RowULONG *Col)
ULONG GetEndRow()
ULONG GetEndCol()
ULONG GetLength()
ULONG GetScreen(char *Buff, ULONG BuffLen, PS_PLANE Plane = TextPlane)
void SetText(char *text)
BOOL IsModified()
BOOL IsProtected()
BOOL IsNumeric()
BOOL IsHighIntensity()
BOOL IsPenDetectable()
BOOL IsDisplay()
unsigned charGetAttribute()

The following methods are valid for the ECLField class :

ULONG GetScreen(WCHAR *Buff, ULONG BuffLen, PS_PLANE Plane = TextPlane)
void SetText(WCHAR *text)

GetStart

This method returns the position in the presentation space of the first character of the field. There are two signatures for the GetStart method. ULONG GetStart returns the position as a linear value with the upper left corner of the presentation space being "1". void GetStart(ULONG *Row, ULONG *Col) returns the position as a row and column coordinate.

Prototype

ULONG GetStart(),

void GetStart(ULONG *Row, ULONG *Col)

Parameters

ULONG *Row
This output parameter is a pointer to the row value to be updated.
ULONG *Col
This output parameter is a pointer to the column value to be updated.

Return Value

ULONG
Position in the presentation space represented as a linear array.

Example

The following example shows how to return the position in the presentation space of the first character of the field.

/-------------------------------------------------------------------
// ECLField::GetStart
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)
     Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(),
      pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetStartRow

This method returns the starting row position of a given field in the ECLFieldList collection for the connection associated with the ECLPS object.

Prototype

ULONG GetStartRow()

Parameters

None

Return Value

ULONG
This is the starting row of a given field.

Example

/-------------------------------------------------------------------
// ECLField::GetStartRow
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)  Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(), pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetStartCol

This method return the starting column position of a given field in the ECLFieldList collection for the connection associated with the ECLPS object.

Prototype

ULONG GetStartCol()

Parameters

None

Return Value

ULONG
This is the starting column of a given field.

Example

/-------------------------------------------------------------------
// ECLField::GetStartCol
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)
      Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(),
      pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetEnd

This method returns the position in the presentation space of the last character of the field. There are two signatures for the GetEnd method. ULONG GetEnd returns the position as a linear value with the upper left corner of the presentation space being "1". void GetEnd(ULONG *Row, ULONG *Col) returns the position as a row and column coordinate.

Prototype

ULONG GetEnd()

void GetEnd(ULONG *Row, ULONG *Col)

Parameters

ULONG *Row
This output parameter is a pointer to the row value to be updated.
ULONG *Col
This output parameter is a pointer to the column value to be updated.

Return Value

ULONG
Position in the presentation space represented as a linear array.

Example

The following example shows how to return the position in the presentation space of the last character of the field.

/-------------------------------------------------------------------
// ECLField::GetEnd
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)
     Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(),
      pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetEndRow

This method returns the ending row position of the field.

Prototype

ULONG GetEndRow()

Parameters

None

Return Value

ULONG
This is the ending row in a given field.

Example

/-------------------------------------------------------------------
// ECLField::GetEndRow
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)
     Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(),
      pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetEndCol

This method returns the ending column position of a field.

Prototype

ULONG GetEndCol()

Parameters

None

Return Value

ULONG
This is the ending row in a given field.

Example

/-------------------------------------------------------------------
// ECLField::GetEndCol
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)
     Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(),
      pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetLength

This method returns the length of the field. The length includes the entire field even if it spans multiple lines of the presentation space. It does not include the field attribute character that starts the field.

Prototype

ULONG GetLength()

Parameters

None

Return Value

ULONG
Length of the field.

Example

The following example shows how to return the length of the field.

/-------------------------------------------------------------------
// ECLField::GetLength
//
// Iterate over list of fields and print each field
// starting pos, row, col, and ending pos, row, col.
//-------------------------------------------------------------------
void Sample34() {
 
ECLPS        *pPS;           // Pointer to PS object
ECLFieldList *pFieldList;    // Pointer to field list object
ECLField     *pField;        // Pointer to field object
 
try {
  pPS = new ECLPS('A');                // Create PS object for 'A'
 
  pFieldList = pPS->GetFieldList();    // Get pointer to field list
  pFieldList->Refresh();               // Build the field list
 
  printf("Start(Pos,Row,Col)  End(Pos,Row,Col) Length(Len)\n");
  for (pField = pFieldList->GetFirstField();      // First field
    pField != NULL;                               // While more
    pField = pFieldList->GetNextField(pField)) {  // Next field
 
    printf("Start(%04lu,%04lu,%04lu)  End(%04lu,%03lu,%04lu)  Length(%04lu)\n",
      pField->GetStart(), pField->GetStartRow(), pField->GetStartCol(),
      pField->GetEnd(), pField->GetEndRow(),
      pField->GetEndCol(), pField->GetLength());
  }
  delete pPS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetScreen

The GetScreen method fills an application-supplied buffer with data from the field. The type of data copied to the buffer is selected with the optional Plane parameter. The default is to return the text plane data. The data returned is the field as it existed at the time this field object was created; it will not reflect the current contents of the field if it has been updated since the ECLFieldList::Refresh function was called.

The length of the data returned is the length of the field (see GetLength). When the TextPlane is copied, an additional null terminating byte is added after the last data byte. Therefore, the application should provide a buffer that is at least 1 byte more than the field length when getting the text plane. If the application buffer is too small the returned data is truncated. The number of bytes of copied to the application buffer is returned as the function result (not including the null terminator for copies of the text plane).

The FieldPlane cannot be obtained with this function. The ECLField::GetAttribute can be used to obtain the field attribute value.

Prototype

ULONG GetScreen(char *Buff, ULONG BuffLen, PS_PLANE Plane=TextPlane)

Parameters

char * Buff
Pointer to application buffer to be filled with field data.
ULONG BuffLen
Length of application buffer.
PS_PLANE Plane
Optional parameter. Enumeration which indicates what plane of field data is to be retrieved. Must be one of TextPlane, ColorPlane, or ExtendedFieldPlane.

Return Value

ULONG
Number of bytes copied to application buffer, not including trailing null character for TextPlane data.

Example

The following example shows how to return a pointer to the field data indicated by the Plane parameter.

/-------------------------------------------------------------------
// ECLField::GetScreen
//
// Iterate over list of fields and print each fields text contents.
//-------------------------------------------------------------------
void Sample35() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
char         *Buff;         // Screen data buffer
ULONG        BuffLen;
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  BuffLen = PS->GetSize() + 1;        // Make big enough for entire screen
  Buff = new char[BuffLen];           // Allocate screen buffer
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  for (Field = FieldList->GetFirstField();     // First field
    Field != NULL;                             // While more
    Field = FieldList->GetNextField(Field)) {  // Next field
 
      Field->GetScreen(Buff, BuffLen); // Get this fields text
      printf("%02lu,%02lu: %s\n",      // Print "row,col: text"
             Field->GetStartRow(),
             Field->GetStartCol(),
             Buff);
  }
  delete []Buff;
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

SetText

This method populates a given field in the presentation space with the character string passed in as text. If the text exceeds the length of the field, the text is truncated. If the text is shorter than the field, the field is padded with nulls.

Prototype

void SetText(char *text)

Parameters

char *text
Null terminated string to set in field.

Return Value

None

Example

The following example shows how to populate a given field in the presentation space with the character string passed in as text.

//-------------------------------------------------------------------
// ECLField::SetText
//
// Set the field that contains row 2, column 10 to a value.
//-------------------------------------------------------------------
void Sample36() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  // If the field at row 2 col 10 is an input field, set
  // it to a new value.
  Field = FieldList->FindField(2, 10);    // Find field at this location
  if (Field != NULL) {
    if (!Field->IsProtected())            // Make sure its an input field
      Field->SetText("Way cool!");        // Assign new field text
    else
      printf("Position 2,10 is protected.\n");
  }
  else printf("Cannot find field at position 2,10.\n");
 
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

IsModified, IsProtected, IsNumeric, IsHighIntensity, IsPenDetectable, IsDisplay

This method determines if a given field in the presentation space has a particular attribute. The method returns a TRUE value if the field has the attribute or a FALSE value if the field does not have the attribute.

Prototype

BOOL IsModified()

BOOL IsProtected()

BOOL IsNumeric()

BOOL IsHighIntensity()

BOOL IsPenDetectable()

BOOL IsDisplay()

Parameters

None

Return Value

BOOL
Returns a TRUE value if the attribute is present; a FALSE value if the attribute is not present.

Example

The following example shows how to determine if a given field has an attribute.

//-------------------------------------------------------------------
// ECLField::IsModified
// ECLField::IsProtected
// ECLField::IsNumeric
// ECLField::IsHighIntensity
// ECLField::IsPenDetectable
// ECLField::IsDisplay
//
// Iterate over list of fields and print each fields attributes.
//-------------------------------------------------------------------
void Sample37() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  for (Field = FieldList->GetFirstField();     // First field
    Field != NULL;                             // While more
    Field = FieldList->GetNextField(Field)) {  // Next field
 
      printf("Field at %02lu,%02lu is: ",
             Field->GetStartRow(), Field->GetStartCol());
 
      if (Field->IsProtected())
        printf("Protect ");
      else
        printf("Input   ");
 
      if (Field->IsModified())
        printf("Modified   ");
      else
        printf("Unmodified ");
 
      if (Field->IsNumeric())
        printf("Numeric  ");
      else
        printf("Alphanum ");
 
      if (Field->IsHighIntensity())
        printf("HiIntensity ");
      else
        printf("Normal      ");
 
      if (Field->IsPenDetectable())
        printf("Penable ");
      else
        printf("NoPen   ");
 
      if (Field->IsDisplay())
        printf("Display \n");
      else
        printf("Hidden  \n");
  }
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
//-------------------------------------------------------------------

GetAttribute

This method returns the attribute of the field. The value returned contains the bit flags for each of the possible field attributes (modified, protected, numeric, high intensity, pen, and display). See Appendix B. ECL Planes -- Format and Content for more details on these bits. There is a method provided for each type of attribute (for example, IsModified or IsHighIntensity). This method can be used to obtain complete attribute information in a single call.

Prototype

unsigned char GetAttribute()

Parameters

None

Return Value

unsigned char
Attribute bits of the field.

Example

The following example shows how to return the attribute of the field.

/ ECLField::GetAttribute
//
// Iterate over list of fields and print each fields attribute
// value.
//-------------------------------------------------------------------
void Sample38() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  for (Field = FieldList->GetFirstField();     // First field
    Field != NULL;                             // While more
    Field = FieldList->GetNextField(Field)) {  // Next field
 
      printf("Attribute value for field at %02lu,%02lu is: 0x%02x\n",
             Field->GetStartRow(), Field->GetStartCol(),
             Field->GetAttribute());
  }
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

ECLFieldList Class

The ECLFieldList class performs operations on a list of fields in a host presentation space. An application should not create an ECLFieldList object directly, but only indirectly by creating an ECLPS object.

ECLFieldList contains a collection of all the fields in the presentation space. Each element of the collection is an ECLField object. See ECLField Class for details on its properties and methods.

An ECLFieldList object provides a static snapshot of what the presentation space contained when the Refresh method was called. If the presentation space is updated after the call to Refresh(), the field list does not reflect those changes. An application must explicitly call Refresh to refresh the field list.

Once an application has called Refresh it can begin walking through the collection of fields using GetFirstField and GetNextField. If the location of a field is known, FindField can be used to locate it in the list directly.

Note:
All ECLField object pointers returned by GetFirstField, GetNextField, and FindField become invalid when Refresh is called or the ECLFieldList object is destroyed.

Derivation

ECLBase > ECLFieldList

Properties

None

ECLFieldList Methods

The following section describes the methods that are valid for the ECLFieldList class.

void Refresh(PS_PLANE Planes)
ULONG GetFieldCount()
ECLField * GetFirstField()
ECLField *GetNextField(ECLField *Prev)
ECLField * FindField(ULONG Pos)
ECLField * FindField(ULONG Row, ULONG Col)
ECLField *FindField(char* text, PS_DIR DIR=SrchForward);
ECLField *FindField(char* text, ULONG Pos, PS_DIR DIR=SrchForward);
ECLField *FindField(char* text, ULONG Row, ULONG Col, PS_DIR DIR=SrchForward);

Refresh

This method gets a snapshot of all the fields currently in the presentation space. All ECLField object pointers previously returned by this object become invalid. To improve performance, the field data can be limited to the planes of interest. Note that the TextPlane and FieldPlane are always obtained.

Prototype

void Refresh(PS_PLANE Planes=TextPlane)

Parameters

PS_PLANE Planes
Plane for which fields are built. Valid values are TextPlane, ColorPlane, FieldPlane, ExfieldPlane, and AllPlanes (to build for all). This is an enumeration defined in ECLPS.HPP. This optional parameter defaults to TextPlane.

Return Value

None

Example

The following example shows how to use the Refresh method to get a snapshot of all the fields currently in the presentation space.

///-------------------------------------------------------------------
// ECLFieldList::Refresh
//
// Display number of fields on the screen.
//-------------------------------------------------------------------
void Sample39() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  printf("There are %lu fields on the screen of connection %c.\n",
    FieldList->GetFieldCount(), PS->GetName());
 
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
----------------------------------------

GetFieldCount

This method returns the number of fields present in the ECLFieldList collection (based on the most recent call to the Refresh method).

Prototype

ULONG GetFieldCount()

Parameters

None

Return Value

ULONG
Number of fields in the ECLFieldList collection.

Example

The following example shows how to use the GetFieldCount method to return the number of fields present in the ECLFieldList collection.

//-------------------------------------------------------------------
// ECLFieldList::GetFieldCount
//
// Display number of fields on the screen.
//-------------------------------------------------------------------
void Sample40() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  printf("There are %lu fields on the screen of connection %c.\n",
    FieldList->GetFieldCount(), PS->GetName());
 
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetFirstField

This method returns a pointer to the first ECLField object in the collection. ECLFieldList contains a collection of ECLField objects. See ECLField Class for more information. The method returns a NULL pointer if there are no fields in the collection.

Prototype

ECLField * GetFirstField();

Parameters

None

Return Value

ECLField *
Pointer to an ECLField object. If there are no fields in the connection, a null is returned.

Example

The following example shows how to use the GetFirstField method to return a pointer to the first ECLField object in the collection.

/-------------------------------------------------------------------
// ECLFieldList::GetFirstField
//
// Display starting position of every input (unprotected) field.
//-------------------------------------------------------------------
void Sample41() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  // Interate over (only) unprotected fields
  printf("List of input fields:\n");
  for (Field = FieldList->GetFirstField(GetUnprotected);
    Field != NULL;
    Field = FieldList->GetNextField(Field, GetUnprotected)) {
 
    printf("Input field starts at %02lu,%02lu\n",
            Field->GetStartRow(), Field->GetStartCol());
  }
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetNextField

This method returns the next ECLField object in the collection after a given object. If there are no more objects in the collection after the given object, a NULL pointer is returned. An application can make repeated calls to this method to iterate over the ECLField objects in the collection.

Prototype

ECLField *GetNextField(ECLField *Prev)

Parameters

ECLField *Prev
A pointer to any ECLField object in the collection. The returned pointer will be the next object after this one. If this value is NULL a pointer to the first object in the collection is returned. This pointer is a pointer returned by the GetFirstField, GetNextField, or FindField member functions.

Return Value

ECLField *
A pointer to the next object in the collection. If there are no more objects in the collection after the Prev object, NULL is returned.

Example

The following example shows how to use the GetNextFieldInfo method to return a pointer to the next ECLField object in the collection.

///-------------------------------------------------------------------
// ECLFieldList::GetNextField
//
// Display starting position of every input (unprotected) field.
//-------------------------------------------------------------------
void Sample42() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  // Interate over (only) unprotected fields
  printf("List of input fields:\n");
  for (Field = FieldList->GetFirstField(GetUnprotected);
    Field != NULL;
    Field = FieldList->GetNextField(Field, GetUnprotected)) {
 
    printf("Input field starts at %02lu,%02lu\n",
            Field->GetStartRow(), Field->GetStartCol());
  }
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

FindField

This method finds a field in the ECLFieldList collection using either text or a position. The position can be either a linear position or a row, column position. If a field contains the text or the position, a pointer to an ECLField object for that field is returned. The returned pointer is to an object in the field list collection. NULL is returned if the field is not found. When searching for text, the search begins at row1 column1 unless you specify a starting position. Also for text, this method will search forward in the list as a default; however, you can specify the direction to search explicitly.

Note:
A search for text will be successful even if the text spans multiple fields. The field object returned will be the field where the found text begins.

Prototype

Parameters

ULONG Pos
Linear position to search for OR linear position to begin text search.
ULONG Row
Row position to search for OR row to begin text search.
ULONG Col
Column position to search for OR column to begin text search.
char *text
String to search
PS_DIR Dir
Direction to search

Return Value

ECLField *
Pointer to an ECLField object if field is found. NULL if field is not found. Returned pointer is invalid after the next call to Refresh.

Example

The following is an example of the FindField method.

//-------------------------------------------------------------------
// ECLFieldList::FindField
//
// Display the field which contains row 2 column 10.  Also find
// the first field containing a particular string.
//-------------------------------------------------------------------
void Sample43() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
ECLField     *Field;        // Pointer to field object
char         Buff[4000];
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  // Find by row,column coordinate
 
  Field = FieldList->FindField(2, 10);
  if (Field != NULL) {
    Field->GetText(Buff, sizeof(Buff));
    printf("Field at 2,10: %s\n", Buff);
  }
  else printf("No field found at 2,10.\n");
 
  // Find by text.  Note that text may span fields, this
  // will find the field in which the text starts.
 
  Field = FieldList->FindField("HCL");
  if (Field != NULL) {
    printf("String 'HCL' found in field that starts at %lu,%lu.\n",
            Field->GetStartRow(), Field->GetStartCol());
  }
  else printf("String 'HCL' not found.\n");
 
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
//---------------------------

ECLKeyNotify Class

ECLKeyNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLKeyNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLKeyNotify class is used to allow an application to be notified of keystroke events. The application can also choose to filter (remove) the keystrokes so they are not sent to the host screen, or replace them with other keystrokes. Keystroke notifications are queued so that the application will always receive a notification for each and every keystroke. Only keystrokes made by the real physical keyboard are detected by this object; keystrokes sent to the host by other ECL objects (such as ECLPS::SendKeys) do not cause keystroke notification events.

To be notified of keystroke events, the application must perform the following steps:

  1. Define a class derived from ECLKeyNotify.
  2. Implement the derived class and implement the NotifyEvent() member function.
  3. Optionally implement the NotifyError() and/or NotifyStop() functions.
  4. Create an instance of the derived class.
  5. Register the instance with the ECLPS::RegisterKeyEvent() function.

The example shown demonstrates how this may be done. When the above steps are complete, each keystroke in the emulator window will cause the applications NotifyEvent() member function to be called. The function is passed parameters indicating the type of keystroke (plain ASCII key, or special function key), and the value of the key (a single ASCII character, or a keyword representing a function key). The application may perform any functions required in the NotifyEvent() procedure, including calling other ECL functions such as ECLPS::SendKeys(). The application returns a value from NotifyEvent() to indicate if the keystroke is to be filtered or not (return 1 to filter (discard) the keystroke, return 0 to have it processed normally).

If an error is detected during keystroke event generation, the NotifyError() member function is called with an ECLErr object. Keystroke events may or may not continue to be generated after an error, depending on the nature of the error. When event generation terminates (either due to an error, by calling ECLPS::UnregisterKeyEvent, or by destruction of the ECLPS object) the NotifyStop() member function is called. However event notification is terminated, the NotifyStop() member function is always called, and the application object is unregistered.

If the application does not provide an implementation of the NotifyError() member function, the default implementation is used (a simple message box is displayed to the user). The application can override the default behavior by implementing the NotifyError() function in the applications derived class. Likewise, the default NotifyStop() function is used if the application does not provide this function (the default behavior is to do nothing).

Note that the application can also choose to provide its own constructor and destructor for the derived class. This can be useful if the application wants to store some instance-specific data in the class and pass that information as a parameter on the constructor. For example, the application may want to post a message to an application window when a keystroke occurs. Rather than define the window handle as a global variable (so it would be visible to the NotifyEvent() function), the application can define a constructor for the class which takes the window handle and stores it in the class member data area.

The application must not destroy the notification object while it is registered to receive events.

The same instance of a keystroke notification object can be registered with multiple ECLPS objects to receive keystrokes for multiple connections. Thus an application can use a single instance of this object to process keystrokes on any number of sessions. The member functions are passed a pointer to the ECLPS object for which the event occurred so an application can distinguish between events on different connections. The sample shown uses the same object to process keystrokes on two connections.

Implementation Restriction: Currently the ECLPS object allows only one notification object to be registered for a given connection. The ECLPS::RegisterKeyEvent will throw an error if a notify object is already registered for that ECLPS object.

Derivation

ECLBase > ECLNotify > ECLKeyNotify

Example

The following is an example of how to construct and use an ECLKeyNotify object.

// ECLKeyNotify class
//
// This sample demonstrates the use of:
//
// ECLKeyNotify::NotifyEvent
// ECLKeyNotify::NotifyError
// ECLKeyNotify::NotifyStop
// ECLPS::RegisterKeyEvent
// ECLPS::UnregisterKeyEvent
//-------------------------------------------------------------------
 
//...................................................................
// Define a class derived from ECLKeyNotify
//...................................................................
class MyKeyNotify: public ECLKeyNotify
{
public:
  // Define my own constructor to store instance data
  MyKeyNotify(HANDLE DataHandle);
 
  // We have to implement this function
  virtual int NotifyEvent(ECLPS *PSObj, char const KeyType[2],
                          const char * const KeyString);
 
  // We choose to implement this function
  void NotifyStop (ECLPS *PSObj, int Reason);
 
  // We will take the default behaviour for this so we
  // don't implement it in our class:
  // void NotifyError (ECLPS *PSObj, ECLErr ErrObject);
 
private:
  // We will store our application data handle here
  HANDLE MyDataH;
};
 
 //..................................................................
MyKeyNotify::MyKeyNotify(HANDLE DataHandle)   // Constructor
//...................................................................
{
  MyDataH = DataHandle;  // Save data handle for later use
}
 
//...................................................................
int MyKeyNotify::NotifyEvent(ECLPS *PSObj,
                             char const KeyType[2],
                             const char * const KeyString)
//...................................................................
 
{
  // This function is called whenever a keystroke occurs.  We will
  // just do something simple: when the user presses PF1 we will
  // send a PF2 to the host instead.  All other keys will be unchanged.
 
  if (KeyType[0] == 'M') {             // Is this a mnemonic keyword?
    if (!strcmp(KeyString, "[pf1]")) { // Is it a PF1 key?
      PSObj->SendKeys("[pf2]");        // Send PF2 instead
      printf("Changed PF1 to PF2 on connection %c.\n",
             PSObj->GetName());
      return 1;                        // Discard this PF1 key
    }
  }
 
  return 0;                            // Process key normally
}
 
 
//..................................................................
void MyKeyNotify::NotifyStop (ECLPS *PSObj, int Reason)
//...................................................................
{
  // When notification ends, display message
  printf("Keystroke intercept for connection %c stopped.\n", PSObj->GetName());
}
 
//...................................................................
// Create the class and start keystroke processing on A and B.
//...................................................................
void Sample44() {
 
ECLPS *PSA, *PSB;       // PS objects
MyKeyNotify *Event;     // Ptr to my event handling object
HANDLE InstData;	    	// Handle to application data block (for example)
 
try {
 
  PSA = new ECLPS('A');               // Create PS objects
  PSB = new ECLPS('B');
  Event = new MyKeyNotify(InstData);  // Create event handler
 
  PSA->RegisterKeyEvent(Event);       // Register for keystroke events
  PSB->RegisterKeyEvent(Event);       // Register for keystroke events
 
  // At this point, any keystrokes on A or B will cause the
  // MyKeyEvent::NotifyEvent() function to execute.  For
  // this sample, we put this thread to sleep during this
  // time.
 
  printf("Processing keystrokes for 60 seconds on A and B...\n");
  Sleep(60000);
 
  // Now stop event generation.  This will cause the NotifyStop
  // member to be called.
  PSA->UnregisterKeyEvent(Event);
  PSB->UnregisterKeyEvent(Event);
 
  delete Event;  // Don't delete until after unregister!
  delete PSA;
  delete PSB;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
//-------------------------------------------------------------------

ECLKeyNotify Methods

The following section describes the methods that are valid for the ECLKeyNotify class.

virtual int NotifyEvent (ECLPS *PSObj, char const KeyType [2],
      const char * const KeyString ) =0
virtual void NotifyError (ELLPS *PSobj, ECLErr ErrObject)
virtual void NotifyStop (ELLPS *PSObj, int Reason)

NotifyEvent

This method is a"pure virtual" member function (the application must implement this function in classes derived from ECLKeyNotify). This function is called whenever a keystroke event occurs and the object is registered for keystroke events. The return value indicates the disposition of the keystroke (return 1 to discard, 0 to process).

Prototype

virtual int NotifyEvent (ECLPS *PSObj, char const KeyType [2], const char * const KeyString ) =0

Parameters

ECLPS *PSObj
This is a ptr to ECLPS object in which the event occurred.
char const KeyType[2]
This is a null terminated 1-char string indicating the type of key:
       A = Plain ASCII keystroke
       M = Mnemonic keyword

const char * const KeyString
This is a null terminated string containing the keystroke or mnemonic keyword. Keywords will always be in lowercase (for example, "[enter]"). See Appendix A. Sendkeys Mnemonic Keywords for a list of mnemonic keywords.

Return Value

int
This is the filter indicator.
            1 = Filter (discard) keystroke
            0 = Process keystroke (send to host)

NotifyError

This method is called whenever the ECLPS object detects an error during keystroke event generation. The error object contains information about the error (see ECLErr Class). Keystroke events may continue to be generated after the error, depending on the nature of the error. If keystroke event generation stops due to an error, the NotifyStop() function will be called.

Prototype

virtual void NotifyError (ELLPS *PSobj, ECLErr ErrObject)

Parameters

ECLPS *PSObj
This is the ptr to ECLPS object in which the error occurred.
ECLErr ErrObject
This is the ECLErr object describing the error.

Return Value

None

NotifyStop

This method is called when keystroke event generation is stopped for any reason (for example, due to an error condition, a call to ECLPS::UnregisterKeyEvent, destruction of the ECLPS object, etc.).

Prototype

virtual void NotifyStop (ELLPS *PSObj, int Reason)

Parameters

ECLPS *PSObj
This is the ptr to ECLPS object in which events are stopping.
int Reason
This is unused (zero).

Return Value

None

ECLListener Class

ECLListener is the base class for all HACL "listener" objects. Listeners are objects which are registered to receive particular types of asynchronous events. Methods on the listener objects are called when events occur or errors are detected.

There are no public methods on the ECLListener class.

Derivation

ECLBase > ECLListener

Usage Notes

Applications do not use this class directly, but create instances of classes which are derived from it (for example, ECLPSListener).

ECLOIA Class

ECLOIA provides Operator Information Area (OIA) services.

Because ECLOIA is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

The ECLOIA object is created for the connection identified upon construction. You may create an ECLOIA object by passing either the connection name (a single, alphabetic character from A-Z or a-z) or the connection handle, which is usually obtained from the ECLConnList object. There can be only one Z and I Emulator for Windows connection with a given name or handle open at a time.

Derivation

ECLBase > ECLConnection > ECLOIA

Usage Notes

The ECLSession class creates an instance of this object. If the application does not need other services, this object may be created directly. Otherwise, consider using an ECLSession object to create all the objects needed.

ECLOIA Methods

The following section describes the methods that are valid for the ECLOIA class.

ECLOIA(char ConnName)
ECLOIA(long ConnHandle)
~ECLOIA()
BOOL IsAlphanumeric()
BOOL IsAPL()

BOOL IsUpperShift()
BOOL IsNumeric()
BOOL IsCapsLock()
BOOL IsInsertMode()
BOOL IsCommErrorReminder()
BOOL IsMessageWaiting()
BOOL WaitForInputReady( long nTimeOut = INFINITE )
BOOL WaitForAppAvailable( long nTimeOut = INFINITE )
BOOL WaitForSystemAvailable( long nTimeOut = INFINITE )
BOOL WaitForTransition( BYTE nIndex = 0xFF, long nTimeOut = INFINITE )
INHIBIT_REASON InputInhibited()
ULONG GetStatusFlags()

ECLOIA Constructor

This method creates an ECLOIA object from a connection name (a single, alphabetic character from A-Z or a-z) or a connection handle. There can be only one Z and I Emulator for Windows connection started with a given name.

Prototype

ECLOIA(char ConnName)

ECLOIA(long ConnHandle)

Parameters

char ConnName
One-character short name of the connection (A-Z or a-z).
long ConnHandle
Handle of an ECL connection.

Return Value

None

Example

The following example shows how to create an ECLOIA object using the connection name.

// ECLOIA::ECLOIA              (Constructor)
//
// Build an OIA object from a name, and another from a handle.
//-------------------------------------------------------------------
void Sample45() {
 
ECLOIA *OIA1, *OIA2;    // Pointer to OIA objects
ECLConnList ConnList;   // Connection list object
 
try {
  // Create OIA object for connection 'A'
  OIA1 = new ECLOIA('A');
 
  // Create OIA object for first connection in conn list
  OIA2 = new ECLOIA(ConnList.GetFirstConnection()->GetHandle());
 
  printf("OIA #1 is for connection %c, OIA #2 is for connection %c.\n",
         OIA1->GetName(), OIA2->GetName());
  delete OIA1;
  delete OIA2;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
-------------------------------------------

IsAlphanumeric

This method checks to determine if the OIA indicates that the cursor is at an alphanumeric location.

Prototype

BOOL IsAlphanumeric()

Parameters

None

Return Value

BOOL
TRUE if the keyboard is in alphanumeric mode; FALSE if the keyboard is not in alphanumeric mode.

Example

The following example shows how to determine if the OIA indicates that the keyboard is in alphanumeric mode.

//-------------------------------------------------------------------
// ECLOIA::IsAlphanumeric
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample46() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsAlphanumeric())
  printf("Alphanumeric.\n");
else
  printf("Not Alphanumeric.\n");
 
} // end sample
 

IsAPL

This method checks to determine if the OIA indicates that the keyboard is in APL mode.

Prototype

BOOL IsAPL()

Parameters

None

Return Value

BOOL
TRUE if the keyboard is in APL mode; FALSE if the keyboard is not in APL mode.

Example

The following example shows how to determine if the OIA indicates that the keyboard is in APL mode.

//-------------------------------------------------------------------
// ECLOIA::IsAPL
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample47() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsAPL())
  printf("APL.\n");
else
  printf("Not APL.\n");
 
} // end sample
 
//------------------------

IsUpperShift

This method checks to determine if the OIA indicates that the keyboard is in upper shift mode.

Prototype

BOOL IsUpperShift()

Parameters

None

Return Value

BOOL
TRUE if the keyboard is in upper shift mode; FALSE if the keyboard is not in upper shift mode.

Example

The following example shows how to determine if the OIA indicates that the keyboard is in upper shift mode.

//-------------------------------------------------------------------
// ECLOIA::IsUpperShift
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample51() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsUpperShift())
  printf("UpperShift.\n");
else
  printf("Not UpperShift.\n");
 
} // end sample
 

IsNumeric

This method checks to determine if the OIA indicates that the cursor is at a numeric-only location.

Prototype

BOOL IsNumLock()

Parameters

None

Return Value

BOOL
TRUE if Numeric is on; FALSE if not Numeric.

Example

The following example shows how to determine if the OIA indicates that the cursor is at a numeric location.

//-------------------------------------------------------------------
// ECLOIA::IsNumeric
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample52() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsNumeric())
  printf("Numeric.\n");
else
  printf("Not Numeric.\n");
 
} // end sample
 

IsCapsLock

This method checks to determine if the OIA indicates that the keyboard has Caps Lock on.

Prototype

BOOL IsCapsLock()

Parameters

None

Return Value

BOOL
TRUE if Caps Lock is on; FALSE if Caps Lock is not on.

Example

The following example shows how to determine if the OIA indicates that the keyboard has Caps Lock on.

//-------------------------------------------------------------------
// ECLOIA::IsCapsLock
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample53() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsCapsLock())
  printf("CapsLock.\n");
else
  printf("Not CapsLock.\n");
 
} // end sample
 

IsInsertMode

This method checks to determine if the OIA indicates that the keyboard is in insert mode.

Prototype

BOOL IsInsertMode()

Parameters

None

Return Value

BOOL
TRUE if the keyboard is in insert mode; FALSE if the keyboard is not in insert mode.

Example

The following example shows how to determine if the OIA indicates that the keyboard is in insert mode.

//-------------------------------------------------------------------
// ECLOIA::IsInsertMode
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample54() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsInsertMode())
  printf("InsertMode.\n");
else
  printf("Not InsertMode.\n");
 
} // end sample
 

IsCommErrorReminder

This method checks to determine if the OIA indicates that a communications error reminder condition exists.

Prototype

BOOL IsCommErrorReminder()

Parameters

None

Return Value

BOOL
TRUE if a condition exists; FALSE if a condition does not exist.

Example

The following example shows how to determine if the OIA indicates that a communications error reminder condition exists.

//-------------------------------------------------------------------
// ECLOIA::IsCommErrorReminder
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample55() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsCommErrorReminder())
  printf("CommErrorReminder.\n");
else
  printf("Not CommErrorReminder.\n");
 
} // end sample
 
//

IsMessageWaiting

This method checks to determine if the OIA indicates that the message waiting indicator is on. This can only occur for 5250 connections.

Prototype

BOOL IsMessageWaiting()

Parameters

None

Return Value

BOOL
TRUE if the message waiting indicator is on; FALSE if the indicator is not on.

Example

The following example shows how to determine if the OIA indicates that the message waiting indicator is on.

-------------------------------------------------------------------
// ECLOIA::IsMessageWaiting
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample56() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
if (OIA.IsMessageWaiting())
  printf("MessageWaiting.\n");
else
  printf("Not MessageWaiting.\n");
 
} // end sample
 

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

BOOL WaitForInputReady( long nTimeOut = INFINITE )

Parameters

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

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

WaitForSystemAvailable

The WaitForSystemAvailable method waits until the OIA of the session connected with the ECLOIA object indicates that session is connected to a host system.

Prototype

BOOL WaitForSystemAvailable( long nTimeOut = INFINITE )

Parameters

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

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

WaitForAppAvailable

The WaitForAppAvailable method waits while the OIA of the connected session indicates that the application is initialized and ready for use.

Prototype

BOOL WaitForAppAvailable( long nTimeOut = INFINITE )

Parameters

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

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

WaitForTransition

The WaitForTransition method waits for the value at the specified position in the OIA of the connected session to change.

Prototype

BOOL WaitForTransition( BYTE nIndex = 0xFF, long nTimeOut = INFINITE )

Parameters

BYTE nIndex
The 1 byte Hex position of the OIA to monitor. This parameter is optional. The default is 3.
long nTimeOut
The maximum length of time to wait in milliseconds, this parameter is optional. The default is INFINITE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

InputInhibited

This method returns an enumerated value that indicates whether input is inhibited or not. If input is inhibited, the reason for the inhibit can be determined. If input is inhibited for more than one reason the highest value enumeration is returned (for example, if there is a communications error and a protocol programming error, the ProgCheck value is returned).

Prototype

INHIBIT_REASON InputInhibited ()

Parameters

None

Return Value

INHIBIT_REASON
Returns one of the INHIBIT_REASON values as defined in ECLOIA.HPP. The value NotInhibited is returned if input is currently not inhibited.

Example

The following example shows how to determine whether input is inhibited or not.

//-------------------------------------------------------------------
// ECLOIA::InputInhibited
//
// Determine status of connection 'A' OIA indicator
//-------------------------------------------------------------------
void Sample57() {
 
ECLOIA OIA('A');   // OIA object for connection A
 
switch (OIA.InputInhibited()) {
case NotInhibited:
  printf("Input not inhibited.\n");
  break;
case SystemWait:
  printf("Input inhibited for SystemWait.\n");
  break;
case CommCheck:
  printf("Input inhibited for CommCheck.\n");
  break;
case ProgCheck:
  printf("Input inhibited for ProgCheck.\n");
  break;
case MachCheck:
  printf("Input inhibited for MachCheck.\n");
  break;
case OtherInhibit:
  printf("Input inhibited for OtherInhibit.\n");
  break;
default:
  printf("Input inhibited for unknown reason.\n");
  break;
}
} // end sample
 

GetStatusFlags

This method returns a set of status bits that represent various OIA indicators. This method can be used to collect a set of OIA indicators in a single call rather than making calls to several different IsXXX methods. Each bit returned represents a single OIA indicator where a value of 1 means the indicator is on (TRUE), and 0 means it is off (FALSE). A set of bitmask constants are defined in the ECLOIA.HPP header file for isolating individual indicators in the returned 32-bit value.

Prototype

ULONG GetStatusFlags()

Parameters

None

Return Value

ULONG
Set of bit flags defined as follows:
Bit Position Mask Constant Description
31 (msb) OIAFLAG_ALPHANUM IsAlphanumeric
30 OIAFLAG_APL IsAPL
26 OIAFLAG_UPSHIFT IsUpperShift
25 OIAFLAG_NUMERIC IsNumeric
24 OIAFLAG_CAPSLOCK IsCapsLock
23 OIAFLAG_INSERT IsInsertMode
22 OIAFLAG_COMMERR IsCommErrorReminder
21 OIAFLAG_MSGWAIT IsMessageWaiting
20 OIAFLAG_ENCRYPTED IsConnectionEncrypted
19-4 <reserved>
3-0 OIAFLAG_INHIBMASK InputInhibited:
  • 0=NotInhibited
  • 1=SystemWait
  • 2=CommCheck
  • 3=ProgCheck
  • 4=MachCheck
  • 5=OtherInhibit

RegisterOIAEvent

This member function registers an application object to receive notifications of OIA update events. To use this function the application must create an object derived from ECLOIANotify. A pointer to that object is then passed to this registration function. Any number of notify objects may be registered at the same time. The order in which multiple listeners receive events is not defined and should not be assumed.

After an ECLOIANotify object is registered with this function, its NotifyEvent() method will be called whenever a update to the OIA occurs. Multiple updates to the OIA in a short time period may be aggregated into a single event.

The application must unregister the notify object before destroying it. The object will automatically be unregistered if the ECLOIA object is destroyed.

Prototype

void RegisterOIAEvent(ECLOIANotify * notify)

Parameters

ECLOIANotify *
Pointer to the ECLOIANotify object to be registered.

Return Value

None

UnregisterOIAEvent

This member function unregisters an application object previously registered with the RegisterOIAEvent function. An object registered to receive events should not be destroyed without first calling this function to unregister it. If the specific object is not currently registered, no action is taken and no error occurs.

When an ECLOIANotify object is unregistered its NotifyStop() method is called.

Prototype

void UnregisterOIAEvent(ECLOIANotify * notify)

Parameters

ECLPSNotify *
Pointer to the ECLOIANotify object to be unregistered.

Return Value

None

ECLOIANotify Class

ECLOIANotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLOIANotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLOIANotify class is used to allow an application to be notified of updates to the Operator Information Area. Events are generated whenever any indicator on the OIA is updated.

Derivation

ECLBase > ECLNotify > ECLOIANotify

Usage Notes

To be notified of OIA updates using this class, the application must perform the following steps:

  1. Define a class derived from ECLOIANotify.
  2. Implement the NotifyEvent method of the ECLOIANotify-derived class.
  3. Optionally implement other member functions of ECLOIANotify.
  4. Create an instance of the derived class.
  5. Register the instance with the ECLOIA::RegisterOIAEvent() method.

After registration is complete, updates to the OIA indicators will cause the NotifyEvent() method of the ECLOIANotify-derived class to be called.

Note that multiple OIA updates which occur in a short period of time may be aggregated into a single event notification.

An application can choose to provide its own constructor and destructor for the derived class. This can be useful if the application needs to store some instance-specific data in the class and pass that information as a parameter on the constructor.

If an error is detected during event registration, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error. When event generation terminates (due to an error or some other reason) the NotifyStop() member function is called. The default implementation of NotifyError() will present a message box to the user showing the text of the error messages retrieved from the ECLErr object.

When event notification stops for any reason (error or a call the ECLOIA::UnregisterOIAEvent) the NotifyStop() member function is called. The default implementation of NotifyStop() does nothing.

ECLOIANotify Methods

The following section describes the methods that are valid for the ECLOIANotify class and all classes derived from it.

ECLOIANotify()
~ECLOIANotify()
virtual void NotifyEvent(ECLOIA * OIAObj) = 0
virtual void NotifyError(ECLOIA * OIAObj,  ECLErr ErrObj)
virtual void NotifyStop(ECLOIA * OIAObj, int Reason)

NotifyEvent

This method is a pure virtual member function (the application must implement this function in classes derived from ECLOIANotify). This method is called whenever the OIA is updated and this object is registered to receive update events.

Multiple OIA updates may be aggregated into a single event causing only a single call to this method.

Prototype

virtual void NotifyEvent(ECLOIA * OIAObj) = 0

Parameters

ECLOIA *
Pointer to the ECLOIA object which generated this event.

Return Value

None

NotifyError

This method is called whenever the ECLOIA object detects an error during event generation. The error object contains information about the error (see the ECLErr class description). Events may continue to be generated after the error depending on the nature of the error. If the event generation stops due to an error, the NotifyStop() method is called.

An application can choose to implement this function or allow the base ECLOIANotify class handle it. The default implementation will display the error in a message box using text supplied by the ECLErr::GetMsgText() method. If the application implements this function in its derived class it overrides this behavior.

Prototype

virtual void NotifyError(ECLOIA * OIAObj,  ECLErr ErrObj)

Parameters

ECLOIA *
Pointer to the ECLOIA object which generated this event.
ECLErr
An ECLErr object which describes the error.

Return Value

None

NotifyStop

This method is called when event generation is stopped for any reason (for example, due to an error condition or a call to ECLOIA::UnregisterOIAEvent).

The reason code parameter is currently unused and will be zero.

The default implementation of this function does nothing.

Prototype

virtual void NotifyStop(ECLOIA * OIAObj, int Reason)

Parameters

ECLOIA *
Pointer to the ECLOIA object which generated this event.
int
Reason event generation has stopped (currently unused and will be zero).

Return Value

None

ECLPS Class

The ECLPS class performs operations on a host presentation space.

The ECLPS object is created for the connection identified upon construction. You may create an ECLPS object by passing either the connection name (a single, alphabetic character from A-Z) or the connection handle, which is usually obtained from an ECLConnection object. There can be only one Z and I Emulator for Windows connection with a given name or handle open at a time.

Derivation

ECLBase > ECLConnection > ECLPS

Properties

None

Usage Notes

The ECLSession class creates an instance of this object. If the application does not need other services, this object may be created directly. Otherwise, you may want to consider using an ECLSession object to create all the objects needed.

ECLPS Methods

The following section describes the methods available for ECLPS.

ECLPS(char ConnName)
ECLPS(char ConnName)
ECLPS(long ConnHandle)
~ECLPS()
int GetPCCodePage()
int GetHostCodePage()
int GetOSCodePage()
void GetSize(ULONG *Rows, ULONG *Cols) ULONG GetSize()
ULONG GetSizeCols() ULONG GetSizeRows()
void GetCursorPos(ULONG *Row, ULONG *Col) ULONG GetCursorPos()
ULONG GetCursorPosRow()
ULONG GetCursorPosCol()
void SetCursorPos(ULONG pos),
void SetCursorPos(ULONG Row, ULONG Col)
void SendKeys(Char *text, ULONG AtPos),
void SendKeys(Char * text),
void SendKeys(Char *text, ULONG AtRow, ULONG AtCol)
ULONG SearchText(const char * const text, PS_DIR Dir=SrchForward,
      BOOL FoldCase=FALSE)
ULONG SearchText(const char * const text,
ULONG StartPos, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)
ULONG SearchText(const char char * const text, ULONG StartRow,
       ULONG StartCol, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)
ULONG GetScreen(char * Buff, ULONG BuffLen, PS_PLANE Plane=TextPlane)
ULONG GetScreen(char * Buff, ULONG BuffLen, ULONG StartPos,
       ULONG Length, PS_PLANE Plane=TextPlane)
ULONG GetScreen(char * Buff, ULONG BuffLen, ULONG StartRow,
       ULONG StartCol, ULONG Length, PS_PLANE Plane=TextPlane)
ULONG GetScreenRect(char * Buff, ULONG BuffLen, ULONG StartPos,
       ULONG EndPos, PS_PLANE Plane=TextPlane)  
ULONG StartCol, ULONG EndRow, ULONG EndCol,
ULONG GetScreenRect(char * Buff, ULONG BuffLen, ULONG StartRow,
       ULONG StartCol, ULONG EndRow, ULONG EndCol,
       PS_PLANE Plane=TextPlane)
void SetText(char *text);
void SetText(char *text, ULONG AtPos);
void SetText(char *text, ULONG AtRow, ULONG AtCol);
void CopyText ();
void CopyText (ULONG Long Len);
void CopyText (ULONG AtPos, ULONG Long Len);
void CopyText (ULONG AtRow, ULONG AtCol, ULONG Long Len );
void PasteText ();
void PasteText (ULONG Long Len);
void PasteText (ULONG AtPos, ULONG Long Len);
void PasteText (ULONG AtRow, ULONG AtCol, ULONG Long Len );
void ConvertPosToRowCol(ULONG pos, ULONG *row, ULONG *col)
ULONG ConvertRowColToPos(ULONG row, ULONG col)
ULONG ConvertPosToRow(ULONG Pos)
ULONG ConvertPosToCol(ULONG Pos)
void RegisterKeyEvent(ECLKeyNotify *NotifyObject)
virtual UnregisterKeyEvent(ECLKeyNotify *NotifyObject )
ECLFieldList *GetFieldList()
BOOL WaitForCursor(int Row, int Col, long nTimeOut=INFINITE,
       BOOL bWaitForIR=TRUE)
BOOL WaitWhileCursor(int Row, int Col, long nTimeOut=INFINITE,
       BOOL bWaitForIR=TRUE)
BOOL WaitForString(char* WaitString, int Row=0, int Col=0,
       long nTimeOut=INFINITE, BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)
BOOL WaitWhileString(char* WaitString, int Row=0, int Col=0,
       long nTimeOut=INFINITE, BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)
BOOL WaitForStringInRect(char* WaitString, int sRow, int sCol,
       int eRow,int eCol, long nTimeOut=INFINITE,
       BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)
BOOL WaitWhileStringInRect(char* WaitString, int sRow, int sCol,
       int eRow,int eCol, long nTimeOut=INFINITE, BOOL bWaitForIR=TRUE,
       BOOL bCaseSens=TRUE)
BOOL WaitForAttrib(int Row, int Col, unsigned char AttribDatum,
       unsigned char MskDatum = 0xFF, PS_PLANE plane = FieldPlane,
       long TimeOut = INFINITE, BOOL bWaitForIR = TRUE)
BOOL WaitWhileAttrib(int Row, int Col, unsigned char AttribDatum,
       unsigned char MskDatum = 0xFF, PS_PLANE plane = FieldPlane,
       long TimeOut = INFINITE, BOOL bWaitForIR = TRUE)
BOOL WaitForScreen(ECLScreenDesc* screenDesc, long TimeOut = INFINITE)
BOOL WaitWhileScreen(ECLScreenDesc* screenDesc, long TimeOut = INFINITE)
void RegisterPSEvent(ECLPSNotify * notify)
void RegisterPSEvent(ECLPSListener * listener)
void RegisterPSEvent(ECLPSListener * listener, int type)
void StartMacro(String MacroName)
void UnregisterPSEvent(ECLPSNotify * notify)
void UnregisterPSEvent(ECLPSListener * listener)
void UnregisterPSEvent(ECLPSListener * listener, int type)

The following methods are available for ECLPS :

void SendKeys(WCHAR * text),
void SendKeys(WCHAR *text, ULONG AtPos),
void SendKeys(WCHAR *text, ULONG AtRow, ULONG AtCol)
ULONG SearchText(const WCHAR * const text, PS_DIR Dir=SrchForward,
       BOOL FoldCase=FALSE)
ULONG SearchText(const WCHAR * const text,
       ULONG StartPos, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)
ULONG SearchText(const WCHAR * const text, ULONG StartRow,
       ULONG StartCol, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)
ULONG GetScreen(WCHAR * Buff, ULONG BuffLen, PS_PLANE Plane=TextPlane)
ULONG GetScreen(WCHAR * Buff, ULONG BuffLen, ULONG StartPos,
       ULONG Length, PS_PLANE Plane=TextPlane)
ULONG GetScreen(WCHAR * Buff, ULONG BuffLen, ULONG StartRow,
       ULONG StartCol, ULONG Length, PS_PLANE Plane=TextPlane)

ECLPS Constructor

This method uses a connection name or handle to create an ECLPS object.

Prototype

ECLPS(char ConnName)
ECLPS(long ConnHandle)

Parameters

char ConnName
One-character short name of the connection (A-Z or a-z).
long ConnHandle
Handle of an ECL connection.

Return Value

None

Example

The following example shows how to use a connection name to create an ECLPS object.

//-------------------------------------------------------------------
// ECLPS::ECLPS              (Constructor)
//
// Build a PS object from a name, and another from a handle.
//-------------------------------------------------------------------
void Sample58() {
 
ECLPS *PS1, *PS2;       // Pointer to PS objects
ECLConnList ConnList;   // Connection list object
 
try {
  // Create PS object for connection 'A'
  PS1 = new ECLPS('A');
 
  // Create PS object for first connection in conn list
  PS2 = new ECLPS(ConnList.GetFirstConnection()->GetHandle());
 
  printf("PS #1 is for connection %c, PS #2 is for connection %c.\n",
         PS1->GetName(), PS2->GetName());
  delete PS1;
  delete PS2;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 

ECLPS Destructor

This method destroys the ECLPS object.

Prototype

~ECLPS()

Parameters

None

Return Value

None

Example

The following example shows how to destroy an ECLPS object.

ULONG		RowPos, ColPos;
ECLPS		*pPS;
						
try {
      pPS = new ECLPS('A');
      RowPos = pPS->ConvertPosToRow(544);
      ColPos = pPS->ConvertPosToCol(544);
      printf("PS position is at row %lu column %lu.",
      RowPos, ColPos);
      // Done with PS object so kill it
      delete pPS;
}
catch (ECLErr HE) {
  // Just report the error text in a message box
  MessageBox( NULL, HE.GetMsgText(), "Error!", MB_OK );
}

GetPCCodePage

The GetPCCodePage method retrieves the number designating the code page in force for the personal computer.

Prototype

int GetPCCodePage()

Parameters

None

Return Value

int
Number of the code page.

GetHostCodePage

The GetHostCodePage method retrieves the number designating the code page in force for the host computer.

Prototype

int GetHostCodePage()

Parameters

None

Return Value

int
Number of the code page.

GetOSCodePage

The GetOSCodePage method retrieves the number designating the code page in force for the operating system on the personal computer.

Prototype

int GetOSCodePage()

Parameters

None

Return Value

int
Number of the code page.

GetSize

This method returns the size of the presentation space for the connection associated with the ECLPS object. There are two signatures of the GetSize method. Using ULONG GetSize(), the size is returned as a linear value and represents the total number of characters in the presentation space. With void GetSize(ULONG *Rows, ULONG *Cols), the number of rows and columns of the presentation space is returned.

Prototype

ULONG GetSize()

void GetSize(ULONG *Rows, ULONG *Cols)

Parameters

ULONG *Rows
This output parameter is the number of rows in the presentation space.
ULONG *Cols
This output parameter is the number of columns in the presentation space.

Return Value

ULONG
Size of the presentation space as a linear value.

Example

The following is an example of using the GetSize method.

//-------------------------------------------------------------------
// ECLPS::GetSize
//
// Display dimensions of connection 'A'
//-------------------------------------------------------------------
void Sample59() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Rows, Cols, Len;
 
PS.GetSize(&Rows, &Cols);   // Get num of rows and cols
// Could also write as:
Rows = PS.GetSizeRows();    // Redundant
Cols = PS.GetSizeCols();    // Redundant
 
Len = PS.GetSize();         // Get total size
 
printf("Connection A has %lu rows and %lu columns (%lu total length)\n",
       Rows, Cols, Len);
 
} // end sample
 

GetSizeRows

This method returns the number of rows in the Presentation Space for the connection associated with the ECLPS object.

Prototype

ULONG GetSizeRows()

Parameters

None

Return Value

ULONG
This is the number of rows in the Presentation Space.

Example

The following is an example of using the GetSizeRows method.

//-------------------------------------------------------------------
// ECLPS::GetSizeRows
//
// Display dimensions of connection 'A'
//-------------------------------------------------------------------
void Sample59() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Rows, Cols, Len;
 
PS.GetSize(&Rows, &Cols);   // Get num of rows and cols
// Could also write as:
Rows = PS.GetSizeRows();    // Redundant
Cols = PS.GetSizeCols();    // Redundant
 
Len = PS.GetSize();         // Get total size
 
printf("Connection A has %lu rows and %lu columns (%lu total length)\n",
       Rows, Cols, Len);
 
} // end sample
 

GetSizeCols

This method returns the number of columns in the Presentation Space for the connection associated with the ECLPS object.

Prototype

ULONG GetSizeCols()

Parameters

None

Return Value

ULONG
This is the number of columns in the Presentation Space.

Example

The following is an example of using the GetSizeCols method.

//-------------------------------------------------------------------
// ECLPS::GetSizeCols
//
// Display dimensions of connection 'A'
//-------------------------------------------------------------------
void Sample59() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Rows, Cols, Len;
 
PS.GetSize(&Rows, &Cols);   // Get num of rows and cols
// Could also write as:
Rows = PS.GetSizeRows();    // Redundant
Cols = PS.GetSizeCols();    // Redundant
 
Len = PS.GetSize();         // Get total size
 
printf("Connection A has %lu rows and %lu columns (%lu total length)\n",
       Rows, Cols, Len);
 
} // end sample
 

GetCursorPos

This method returns the position of the cursor in the presentation space for the connection associated with the ECLPS object. There are two signatures for the GetCursorPos method. Using ULONG GetCursorPos(), the position is returned as a linear (1-based) position. With void GetCursorPos(ULONG *Row, ULONG * Col), the position is returned as a row and column coordinate.

Prototype

ULONG  GetCursorPos()
void GetCursorPos(ULONG *Row, ULONG *Col)

Parameters

ULONG *Row
This output parameter is the row coordinate of the host cursor.
ULONG *Col
This output parameter is the column coordinate of the host cursor.

Return Value

ULONG
Cursor position represented as a linear value.

Example

The following is an example of using the GetCursorPos method.

//-------------------------------------------------------------------
// ECLPS::GetCursorPos
//
// Display position of host cursor in connection 'A'
//-------------------------------------------------------------------
void Sample60() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Row, Col, Pos;
 
PS.GetCursorPos(&Row, &Col);   // Get row/col position
// Could also write as:
Row = PS.GetCursorPosRow();    // Redundant
Col = PS.GetCursorPosCol();    // Redundant
 
Pos = PS.GetCursorPos();       // Get linear position
 
printf("Host cursor of connection A is at row %lu column %lu
 (linear position %lu)\n", Row, Col, Pos);
 
} // end sample
 
/

GetCursorPosRow

This method returns the row position of the cursor in the Presentation Space for the connection associated with the ECLPS object.

Prototype

ULONG GetCursorPosRow()

Parameters

None

Return Value

ULONG
This is the row position of the cursor in the Presentation Space.

Example

The following is an example of using the GetCursorPosRow method.

//-------------------------------------------------------------------
// ECLPS::GetCursorPosRow
//
// Display position of host cursor in connection 'A'
//-------------------------------------------------------------------
void Sample60() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Row, Col, Pos;
 
PS.GetCursorPos(&Row, &Col);   // Get row/col position
// Could also write as:
Row = PS.GetCursorPosRow();    // Redundant
Col = PS.GetCursorPosCol();    // Redundant
 
Pos = PS.GetCursorPos();       // Get linear position
 
printf("Host cursor of connection A is at row %lu column %lu
 (linear position %lu)\n", Row, Col, Pos);
 
} // end sample
 

GetCursorPosCol

This method returns the column position of the cursor in the Presentation Space for the connection associated with the ECLPS object.

Prototype

ULONG GetCursorPosCol()

Parameters

None

Return Value

ULONG
This is the column position of the cursor in the Presentation Space.

Example

The following is an example of using the GetCursorPosCol method.

//-------------------------------------------------------------------
// ECLPS::GetCursorPosCol
//
// Display position of host cursor in connection 'A'
//-------------------------------------------------------------------
void Sample60() {
 
ECLPS PS('A');       // PS object for connection A
ULONG Row, Col, Pos;
 
PS.GetCursorPos(&Row, &Col);   // Get row/col position
// Could also write as:
Row = PS.GetCursorPosRow();    // Redundant
Col = PS.GetCursorPosCol();    // Redundant
 
Pos = PS.GetCursorPos();       // Get linear position
 
printf("Host cursor of connection A is at row %lu column %lu
 (linear position %lu)\n", Row, Col, Pos);
 
} // end sample
 
//-----------------------------------------------------------------

SetCursorPos

The SetCursorPos method sets the position of the cursor in the presentation space for the connection associated with the ECLPS object. There are two signatures for the SetCursorPos method. The position can be specified as a linear (1-based) position using void SetCursorPos(ULONG pos), or as a row and column coordinate using void SetCursorPos(ULONG Row, ULONG Col).

Prototype

void SetCursorPos(ULONG pos),

void SetCursorPos(ULONG Row, ULONG Col)

Parameters

ULONG pos
Cursor position as a linear position.
ULONG Row
Cursor row coordinate.
ULONG Col
Cursor column coordinate.

Return Value

None

Example

The following is an example of using the SetCursorPos method.

--
// ECLPS::SetCursorPos
//
// Set host cursor to row 2 column 1.
//-------------------------------------------------------------------
void Sample61() {
 
ECLPS PS('A');          // PS object for connection A
 
PS.SetCursorPos(2, 1);  // Put cursor at row 2, column 1
printf("Cursor of connection A set to row 2 column 1.\n");
 
} // end sample
 
/

SendKeys

The SendKeys method sends a null-terminated string of keys to the presentation space for the connection associated with the ECLPS object. There are three signatures for the SendKeys method. If no position is specified, the keystrokes are entered starting at the current host cursor position. A position may be specified (in linear or row and column coordinates), in which case the host cursor is first moved to the given position.

The text string may contain plain text characters, which are written to the presentation space exactly as given. In addition, the string can contain imbedded keywords (mnemonics) that represent various control keystrokes such as 3270 Enter keys and 5250 PageUp keys. Keywords are enclosed in square brackets (for example, [enter]). When such a keyword is encountered in the string it is translated into the proper emulator command and sent. A text string may contain any number of plain characters and imbedded keywords. The keywords are processed from left to right until the end of the string is reached. For example, the following string would cause the characters ABC to be typed at the current cursor position, followed by a 3270 Erase-end-of-field keystroke, followed by a 3270 Tab keystroke, followed by XYZ and a PF1 key:

ABC[eraseeof][tab]XYZ[pf1]
Note:
Blank characters in the string are written to the host presentation space like any other plain text character. Therefore, blanks should not be used to separate keywords or text.

To send a left or right square bracket character to the host, it must be doubled in the text string (for example, it must occur twice to cause a single bracket to be written). The following example causes the string "A [:]" to be written to the presentation space.

A[[:]]

If you attempt to write keystrokes to a protected position on the screen, the keyboard locks and the remainder of the keystrokes are discarded.

Refer to Appendix A. Sendkeys Mnemonic Keywords for a list of keywords.

Prototype

void SendKeys(char * text),
void SendKeys(char * text, ULONG AtPos),
void SendKeys(char * text, ULONG AtRow, ULONG AtCol)

Parameters

Char *text
String of keys to send to the presentation space.
ULONG AtPos
Position at which to start writing keystrokes.
ULONG AtRow
Row at which to start writing keystrokes.
ULONG AtCol
Column at which to start writing keystrokes.

Return Value

None

Example

The following is an example of using the SendKeys method.

//-------------------------------------------------------------------
// ECLPS::SendKeys
//
// Sends a series of keystrokes, including 3270 function keys, to
// the host on connection A.
//-------------------------------------------------------------------
void Sample62() {
 
ECLPS PS('A');         // PS object for connection A
 
// The following key string will erase from the current cursor
// position to the end of the field, and then type the given
// characters into the field.
char		SendStr[] = "[eraseeof]ZIEWin is really cool";
 
// Note that an ECL error is thrown if we try to send keys to
// a protected field.
 
try {
  PS.SendKeys(SendStr);        // Do it at the current cursor position
  PS.SendKeys(SendStr, 3, 10); // Again at row 3 column 10
}
catch (ECLErr Err) {
  printf("Failed to send keys: %s\n", Err.GetMsgText());
}
 
} // end sample
 

SearchText

The SearchText method searches for text in the presentation space of the connection associated with the ECLPS object. The method returns the linear position at which the text is found, or zero if the text is not found. The search may be made in the forward (left to right, top to bottom) or backward (right to left, bottom to top) directions using the optional Dir parameter. The search can be case-sensitive or case folded (insensitive) using the optional FoldCase parameter.

If no starting position is given, the search starts at the beginning of the screen for forward searches, or at the end of the screen for backward searches. A starting position may be given in terms of a linear position or row and column coordinates. If a starting position is given it indicates the position at which to begin the search. Forward searches search from the starting position (inclusive) to the last character of the screen. Backward searches search from the starting position (inclusive) to the first character of the screen.

The search string must exist completely within the search area for the search to be successful (for example, if the search string spans over the specified starting position it will not be found).

The returned linear position may be converted to row and column coordinates using the base class ConvertPosToRowCol method.

Prototype

ULONG SearchText(const char * const text, PS_DIR Dir=SrchForward,
       BOOL FoldCase=FALSE)
ULONG SearchText(const char * const text,
       ULONG StartPos, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)
ULONG SearchText(const char char * const text, ULONG StartRow,
       ULONG StartCol, PS_DIR Dir=SrchForward, BOOL FoldCase=FALSE)

Parameters

char *text
Null-terminated string to search for.
PS_DIR Dir
Optional parameter indicating the direction in which to search. If specified, must be one of SrchForward or SrchBackward. The default is SrchForward.
BOOL FoldCase
Optional parameter indicating the case-sensitivity of the search. If specified as FALSE the text string must exactly match the presentation space including the use of uppercase and lowercase characters. If specified as TRUE, the text string will be found without regard to uppercase or lowercase. The default is FALSE.
ULONG StartPos
Indicates the starting linear position of the search. This position will be included in the search.
ULONG StartRow
Indicates the row in which to start the search.
ULONG StartCol
Indicates the column in which to start the search.

Return Value

ULONG
Linear position of the found string, or zero if not found.

Example

The following is an example of using the SearchText method.

/-------------------------------------------------------------------
// ECLPS::SearchText
//
// Search for a string in various parts of the screen.
//-------------------------------------------------------------------
void Sample63() {
 
ECLPS PS('A');            // PS object
char  FindStr[] = "HCL";  // String to search for
ULONG LastOne;            // Position of search result
 
// Case insensative search of entire screen
 
printf("Searching for '%s'...\n", FindStr);
printf("  Anywhere, any case: ");
if (PS.SearchText(FindStr, TRUE) != 0)
  printf("Yes\n");
else
  printf("No\n");
 
// Backward, case sensative search on line 1
 
printf("  Line 1, exact match: ");
if (PS.SearchText(FindStr, 1, 80, SrchBackward) != 0)
  printf("Yes\n");
else
  printf("No\n");
 
// Backward, full screen search
 
LastOne = PS.SearchText(FindStr, SrchBackward, TRUE);
if (LastOne != 0)
  printf("  Last occurance on the screen is at row %lu, column %lu.\n",
         PS.ConvertPosToRow(LastOne), PS.ConvertPosToCol(LastOne));
 
} // end sample
 

GetScreen

This method retrieves data from the presentation space of the connection associated with the ECLPS object. The data is returned as a linear array of byte values, one byte per presentation space character position. The array is not null terminated except when data is retrieved from the TextPlane, in which case a single null termination byte is appended.

The application must supply a buffer for the returned data, and the length of the buffer. If the requested data does not fit into the buffer it is truncated. For TextPlane data, the buffer must include at least one extra byte for the terminating null. The method returns the number of bytes copied to the application buffer (not including the terminating null for TextPlane copies).

The application must specify the number of bytes of data to retrieve from the presentation space. If the starting position plus this length exceeds the size of the presentation space an error is thrown. Data is returned starting at the given starting position or row 1, column 1 if no starting position is specified. Returned data is copied from the presentation space in a linear fashion from left to right, top to bottom spanning multiple rows up to the length specified. If the application wants to get screen data for a rectangular area of the screen, the GetScreenRect method should be used.

The application can specify any plane for which to retrieve data. If no plane is specified, the TextPlane is retrieved. See Appendix B. ECL Planes -- Format and Content for details on the different ECL planes.

Prototype

ULONG GetScreen(char * Buff, ULONG BuffLen, PS_PLANE Plane=TextPlane)
ULONG GetScreen(char * Buff, ULONG BuffLen, ULONG StartPos, ULONG Length,
       PS_PLANE Plane=TextPlane)
ULONG GetScreen(char * Buff, ULONG BuffLen, ULONG StartRow, ULONG StartCol,
       ULONG Length, PS_PLANE Plane=TextPlane)

Parameters

char *Buff
Pointer to application supplied buffer of at least BuffLen size.
ULONG BuffLen
Number of bytes in the supplied buffer.
ULONG StartPos
Linear position in the presentation space at which to start the copy.
ULONG StartRow
Row in the presentation space at which to start the copy.
ULONG StartCol
Column in the presentation space at which to start the copy.
ULONG Length
Linear number of bytes to copy from the presentation space.
PS_PLANE plane
Optional parameter specifying which presentation space plane is to be copied. If specified, must be one of TextPlane, ColorPlane, FieldPlane, and ExfieldPlane. The default is TextPlane. See Appendix B. ECL Planes -- Format and Content for the content and format of the different ECL planes.

Return Value

ULONG
Number of data bytes copied from the presentation space. This value does not include the trailing null byte for TextPlane copies.

Example

The following is an example of using the GetScreen method.

//-------------------------------------------------------------------
// ECLPS::GetScreen
//
// Get text and other planes of data from the presentation space.
//-------------------------------------------------------------------
void Sample64() {
 
ECLPS PS('A');            // PS object
char  *Text;              // Text plane data
char  *Field;             // Field plane data
ULONG Len;                // Size of PS
 
Len = PS.GetSize();
 
// Note text buffer needs extra byte for null terminator
 
Text  = new char[Len + 1];
Field = new char[Len];
 
PS.GetScreen(Text, Len+1);                // Get entire screen (text)
PS.GetScreen(Field, Len, FieldPlane);     // Get entire field plane
PS.GetScreen(Text, Len+1, 1, 1, 80);      // Get line 1 of text
 
printf("Line 1 of the screen is:\n%s\n", Text);
 
delete []Text;
delete []Field;
 
} // end sample
 

GetScreenRect

This method retrieves data from the presentation space of the connection associated with the ECLPS object. The data is returned as a linear array of byte values, one byte per presentation space character position. The array is not null terminated.

The application supplies a starting and ending coordinate in the presentation space. These coordinates form the opposing corner points of a rectangular area. The presentation space within the rectangular area is copied to the application buffer as a single linear array. The starting and ending points may be in any spatial relationship to each other. The copy is defined to start from the row containing the uppermost point to the row containing the lowermost point, and from the left-most column to the right-most column. Both coordinates must be within the bounds of the size of the presentation space or an error is thrown. The coordinates may be specified in terms of linear position or row and column numbers.

The supplied application buffer must be at least large enough to contain the number of bytes in the rectangle. If the buffer is too small, no data is copied and zero is returned as the method result. Otherwise the method returns the number of bytes copied.

The application can specify any plane for which to retrieve data. If no plane is specified, the TextPlane is retrieved. See Appendix B. ECL Planes -- Format and Content for details on the different ECL planes.

Prototype

ULONG GetScreenRect(char * Buff, ULONG BuffLen,
       ULONG StartPos, ULONG EndPos, PS_PLANE Plane=TextPlane)
ULONG GetScreenRect(char * Buff, ULONG BuffLen,
       ULONG StartRow, ULONG StartCol, ULONG EndRow,
       ULONG EndCol, PS_PLANE Plane=TextPlane)

Parameters

char *Buff
Pointer to application supplied buffer of at least BuffLen size.
ULONG BuffLen
Number of bytes in the supplied buffer.
ULONG StartPos
Linear position in the presentation space of one corner of the copy rectangle.
ULONG EndPos
Linear position in the presentation space of one corner of the copy rectangle.
ULONG StartRow
Row in the presentation space of one corner of the copy rectangle.
ULONG StartCol
Column in the presentation space of one corner of the copy rectangle.
ULONG EndRow
Row in the presentation space of one corner of the copy rectangle.
ULONG EndCol
Column in the presentation space of one corner of the copy rectangle.
PS_PLANE plane
Optional parameter specifying which presentation space plane is to be copied. If specified, must be one of TextPlane, ColorPlane, FieldPlane, or ExfieldPlane. The default is TextPlane. See Appendix B. ECL Planes -- Format and Content for the content and format of the different ECL planes.

Return Value

ULONG
Number of data bytes copied from the presentation space.

Example

The following is an example of using the GetScreenRect method.

------------------------------
// ECLPS::GetScreenRect
//
// Get rectangular parts of the host screen.
//-------------------------------------------------------------------
void Sample66() {
 
ECLPS PS('A');         // PS object for connection A
char Buff[4000];       // Big buffer
 
// Get first 2 lines of the screen text
PS.GetScreenRect(Buff, sizeof(Buff), 1, 1, 2, 80);
 
// Get last 2 lines of the screen
PS.GetScreenRect(Buff, sizeof(Buff),
                 PS.GetSizeRows()-1,
                 1,
                 PS.GetSizeRows(),
                 PS.GetSizeCols());
 
// Get just a part of the screen (VM main menu calendar)
PS.GetScreenRect(Buff, sizeof(Buff),
                 5,  51,
                 13, 76);
 
// Same as previous (specify any 2 oposite corners of the rectangle)
PS.GetScreenRect(Buff, sizeof(Buff),
                 13, 51,
                 5,  76);
 
// Note results are placed in buffer end-to-end with no line delimiters
printf("Contents of rectangular screen area:\n%s\n", Buff);
 
} // end sample
 

SetText

The SetText method sends a character array to the Presentation Space for the connection associated with the ECLPS object. Although this is similar to the SendKeys method, it is different in that it does not send mnemonic keystrokes (for example, [enter] or [pf1]).

If a position is not specified, the text is written starting at the current cursor position.

Prototype

void SetText(char *text);

void SetText(char *text, ULONG AtPos);

void SetText(char *text, ULONG AtRow, ULONG AtCol);

Parameters

char *text
Null terminated string of characters to copy to the presentation space.
ULONG AtPos
Linear position in the presentation space at which to begin the copy.
ULONG AtRow
Row in the presentation space of which to begin the copy.
ULONG AtCol
Column in the presentation space at which to begin the copy.

Return Value

None

Example

The following is an example of using the SetText method.

//-------------------------------------------------------------------
// ECLPS::SetText
//
// Update various input fields of the screen.
//-------------------------------------------------------------------
void Sample65() {
 
ECLPS PS('A');         // PS object for connection A
 
// Note that an ECL error is thrown if we try to write to
// a protected field.
 
try {
  // Update first 2 input fields of the screen.  Note
  // fields are not erased before update.
  PS.SendKeys("[home]");
  PS.SetText("Field 1");
  PS.SendKeys("[tab]");
  PS.SetText("Field 2");
  // Note: Above 4 lines could also be written as:
  // PS.SendKeys("[home]Field 1[tab]Field 2");
  // But SetText() is faster, esp for long strings
}
catch (ECLErr Err) {
  printf("Failed to send keys: %s\n", Err.GetMsgText());
}
 
} // end sample
 
//-------------------------------------

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

void CopyText (ULONG Long Len);

void CopyText (ULONG AtPos, ULONG Long Len);

void CopyText (ULONG AtRow, ULONG AtCol, ULONG Long Len );

Parameters

ULONG Long Len
Linear number of bytes to copy from the presentation space.
ULONG AtPos
Linear position in the presentation space at which to begin the copy.
ULONG AtRow
Row in the presentation space of which to begin the copy.
ULONG AtCol
Column in the presentation space at which to begin the copy.

Return Value

None

Example

The following is an example of using the CopyText method.

//-------------------------------------------------------------------
// ECLPS::CopyText
//
// Copy text from Presentation Space to clipboard.
//-------------------------------------------------------------------
void Sample126() {
    
ECLPS PS('A');         // PS object for connection A
long row, col, length2copy;
 
// Note that an ECL error is thrown if we try to write to
// a protected field.
try {
  	printf("Please enter the position and length to copy from PS [row col length2copy] \n");

  	scanf("%ld %ld %ld", &row, &col, &length2copy);   
		PS.CopyText(row, col, length2copy); 
		} 
catch (ECLErr Err) {
   printf("Failed to copy text: %s\n", Err.GetMsgText()); 
} 
} // end sample 
//-------------------------------------

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

void PasteText (ULONG Long Len);

void PasteText (ULONG AtPos, ULONG Long Len);

void PasteText (ULONG AtRow, ULONG AtCol, ULONG Long Len );

Parameters

ULONG Long Len
Linear number of bytes to paste from the presentation space.
ULONG AtPos
Linear position in the presentation space at which to begin the paste.
ULONG AtRow
Row in the presentation space of which to begin the paste.
ULONG AtCol
Column in the presentation space at which to begin the paste.

Return Value

None

Example

The following is an example of using the PasteText method.

//-------------------------------------------------------------------
// ECLPS::PasteText
//
// Paste text to Presentation Space from clipboard.
//-------------------------------------------------------------------
void Sample127() {
    
ECLPS PS('A');         // PS object for connection A
long row, col, length2paste;
 
// Note that an ECL error is thrown if we try to write to
// a protected field.
try {
  	printf("Please enter the position and length to paste from clipboard [row col length2paste] \n");
  	scanf("%ld %ld %ld", &row, &col, &length2paste);   
		PS.PasteText(row, col, length2paste); 
} 
catch (ECLErr Err) {   
		printf("Failed to paste text: %s\n", Err.GetMsgText()); 
} 
} // end sample
//----------------------------------------------

ConvertPosToRowCol

The ConvertPosToRowCol method converts a position in the presentation space represented as a linear array to a position in the presentation space given in row and column coordinates. The position converted is in the presentation space for the connection associated with the ECLPS object.

Prototype

void ConvertPosToRowCol(ULONG pos, ULONG *row, ULONG *col)

Parameters

ULONG pos
Position to convert in the presentation space represented as a linear array.
ULONG *row
Converted row coordinate in the presentation space.
ULONG *col
Converted column coordinate in the presentation space.

Return Value

None

Example

The following example shows how to convert a position in the presentation space represented as a linear array to a position shown in row and column coordinates.

///-------------------------------------------------------------------
// ECLPS::ConvertPosToRowCol
//
// Find a string in the presentation space and display the row/column
// coordinate of its location.
//-------------------------------------------------------------------
void Sample67() {
 
ECLPS PS('A');            // PS Object
ULONG FoundPos;           // Linear position
ULONG FoundRow,FoundCol;
 
 
FoundPos = PS.SearchText("HCL", TRUE);
if (FoundPos != 0) {
  PS.ConvertPosToRowCol(FoundPos, &FoundRow, &FoundCol);
  // Another way to do the same thing:
  FoundRow = PS.ConvertPosToRow(FoundPos);
  FoundCol = PS.ConvertPosToCol(FoundPos);
 
  printf("String found at row %lu column %lu (position %lu)\n",
         FoundRow, FoundCol, FoundPos);
}
else printf("String not found.\n");
 
} // end sample
 

ConvertRowColToPos

The ConvertRowColToPos method converts a position in the presentation space in row and column coordinates to a position in the presentation space represented as a linear array. The position converted is in the presentation space for the connection associated with the ECLPS object.

Prototype

ULONG ConvertRowColToPos(ULONG row, ULONG col)

Parameters

ULONG row
Row coordinate to convert in the presentation space.
ULONG col
Column coordinate to convert in the presentation space.

Return Value

ULONG
Converted position in the presentation space represented as a linear array.

Example

The following example shows how to convert a position in the presentation space shown in row and column coordinates to a linear array position.

///-------------------------------------------------------------------
// ECLPS::ConvertRowColToPos
//
// Find a string in the presentation space and display the row/column
// coordinate of its location.
//-------------------------------------------------------------------
void Sample67() {
 
ECLPS PS('A');            // PS Object
ULONG FoundPos;           // Linear position
ULONG FoundRow,FoundCol;
 
 
FoundPos = PS.SearchText("HCL", TRUE);
if (FoundPos != 0) {
  PS.ConvertPosToRowCol(FoundPos, &FoundRow, &FoundCol);
  // Another way to do the same thing:
  FoundRow = PS.ConvertPosToRow(FoundPos);
  FoundCol = PS.ConvertPosToCol(FoundPos);
 
  printf("String found at row %lu column %lu (position %lu)\n",
         FoundRow, FoundCol, FoundPos);
}
else printf("String not found.\n");
 
} // end sample
 

ConvertPosToRow

This method takes a linear position value in the Presentation Space and returns the row in which it resides for the connection associated with the ECLPS object.

Prototype

ULONG ConvertPosToRow(ULONG Pos)

Parameters

ULONG Pos
This is the linear position in the Presentation Space to convert.

Return Value

ULONG
This is the row position for the linear position.

Example

The following is an example of using the ConvertPosToRow method.

///-------------------------------------------------------------------
// ECLPS::ConvertPosToRow
//
// Find a string in the presentation space and display the row/column
// coordinate of its location.
//-------------------------------------------------------------------
void Sample67() {
 
ECLPS PS('A');            // PS Object
ULONG FoundPos;           // Linear position
ULONG FoundRow,FoundCol;
 
 
FoundPos = PS.SearchText("HCL", TRUE);
if (FoundPos != 0) {
  PS.ConvertPosToRowCol(FoundPos, &FoundRow, &FoundCol);
  // Another way to do the same thing:
  FoundRow = PS.ConvertPosToRow(FoundPos);
  FoundCol = PS.ConvertPosToCol(FoundPos);
 
  printf("String found at row %lu column %lu (position %lu)\n",
         FoundRow, FoundCol, FoundPos);
}
else printf("String not found.\n");
 
} // end sample
 

ConvertPosToCol

This method takes a linear position value in the Presentation Space and returns the column in which it resides for the connection associated with the ECLPS object.

Prototype

ULONG ConvertPosToCol(ULONG Pos)

Parameters

ULONG Pos
This is the linear position in the Presentation Space to convert.

Return Value

ULONG
This is the column position for the linear position.

Example

The following is an example of using the ConvertPosToCol method.

///-------------------------------------------------------------------
/// ECLPS::ConvertPosToCol
//
// Find a string in the presentation space and display the row/column
// coordinate of its location.
//-------------------------------------------------------------------
void Sample67() {
 
ECLPS PS('A');            // PS Object
ULONG FoundPos;           // Linear position
ULONG FoundRow,FoundCol;
 
 
FoundPos = PS.SearchText("HCL", TRUE);
if (FoundPos != 0) {
  PS.ConvertPosToRowCol(FoundPos, &FoundRow, &FoundCol);
  // Another way to do the same thing:
  FoundRow = PS.ConvertPosToRow(FoundPos);
  FoundCol = PS.ConvertPosToCol(FoundPos);
 
  printf("String found at row %lu column %lu (position %lu)\n",
         FoundRow, FoundCol, FoundPos);
}
else printf("String not found.\n");
 
} // end sample
 

RegisterKeyEvent

The RegisterKeyEvent function registers an application-supplied object to receive notification of operator keystroke events. The application must construct an object derived from the ECLKeyNotify abstract base class. When an operator keystroke occurs, the NotifyEvent() method of the application supplied object is called. The application can choose to have the keystroke filtered or passed on and processed in the usual way. See ECLKeyNotify Class for more details.

Implementation Restriction: Only one object may be registered to receive keystroke events at a time.

Prototype

void RegisterKeyEvent(ECLKeyNotify *NotifyObject)

Parameters

ECLKeyNotify *NotifyObject
Application object derived from ECLKeyNotify class.

Return Value

None

Example

The following example shows how to register an application-supplied object to receive notification of operator keystroke events. See the ECLKeyNotify Class for a RegisterKeyEvent example.

// This is the declaration of your class derived from ECLKeyNotify....
class MyKeyNotify: public ECLKeyNotify
{
public:
  // App can put parms on constructors if needed
  MyKeyNotify();	 						  // Constructor
  MyKeyNotify();							  // Destructor
 
  // App must define the NotifyEvent method
  int NotifyEvent(char KeyType[2], char KeyString[7]);  // Keystroke callback
 
private:
  // Whatever you like...
};
// this is the implementation of app methods...
 
int MyKeyNotify::NotifyEvent( ECLPS *, char *KeyType, char *Keystring )
{
  if (...) {
    ...
    return 0;  // Remove keystroke (filter)
  }
  else
    ...
    return 1;  // Pass keystroke to emulator as usual
  }
}
 
// this would be the code in say, WinMain...
 
ECLPS	*pPS;					       // Pointer to ECLPS object
MyKeyNotify *MyKeyNotifyObject;	// My key notification object,derived
                                   // from ECLKeyNotify
 
try {
  pPS = new ECLPS('A');              // Create PS object for 'A' session
 
  // Register for keystroke events
  MyKeyNotifyObject = new MyKeyNotify();
  pPS->RegisterKeyEvent(MyKeyNotifyObject);
 
  // After this, MyKeyNotifyObject->NotifyEvent() will be called
  // for each operator keystroke...
}
catch (ECLErr HE) {
  // Just report the error text in a message box
  MessageBox( NULL, HE.GetMsgText(), "Error!", MB_OK );
}

UnregisterKeyEvent

The UnregisterKeyEvent method unregisters an application object previously registered for keystroke events with the RegisterKeyEvent function. A registered application notify object should not be destroyed without first calling this function to unregister it. If there is no notify object currently registered, or the registered object is not the NotifyObject passed in, this function does nothing (no error is thrown).

Prototype

virtual UnregisterKeyEvent(ECLKeyNotify *NotifyObject )

Parameters

ECLKeyNotify *NotifyObject
Object currently registered for keystroke events.

Return Value

None

Example

See the ECLKeyNotify Class for a UnregisterKeyEvent example.

GetFieldList

This method returns a pointer to an ECLFieldList object. The field list object can be used to iterate over the list of fields in the host presentation space. The ECLFieldList object returned by this function is automatically destroyed when the ECLPS object is destroyed. See ECLFieldList Class for more information about this object.

Prototype

ECLFieldList *GetFieldList()

Parameters

None

Return Value

ECLFieldList *
Pointer to ECLFieldList object.

Example

The following example shows how to return a pointer to an ECLFieldList object.

// ECLPS::GetFieldList
//
// Display number of fields on the screen.
//-------------------------------------------------------------------
void Sample68() {
 
ECLPS        *PS;           // Pointer to PS object
ECLFieldList *FieldList;    // Pointer to field list object
 
try {
  PS = new ECLPS('A');                // Create PS object for 'A'
 
  FieldList = PS->GetFieldList();     // Get pointer to field list
  FieldList->Refresh();               // Build the field list
 
  printf("There are %lu fields on the screen of connection %c.\n",
    FieldList->GetFieldCount(), PS->GetName());
 
  delete PS;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 

WaitForCursor

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

Prototype

BOOL WaitForCursor(int Row, int Col, long nTimeOut=INFINITE,
          BOOL bWaitForIR=TRUE)

Parameters

int Row
Row position of the cursor. If negative, this value indicates the Row position from the bottom of the PS.
int Col
Column position of the cursor. If negative, this value indicates the Cursor position from the edge of the PS.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = ps.WaitForCursor(23,1,TimeOut, TRUE); 
 
// do the processing for the screen 

WaitWhileCursor

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

Prototype

BOOL WaitWhileCursor(int Row, int Col, long nTimeOut=INFINITE,
          BOOL bWaitForIR=TRUE)

Parameters

int Row
Row position of the cursor. If negative, this value indicates the Row position from the bottom of the PS.
int Col
Column position of the cursor. If negative, this value indicates the Cursor position from the edge of the PS.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = ps.WaitWhileCursor(23,1,TimeOut, TRUE); 
 
// do the processing for when the screen goes away

WaitForString

The WaitForString method waits for the specified string to appear in the presentation space of the connection associated with the ECLPS 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

BOOL WaitForString( char* WaitString, int Row=0, int Col=0, long nTimeOut=INFINITE,
       BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)

Parameters

char* WaitString
The string which will be the subject of the wait.
int Row
Row position of the cursor. If negative, this value indicates the Row position from the bottom of the PS. The default is zero.
int Col
Column position of the cursor. If negative, this value indicates the Cursor position from the edge of the PS. The default is zero.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.
BOOL bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitForString("LOGON"); 
 
// do the processing for the screen 

WaitWhileString

The WaitWhileString method waits while the specified string is in the presentation space of the connection associated with the ECLPS 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

BOOL WaitWhileString(char* WaitString, int Row=0, int Col=0,
                                    long nTimeOut=INFINITE,
                                    BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)

Parameters

char* WaitString
The string which will be the subject of the wait.
int Row
Start Row position of the string. If negative, this value indicates the Row position from the bottom of the PS. The default is zero.
int Col
Start Column position of the string. If negative, this value indicates the Cursor position from the edge of the PS. The default is zero.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.
BOOL bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitWhileString("LOGON"); 
 
// do the processing for when the screen goes away 

WaitForStringInRect

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

Prototype

BOOL WaitForStringInRect(char* WaitString, int sRow, int sCol, int eRow,int eCol,
       long nTimeOut=INFINITE, BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)

Parameters

char* WaitString
The string which will be the subject of the wait.
int Row
Start Row position of the rectangle.
int Col
Start Column position of the rectangle.
int eRow
Ending row position of the search rectangle.
int eCol
Ending column position of the search rectangle.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.
BOOL bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitForStringInRect("LOGON",1,1,23,80); 
 
// do the processing for the screen 

WaitWhileStringInRect

The WaitWhileStringInRect method waits while the specified string is in the presentation space of the connection associated with the ECLPS object in the specified Rectangle.

Prototype

BOOL WaitWhileStringInRect(char* WaitString, int sRow, int sCol, int eRow,int eCol,
       long nTimeOut=INFINITE, BOOL bWaitForIR=TRUE, BOOL bCaseSens=TRUE)  

Parameters

char* WaitString
The string which will be the subject of the wait.
int Row
Start Row position of the rectangle.
int Col
Start Column position of the rectangle.
int eRow
Ending row position of the search rectangle.
int eCol
Ending column position of the search rectangle.
long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.
BOOL bCaseSens
If this value is True, the wait condition is verified as case-sensitive. This parameter is optional. The default is TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitWhileStringInRect("LOGON",1,1,23,80); 
 
// do the processing for when the screen goes away 

WaitForAttrib

The WaitForAttrib method will wait until the specified Attribute value appears in the presentation space of the connection associated with the ECLPS 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

BOOL WaitForAttrib(int Row, int Col, unsigned char AttribDatum,
       unsigned char MskDatum= 0xFF, PS_PLANE plane = FieldPlane,
       long TimeOut = INFINITE, BOOL bWaitForIR = TRUE)

Parameters

int Row
Row position of the attribute.
int Col
Column position of the attribute.
unsigned char AttribDatum
The 1 byte HEX value of the attribute to wait for.
unsigned char MskDatum
The 1 byte HEX value to use as a mask with the attribute. This parameter is optional. The default value is 0xFF.
PS_PLANE plane
The plane of the attribute to get. The plane can have the following values: TextPlane, ColorPlane, FieldPlane, and ExfieldPlane. See Appendix B. ECL Planes -- Format and Content for the content and format of the different ECL planes.

This parameter is optional. The default is FieldPlane.

long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitForAttrib(10, 16, 0xE0, 0xFF, FieldPlane, INFINITE, FALSE);
 
// do the processing for when the screen goes away 

WaitWhileAttrib

The WaitWhileAttrib method waits while the specified Attribute value appears in the presentation space of the connection associated with the ECLPS 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

BOOL WaitWhileAttrib(int Row, int Col, unsigned char AttribDatum,
       unsigned char MskDatum= 0xFF, PS_PLANE plane = FieldPlane,
       long TimeOut = INFINITE, BOOL bWaitForIR = TRUE)

Parameters

int Row
Row position of the attribute.
int Col
Column position of the attribute unsigned.
char AttribDatum
The 1 byte HEX value of the attribute to wait for.
unsigned char MskDatum
The 1 byte HEX value to use as a mask with the attribute. This parameter is optional. The default value is 0xFF.
PS_PLANE plane
The plane of the attribute to get. The plane can have the following values: TextPlane, ColorPlane, FieldPlane, and ExfieldPlane. See Appendix B. ECL Planes -- Format and Content for the content and format of the different ECL planes.

This parameter is optional. The default is FieldPlane.

long nTimeOut
The maximum length of time in milliseconds to wait. This parameter is optional. The default is INFINITE.
BOOL bWaitForIR
If this value is true, after meeting the wait condition the function will wait until the OIA indicates the PS is ready to accept input. This parameter is optional and is defaulted to TRUE.

Return Value

The method returns TRUE if the condition is met, or FALSE if nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// do the wait
BOOL waitOK = ps.WaitWhileAttrib(10, 16, 0xE0, 0xFF, FieldPlane, INFINITE, FALSE);
 
// do the processing for when the screen goes away 

WaitForScreen

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

Prototype

BOOL WaitForScreen(ECLScreenDesc* screenDesc, long TimeOut = INFINITE)

Parameters

ECLScreenDesc
screenDesc Object that describes the screen (see ECLScreenDesc Class).
long nTimeOut
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 nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddCursorPos(23,1);
eclSD.AddString("LOGON");
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = ps.WaitForScreen(eclSD, timeInt.intValue()); 
 
// do processing for the screen 

WaitWhileScreen

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

Prototype

BOOL WaitWhileScreen(ECLScreenDesc* screenDesc, long TimeOut = INFINITE)

Parameters

ECLScreenDesc
screenDesc Object that describes the screen (see ECLScreenDesc Methods).
long nTimeOut
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 nTimeOut (in milliseconds) has elapsed.

Note:
This method will block if nTimeOut is default value (INFINITE) when the test condition would return FALSE.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddCursorPos(23,1);
eclSD.AddString("LOGON");
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = ps.WaitWhileScreen(eclSD, timeInt.intValue()); 
 
// do processing for when the screen goes away 

RegisterPSEvent

This member function registers an application object to receive notifications of PS update events. To use this function the application must create an object derived from either ECLPSNotify or ECLPSListener. A pointer to that object is then passed to this registration function. Any number of notify or listener objects may be registered at the same time. The order in which multiple listeners receive events is not defined and should not be assumed.

Different prototypes for this function allow different types of update events to be generated, and different levels of detail about the updates. The simplest update event is registered with an ECLPSNotify object. The type of registration produces an event for every PS update. No information about the update is generated. See the description of the ECLPSNotify object for more information.

For applications with need more information about the update, the ECLPSListener object can be registered. Registration of this object gives the application the ability to ignore some types of updates (for example, local terminal functions such as keystrokes) and to determine the region of the screen which was updated. See the description of the ECLPSListener object for more information. When registering an ECLPSListener object, the application can optionally specify the type of updates which are to cause events.

After an ECLPSNotify or ECLPSListener object is registered with this function, it's NotifyEvent() method will be called whenever a update to the presentation space occurs. Multiple updates to the PS in a short time period may be aggregated into a single event.

The application must unregister the notify/listener object before destroying it. The object will automatically be unregistered if the ECLPS object is destroyed.

Prototype

void RegisterPSEvent(ECLPSNotify * notify)
void RegisterPSEvent(ECLPSListener * listener)
void RegisterPSEvent(ECLPSListener * listener, int type)

Parameters

ECLPSNotify *
Pointer to the ECLPSNotify object to be registered.
ECLPSListener *
Pointer to the ECLPSListener object to be registered.
int
Type of updates which will cause events:

Return Value

None

StartMacro

The StartMacro method runs the Z and I Emulator for Windows macro file indicated by the MacroName parameter.

Prototype

void StartMacro(String MacroName)

Parameters

String MacroName
Name of macro file located in the Z and I Emulator for Windows 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("ZIEWin.autECLPS")
PS.StartMacro "mymacro"
 

UnregisterPSEvent

This member function unregisters an application object previously registered with the RegisterPSEvent function. An object registered to receive events should not be destroyed without first calling this function to unregister it. If the specific object is not currently registered, no action is taken and no error occurs.

When an ECLPSNotify or ECLPSListener object is unregistered its NotifyStop() method is called.

Prototype

void UnregisterPSEvent(ECLPSNotify * notify)
void UnregisterPSEvent(ECLPSListener * listener)
void UnregisterPSEvent(ECLPSListener * listener, int type)

Parameters

ECLPSNotify *
Pointer to the ECLPSNotify object to be unregistered.
ECLPSListener *
Pointer to the ECLPSListener object to be unregistered.
int
Type of updates which where registered:

Return Value

None

ECLPSEvent Class

ECLPSEvent objects are passed to ECLListener objects when the presentation space has been updated. This event object represents the presentation space update event and contains information about the update.

There are two sets of functions an application can use to determine the region of the presentation space which was updated. The GetStart() and GetEnd() methods return a linear position indicating the starting position and ending position of the update region in the presentation space. Linear addressing starts at 1 for the upper-left-most character and proceeds left-to-right wrapping from row to row. A corresponding set of functions (GetStartRow, GetStartCol, GetEndRow, GetEndCol) return the same information in row/column coordinates.

The update region includes all PS characters from the starting character to the ending character (inclusive). If the start and end position are not on the same row then the update region wraps from the end of one row to the first column of the next row. Note that the update region is (generally) not rectangular. If the starting position is greater than the ending position, the update region starts at the starting position, wraps from the last character of the screen to the first, and continues to the ending position.

Note that the update region may encompass more than the actual changed portion of the presentation space, but it is guaranteed to cover at least the changed area. When multiple PS updates occur in a short period of time the changes may be aggregated into a single event in which the update region spans the sum of all the updates.

Derivation

ECLBase > ECLEvent > ECLPSEvent

Usage Notes

Applications do not use this class directly. Applications create ECLListener-derived objects which receive ECLPSEvent objects on the ECLListener::NotifyEvent method.

ECLPSEvent Methods

The following section describes the methods that are valid for the ECLPSEvent class and all classes derived from it.

ECLPS * GetPS()
int GetType()
ULONG GetStart()
ULONG GetEnd()
ULONG GetStartRow()
ULONG GetStartCol()
ULONG GetEndRow()
ULONG GetEndCol()

GetPS

This method returns the ECLPS object which generated this event.

Prototype

ECLPS * GetPS()

Parameters

None

Return Value

ECLPS *
Pointer to ECLPS object which generated the event.

GetType

This method returns the type of presentation space update which generated this event. The return value is on of USER_EVENTS or HOST_EVENTS. User events are defined as any PS update which occurs as a local terminal function (for example, keystrokes entered by the user or by a programming API). Host events are PS updates which occur from host outbound datastreams.

Prototype

int GetType()

Parameters

None

Return Value

int
Returns USER_EVENTS or HOST_EVENTS constants.

GetStart

This method returns the linear location in the presentation space of the start of the update region. Note that the row/column coordinate of this location is dependant on the number of columns currently defined for the presentation space. If this value is greater than that returned by GetEnd(), then the update region starts at this location, wraps at the end of the screen to the beginning of the screen, and continues to the ending position.

Prototype

ULONG GetStart()

Parameters

None

Return Value

ULONG
Linear position of start of the update region.

GetEnd

This method returns the linear location in the presentation space of the end of the update region. Note that the row/column coordinate of this location is dependant on the number of columns currently defined for the presentation space. If this value is less than that returned by GetStart(), then the update region starts at the GetStart() location, wraps at the end of the screen to the beginning of the screen, and continues to this position.

Prototype

ULONG GetEnd()

Parameters

None

Return Value

ULONG
Linear position of end of the update region.

GetStartRow

This method returns the row number in the presentation space of the start of the update region. If the starting row/column position is greater than that of the ending row/column position, then the update region starts at this location, wraps at the end of the screen to the beginning of the screen, and continues to the ending position.

Prototype

ULONG GetStartRow()

Parameters

None

Return Value

ULONG
Row number of start of the update region.

GetStartCol

This method returns the column number in the presentation space of the start of the update region. If the starting row/column position is greater than that of the ending row/column position, then the update region starts at the starting row/column, wraps at the end of the screen to the beginning of the screen, and continues to the ending position.

Prototype

ULONG GetStartCol()

Parameters

None

Return Value

ULONG
Column number of start of the update region.

GetEndRow

This method returns the row number in the presentation space of the end of the update region. If the starting row/column position is greater than that of the ending row/column position, then the update region starts at the starting row/column, wraps at the end of the screen to the beginning of the screen, and continues to the ending row/column.

Prototype

ULONG GetEndRow()

Parameters

None

Return Value

ULONG
Row number of end of the update region.

GetEndCol

This method returns the column number in the presentation space of the end of the update region. If the starting row/column position is greater than that of the ending row/column position, then the update region starts at the starting row/column, wraps at the end of the screen to the beginning of the screen, and continues to the ending row/column.

Prototype

ULONG GetEndCol()

Parameters

None

Return Value

ULONG
Column number of end of the update region.

ECLPSListener Class

ECLPSListener is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLPSListener. The application must implement all the methods in this class.

The ECLPSListener class is used to allow an application to be notified of updates to the presentation space. Events are generated whenever the host screen is updated (any data in the presentation space is changed in any plane).

This class is similar to the ECLPSNotify class in that it is used to receive notifications of PS updates. It differs however in that it receives much more information about the cause and scope of the update than the ECLPSNotify class. In general using this class will be more expensive in terms of processing time and memory since more information has to be generated with each event. For applications which need to efficiently update a visual representation of the host screen this class may be more efficient than redrawing the representation each time an update occurs. Using this class the application can update only the portion of the visual representation that has changed.

This class also differs from ECLPSNotify in that all the methods are pure virtual and therefor must be implemented by the application (there is no default implementation of any methods).

Derivation

ECLBase > ECLListener > ECLPSListener

Usage Notes

To be notified of PS updates using this class, the application must perform the following steps:

  1. Define a class derived from ECLPSListener.
  2. Implement all methods of the ECLPSListener-derived class.
  3. Create an instance of the derived class.
  4. Register the instance with the ECLPS::RegisterPSEvent() method.

After registration is complete, updates to the presentation space will cause the NotifyEvent() method of the ECLPSListener-derived class to be called. The application can then used the ECLPSEvent object supplied on the method call to determine what caused the PS update and the region of the screen affected.

Note that multiple PS updates which occurred in a short period of time may be aggregated into a single event notification.

An application can choose to provide its own constructor and destructor for the derived class. This can be useful if the application needs to store some instance-specific data in the class and pass that information as a parameter on the constructor.

If an error is detected during event registration, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error. When event generation terminates (due to an error or some other reason) the NotifyStop() member function is called.

ECLPSListener Methods

The following section describes the methods that are valid for the ECLPSListener class and all classes derived from it. Note that all methods except the constructor and destructor are pure virtual methods.

ECLPSListener()
ECLPSListener()
virtual void NotifyEvent(ECLPSEvent * event) = 0
virtual void NotifyError(ECLPS * PSObj,  ECLErr ErrObj) = 0
virtual void NotifyStop(ECLPS * PSObj, int Reason) = 0

NotifyEvent

This method is a pure virtual member function (the application must implement this function in classes derived from ECLPSListener). This method is called whenever the presentation space is updated and this object is registered to receive update events. The ECLPSEvent object passed as a parameter contains information about the event including the region of the screen that was modified. See ECLPSEvent Class for details.

Multiple PS updates may be aggregated into a single event causing only a single call to this method. The changed region contained in the ECLPSEvent object will encompass the sum of all the modifications.

Events may be restricted to only a particular type of PS update by supplying the appropriate parameters on the ECLPS::RegisterPSEvent() method. For example the application may choose to be notified only for updates from the host and not for local keystrokes.

Prototype

virtual void NotifyEvent(ECLPSEvent * event) = 0

Parameters

ECLPSEvent *
Pointer to an ECLPSEvent object which represents the PS update.

Return Value

None

NotifyError

This method is called whenever the ECLPS object detects an error during event generation. The error object contains information about the error (see ECLErr Class). Events may continue to be generated after the error depending on the nature of the error. If the event generation stops due to an error, the NotifyStop() method is called.

This is a pure virtual method which the application must implement.

Prototype

virtual void NotifyError(ECLPS * PSObj,  ECLErr ErrObj) = 0

Parameters

ECLPS *
Pointer to the ECLPS object which generated this event.
ECLErr
An ECLErr object which describes the error.

Return Value

None

NotifyStop

This method is called when event generation is stopped for any reason (for example, due to an error condition or a call to ECLPS::UnregisterPSEvent).

This is a pure virtual method which the application must implement.

The reason code parameter is currently unused and will be zero.

Prototype

virtual void NotifyStop(ECLPS * PSObj, int Reason) = 0

Parameters

ECLPS *
Pointer to the ECLPS object which generated this event.
int
Reason event generation has stopped (currently unused and will be zero).

Return Value

None

ECLPSNotify Class

ECLPSNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLPSNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLPSNotify class is used to allow an application to be notified of updates to the presentation space. Events are generated whenever the host screen is updated (any data in the presentation space is changed in any plane).

This class is similar to the ECLPSListener class in that it is used to receive notifications of PS updates. It differs however in that it receives no information about the cause and scope of the update than the ECLPSNotify class. In general using this class will be more efficient in terms of processing time and memory since no information has to be generated with each event. This class may be used for applications which only need notification of updates and do not need the details of what caused the event or what part of the screen was updated.

This class also differs from ECLPSListener in that default implementations are provided for the NotifyError() and NotifyStop() methods.

Derivation

ECLBase > ECLNotify > ECLPSNotify

Usage Notes

To be notified of PS updates using this class, the application must perform the following steps:

  1. Define a class derived from ECLPSNotify.
  2. Implement the NotifyEvent method of the ECLPSNotify-derived class.
  3. Optionally implement other member functions of ECLPSNotify.
  4. Create an instance of the derived class.
  5. Register the instance with the ECLPS::RegisterPSEvent() method.

After registration is complete, updates to the presentation space will cause the NotifyEvent() method of the ECLPSNotify-derived class to be called.

Note that multiple PS updates which occur in a short period of time may be aggregated into a single event notification.

An application can choose to provide its own constructor and destructor for the derived class. This can be useful if the application needs to store some instance-specific data in the class and pass that information as a parameter on the constructor.

If an error is detected during event registration, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error. When event generation terminates (due to an error or some other reason) the NotifyStop() member function is called. The default implementation of NotifyError() will present a message box to the user showing the text of the error messages retrieved from the ECLErr object.

When event notification stops for any reason (error or a call the ECLPS::UnregisterPSEvent) the NotifyStop() member function is called. The default implementation of NotifyStop() does nothing.

ECLPSNotify Methods

The following section describes the methods that are valid for the ECLPSNotify class and all classes derived from it.

ECLPSNotify()=0
~ECLPSNotify()
virtual void NotifyEvent(ECLPS * PSObj)
virtual void NotifyError(ECLPS * PSObj,  ECLErr ErrObj)
virtual void NotifyStop(ECLPS * PSObj, int Reason)

NotifyEvent

This method is a pure virtual member function (the application must implement this function in classes derived from ECLPSNotify). This method is called whenever the presentation space is updated and this object is registered to receive update events.

Multiple PS updates may be aggregated into a single event causing only a single call to this method.

Prototype

virtual void NotifyEvent(ECLPS * PSObj)

Parameters

ECLPS *
Pointer to the ECLPS object which generated this event.

Return Value

None

NotifyError

This method is called whenever the ECLPS object detects an error during event generation. The error object contains information about the error (see ECLErr Class). Events may continue to be generated after the error depending on the nature of the error. If the event generation stops due to an error, the NotifyStop() method is called.

An application can choose to implement this function or allow the base ECLPSNotify class handle it. The default implementation will display the error in a message box using text supplied by the ECLErr::GetMsgText() method. If the application implements this function in its derived class it overrides this behavior.

Prototype

virtual void NotifyError(ECLPS * PSObj,  ECLErr ErrObj) = 0

Parameters

ECLPS *
Pointer to the ECLPS object which generated this event.
ECLErr
An ECLErr object which describes the error.

Return Value

None

NotifyStop

This method is called when event generation is stopped for any reason (for example, due to an error condition or a call to ECLPS::UnregisterPSEvent).

The reason code parameter is currently unused and will be zero.

The default implementation of this function does nothing.

Prototype

virtual void NotifyStop(ECLPS * PSObj, int Reason) = 0

Parameters

ECLPS *
Pointer to the ECLPS object which generated this event.
int
Reason event generation has stopped (currently unused and will be zero).

Return Value

None

ECLRecoNotify Class

ECLRecoNotify can be used to implement an object which will receive and handle ECLScreenReco events. Events are generated whenever any screen in the PS is matched to an ECLScreenDesc object in ECLScreenReco. Special events are generated when event generation stops and when errors occur during event generation.

To be notified of ECLScreenReco events, the application must perform the following steps:

  1. Define a class which derives from the ECLRecoNotify class.
  2. Implement the NotifyEvent(), NotifyStop(), and NotifyError() methods.
  3. Create an instance of the new class.
  4. Register the instance with the ECLScreenReco::RegisterScreen() method.

See ECLScreenReco Class for an example.

Derivation

ECLBase > ECLNotify > ECLRecoNotify

ECLRecoNotify Methods

Valid methods for ECLRecoNotify are listed below:

ECLRecoNotify()
~ECLRecoNotify()
void NotifyEvent(ECLPS *ps, ECLScreenDesc *sd)
void NotifyStop(ECLPS *ps, ECLScreenDesc *sd)
void NotifyError(ECLPS *ps, ECLScreenDesc *sd, ECLErr e)

ECLRecoNotify Constructor

Creates an empty instance of ECLRecoNotify.

Prototype

ECLRecoNotify()

Parameters

None

Return Value

None

Example

See ECLScreenReco Class for an example.

ECLRecoNotify Destructor

Destroys the instance of ECLRecoNotify

Prototype

~ECLRecoNotify()

Parameters

None

Return Value

None

Example

See ECLScreenReco Class for an example.

NotifyEvent

Called when the ECLScreenDesc registered with the ECLRecoNotify object on ECLScreenReco appears in the presentation space.

Prototype

void NotifyEvent(ECLPS *ps, ECLScreenDesc *sd)

Parameters

ECLPS ps
The ECLPS object that you registered.
ECLScreenDesc sd
ECLScreenDesc that you registered.

Return Value

None

Example

See ECLScreenReco Class for an example.

NotifyStop

Called when the ECLScreenReco object stops monitoring its ECLPS objects for the registered ECLScreenDesc objects.

Prototype

void NotifyStop(ECLPS *ps, ECLScreenDesc *sd)

Parameters

ECLPS ps
The ECLPS object that you registered.
ECLScreenDesc sd
ECLScreenDesc that you registered.

Return Value

None

Example

See ECLScreenReco Class for an example.

NotifyError

Called when the ECLScreenReco object encounters an error.

Prototype

void NotifyError(ECLPS *ps, ECLScreenDesc *sd, ECLErr e)

Parameters

ECLPS ps
The ECLPS object that you registered.
ECLScreenDesc sd
ECLScreenDesc that you registered.
ECLErr e
ECLErr object that contains the error information.

Return Value

None

Example

See ECLScreenReco Class for an example.

ECLScreenDesc Class

ECLScreenDesc is the class that is used to describe a screen for the Host Access Class Library screen recognition technology. It uses all four major planes of the presentation space to describe it (TEXT,FIELD,EXFIELD, COLOR), 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 ECLScreenDesc object is created and set, it may be passed to either the synchronous WaitFor... methods provided on ECLPS, or it may be passed to ECLScreenReco, which fires an asynchronous event if the screen matching the ECLScreenDesc object appears in the PS.

Derivation

ECLBase > ECLScreenDesc

ECLScreenDesc Methods

Valid methods for ECLScreenDesc are listed below:

ECLScreenDesc()
~ECLScreenDesc()
void AddAttrib(BYTE attrib, UINT pos, PS_PLANE plane=FieldPlane);
void AddAttrib(BYTE attrib, UINT row, UINT col, PS_PLANE plane=FieldPlane);
void AddCursorPos(uint row, uint col)
void AddNumFields(uint num)
void AddNumInputFields(uint num)
void AddOIAInhibitStatus(OIAStatus type=NOTINHIBITED)
void AddString(LPCSTR s, UINT row, UINT col, BOOL caseSensitive=TRUE)
void AddStringInRect(char * str, int Top, int Left, int Bottom, int Right,
                                 BOOL caseSense=TRUE)
void Clear()

ECLScreenDesc Constructor

Creates an empty instance of ECLScreenDesc.

Prototype

ECLScreenDesc()

Parameters

None

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddCursorPos(23,1);
eclSD.AddString("LOGON"); 
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

ECLScreenDesc Destructor

Destroys the instance of ECLScreenDesc.

Prototype

~ ECLScreenDesc()

Parameters

None

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddCursorPos(23,1);
eclSD.AddString("LOGON"); 
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
// destroy the descriptor
delete eclSD;
 

AddAttrib

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

Prototype

void AddAttrib(BYTE attrib, UINT pos, PS_PLANE plane=FieldPlane);
void AddAttrib(BYTE attrib, UINT row, UINT col, PS_PLANE plane=FieldPlane);

Parameters

BYTE attrib
Attribute value to add.
int row
Row position.
int col
Column position.
PS_PLANE plane
Plane in which attribute resides. Valid values are: TextPlane, ColorPlane, FieldPlane, Exfield Plane, GridPlane.TextPlane, ColorPlane, FieldPlane, and ExfieldPlane. See Appendix B. ECL Planes -- Format and Content for the content and format of the different ECL planes.

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddCursorPos

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

Prototype

void AddCursorPos(uint row, uint col)

Parameters

uint row
Row position.
uint col
Column position.

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddNumFields

Adds the number of input fields to the screen description.

Prototype

void AddNumFields(uint num)

Parameters

uint num
Number of fields.

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddNumInputFields

Adds the number of input fields to the screen description.

Prototype

void AddNumInputFields(uint num)

Parameters

uint num
Number of input fields.

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddOIAInhibitStatus

Sets the type of OIA monitoring for the screen description.

Prototype

void AddOIAInhibitStatus(OIAStatus type=NOTINHIBITED)

Parameters

OIAStatus type
Type of OIA status. Current valid values are DONTCARE and NOTINHIBITED.

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddString

Adds a string at the given location to the screen description. If row and column are not provided, string may appear anywhere in the PS.

Note:
Negative values are absolute positions from the bottom of the PS. For example, row=-2 is row 23 out of 24 rows.

Prototype

void AddString(LPCSTR s, UINT row, UINT col, BOOL caseSensitive=TRUE)

Parameters

LPCSTR s
String to add.
uint row
Row position.
uint col
Column position.
BOOL 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

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

AddStringInRect

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

Prototype

void AddStringInRect(char * str, int Top, int Left, int Bottom, int Right,
                                 BOOL caseSense=TURE)

Parameters

char * str
String to add.
int Top
Upper left row position. This parameter is optional. The default is the first row.
int Left
Upper left column position. This parameter is optional. The default is the first column.
int Bottom
Lower right row position. This parameter is optional. The default is the last row.
int Right
Lower right column position. This parameter is optional. The default is the last column.
BOOL 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

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 

Clear

Removes all description elements from the screen description.

Prototype

void Clear()

Parameters

None

Return Value

None

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45) ;
eclSD.AddNumInputFields(17) ;
AddOIAInhibitStatus(NOTINHIBITED) ;
eclSD.AddString("LOGON"., 23, 11, TRUE) ;
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE) ;
 
// do the wait
int TimeOut = 5000;
BOOL waitOK = eclPS.WaitForScreen(eclSD, timeInt.intValue());
 
// do processing for the screen 
 
eclSD.Clear() // start over for a new screen
 

ECLScreenReco Class

The ECLScreenReco 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 handler code for those screens.

Think of an object of the ECLScreenReco class as a unique recognition set. The object can have multiple ECLPS objects that it watches for screens, multiple screens to look for, and multiple callback points to call when it sees a screen in any of the ECLPS objects.

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

Here's an example of a common implementation:

class MyApp { 
ECLPS myECLPS('A'); // My main HACL PS object
ECLScreenReco myScreenReco(); // My screen reco object 
ECLScreenDesc myScreenDesc(); // My screen descriptor 
MyRecoCallback myCallback(); // My GUI handler 
 
MyApp() { 
// Save the number of fields for below 
ECLFieldList *fl = myECLPS.GetFieldList() 
Fl->Refresh(); 
int numFields = fl->GetFieldCount(); 
 
// Set up my HACL screen description object. Say the screen 
// is identified by a cursor position, a key word, and the 
// number of fields 
myScreenDesc.AddCursorPos(23,1); 
myScreenDesc.AddString("LOGON"); 
myScreenDesc.AddNumFields(numFields); 
 
 
// Set up HACL screen reco object, it will begin monitoring here 
myScreenReco.AddPS(myECLPS); 
myScreenReco.RegisterScreen(&myScreenDesc, &myCallback); 
} 
 
 MyApp() { 
myScreenReco.UnregisterScreen(&myScreenDesc, &myCallback);
myScreenReco.RemovePS(&eclPS);
}
 
public void showMainGUI() { 
// Show the main application GUI, this is just a simple example 
} 
 
 
// ECLRecoNotify-derived inner class (the "callback" code) 
class MyRecoCallback public: ECLRecoNotify { 
public: void NotifyEvent(ECLScreenDesc *sd, ECLPS *ps) { 
// GUI code here for the specific screen 
// Maybe fire a dialog that front ends the screen 
} 
 
public void NotifyError(ECLScreenDesc *sd, ECLPS *ps, ECLErr e) { 
// Error handling 
} 
 
 
public void NotifyStop(ECLScreenDesc *sd, ECLPS *ps, int Reason) { 
// Possible stop monitoring, not essential 
} 
} 
 
}
 
int main() { 
MyApp app = new MyApp(); 
app.showMainGUI(); 
} 

Derivation

ECLBase > ECLScreenReco

ECLScreenReco Methods

The following methods are valid for ECLScreenReco:

ECLScreenReco()
~ECLScreenReco()
AddPS(ECLPS*)
IsMatch(ECLPS*, ECLScreenDesc*)
RegisterScreen(ECLScreenDesc*, ECLRecoNotify*)
RemovePS(ECLPS*)
UnregisterScreen(ECLScreenDesc*)

ECLScreenReco Constructor

Creates an empty instance of ECLScreenReco

Prototype

ECLScreenReco()

Parameters

None

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

ECLScreenReco Destructor

Destroys the instance of ECLScreenReco

Prototype

~ECLScreenReco()

Parameters

None

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

AddPS

Adds Presentation Space object to monitor.

Prototype

AddPS(ECLPS*)

Parameters

ECLPS*
PS object to monitor.

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

IsMatch

Static member method that allows for passing an ECLPS object and an ECLScreenDesc object and determining if the screen description matches the PS. It is provided as a static method so any routine can call it without creating an ECLScreenReco object.

Prototype

IsMatch(ECLPS*, ECLScreenDesc*)

Parameters

ECLPS*
ECLPS object to compare.
ECLScreenDesc*
ECLScreenDesc object to compare.

Return Value

TRUE if the screen in PS matches, FALSE otherwise.

Example

// set up PS
ECLPS ps = new ECLPS('A');
 
// set up screen description
ECLScreenDesc eclSD = new ECLScreenDesc();
eclSD.AddAttrib(0xe8, 1, 1, ColorPlane);
eclSD.AddCursorPos(23,1);
eclSD.AddNumFields(45);
eclSD.AddNumInputFields(17);
AddOIAInhibitStatus(NOTINHIBITED);
eclSD.AddString("LOGON"., 23, 11, TRUE);
eclSD.AddStringInRect("PASSWORD", 23, 1, 24, 80, FALSE);
if(ECLScreenReco::IsMatch(ps,eclSD)) {
        // Handle Screen Match here . . .
}

RegisterScreen

Begins monitoring all ECLPS objects added to the screen recognition object for the given screen description. If the screen appears in the PS, the NotifyEvent method on the ECLRecoNotify object will be called.

Prototype

RegisterScreen(ECLScreenDesc*, ECLRecoNotify*)

Parameters

ECLScreenDesc*
Screen description object to register.
ECLRecoNotify*
Object that contains the callback code for the screen description.

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

RemovePS

Removes the ECLPS object from screen recognition monitoring.

Prototype

RemovePS(ECLPS*)

Parameters

ECLPS*
ECLPS object to remove.

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

UnregisterScreen

Removes the screen description and its callback code from screen recognition monitoring.

Prototype

UnregisterScreen(ECLScreenDesc*)

Parameters

ECLScreenDesc*
Screen description object to remove.

Return Value

None

Example

See the example of a common implementation provided in ECLScreenReco Class.

ECLSession Class

ECLSession provides general emulator connection-related services and contains pointers to instances of other objects in the Host Access Class Library.

Derivation

ECLBase > ECLConnection > ECLSession

Properties

None

Usage Notes

Because ECLSession is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

Although the objects ECLSession contains are capable of standing on their own, pointers to them exist in the ECLSession class. When an ECLSession object is created, ECLPS, ECLOIA, ECLXfer, and ECLWinMetrics objects are also created.

ECLSession Methods

The following section describes the methods that are valid for the ECLSession class:

ECLSession(char Name)
ECLSession(Long Handle)
~ECLSession()
ECLPS *GetPS()
ECLOIA *GetOIA()
ECLXfer *GetXfer()
ECLWinMetrics *GetWinMetrics()
void RegisterUpdateEvent(UPDATETYPE Type, ECLUpdateNotify *UpdateNotifyClass,
       BOOL InitEvent)
void UnregisterUpdateEvent(ECLUpdateNotify *UpdateNotifyClass,)

ECLSession Constructor

This method creates an ECLSession object from a connection name (a single, alphabetic character from A-Z or a-z) or a connection handle. There can be only one Z and I Emulator for Windows connection open with a given name. For example, there can only be one connection "A" open at a time.

Prototype

ECLSession(char Name)

ECLSession(long Handle)

Parameters

char Name
One-character short name of the connection (A-Z or a-z).
long Handle
Handle of an ECL connection.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLSession::ECLSession      (Constructor)
//
// Build PS object from name.
//-------------------------------------------------------------------
void Sample73() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLPS      *PS;         // PS object pointer
 
try {
  Sess = new ECLSession('A');
 
  PS = Sess->GetPS();
  printf("Size of presentation space is %lu.\n", PS->GetSize());
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

ECLSession Destructor

This method destroys an ECLSession object.

Prototype

~ECLSession();

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLSession::~ECLSession      (Destructor)
//
// Build PS object from name and then delete it.
//-------------------------------------------------------------------
void Sample74() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLPS      *PS;         // PS object pointer
 
try {
  Sess = new ECLSession('A');
 
  PS = Sess->GetPS();
  printf("Size of presentation space is %lu.\n", PS->GetSize());
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

GetPS

This method returns a pointer to the ECLPS object contained in the ECLSession object. Use this method to access the ECLPS object methods. See ECLPS Class for more information.

Prototype

ECLPS *GetPS()

Parameters

None

Return Value

ECLPS *
ECLPS object pointer.

Example

//-------------------------------------------------------------------
// ECLSession::GetPS
//
// Get PS object from session object and use it.
//-------------------------------------------------------------------
void Sample69() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLPS      *PS;         // PS object pointer
 
try {
  Sess = new ECLSession('A');
 
  PS = Sess->GetPS();
  printf("Size of presentation space is %lu.\n", PS->GetSize());
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

GetOIA

This method returns a pointer to the ECLOIA object contained in the ECLSession object. Use this method to access the ECLOIA methods. See ECLOIA Class for more information.

Prototype

ECLOIA *GetOIA()

Parameters

None

Return Value

ECLOIA *
ECLOIA object pointer.

Example

//-------------------------------------------------------------------
// ECLSession::GetOIA
//
// Get OIA object from session object and use it.
//-------------------------------------------------------------------
void Sample70() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLOIA     *OIA;        // OIA object pointer
 
try {
  Sess = new ECLSession('A');
 
  OIA = Sess->GetOIA();
  if (OIA->InputInhibited() == NotInhibited)
    printf("Input is not inhibited.\n");
  else
    printf("Input is inhibited.\n");
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

GetXfer

This method returns a pointer to the ECLXfer object contained in the ECLSession object. Use this method to access the ECLXfer methods. See ECLXfer Class for more information.

Prototype

ECLXfer *GetXfer()

Parameters

None

Return Value

ECLXfer *
ECLXfer object pointer.

Example

//-------------------------------------------------------------------
// ECLSession::GetXfer
//
// Get OIA object from session object and use it.
//-------------------------------------------------------------------
void Sample71() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLXfer    *Xfer;       // Xfer object pointer
 
try {
  Sess = new ECLSession('A');
 
  Xfer = Sess->GetXfer();
  Xfer->SendFile("c:\\autoexec.bat", "AUTOEXEC BAT A", "(ASCII CRLF");
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

GetWinMetrics

This method returns a pointer to the ECLWinMetrics object contained in the ECLSession object. Use this method to access the ECLWinMetrics methods. See ECLWinMetrics Class for more information.

Prototype

ECLWinMetrics *GetWinMetrics()

Parameters

None

Return Value

ECLWinMetrics *
ECLWinMetrics object pointer.

Example

//-------------------------------------------------------------------
// ECLSession::GetWinMetrics
//
// Get WinMetrics object from session object and use it.
//-------------------------------------------------------------------
void Sample72() {
 
ECLSession *Sess;       // Pointer to Session object for connection A
ECLWinMetrics *Metrics; // WinMetrics object pointer
 
try {
  Sess = new ECLSession('A');
 
  Metrics = Sess->GetWinMetrics();
  printf("Window height is %lu pixels.\n", Metrics->GetHeight());
 
  delete Sess;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
} // end sample
 
 

GetPageSettings

This method returns a pointer to the ECLPageSettings object contained in the ECLSession object. Use this method to access the ECLPageSettings methods. See ECLPageSettings Class for more information.

Prototype

ECLPageSettings *GetPageSettings() const;

Parameters

None

Return Value

ECLPageSettings *
ECLPageSettings object pointer.

Example

//--------------------------------------------------------------------
// ECLSession::GetPageSettings
//
// Get PageSettings object from session object and use it.
//--------------------------------------------------------------------
void Sample124() {
   ECLSession *Sess;       // Pointer to Session object for connection A
   ECLPageSettings *PgSet; // PageSettings object pointer

   try {
      Sess = new ECLSession('A');
      PgSet = Sess->GetPageSettings();
      printf("FaceName = %s\n", PgSet->GetFontFaceName());
      delete Sess;
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

GetPrinterSettings

This method returns a pointer to the ECLPrinterSettings object contained in the ECLSession object. Use this method to access the ECLPrinterSettings methods. See ECLPageSettings Class for more information.

Prototype

ECLPrinterSettings *GetPrinterSettings() const;

Parameters

None

Return Value

ECLPrinterSettings *
ECLPrinterSettings object pointer.

Example

//--------------------------------------------------------------------
// ECLSession::GetPrinterSettings
//
// Get PrinterSettings object from session object and use it.
//--------------------------------------------------------------------
void Sample125() {
   ECLSession *Sess;        // Pointer to Session object for connection A
   ECLPrinterSettings *PrSet; // PrinterSettings object pointer

   try {
      Sess = new ECLSession('A');
      PrSet = Sess->GetPrinterSettings();
      if (PrSet->IsPDTMode())
         printf("PDTMode\n");
      else
         printf("Not PDTMode\n");
      delete Sess;
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

RegisterUpdateEvent

Deprecated. See ECLPS::RegisterPSEvent in RegisterPSEvent.

UnregisterUpdateEvent

Deprecated. See ECLPS::UnregisterPSEvent in UnregisterPSEvent.

ECLStartNotify Class

ECLStartNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLStartNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLStartNotify class is used to allow an application to be notified of the starting and stopping of ZIEWin connections. Start/stop events are generated whenever a ZIEWin connection (window) is started or stopped by any means, including the ECLConnMgr start/stop methods.

To be notified of start/stop events, the application must perform the following steps:

  1. Define a class derived from ECLStartNotify.
  2. Implement the derived class and implement the NotifyEvent() member function.
  3. Optionally implement the NotifyError() and/or NotifyStop() functions.
  4. Create an instance of the derived class.
  5. Register the instance with the ECLConnMgr::RegisterStartEvent() function.

The example shown demonstrates how this may be done. When the above steps are complete, each time a connection is started or stopped the applications NotifyEvent() member function will be called. The function is passed two parameters giving the handle of the connection, and a BOOL start/stop indicator. The application may perform any functions required in the NotifyEvent() procedure, including calling other ECL functions. Note that the application cannot prevent the stopping of a connection; the notification is made after the session is already stopped.

If an error is detected during event generation, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error, depending on the nature of the error. When event generation terminates (either due to an error, by calling the ECLConnMgr::UnregisterStartEvent, or by destruction of the ECLConnMgr object) the NotifyStop() member function is called. However event notification is terminated, the NotifyStop() member function is always called, and the application object is unregistered.

If the application does not provide an implementation of the NotifyError() member function, the default implementation is used (a simple message box is displayed to the user). The application can override the default behavior by implementing the NotifyError() function in the applications derived class. Likewise, the default NotifyStop() function is used if the application does not provide this function (the default behavior is to do nothing).

Note that the application can also choose to provide its own constructor and destructor for the derived class. This can be useful if the application wants to store some instance-specific data in the class and pass that information as a parameter on the constructor. For example, the application may want to post a message to an application window when a start/stop event occurs. Rather than define the window handle as a global variable (so it would be visible to the NotifyEvent() function), the application can define a constructor for the class which takes the window handle and stores it in the class member data area.

The application must not destroy the notification object while it is registered to receive events.

Implementation Restriction:Currently, the ECLConnMgr object allows only one notification object to be registered for a start/stop event notification. The ECLConnMgr::RegisterStartEvent will throw an error if a notify object is already registered for that ECLConnMgr object.

Derivation

ECLBase > ECLNotify > ECLStartNotify

Example

//-------------------------------------------------------------------
// ECLStartNotify class
//
// This sample demonstrates the use of:
//
// ECLStartNotify::NotifyEvent
// ECLStartNotify::NotifyError
// ECLStartNotify::NotifyStop
// ECLConnMgr::RegisterStartEvent
// ECLConnMgr::UnregisterStartEvent
//-------------------------------------------------------------------
 
//...................................................................
// Define a class derived from ECLStartNotify
//...................................................................
class MyStartNotify: public ECLStartNotify
{
public:
  // Define my own constructor to store instance data
  MyStartNotify(HANDLE DataHandle);
 
  // We have to implement this function
  void	NotifyEvent(ECLConnMgr *CMObj, long ConnHandle,
                    BOOL Started);
 
  // We will take the default behaviour for these so we
  // don't implement them in our class:
  // void NotifyError (ECLConnMgr *CMObj, long ConnHandle, ECLErr ErrObject);
  // void NotifyStop (ECLConnMgr *CMObj, int Reason);
 
private:
  // We will store our application data handle here
  HANDLE MyDataH;
};
 
 //...................................................................
MyStartNotify::MyStartNotify(HANDLE DataHandle)   // Constructor
//...................................................................
{
  MyDataH = DataHandle;  // Save data handle for later use
}
 
//...................................................................
void	MyStartNotify::NotifyEvent(ECLConnMgr *CMObj, long ConnHandle,
                    BOOL Started)
//...................................................................
{
  // This function is called whenever a connection start or stops.
 
  if (Started)
    printf("Connection %c started.\n", CMObj->ConvertHandle2ShortName(ConnHandle));
  else
    printf("Connection %c stopped.\n", CMObj->ConvertHandle2ShortName(ConnHandle));
 
  return;
}
 
 //...................................................................
// Create the class and begin start/stop monitoring.
//...................................................................
void Sample75() {
 
ECLConnMgr    CMgr;     // Connection manager object
MyStartNotify *Event;   // Ptr to my event handling object
HANDLE InstData;	    	// Handle to application data block (for example)
 
try {
  Event = new MyStartNotify(InstData);  // Create event handler
 
  CMgr.RegisterStartEvent(Event);       // Register to get events
 
  // At this point, any connection start/stops will cause the
  // MyStartEvent::NotifyEvent() function to execute.  For
  // this sample, we put this thread to sleep during this
  // time.
 
  printf("Monitoring connection start/stops for 60 seconds...\n");
  Sleep(60000);
 
  // Now stop event generation.
  CMgr.UnregisterStartEvent(Event);
  printf("Start/stop monitoring ended.\n");
 
  delete Event;  // Don't delete until after unregister!
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

ECLStartNotify Methods

The following section describes the methods that are valid for the ECLStartNotify class.

ECLStartNotfiy()
ECLStartNotify()
virtual int NotifyEvent (ECLConnMgr *CMObj, long ConnHandle,
                         BOOL Started) = 0
virtual void NotifyError  (ECLConnMgr *CMObj, long ConnHandle,
                         ECLErr ErrObject)
virtual void NotifyStop (ECLConnMgr *CMObj int Reason)

NotifyEvent

This method is a pure virtual member function (the application must implement this function in classes derived from ECLStartNotify). This function is called whenever a connection starts or stops and the object is registered for start/stop events. The Started BOOL is TRUE if the connection is started, or FALSE if is stopped.

Prototype

virtual int NotifyEvent (ECLConnMgr  *CMObj, long ConnHandle,
                         BOOL Started) = 0

Parameters

ECLConnMgr *CMObj
This is the pointer to ECLConnMgr object in which the event occurred.
long ConnHandle
This is the handle of the connection that started or stopped.
BOOL Started
This is TRUE if the connection is started, or FALSE if the connection is stopped.

Return Value

None

NotifyError

This method is called whenever the ECLConnMgr object detects an error event generation. The error object contains information about the error (see the ECLErr class description). Events may continue to be generated after the error, depending on the nature of the error. If event generation stops due to an error, the NotifyStop() function is called.

The ConnHandle contains the handle of the connection that is related to the error. This value may be zero if the error is not related to any specific connection.

An application can choose to implement this function or allow the ECLStartNotify base class to handle the error. The base class will display the error in a message box using the text supplied by the ECLErr::GetMsgText() function. If the application implements this function in its derived class it will override the base class function.

Prototype

virtual void NotifyError  (ECLConnMgr  *CMObj, long ConnHandle,
                  ECLErr ErrObject)

Parameters

ECLConnMgr *CMObj
This is the ptr to ECLConnMgr object in which the error occurred.
long ConnHandle
This is the handle of the connection related to the error or zero.
ECLErr ErrObject
This is theECLErr object describing the error.

Return Value

None

NotifyStop

This method is called when event generation is stopped for any reason (for example, due to an error condition or a call to ECLConnMgr::UnregisterStartEvent).

Prototype

virtual void NotifyStop   (ECLConnMgr *CMObj int Reason)

Parameters

ECLConnMgr *CMObj
This is the ptr to ECLConnMgr object that is stopping notification.
int Reason
This is the unused zero.

Return Value

None

ECLUpdateNotify Class

Deprecated. See the class descriptions in ECLPSListener Class and ECLOIA Class.

ECLWinMetrics Class

The ECLWinMetrics class performs operations on a Z and I Emulator for Windows connection window. It allows you to perform window rectangle and position manipulation (for example, SetWindowRect, GetXpos or SetWidth), as well as window state manipulation (for example, SetVisible or IsRestored).

Derivation

ECLBase > ECLConnection > ECLWinMetrics

Properties

None

Usage Notes

Because ECLWinMetrics is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

The ECLWinMetrics object is created for the connection identified upon construction. You may create an ECLWinMetrics object by passing either the connection ID (a single, alphabetical character from A-Z or a-z) or the connection handle, which is usually obtained from the ECLConnection object. There can be only one Z and I Emulator for Windows connection with a given name or handle open at a time.

Note:
There is a pointer to the ECLWinMetrics object in the ECLSession class. If you just want to manipulate the connection window, create ECLWinMetrics on its own. If you want to do more, you may want to create an ECLSession object.

ECLWinMetrics Methods

The following methods apply to the ECLWinMetrics class.

ECLWinMetrics(char Name)
ECLWinMetrics(long Handle)
~ECLWinMetrics()
const char *GetWindowTitle()
void SetWindowTitle(char *NewTitle)
long GetXpos()
void SetXpos(long NewXpos)
long GetYpos()
void SetYpos(long NewYpos)
long GetWidth()
void SetWidth(long NewWidth)
long GetHeight()
void SetHeight(long NewHeight)
void GetWindowRect(Long *left, Long *top, Long *right, Long *bottom)
void SetWindowRect(Long left, Long top, Long right, Long bottom)
BOOL IsVisible()
void SetVisible(BOOL SetFlag)
BOOL Active()
void SetActive(BOOL SetFlag)
BOOL IsMinimized()
void SetMinimized()
BOOL IsMaximized()
void SetMaximized()
BOOL IsRestored()
void SetRestored()

ECLWinMetrics Constructor

This method creates an ECLWinMetrics object from a connection name or connection handle. There can be only one Z and I Emulator for Windows connection open with a given name. For example, there can be only one connection "A" open at a time.

Prototype

ECLWinMetrics(char Name)

ECLWinMetrics(long Handle)

Parameters

char Name
One-character short name of the connection (A-Z or a-z).
long Handle
Handle of an ECL connection.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::ECLWinMetrics   (Constructor)
//
// Build WinMetrics object from name.
//-------------------------------------------------------------------
void Sample77() {
 
ECLWinMetrics *Metrics;    // Ptr to object
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  printf("Window of connection A is %lu pixels wide.\n",
    Metrics->GetWidth());
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

ECLWinMetrics Destructor

This method destroys a ECLWinMetrics object.

Prototype

~ECLWinMetrics()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::ECLWinMetrics   (Destructor)
//
// Build WinMetrics object from name.
//-------------------------------------------------------------------
void Sample78() {
 
ECLWinMetrics *Metrics;    // Ptr to object
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  printf("Window of connection A is %lu pixels wide.\n",
    Metrics->GetWidth());
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

GetWindowTitle

The GetWindowTitle method returns a pointer to a null terminate string containing the title that is currently in the title bar for the connection associated with the ECLWinMetrics object. Do not assume that the string returned is persistent over time. You must either make a copy of the string or make a call to this method each time you need it.

Prototype

const char *GetWindowTitle()

Parameters

None

Return Value

Pointer to null terminated string that contains the title.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::GetWindowTitle
//
// Display current window title of connection A.
//-------------------------------------------------------------------
void Sample79() {
 
ECLWinMetrics *Metrics;    // Ptr to object
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  printf("Title of connection A is: %s\n",
    Metrics->GetWindowTitle());
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SetWindowTitle

The SetWindowTitle method changes the title currently in the title bar for the connection associated with the ECLWinMetrics object to the title passed in the input parameter. A null string can be used to reset the title to the default title.

Prototype

void SetWindowTitle(char *NewTitle)

Parameters

char *NewTitle
Null-terminated title string.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetWindowTitle
//
// Change current window title of connection A.
//-------------------------------------------------------------------
void Sample80() {
 
ECLWinMetrics *Metrics;    // Ptr to object
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  // Get current title
  printf("Title of connection A is: %s\n", Metrics->GetWindowTitle());
 
  // Set new title
  Metrics->SetWindowTitle("New Title");
  printf("New title is: %s\n", Metrics->GetWindowTitle());
 
  // Reset back to original title
  Metrics->SetWindowTitle("");
  printf("Returned title to: %s\n", Metrics->GetWindowTitle());
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

Usage Notes

If NewTitle is a null string, SetWindowTitle will restore the window title to its original setting.

GetXpos

The GetXpos method returns the x position of the upper left point of the connection window rectangle.

Prototype

long GetXpos()

Parameters

None

Return Value

long
x position of connection window.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::GetXpos
//
// Move window 10 pixels.
//-------------------------------------------------------------------
void Sample81() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot move minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetXpos();
    Y = Metrics->GetYpos();
    Metrics->SetXpos(X+10);
    Metrics->SetYpos(Y+10);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SetXpos

The SetXpos method sets the x position of the upper left point of the connection window rectangle.

Prototype

void SetXpos(long NewXpos)

Parameters

long NewXpos
The new x coordinate of the window rectangle.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetXpos
//
// Move window 10 pixels.
//-------------------------------------------------------------------
void Sample83() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot move minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetXpos();
    Y = Metrics->GetYpos();
    Metrics->SetXpos(X+10);
    Metrics->SetYpos(Y+10);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

GetYpos

The GetYpos method returns the y position of the upper left point of the connection window rectangle.

Prototype

long GetYpos()

Parameters

None

Return Value

long
y position of the connection window.

Example

a//-------------------------------------------------------------------
// ECLWinMetrics::GetYpos
//
// Move window 10 pixels.
//-------------------------------------------------------------------
void Sample82() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot move minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetXpos();
    Y = Metrics->GetYpos();
    Metrics->SetXpos(X+10);
    Metrics->SetYpos(Y+10);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SetYpos

The SetYpos method sets the y position of the upper left point of the connection window rectangle.

Prototype

void SetYpos(long NewYpos)

Parameters

long NewYpos
New y coordinate of the window rectangle.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetYpos
//
// Move window 10 pixels.
//-------------------------------------------------------------------
void Sample84() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot move minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetXpos();
    Y = Metrics->GetYpos();
    Metrics->SetXpos(X+10);
    Metrics->SetYpos(Y+10);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

GetWidth

This method returns the width of the connection window rectangle.

Prototype

long GetWidth()

Parameters

None

Return Value

long
Width of the connection window.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::GetWidth
//
// Make window 1/2 its current size.  Depending on display settings
// (Appearance->Display Setup menu) it may snap to a font that is
// not exactly the 1/2 size we specify.
//-------------------------------------------------------------------
void Sample85() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot size minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetWidth();
    Y = Metrics->GetHeight();
    Metrics->SetWidth(X/2);
    Metrics->SetHeight(Y/2);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
  

SetWidth

The SetWidth method sets the width of the connection window rectangle.

Prototype

void SetWidth(long NewWidth)

Parameters

long NewWidth
New width of the window rectangle.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetWidth
//
// Make window 1/2 its current size.  Depending on display settings
// (Appearance->Display Setup menu) it may snap to a font that is
// not exactly the 1/2 size we specify.
//-------------------------------------------------------------------
void Sample87() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot size minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetWidth();
    Y = Metrics->GetHeight();
    Metrics->SetWidth(X/2);
    Metrics->SetHeight(Y/2);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 

GetHeight

The GetHeight method returns the height of the connection window rectangle.

Prototype

long GetHeight()

Parameters

None

Return Value

long
Height of the connection window.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::GetHeight
//
// Make window 1/2 its current size.  Depending on display settings
// (Appearance->Display Setup menu) it may snap to a font that is
// not exactly the 1/2 size we specify.
//-------------------------------------------------------------------
void Sample86() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot size minimized or maximized window.\n");
  }
  else {
    X = Metrics->GetWidth();
    Y = Metrics->GetHeight();
    Metrics->SetWidth(X/2);
    Metrics->SetHeight(Y/2);
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SetHeight

This method sets the height of the connection window rectangle.

Prototype

void SetHeight(Long NewHeight)

Parameters

long NewHeight
New height of the window rectangle.

Return Value

None

Example

The following example shows how to use the SetHeight method to set the height of the connection window rectangle.

ECLWinMetrics	  *pWM;
ECLConnList  ConnList();			
 
// Create using connection handle of first connection in the list of
// active connections
try {
  if ( ConnList.Count() != 0 ) {
    pWM = new ECLWinMetrics(ConnList.GetFirstSession()->GetHandle());
 
    // Set the height
    pWM->SetHeight(6081);
  }
}
catch (ECLErr ErrObj) {
  // Just report the error text in a message box
  MessageBox( NULL, ErrObj.GetMsgText(), "Error!", MB_OK );
}

GetWindowRect

This method returns the bounding points of the connection window rectangle.

Prototype

void GetWindowRect(Long *left, Long *top, Long *right, Long *bottom)

Parameters

long *left
This output parameter is set to the left coordinate of the window rectangle.
long *top
This output parameter is set to the top coordinate of the window rectangle.
long *right
This output parameter is set to the right coordinate of the window rectangle.
long *bottom
This output parameter is set to the bottom coordinate of the window rectangle.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::GetWindowRect
//
// Make window 1/2 its current size.  Depending on display settings
// (Appearance->Display Setup menu) it may snap to a font that is
// not exactly the 1/2 size we specify.  Also move the window.
//-------------------------------------------------------------------
void Sample88() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y, Width, Height;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot size/move minimized or maximized window.\n");
  }
  else {
    Metrics->GetWindowRect(&X, &Y, &Width, &Height);
    Metrics->SetWindowRect(X+10, Y+10,         // Move window
                           Width/2, Height/2); // Size window
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SetWindowRect

This method sets the bounding points of the connection window rectangle.

Prototype

void SetWindowRect(long left, long top, long right, long bottom)

Parameters

long left
The left coordinate of the window rectangle.
long top
The top coordinate of the window rectangle.
long right
The right coordinate of the window rectangle.
long bottom
The bottom coordinate of the window rectangle.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetWindowRect
//
// Make window 1/2 its current size.  Depending on display settings
// (Appearance->Display Setup menu) it may snap to a font that is
// not exactly the 1/2 size we specify.  Also move the window.
//-------------------------------------------------------------------
void Sample89() {
 
ECLWinMetrics *Metrics;    // Ptr to object
long X, Y, Width, Height;
 
try {
  Metrics = new ECLWinMetrics('A');  // Create for connection A
 
  if (Metrics->IsMinimized() || Metrics->IsMaximized()) {
    printf("Cannot size/move minimized or maximized window.\n");
  }
  else {
    Metrics->GetWindowRect(&X, &Y, &Width, &Height);
    Metrics->SetWindowRect(X+10, Y+10,         // Move window
                           Width/2, Height/2); // Size window
  }
 
  delete Metrics;
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

IsVisible

This method returns the visibility state of the connection window.

Prototype

BOOL IsVisible()

Parameters

None

Return Value

Visibility state. TRUE value if the window is visible, FALSE value if the window is not visible.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::IsVisible
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample90() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsVisible(); // Get state
Metrics.SetVisible(!CurrState);  // Set state
 
} // end sample
 
 

SetVisible

This method sets the visibility state of the connection window.

Prototype

void SetVisible(BOOL SetFlag)

Parameters

BOOL SetFlag
TRUE for visible, FALSE for invisible.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetVisible
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample91() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsVisible(); // Get state
Metrics.SetVisible(!CurrState);  // Set state
 
} // end sample
 
//-------------------------------------------------------------------

IsActive

This method returns the focus state of the connection window.

Prototype

BOOL Active()

Parameters

None

Return Value

BOOL
Focus state. TRUE if active, FALSE if not active.

Example

 
// ECLWinMetrics::IsActive
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample92() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsActive();  // Get state
Metrics.SetActive(!CurrState);   // Set state
 
} // end sample
 

SetActive

This method sets the focus state of the connection window.

Prototype

void SetActive(BOOL SetFlag)

Parameters

Bool SetFlag
New state. TRUE for active, FALSE for inactive.

Return Value

None

Example

The following is an example of the SetActive method.

ECLWinMetrics	*pWM;
ECLConnList  ConnList();			
 
// Create using connection handle of first connection in the list of
// active connections
try {
  if ( ConnList.Count() != 0 ) {
    pWM = new ECLWinMetrics(ConnList.GetFirstSession()->GetHandle());
 
    // Set to inactive if active
    if ( pWM->Active() )
	  pWM->SetActive(FALSE);
  }
}
catch (ECLErr ErrObj) {
  // Just report the error text in a message box
  MessageBox( NULL, ErrObj.GetMsgText(), "Error!", MB_OK );
}

IsMinimized

This method returns the minimize state of the connection window.

Prototype

BOOL IsMinimized()

Parameters

None

Return Value

BOOL
Minimize state. TRUE value returned if the window is minimized; FALSE value returned if the window is not minimized.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::IsMinimized
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample93() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsMinimized();  // Get state
if (!CurrState)
  Metrics.SetMinimized();           // Set state
else
  Metrics.SetRestored();
 
} // end sample
 
 

SetMinimized

This method sets the connection window to minimized

Prototype

void SetMinimized()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetMinimized
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample94() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsMinimized();  // Get state
if (!CurrState)
  Metrics.SetMinimized();           // Set state
else
  Metrics.SetRestored();
 
} // end sample
 
 

IsMaximized

This method returns the maximize state of the connection window.

Prototype

BOOL IsMaximized()

Parameters

None

Return Value

BOOL
Maximize state. TRUE value if the window is maximized; FALSE value if the window is not maximized.

Example

// ECLWinMetrics::IsMaximized
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample97() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsMaximized();  // Get state
if (!CurrState)
  Metrics.SetMaximized();           // Set state
else
  Metrics.SetMinimized();
 
} // end sample
 
 

SetMaximized

This method sets the connection window to maximized.

Prototype

void SetMaximized()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetMaximized
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample98() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsMaximized();  // Get state
if (!CurrState)
  Metrics.SetMaximized();           // Set state
else
  Metrics.SetMinimized();
 
} // end sample
 
 

IsRestored

This method returns the restore state of the connection window.

Prototype

BOOL IsRestored()

Parameters

None

Return Value

BOOL
Restore state. TRUE value if the window is restored; FALSE value if the window is not restored.

Example

//-------------------------------------------------------------------
// ECLWinMetrics::IsRestored
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample95() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsRestored();  // Get state
if (!CurrState)
  Metrics.SetRestored();           // Set state
else
  Metrics.SetMinimized();
 
} // end sample
 
 

SetRestored

The SetRestored method sets the connection window to restored.

Prototype

void SetRestored()

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLWinMetrics::SetRestored
//
// Get current state of window, and then toggle it.
//-------------------------------------------------------------------
void Sample96() {
 
ECLWinMetrics Metrics('A');      // Window metrics class
BOOL  CurrState;
 
CurrState = Metrics.IsRestored();  // Get state
if (!CurrState)
  Metrics.SetRestored();           // Set state
else
  Metrics.SetMinimized();
 
} // end sample
 
//-------------------------------------------------------------------
 

ECLXfer Class

ECLXfer provides file transfer services.

Derivation

ECLBase > ECLConnection > ECLXfer

Properties

None

Usage Notes

Because ECLXfer is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

The ECLXfer object is created for the connection identified upon construction. You may create an ECLXfer object by passing either the connection ID (a single, alphabetic character from A-Z or a-z) or the connection handle, which is usually obtained from the ECLConnList object. There can be only one Z and I Emulator for Windows connection with a given name or handle open at a time.

Note:
There is a pointer to the ECLXfer object in the ECLSession class. If you only want to manipulate the connection window, create an ECLXfer object on its own. If you want to do more, you may want to create an ECLSession object.

ECLXfer Methods

The following section describes the methods that are valid for the ECLXfer class:

ECLXfer(char Name)
ECLXfer(long Handle)
~ECLXfer()
int SendFile(char *PCFile, char *HostFile, char *Options)
int ReceiveFile(char *PCFile, char *HostFile, char *Options)

ECLXfer Constructor

This method creates an ECLXfer object from a connection ID (a single, alphabetic character from A-Z or a-z) or a connection handle. There can be only one Z and I Emulator for Windows connection open with a given ID. For example, there can be only one connection "A" open at a time.

Prototype

ECLXfer(char Name)

ECLXfer(long Handle)

Parameters

char Name
One-character short name of the connection (A-Z or a-z).
long Handle
Handle of an ECL connection.

Return Value

None

Example

//-------------------------------------------------------------------
// ECLXfer::ECLXfer          (Constructor)
//
// Build ECLXfer object from a connection name.
//-------------------------------------------------------------------
void Sample99() {
 
ECLXfer  *Xfer;             // Pointer to Xfer object
 
try {
  Xfer = new ECLXfer('A');  // Create object for connection A
  printf("Created ECLXfer for connection %c.\n", Xfer->GetName());
 
  delete Xfer;              // Delete Xfer object
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

ECLXfer Destructor

This method destroys an ECLXfer object.

Prototype

~ECLXfer();

Parameters

None

Return Value

None

Example

//-------------------------------------------------------------------
// ECLXfer::~ECLXfer          (Destructor)
//
// Build ECLXfer object from a connection name.
//-------------------------------------------------------------------
void Sample100() {
 
ECLXfer  *Xfer;             // Pointer to Xfer object
 
try {
  Xfer = new ECLXfer('A');  // Create object for connection A
  printf("Created ECLXfer for connection %c.\n", Xfer->GetName());
 
  delete Xfer;              // Delete Xfer object
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

SendFile

This method sends a file from the workstation to the host.

Prototype

int SendFile(char *PCFile, char *HostFile, char *Options)

Parameters

char *PCFile
Pointer to a string containing the workstation file name to be sent to the host.
char *HostFile
Pointer to a string containing the host file name to be created or updated on the host.
char *Options
Pointer to a string containing the options to be used during the transfer.

Return Value

int
EHLLAPI return code as documented in Emulator Programming for the SendFile EHLLAPI function.

Example

//-------------------------------------------------------------------
// ECLXfer::SendFile
//
// Send a file to a VM/CMS host with ASCII translation.
//-------------------------------------------------------------------
void Sample101() {
 
ECLXfer  *Xfer;             // Pointer to Xfer object
int Rc;
 
try {
  Xfer = new ECLXfer('A');  // Create object for connection A
 
  printf("Sending file...\n");
  Rc = Xfer->SendFile("c:\\autoexec.bat", "autoexec bat a", "(ASCII CRLF QUIET");
  switch (Rc) {
  case 2:
    printf("File transfer failed, error in parameters.\n", Rc);
    break;
  case 3:
    printf("File transfer sucessfull.\n");
    break;
  case 4:
    printf("File transfer sucessfull, some records were segmented.\n");
    break;
  case 5:
    printf("File transfer failed, workstation file not found.\n");
    break;
  case 27:
    printf("File transfer cancelled or timed out.\n");
    break;
  default:
    printf("File transfer failed, code %u.\n", Rc);
    break;
  } // case
 
  delete Xfer;              // Delete Xfer object
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
 
 

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.

ReceiveFile

This method receives a file from the host and sends the file to the workstation.

Prototype

int ReceiveFile(char *PCFile, char *HostFile, char *Options)

Parameters

char *PCFile
Pointer to a string containing the workstation file name to be sent to the host.
char *HostFile
Pointer to a string containing the host file name to be created or updated on the host.
char *Options
Pointer to a string containing the options to be used during the transfer.

Return Value

int
EHLLAPI return code as documented in Emulator Programming for the ReceiveFile EHLLAPI function.

Example

//-------------------------------------------------------------------
// ECLXfer::ReceiveFile
//
// Receive file from a VM/CMS host with ASCII translation.
//-------------------------------------------------------------------
void Sample102() {
 
ECLXfer  *Xfer;             // Pointer to Xfer object
int Rc;
 
try {
  Xfer = new ECLXfer('A');  // Create object for connection A
 
  printf("Receiving file...\n");
  Rc = Xfer->ReceiveFile("c:\\temp.txt", "temp text a", "(ASCII CRLF QUIET");
  switch (Rc) {
  case 2:
    printf("File transfer failed, error in parameters.\n", Rc);
    break;
  case 3:
    printf("File transfer sucessfull.\n");
    break;
  case 4:
    printf("File transfer sucessfull, some records were segmented.\n");
    break;
  case 27:
    printf("File transfer cancelled or timed out.\n");
    break;
  default:
    printf("File transfer failed, code %u.\n", Rc);
    break;
  } // case
 
  delete Xfer;              // Delete Xfer object
}
catch (ECLErr Err) {
  printf("ECL Error: %s\n", Err.GetMsgText());
}
 
} // end sample
  

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.

ECLPageSettings Class

The ECLPageSettings class performs operations on the session page settings. It enables you to retrieve and configure the File -> Page Setup dialog settings, such as CPI, LPI, and Face Name. Only the settings in the Text tab of the dialog are supported.

Derivation

ECLBase > ECLConnection > ECLPageSettings

Properties

None

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 apply when any method of the ECLPageSettings class is invoked. If the restrictions are not met, an exception is thrown.

Additional restrictions might apply for each specific method.

Usage Notes

Because ECLPageSettings is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

The ECLPageSettings object is created for the connection identified upon construction. You can create an ECLPageSettings object by passing the connection ID (a single alphabetical character from A to Z) or the connection handle (usually obtained from the ECLConnection object). There can be only one Z and I Emulator for Windows connection with a given name or handle open at one time.

The ECLSession class creates an instance of this object. If the application does not need other services provided by ECLSession, you can create this object independently. Otherwise, consider creating an ECLSession object and use the objects created by ECLSession. See ECLSession Class for more information.

Each method supports only certain connection types of the connection associated with the ECLPageSettings object. The supported connection types are provided in each method section. If a method is called on an unsupported connection, an exception is thrown. Use the method GetConnType to determine the connection type.

CPI, LPI and FontSize are dependent on the property FaceName. Therefore, if CPI, LPI, and FontSize are set before the FaceName is set, and if the values are not valid for the FaceName property, then different CPI, LPI, or FontSize values might be reconfigured in the connection. You should set the FaceName value before setting the CPI, LPI, or FontSize. Or you can query CPI, LPI, and FontSize each time you set FaceName to ensure that they use the desired values.

ECLPageSettings Methods

The following sections describe the methods that are valid for the ECLPageSettings class.

ECLPageSettings(char Name)
ECLPageSettings(long Handle)
~ECLPageSettings()
void SetCPI(ULONG CPI=FONT_CPI)
ULONG GetCPI() const
BOOL  IsFontCPI()
void SetLPI(ULONG LPI=FONT_LPI)
ULONG GetLPI() const
BOOL  IsFontLPI()
void SetFontFaceName(const char *const FaceName)
const char *GetFontFaceName() const
void SetFontSize(ULONG FontSize)
ULONG GetFontSize()
void SetMaxLinesPerPage(ULONG MPL)
ULONG GetMaxLinesPerPage() const
void SetMaxCharsPerLine(ULONG MPP)
ULONG GetMaxCharsPerLine() const
void RestoreDefaults(ULONG Tabs=PAGE_TEXT) const

Connection types

The valid connection types for the ECLPageSettings methods are as follows:

Connection Type String Value
3270 display HOSTTYPE_3270DISPLAY
5250 display HOSTTYPE_5250DISPLAY
3270 printer HOSTTYPE_3270PRINTER
VT (ASCII) emulation HOSTTYPE_VT

ECLPageSettings Constructor

This method uses a connection name or handle to create an ECLPageSettings object.

Prototype

ECLPageSettings(char Name)

ECLPageSettings(long Handle)

Parameters

char Name
One-character short name of the connection. Valid values are A-Z.
long Handle
Handle of an ECL connection.

Return Value

None

Example

The following example shows how to create an ECLPageSettings object using the connection name and the connection handle.

void Sample108() {
   
   ECLPageSettings *PgSet1, *PgSet2; // Pointer to ECLPageSettings objects
   ECLConnList ConnList; // Connection list object

   try {
      // Create ECLPageSettings object for connection 'A'
      PgSet1 = new ECLPageSettings('A');
      // Create ECLPageSettings object for first connection in conn list
      ECLConnection *Connection = ConnList.GetFirstConnection();
      if (Connection != NULL) {
         PgSet2 = new ECLPageSettings(Connection->GetHandle()); 
         printf("PgSet#1 is for connection %c, PgSet #2 is for connection %c.\n",
                 PgSet1->GetName(), PgSet2->GetName());
         delete PgSet1;
         delete PgSet2;
      }
      else 
         printf("No connections to create PageSettings object.\n");
   } catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

SetCPI

This method sets the CPI (characters per inch) value in the connection. If this method is called without any arguments, it sets the Font CPI in the connection.

Prototype

void SetCPI(ULONG CPI=FONT_CPI);

Parameters

ULONG CPI
Characters per inch. This parameter is optional. The default value is FONT_CPI.

Return Value

None

Example

void Sample109() {

   ECLPageSettings PgSet('A');

   PgSet.SetCPI(10);
   ULONG cpi = PgSet.GetCPI();
   printf("CPI = %ld\n", cpi);
   if (PgSet.IsFontCPI())
      printf("FontCPI\n");
   else
      printf("Not FontCPI\n");
} // end sample

GetCPI

This method returns the CPI (characters per inch) value of the connection. Even if Font CPI is selected in the associated connection, this method returns the value of the CPI selected for the font in the associated connection.

If Font CPI is configured in the connection, this method does not return the constant FONT_CPI . Use the IsFontCPI method to determine whether Font CPI is set in the connection.

Prototype

ULONG GetCPI() const;

Parameters

None

Return Value

ULONG CPI
Characters per inch.

Example

void Sample109() {

   ECLPageSettings PgSet('A');

   PgSet.SetCPI(10);
   ULONG cpi = PgSet.GetCPI();
   printf("CPI = %ld\n", cpi);
   if (PgSet.IsFontCPI())
      printf("FontCPI\n");
   else
      printf("Not FontCPI\n");
} // end sample

IsFontCPI

This method returns an indication of whether Font CPI is set in the connection.

Prototype

BOOL IsFontCPI();

Parameters

None

Return Value

BOOL
Possible values are as follows:

Example

void Sample109() {

   ECLPageSettings PgSet('A');

   PgSet.SetCPI(10);
   ULONG cpi = PgSet.GetCPI();
   printf("CPI = %ld\n", cpi);
   if (PgSet.IsFontCPI())
      printf("FontCPI\n");
   else
      printf("Not FontCPI\n");
} // end sample

SetLPI

This method sets the LPI (lines per inch) value in the connection. If this method is called without any arguments, it sets the Font LPI in the connection.

Prototype

void SetLPI(ULONG LPI=FONT_LPI);

Parameters

ULONG LPI
Lines per inch. This parameter is optional. The default value is FONT_LPI.

Return Value

None

Example

void Sample110() {

   ECLPageSettings PgSet('A');

   PgSet.SetLPI(10);
   ULONG lpi = PgSet.GetLPI();
   printf("LPI = %ld\n", lpi);
   if (PgSet.IsFontLPI())
      printf("FontLPI\n");
   else
      printf("Not FontLPI\n");
} // end sample

GetLPI

This method returns the LPI (lines per inch) value of the connection. Even if Font LPI is selected in the associated connection, this method returns the value of the LPI selected for the font in the associated connection.

If Font LPI is configured in the connection, this method does not return the constant FONT_LPI. Use the IsFontLPI method to determine whether Font LPI is set in the connection.

Prototype

ULONG GetLPI() const;

Parameters

None

Return Value

ULONG LPI
Lines per inch.

Example

void Sample110() {

   ECLPageSettings PgSet('A');

   PgSet.SetLPI(10);
   ULONG lpi = PgSet.GetLPI();
   printf("LPI = %ld\n", lpi);
   if (PgSet.IsFontLPI())
      printf("FontLPI\n");
   else
      printf("Not FontLPI\n");
} // end sample

IsFontLPI

This method returns an indication of whether Font LPI is set in the associated connection.

Prototype

BOOL IsFontLPI();

Parameters

None

Return Value

BOOL
Possible values are as follows:

Example

void Sample110() {

   ECLPageSettings PgSet('A');

   PgSet.SetLPI(10);
   ULONG lpi = PgSet.GetLPI();
   printf("LPI = %ld\n", lpi);
   if (PgSet.IsFontLPI())
      printf("FontLPI\n");
   else
      printf("Not FontLPI\n");
} // end sample

SetFontFaceName

This method sets the font face in the connection.

Prototype

void SetFontFaceName(const char *const FaceName);

Parameters

char *FaceName
A null-terminated string that contains the font face name.

Return Value

None

Example

void Sample111() {

   ECLPageSettings PgSet('A');
   const char *Face;

   PgSet.SetFontFaceName("Courier New");
   Face = PgSet.GetFontFaceName();
   printf("FaceName = %s\n", Face);
} // end sample

GetFontFaceName

This method returns a pointer to a null-terminated string. The string contains the face name of the font that is currently chosen in the page settings for the connection that is associated with the ECLPageSettings object. The method might not return the same string each time.

The string is valid only for the lifetime of the object. You must either make a copy of the string or make a call to this method each time you need it.

Prototype

const char *GetFontFaceName() const;

Parameters

None

Return Value

char *
A pointer to a null-terminated string that contains the face name of the font.

Example

void Sample111() {

   ECLPageSettings PgSet('A');
   const char *Face;

   PgSet.SetFontFaceName("Courier New");
   Face = PgSet.GetFontFaceName();
   printf("FaceName = %s\n", Face);
} // end sample

SetFontSize

This method sets the size of the font.

Prototype

void SetFontSize(ULONG FontSize);

Parameters

ULONG FontSize
Size of the font to set in the connection.

Return Value

None

SetMaxLinesPerPage

This method sets the maximum number of lines that can be printed per page.

Prototype

void SetMaxLinesPerPage(ULONG MPL);

Parameters

ULONG MPL
The maximum lines per page (Maximum Print Lines). Valid values are in the range 1-255.

Return Value

None

Example

void Sample113() {

   ECLPageSettings PgSet('A');

   PgSet.SetMaxLinesPerPage(40);
   ULONG MPL = PgSet.GetMaxLinesPerPage();
   printf("MaxLinesPerPage = %ld\n", MPL);
} // end sample

GetMaxLinesPerPage

This method returns the maximum number of lines that can be printed per page.

Prototype

ULONG GetMaxLinesPerPage() const;

Parameters

None

Return Value

ULONG
The maximum lines per page (Maximum Print Lines).

Example

void Sample113() {

   ECLPageSettings PgSet('A');

   PgSet.SetMaxLinesPerPage(40);
   ULONG MPL = PgSet.GetMaxLinesPerPage();
   printf("MaxLinesPerPage = %ld\n", MPL);
} // end sample

SetMaxCharsPerLine

This method sets the maximum number of characters that can be printed per line.

Prototype

void SetMaxCharsPerLine(ULONG MPP);

Parameters

ULONG MPP
The maximum number of characters that can be printed per line (Maximum Print Position). Valid values are in the range 1-255.

Return Value

None

Example

void Sample114() {

   ECLPageSettings PgSet('A');

   PgSet.SetMaxCharsPerLine(50);
   ULONG MPP = PgSet.GetMaxCharsPerLine();
   printf("MaxCharsPerLine=%ld\n", MPP);
} // end sample

GetMaxCharsPerLine

This method returns the maximum number of characters that can be printed per line.

Prototype

ULONG GetMaxCharsPerLine() const;

Parameters

None

Return Value

ULONG
The maximum number of characters that can be printed per line (Maximum Print Position).

Example

void Sample114() {

   ECLPageSettings PgSet('A');

   PgSet.SetMaxCharsPerLine(50);
   ULONG MPP = PgSet.GetMaxCharsPerLine();
   printf("MaxCharsPerLine=%ld\n", MPP);
} // end sample

RestoreDefaults

This method restores the system default values of the property pages specified in the nFlags field of the PageSetup panel. This is equivalent to clicking the Default button in the connection Page Setup dialog property pages.

Prototype

void RestoreDefaults(ULONG Flags=PAGE_TEXT) const;

Parameters

ULONG Flags
This parameter is optional. The following flag describes the name of the specified Page Setup dialog property page. This flag can be bitwise ORed to restore the property page (defined in PCSAPI32.H).
PAGE_TEXT
This flag describes the Text property page. This is the only property page currently supported.

Return Value

None

Example

void Sample115() {

   ECLPageSettings PgSet('A');

   PgSet.RestoreDefaults(PAGE_TEXT);
} // end sample

ECLPrinterSettings Class

The ECLPrinterSettings class performs operations on the printer settings of the Z and I Emulator for Windows connection. It enables you to retrieve and configure the File -> Printer Setup dialog settings, such as Printer and PDT Mode.

Derivation

ECLBase > ECLConnection > ECLPrinterSettings

Properties

None

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 apply when any method of the ECLPrinterSettings class is invoked. If the restrictions are not met, an exception is thrown.

Additional restrictions might apply for each specific method.

Usage Notes

Because ECLPrinterSettings is derived from ECLConnection, you can obtain all the information contained in an ECLConnection object. See ECLConnection Class for more information.

The ECLPrinterSettings object is created for the connection identified upon construction. You can create an ECLPrinterSettings object by passing either the connection ID (a single alphabetical character from A to Z) or the connection handle (usually obtained from the ECLConnection object). There can be only one Z and I Emulator for Windows connection with a given name or handle open at one time.

The ECLSession class creates an instance of this object. If the application does not need other services provided by ECLSession, you can create this object independently. Otherwise, consider creating an ECLSession object and use the objects created by ECLSession. See ECLSession Class for more information.

ECLPrinterSettings Methods

The following sections describe the methods that are valid for the ECLPrinterSettings class.

ECLPrinterSettings(char Name)
ECLPrinterSettings(long Handle)
~ECLPrinterSettings()
void SetPDTMode(BOOL PDTMode=TRUE, const char*const PDTFile = NULL)
const char *GetPDTFile() const
BOOL IsPDTMode() const
ECLPrinterSettings::PrintMode GetPrintMode() const
void SetPrtToDskAppend(const char *const FileName = NULL)
const char *GetPrtToDskAppendFile()
void SetPrtToDskSeparate(const char *const FileName = NULL)
const char *GetPrtToDskSeparateFile()
void SetSpecificPrinter(const char *const PrinterName)
void SetWinDefaultPrinter()
const char*GetPrinterName()
void SetPromptDialog(BOOL Prompt=TRUE)
BOOL IsPromptDialogEnabled()

ECLPrinterSettings Constructor

This method uses a connection name or handle to create an ECLPrinterSettings object.

Prototype

ECLPrinterSettings(char Name)

ECLPrinterSettings(long Handle)

Parameters

char Name
One-character short name of the connection. Valid values are A-Z.
long Handle
Handle of an ECL connection.

Return Value

None

Example

The following example shows how to create an ECLPrinterSettings object using the connection name and the connection handle.

void Sample116() {
   ECLPrinterSettings *PrSet1, *PrSet2; // Pointer to ECLPrinterSettings objects
   ECLConnList ConnList; // Connection list object

   try {
      // Create ECLPrinterSettings object for connection 'A'
      PrSet1 = new ECLPrinterSettings('A');
      // Create ECLPrinterSettings object for first connection in conn list
      ECLConnection *Connection = ConnList.GetFirstConnection();
      if (Connection != NULL) {
         PrSet2 = new ECLPrinterSettings(Connection->GetHandle()); 
         printf("PrSet#1 is for connection %c, PrSet #2 is for connection %c.\n", 
            PrSet1->GetName(), PrSet2->GetName());
      delete PrSet1;
      delete PrSet2;
   } else 
      printf("No connections to create PageSettings object.\n");
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

SetPDTMode

This method sets the connection in PDT mode with the given PDT file, or it sets the connection in non-PDT mode (GDI mode).

Note:
If this method is called with PDTMode set to FALSE, PrintMode of the associated connection must already be SpecificPrinter or WinDefaultPrinter.

Prototype

void SetPDTMode(BOOL PDTMode=TRUE, const char *const PDTFile = NULL);

Parameters

BOOL PDTMode
This parameter is optional. Possible values are as follows:
char *PDTFile
Null-terminated string containing the name of the PDT file.

This parameter is optional. It is used only if PDTMode is TRUE. The parameter is ignored if PDTMode is FALSE.

Possible values are as follows:

Return Value

None

Example

void Sample117() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPDTMode(TRUE, "epson.pdt");
      const char *PDTFile = PrSet.GetPDTFile();
      printf("PDT File = %s\n", PDTFile);
      if (PrSet.IsPDTMode())
         printf("PDTMode\n");
      else
         printf("Not PDTMode\n");
      PrSet.SetPDTMode(FALSE);
      PrSet.SetPDTMode(TRUE);
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

GetPDTFile

This method returns the PDT file configured in the connection. The method might not return the same string each time.

The string is valid only for the lifetime of the object. You must either make a copy of the string or make a call to this method each time you need it.

Prototype

const char *GetPDTFile() const;

Parameters

None

Return Value

char *
Possible values are as follows:

Example

void Sample117() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPDTMode(TRUE, "epson.pdt");
      const char *PDTFile = PrSet.GetPDTFile();
      printf("PDT File = %s\n", PDTFile);
      if (PrSet.IsPDTMode())
         printf("PDTMode\n");
      else
         printf("Not PDTMode\n");
      PrSet.SetPDTMode(FALSE);
      PrSet.SetPDTMode(TRUE);
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

IsPDTMode

This method returns the state of the PDT mode of the connection.

Prototype

BOOL IsPDTMode() const;

Parameters

None

Return Value

BOOL
Possible values are as follows:

Example

void Sample117() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPDTMode(TRUE, "epson.pdt");
      const char *PDTFile = PrSet.GetPDTFile();
      printf("PDT File = %s\n", PDTFile);
      if (PrSet.IsPDTMode())
         printf("PDTMode\n");
      else
         printf("Not PDTMode\n");
      PrSet.SetPDTMode(FALSE);
      PrSet.SetPDTMode(TRUE);
   }
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

GetPrintMode

This method returns an enumerated value that indicates the PrintMode of the connection. The enum data type ECLPrinterSettings::PrintMode is defined in ECLPRSET.HPP.

PrintMode can be one of the following:

Prototype

ECLPrinterSettings::PrintMode GetPrintMode() const;

Parameters

None

Return Value

ECLPrinterSettings::PrintMode
One of the PrintMode values defined in ECLPRSET.HPP.

Example

void Sample118() {

   ECLPrinterSettings PrSet('A');

   ECLPrinterSettings::PrintMode PrtMode;
   PrtMode = PrSet.GetPrintMode();
   switch (PrtMode) {
   case ECLPrinterSettings::PrtToDskAppend:
      printf("PrtToDskAppend mode\n");
      break;
   case ECLPrinterSettings::PrtToDskSeparate:
      printf("PrtToDskSeparate mode\n");
      break;
   case ECLPrinterSettings::SpecificPrinter:
      printf("SpecificPrinter mode\n");
      break;
   case ECLPrinterSettings::WinDefaultPrinter:
      printf("WinDefaultPrinter mode\n");
      break;
   }
} // end sample

SetPrtToDskAppend

This method sets the PrintMode to Print to Disk-Append mode and sets the appropriate file for this mode.

Notes:
  1. The associated connection must be in PDT mode.
  2. The folder where this file is to be set must have write access. If it does not, this method fails with an exception.
  3. If the file exists, it will be used. Otherwise, it will be created when printing is complete.

Prototype

void SetPrtToDskAppend(const char *const FileName = NULL);

Parameters

char *FileName
Null-terminated string containing the name of the Print to Disk-Append file. This parameter is optional.

Possible values are as follows:

Return Value

None

Example

void Sample119() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPrtToDskAppend("dskapp.txt");
      const char *DskAppFile = PrSet.GetPrtToDskAppendFile();
      printf("Print to Disk-Append File = %s\n", DskAppFile);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   } 
} // end sample

GetPrtToDskAppendFile

This method returns the file configured for Print to Disk-Append mode. This file is called the Print to Disk-Append file. The method might not return the same string each time.

The string is valid only for the lifetime of the object. You must either make a copy of the string or make a call to this method each time you need it.

Prototype

const char *GetPrtToDskAppendFile();

Parameters

None

Return Value

char *
Possible values are as follows:

Example

void Sample119() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPrtToDskAppend("dskapp.txt");
      const char *DskAppFile = PrSet.GetPrtToDskAppendFile();
      printf("Print to Disk-Append File = %s\n", DskAppFile);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   } 
} // end sample

SetPrtToDskSeparate

This method sets the connection in Print to Disk-Separate mode and sets the appropriate file for this mode.

Notes:
  1. The associated connection must be in PDT mode.
  2. The folder where this file is to be set must have write access. If it does not, this method fails with an exception.
  3. The file name must not contain an extension. If it contains an extension, the method fails with an exception.

Prototype

void SetPrtToDskSeparate(const char *const FileName = NULL);

Parameters

char *FileName
Null-terminated string containing the name of the Print to Disk-Separate file. This parameter is optional.

Possible values are as follows:

Return Value

None

Example

void Sample120() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPrtToDskSeparate("dsksep");
      const char *DskSepFile = PrSet.GetPrtToDskSeparateFile();
      printf("Print to Disk-Separate File = %s\n", DskSepFile);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

GetPrtToDskSeparateFile

This method returns the file configured for Print to Disk-Separate mode. This file is called the Print to Disk-Separate file. The method might not return the same string each time.

The string is valid only for the lifetime of the object. You must either make a copy of the string or make a call to this method each time you need it.

Prototype

const char *GetPrtToDskSeparateFile();

Parameters

None

Return Value

char *
Possible values are as follows:

Example

void Sample120() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPrtToDskSeparate("dsksep");
      const char *DskSepFile = PrSet.GetPrtToDskSeparateFile();
      printf("Print to Disk-Separate File = %s\n", DskSepFile);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

SetSpecificPrinter

This method sets the connection in SpecificPrinter mode with the printer specified in the Printer parameter.

Prototype

void SetSpecificPrinter(const char *const Printer);

Parameters

char *Printer
A null-terminated string that contains the printer name and the port name. 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

void Sample121() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetSpecificPrinter("HCL InfoPrint 40 PS on Network Port");
      const char *Printer = PrSet.GetPrinterName();
      printf("Printer = %s\n", Printer); 
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

SetWinDefaultPrinter

This method sets the connection in WinDefaultPrinter mode--that is, the connection is made to use the Windows default printer. If no Windows default printer is configured in the machine, the method fails with an exception.

Prototype

void SetWinDefaultPrinter();

Parameters

None

Return Value

None

Example

void Sample122() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetWinDefaultPrinter();
      const char *Printer = PrSet.GetPrinterName();
   printf("Windows Default Printer = %s\n", Printer);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

GetPrinterName

This method returns NULL or the name of the printer configured in the connection. The method might not return the same string each time.

The string is valid only for the lifetime of the object. You must either make a copy of the string or make a call to this method each time you need it.

PrinterName must have the following format:

<Printer name> on <Port Name>

For example:

Prototype

const char *GetPrinterName();

Parameters

None

Return Value

char *
Possible values are as follows:

Example

void Sample122() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetWinDefaultPrinter();
      const char *Printer = PrSet.GetPrinterName();
   printf("Windows Default Printer = %s\n", Printer);
   }  
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

SetPromptDialog

This method sets or resets the option to show the Printer Setup dialog before printing.

Prototype

void SetPromptDialog(BOOL bPrompt=TRUE);

Parameters

BOOL bPrompt
This parameter is optional. Possible values are as follows:

Return Value

None

Example

void Sample123() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPromptDialog();
      if (PrSet.IsPromptDialogEnabled())
         printf("Prompt Dialog before Printing - Enabled\n");
      else
         printf("Prompt Dialog before Printing - Disabled\n"); 
   } 
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample

IsPromptDialogEnabled

This method checks whether the Printer Setup dialog is shown before printing or not.

Prototype

BOOL IsPromptDialogEnabled();

Parameters

None

Return Value

BOOL
Possible values are as follows:

Example

void Sample123() {

   ECLPrinterSettings PrSet('A');

   try {
      PrSet.SetPromptDialog();
      if (PrSet.IsPromptDialogEnabled())
         printf("Prompt Dialog before Printing - Enabled\n");
      else
         printf("Prompt Dialog before Printing - Disabled\n"); 
   } 
   catch (ECLErr Err) {
      printf("ECL Error: %s\n", Err.GetMsgText());
   }
} // end sample