Session IDs

The HACL architecture is not limited to 52 sessions. Therefore, a single character session ID such as that used in EHLLAPI is not appropriate. The HACL uses the concept of a connection handle, which is a simple 32-bit value that has no particular meaning to the application. A connection handle uniquely identifies a specific connection (session). You can use a connection handle across threads and processes to refer to the same connection.

All HACL objects and methods that need to reference a particular connection accept a connection handle. In addition, for backward compatibility and to allow a reference from the emulator user interface (which does not display the handle), some objects and methods also accept the traditional session ID. The application can obtain a connection handle by enumerating the connections with the ECLConnList object. Each connection is represented by an ECLConnection object. The ECLConnection::GetHandle method can be used to retrieve the handle associated with that specific connection.

It is highly recommended that applications use connection handles instead of connection names (EHLLAPI short session ID). Future implementations of the HACL may prevent applications that use connection names from accessing more than 52 sessions. In some cases it may be necessary to use the name, such as when the user is required to input the name of a specific session the application is to utilize. In the following C+ + example, you supply the name of a session. The application then finds the connection in the connection list and creates PS and OIA objects for that session:

ECLConnList		      ConnList;		// Connection list
ECLConnection	      *ConnFound;		// Ptr to found connection
ECLPS			        *PS;			     // Ptr to PS object
ECLOIA		           *OIA;			   // Ptr to OIA object
char			           UserRequestedID;
 
//... user inputs a session name (A-Z or a-z) and it is put
//... into the UserRequesteID variable.  Then...
 
ConnList.Refresh();		// Update list of connections
ConnFound = ConnList.FindConnection(UserRequestedID);
if (ConnFound == NULL) {
  // Session name given by user does not exist...
}
else {
  // Create PS and OIA objects using handle of the
  // connection just found:
  PS = new ECLPS(ConnFound.GetHandle());
  OIA= new  ECLOIA(ConnFound.GetHandle());
 
  // The following would also work, but is not the
  // preferred method:
  PS = new ECLPS(UserRequestedID);
  OIA= new ECLOIA(UserRequestedID);
}

The second way of creating the PS and OIA objects shown in the example is not preferred because is uses the session name instead of the handle. This creates an implicit 52-session limit in this section of the code. Using the first example shown allows that section of code to work for any number of sessions.