This method creates a new user session, which is used to maintain state information between ispec transactions. It returns an integer session identifier, which must be passed as a parameter to all subsequent ispec transaction method calls that are part of that session.

A negative return value (for example, -999) indicates a Connect() error and a session has not been established. Examples of error codes are:

When you call Connect(), you can also pass in a pointer to an IMessages interface (as the first parameter). This interface points to an object in your own address space that is used to receive asynchronous messages and accepts. If you pass in NULL for this parameter, then you will not receive any messages or accepts. Refer to Handling Unsolicited Messages for more information.

The second parameter is a Boolean that indicates whether this is an “anonymous” login or not. If this parameter is set to TRUE then there is no check for duplicate logins from the same user.

The third parameter is a Boolean that indicates whether to “force” a login for this user or not. Normally, when a Connect() request is made, a check is done to ensure that there is not already an open session for this user. If there is already an open session for this user the Connect() request is rejected and returns a value of -999. However, if the bForceLogin parameter is set to TRUE the existing session for this user is automatically disconnected and the new session is established. This is useful in the situation where an “orphan” session has been left for the current user. This can happen if the client program crashes or exits without doing a Disconnect().

The fourth parameter is optional. A string can be passed and used as the “station name” and loaded into GLB.STATION.