WebDocs Home | Show Navigation Hide Navigation

Setting Up a Connect File

Each system catalog requires a unique connect file. The connect file contains information on the location of the system catalog and the Synergy data files. A connect file is required to open a system catalog in the xfODBC Database Administrator (DBA) program and access data. It can also be used to set the convert_error option, Synergy driver logging, and environment variables for the xfODBC driver.

Creating the connect file

Use a text editor to create a connect file, and then save the file in your GENESIS_HOME directory with whatever name you choose. Connect files should reside in the directory specified by the GENESIS_HOME environment variable even if the data and system catalog files are located in other directories. (See “Specifying the connect file location (GENESIS_HOME)”.)

Connect files must contain

a dictsource line, which specifies the directory that contains, or will contain, your system catalog.

a datasource line, which specifies the directory or directories that contain your Synergy data files.

Connect files can also contain

the convert_error setting. (See “Specifying handling of invalid dates”.)

commands that invoke Synergy driver logging for system catalog caching. (See “Enabling Synergy driver logging”.)

environment variable settings. (See “Setting environment variables in a connect file”.)

Figure 1 shows the connect file for the sample database on Windows. The sample connect file and database are included in the Connectivity Series distribution.

Figure 1. The sample connect file for Windows.


Specifying the location of the system catalog and data files

The dictsource line must specify the full path to the directory that contains (or will contain) your system catalog and, optionally, your data files.

The datasource line must specify the full path to the directory or directories that contain your Synergy data files. However, it is used only if a filename, but no path, is set in the Open filename field of the Repository file definition and no data files exist in the dictsource directory. For example, if you specified only a filename, such as mydata.ism, in the Open filename field, and there were no data files in the dictsource directory, the datasource specification will by used to locate mydata.ism. Note that this line is required even if it isn’t used.


We don’t recommend using dictsource or datasource lines for the location of data files. Instead, use an environment variable for the path in the Repository Open filename field.

The following is a Windows example. The dictsource specification is straightforward, but notice the format of the datasource line: the path must begin and end with a semicolon, and double slashes are used to represent a single backslash in the path.

dictsource "C:\Program Files\Synergex\SynergyDE\connect\synodbc\dict\"
datasource ";C:\\Program Files\\Synergex\\SynergyDE\\connect\\synodbc\\dat;"

The syntax for dictsource and datasource in a UNIX or OpenVMS connect file is the same, but paths must conform to the platform’s standard.


When using SQL OpenNet, don’t use UNC (uniform naming convention) paths or paths that include mapped drives. The service may not have the privilege to map the drive.

The following is a UNIX example:

dictsource       /usr/synergyde/connect/synodbc/dict
datasource      ;/usr/synergyde/connect/synodbc/dat;

The following is an OpenVMS example:


If the data files are in more than one directory, separate directories with a semicolon. For example:

datasource      ;c:\\syndata;c:\\syndata2;c:\\syndata3;

If there are spaces in the path, the path (including semicolons for datasource) must be enclosed in double quotes. For example:

dictsource    "c:\my files\dict"
datasource    ";c:\\my files\\dat;"

Specifying handling of invalid dates

By default, the xfODBC driver treats invalid dates as null. You can use the convert_error option to instruct the xfODBC driver to allow SELECT statements to fail if they encounter invalid dates.

If you don’t set convert_error, or if you set it to no, invalid dates are treated as null data unless they are in userdefined date columns.

If you set convert_error to yes, SELECT statements will fail if they encounter invalid date data.

To set convert_error, add a line with the following syntax to the end of the connect file:

convert_error yes|no

Use lowercase characters for yes and no. For example:

dictsource "C:\Program Files\Synergex\SynergyDE\connect\synodbc\dict\"
datasource ";C:\\Program Files\\Synergex\\SynergyDE\\connect\\synodbc\\dat;"
convert_error yes

Enabling Synergy driver logging

You can use Synergy driver logging to determine if a system catalog is cached. Adding the following lines to the connect file causes xfODBC to log the path and name for the shared memory file and list errors encountered while attempting to use shared memory:

logfile file_spec 
loglevel level 

where file_spec is the path and filename of the log file you want to create and level is the type of logging desired. Loglevel can be set to any or all of the values listed below, but settings other than 1 are for use by Synergy/DE Developer Support. To set multiple levels, add the option values together (e.g., to set both “control blocks and data” and “data conversion output”, set level to 3):

1 = Control blocks and data

2 = Data conversion output

4 = System catalog information

8 = Tag information

16 = Messages

32 = Flush file

64 = Index comparison of queried values and what was fetched


We don’t recommend adding the logging lines before starting the SQL OpenNet server (see “Improving performance with system catalog caching”).