Managing Connection Information
A number of messages pass and return data in a tConnection struct. The tConnection struct contains all information about a connection. This struct is defined as:
A tConnection struct is a handy way to pass connection information around. A tConnection variable does not always represent data from the same source. Depending on how it is used, different members will have different, or in some cases, no meaning.
For example, the tConnection array returned from LoadStoredConnections contains the connections defined in the Connections INI file. This will contain both enabled and disabled connections. The driver index is not yet known and has no meaning. The sConnectionString member has no meaning. The data may not even be valid (e.g., bad driver name).
On the other hand, the tConnection array returned by ConnectionIds contains an array of registered connections. These never contain disabled connections. The driver is successfully loaded and the driver index is set. The sConnectionString member is set. At this point, the sSection member’s value has no meaning.
IsConnectionIdLoggedIn
The function IsConnectionIdLoggedIn tests if the connection identified by the passed connection ID is logged in to the database server. The ID being passed must be registered.
OnAddConnection
The event OnAddConnection is called right before a connection is registered. It is passed the data being used to register the connection in a by-reference tConnection variable. This data can be changed, but should be done so with the greatest of care. Because you can inspect the data that is about to be registered, this can be a useful debugging point.
ConnectionIniFile
The function ConnectionIniFile returns the full path name of the Connections INI file. This file may or may not exist – use File_Exist to determine that. The file may or may not be used.
AssembleConnectionString
The function AssembleConnectionString is a helper function which is passed a server string, a user ID, a password, and a trusted credentials flag, and returns a complete ODBC server string that contains all information required to identify and log in to a database server.
ConnectionIDs
The cConnection object maintains a list of all registered connection IDs in an array of tConnection items. The function ConnectionIds returns this array.
ConnectionIdIndex
The function ConnectionIdIndex returns the index for the passed connection ID within the internal array of connections described in ConnectionIDs. If the ID is not found, it returns -1.
ConnectionIdCLIHandler
The function ConnectionIdCLIHandler returns a handle for the CLI object associated with the passed connection ID. When a driver is registered, a cCLIHandler object is created for this driver. All connection IDs for a driver can access and use the handle. The DriverCLIHandler method can be used to access the same CLI object via a driver name.
ConnectionIdCLIHandler can also be used to test if a connection ID is registered. If it returns 0, the ID is not registered. ConnectionIdIndex can be used for the same purpose.
ConnectionIdInfo
The function ConnectionIdInfo returns complete and up-to-date information for a registered connection. The passed connection ID is used to find the connection and returns its data in a tConnection variable. If the connection ID does not exist, a programming error is raised.
The connection information returned may or may not be logged in. You can use IsConnectionIdLoggedIn to determine that.
The iDriverIndex member can be used to communicate with the driver API interface. The DF_DRIVER_API interfaces require that you pass a driver number. DriverIndex returns that number.
If you wish to communicate with the database API interface, you need to use the iDriverIndex member and a database ID handle. This handle can be obtained by calling ConnectionDatabaseIdHandle, passing the tConnection data returned by ConnectionIdInfo.