Skip to content

Defining a Connection

Defining a Connection ID’s Server String

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 your applications. In any of these cases, you would simply change the contents of the Connections INI file. While most of the 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.
  4. Run the application.

When re-configuring a connection's server string from one server to another, the assumption is made that the server and database being accessed contain the same tables and table structures.

How to Configure and Reconfigure Your Server String

There are various ways to configure and reconfigure your server string:

  1. Change the server string in the Connections INI file and run the application.
  2. Run the application using a different Connections INI file (e.g., DFConnIDDemo.ini). This can be done via a command line interface as well as using lower-level interfaces that would let you customize this inside your 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 ensure 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 and is not used to dynamically set or change connection server strings while an application is running. There are other ways to do this.

Defining Multiple Connection IDs

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 communicate with two logical servers at the same time – ID1 and RS1.

A single Connections INI file may contain a mix of sections that contain 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 Format

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 names 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

Parameters

  • id=
    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.

  • driver=
    This identifies the managed driver being used. Supported managed drivers are MSSQLDRV, ODBC_DRV, and DB2_DRV. Required.

  • connection=
    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.

  • UID=
    Stores the login username. Optional.

  • PWD=
    Stores the user password using the developer-maintained rules for the workspace/application. Optional.

  • trusted_connection=
    If this is a trusted connection, it should be trusted_connection=yes. Optional.

  • DFPWD=
    Stores the DataFlex tool password using the tool’s encryption rules. Optional.

  • disabled=
    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.

Location of the Connections INI File

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 back up these settings without worrying about breaking other configuration settings.

Configuring a Workspace’s Connections INI File Path

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:

  1. The file is a standard INI file with uniquely named [sections].
  2. None of the existing section names start with "connection".
  3. 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.

Setting the Connections INI File at Runtime

You can determine a custom file path for the connections at runtime. This does not change the file path for the Studio but can be used to change how your application runs. This may be useful when testing. You can:

  1. 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.

  2. Set the [psConnectionIni](../VdfClassRef/WebAndWindows/cConnection-Property-psConnectionIni.md) 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 psConnectionIni 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 (first programs folder), (first data folder), or (workspace home). For example, .\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:

  1. If the cConnection[psConnectionIni](../VdfClassRef/WebAndWindows/cConnection-Property-psConnectionIni.md) property is defined directly, use that name.
  2. If the command line parameter is allowed and is passed, use that name.
  3. If the workspace has a definition (ConnectionIni= setting in config.ws), use that name.
  4. Otherwise, use the default of data\DFConnId.ini.

The derived Connections INI file path may be obtained by calling the [ConnectionIniFile](../VdfClassRef/WebAndWindows/cConnection-Function-ConnectionIniFile.md) function.

Previous Topic

Using Managed Connections

Next Topic

Logins, Table Opens and Connection IDs