Once you have defined a Connection ID for an application, the ID name will not change. The server string defined for this ID can change. It can be configured to point to a server/database of your choosing. This means you can deploy applications, switch server/databases or exchange workspaces without ever having to make changes to your table INT files or recompile you applications. In any of these cases, you would simply change the contents of the Connections INI file. While most of connections INI editing can be done manually via a text editor, tools are provided that do this for you.
For example, if you were sent an application along with its workspace and an SQL script to create a database, you would: 1) install the workspace, 2) create the database using the SQL script, 3) change the contents of the connections INI file, and 4) run.
When re-configuring a connection's server string from one server to another the assumption is made that the server and database being accessed contains the same tables and tables structures.
How do you configure and reconfigure your server string? There are various ways to do this:
The most obvious is you change the server string in connections INI file and run the application.
You may also run the application using a different connections INI file (e.g., DFConnIDDemo.ini). This could be done via a command line interface as well as using lower level interfaces that would let you customize this inside via code.
During development and, perhaps to a lesser extent during deployment, you may wish to switch back and forth between servers/databases. The tables in these databases must have the same definitions. While you could edit your server string every time you need to do this, an easier method is provided. Your connections INI may contain multiple connection sections that define the same logical connection ID. This is allowed as long as only one of these sections is marked active at any one time.
[Connection1]
Id=ID1
driver=MSSQLDRV
connection=SERVER=.\SQLEXPRESS;DATABASE=Order
trusted_connection=yes
disabled=yes
[Connection2]
Id=ID1
driver=MSSQLDRV
connection=SERVER=.\SQLEXPRESS;DATABASE=Order_Demo
trusted_connection=yes
In the above example, connection1 and connection2 have the same Id. If a connections INI file contains sections with duplicate IDs, all but one of those must be disabled. Here the ID1 server string in [connection2] will be used. This is most easily managed by using the Studio’s connection manager as it will make sure that at most one set of duplicate Ids is enabled.
This feature is best thought of as providing an easy way to keep a cache of recently used connection-strings. This is configured before an application is run. This is not used to dynamically set or change connection server strings while an application is running. There are other ways to do this.
You can provide multiple uniquely named connection IDs within a connections INI file. You define multiple connections when your application needs to connect to multiple servers/databases simultaneously. In other words, you do this when you need to open tables or ESQL connections across servers. For example:
[Connection1]
Id=ID1
driver=MSSQLDRV
connection=SERVER=.\SQLEXPRESS;DATABASE=Order
trusted_connection=yes
[Connection2]
Id=RS1
driver=MSSQLDRV
connection=SERVER=MyRemoteServer;DATABASE=RemoteData
UID=AppUser
PWD=893753hskfgd
This application can now talk to two logical servers at the same time – ID1 and RS1.
A single connections INI file may contain a mix of sections that contains multiple definitions for a single connection ID (where only one section is enabled) and multiple uniquely named connection Ids (when you need to access tables across servers simultaneously). For example:
[Connection1]
Id=ID1
driver=MSSQLDRV
connection=SERVER=.\SQLEXPRESS;DATABASE=Order
trusted_connection=yes
disabled=yes
[Connection2]
Id=ID1
driver=MSSQLDRV
connection=SERVER=.\SQLEXPRESS;DATABASE=Order_Demo
trusted_connection=yes
[Connection3]
Id=RS1
driver=MSSQLDRV
connection=SERVER=MyRemoteServer;DATABASE=RemoteData
UID=AppUser
PWD=893753hskfgd
Often an application will only ever have a single connection and therefore only contain a single connection ID defined in a single section.
The connections INI file consists of one or more connection sections. Each section is identified with the name "connection" followed by a number making each section name unique ([connection1], [connection2], etc.). A section name has no meaning and you should not attempt to make use of its value. When the Studio’s Connection Manager writes out changes, the name of sections may change.
Each connection section has the following format:
[connection{1…n}]
id={id-name}
driver={MSSQLDRV|ODBC_DRV|DB2_DRV }
connection={server string}
UID={user-name}
PWD={encrypted-password}
trusted_connection=yes
DFPWD={encrypted-password}
disabled=yes
where:
This is the connection id, which is the logical name that will be used in your table INT files and your code to refer to this connection. Because this is a logical name you should give it an abstract name (like "order") and not a name that refers to a physical server. Required.
This identifies the managed driver being using. Support managed drivers are MSSQLDRV, ODBC_DRV and DB2_DRV. Required.
This identifies your server string, which is an ODBC server string that must conform to the requirements of your server and database. It will usually be in the form of "SERVER=…" (e.g., connection=SERVER=.\SQLEXPRESS;DATABASE=Order) or "DSN=…" (e.g., connection=DSN=MSSQLOrder). When using a DSN, the DSN entry will contain the server, default database and most likely all login credentials. While you can define server and credential information in a single connection, you are not encouraged to do this. Required.
Stores the login user name. Optional.
Stores the user password using the developer maintained rules for the workspace/application. Optional.
If this is a trusted connection it should be "trusted_connection=yes". Optional.
Stores the DataFlex tool password using the tool’s encryption rules. Optional.
If this connection is disabled it should be "disabled=yes". If multiple connection sections contain the same "id", only one can be enabled – all others must be disabled. Optional.
The default location and name of the connections INI file is data\DFConnId.ini. In most cases, this locates the connections INI file in the same folder where the table INT files are defined. Since the table INT files rely on connection IDs being defined in the connections INI file this dependency seems appropriate.
The connections INI file is only used to store connection information. This makes it easy to copy, modify and backup these settings without worrying about breaking other configuration settings.
If you wish to customize the connections INI file name or location you may do so by changing a workspace configuration. This value can be changed in the Studio via the Configure Workspace dialog by editing the "Connections Ini:" setting. By default, this value is blank (which means the default "data\DFConnId.ini" is used). When this configuration setting is changed both the tools (Studio, etc.) and your workspace applications will use this changed location.
The connections INI file can be merged with other INI style files as long as the following restrictions are met:
The file is a standard INI file with uniquely named [sections].
None of the existing section names start with "connection".
The tool that maintains this INI file does not remove settings it does not understand (i.e., it will not accidentally remove the [connection] sections).
For example, you could choose to merge the connections INI sections with the config.ws file by setting the "Connections Ini:" form to ".\Programs\config.ws".
You can determine a custom file path for the connections at runtime. This does not change the file path for the Studio but it can be used to change how your application runs. This may be useful when testing. You can:
Specify a custom file path via the command line using the syntax "dfconnid=". This could be used within the Studio when debugging a program. You could set the "parameters" setting in the "Project Properties" dialog to something like "dfconnid=DFConnId_alt.ini". When the program runs it would look for the connections INI file in "data\DFConnId_alt.ini".
You can set the psConnectionIni property in your program to a file path of your choosing. Normally this is blank, which means it uses the default. You do not normally change this and setting this would be part of a larger custom modification.
When you set a custom connections INI file path via psConnectonIni or the dfconnid= command line, you can use relative pathing or fully qualified pathing. If no path is provided (e.g. MyConnection.ini), the first data folder is used. You can provide workspace specific paths by using the special symbols <apppath> (first programs folder), <datapath> (first data folder) or <homepath> (workspace home workspace). For example, <apppath>\config.ws would look for a config.ws file in your programs folder.
Because there are a variety of ways to determine the connections INI file path, precedence is applied as follows:
If the cConnection psConnectionIni property is defined directly, use that name
If the command line parameter is allowed and is passed, use that name
If the workspace has a definition (ConnectionIni= setting in config.ws), use that name
Otherwise, use the default of data\DFConnId.ini
The derived connections INI file path may be obtained by calling the ConnectionIniFile function.
Logins, Table Opens and Connection IDs