Connections, Handles and Names

In the context of the ECL, a connection is a single, unique Z and I Emulator for Windows emulator window. The emulator window may or may not be actually connected to a host and may or may not be visible on the screen. For instance, a Z and I Emulator for Windows window can be in a disconnected state. Connections are distinguished by their connection handle or by their connection name. Most HACL objects are associated with a specific connection. Typically, the object takes a connection handle or connection name as a parameter on the constructor of the object. For languages like Visual Basic® that do not support parameters on constructors, a member function is supplied for making the association. Once constructed, the object cannot be associated with any other connection. For example, to create an ECLPS (Presentation Space) object associated with connection 'B', the following code would be used:

C++

ECLPS *PSObject;
PSObject = new ECLPS('B');

Visual Basic®

Dim PSObject as Object
Set PSObject = CreateObject("ZIEWin.autECLPS")
PSObject.SetConnectionByName("B")

An HACL connection name is a single character from A–Z or a-z. There are a maximum of 52 connection names, and Z and I Emulator for Windows is currently limited to 52 concurrent connections. A connection's name is the same as its EHLLAPI short session ID, and the session ID shown on the Z and I Emulator for Windows window title and OIA.

An HACL handle is a unique 32-bit number that represents a single connection. Unlike a connection name, a connection handle is not limited to 52 values, and the value itself has no significance to the application. You can use a connection handle across threads and processes to refer to the same connection.

For future expansion, applications should use the connection handle whenever possible. Most HACL objects accept a handle or a name when a connection needs to be identified. There are functions available in the base HACL class to convert a handle to a name, and a name to a handle. These functions are available from any HACL object.