Changing connections refers to changing existing server connections. When you do this, you are keeping your Connection ID the same (the ID must always be the same) and you are changing your connection server string so your data can be accessed from a different location. This can occur in a number of different places during an application’s lifetime – before the application launches, as part of application start up or while an application is running. No matter where this occurs, one important restriction applies – the definitions of the tables being accessed from the different sources must be the same. The server strings (which contain a DSN or a Server plus a database) and the login credentials can change, but the table’s back end definition as defined in the table's INT file must be the same. It is your responsibility to make sure that this requirement is met. As we discuss the different ways to change connections, we are assuming that this condition is met.
You change a connection by modifying a connections server string in your Connections INI file. Using the Studio, you can modify a connection or, when the INI contains multiple connections for the same Id, select which connection should be enabled.
This is something you can do during development and it is something you will want to do as part of deployment. Technically, this might be thought of not as changing a connection, but as configuring your connection. This is very easy to do with the Studio and other DataFlex tools. It is even fairly easy to do with a simple text editor.
When your program starts, you can use various techniques to define a connection’s server string as the program starts.
One way to do this is to select a different connections INI file as part of startup (i.e., select a different INI file before you attempt to register any connections). There are a variety of ways to do this:
You can set the cConnection object’s psConnectionIni property. You can set this statically in your object or you could set it dynamically in the object (perhaps in AutoConnect).
You can pass the connections INI file name as a command line property using the dfconnid= command line parameter (e.g., dfconnid=<apppath>\config). When running within the Studio, you can set this parameter in your project’s property page. For security reasons, this feature can be disabled by setting the pbCmdLineIniAllowed property. In case of a command line parameter conflict you may also change the name of the parameter “dfconnid=” to some other name using the psConnectionIdCmdLine property.
You can bypass the connections INI file entirely and define you own connections any way you choose. If you did that you would either want to augment AutoConnect or set pbAutoConnect to false and add the connections later in your application using AddConnection.
You can “switch” a connection-string while an application is running by deleting an existing connection (which does a log out and close of all tables opened for that connection), changing the connection-string, registering the connection, logging in to the connection and opening all tables that need to be opened.
For example, let’s say you wanted to change all of your connection so that they use a different connections INI file. You could do something like this:
Procedure ChangeConnectionINI String sConnectionIni
Boolean bOk
// close all tables, logout, delete connections
Send UnRegisterAllConnections of ghoConnection
Set psConnectionIni of ghoConnection to sConnectionIni
Get AddAllConnections of ghoConnection to bOk
If bOk Begin
Get LoginAllConnections of ghoConnection to bOk
If bOk Begin
Send OpenAllOfYourTablesAgain
End
Else Begin
// handle the error here
End
End
End_Procedure
:
Send ChangeConnectionINI "<apppath>\config.ws"
The Studio actually uses a similar strategy each time it changes a workspace
An advanced method can be used to change existing connections without needing to close connections and re-open tables. The RedirectConnectionId method redirects a connection from one server string to another without closing any tables. In addition, this method will keep existing connections alive so they can be switched back to without requiring a login. If the server is already logged into, switching back to that server will be very fast.
The RedirectConnectionId function is passed a Connection ID, a server string and login credentials. If a login is needed, those credentials must succeed. It is also passed a keep-alive flag, which if true will keep the connection being directed from connected.
In this example, the RedirectTest method will direct the connection to the passed server string. In this case, we assume trusted connections are used with all connections.
Procedure RedirectTest String sID1 String sServer
Boolean bOk
Get RedirectConnectionId of ghoConnection sID1 sServer "" "" True True to bOk
If not bOk Begin
// handle error
End
End_Procedure
:
Send RedirectTest "Id1" ".\SQLEXPRESS;DATABASE=Order_1"
:
Send RedirectTest "Id1" ".\SQLEXPRESS;DATABASE=Order_2"
This is an advanced and powerful capability and must be used with caution. Note that:
An existing connection must exist (must be logged in to) before RedirectConnectionId can be called.
The password credentials for the new connection must succeed for the new login.
It is your responsibility to make sure that any application data being displayed is properly cleared or initialized after the connection redirect.
Logging Out and Removing Connections
Managing Connection Information