Setting Up a Connect File

This topic includes the following sections:

 

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

Connect files can also contain

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.

1. The sample connect file for Windows.

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.

Note

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.

Note

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:

dictsource       DKA600:[SYNERGYDE.CONNECT.SYNODBC.DICT]
datasource      ;DKA600:[SYNERGYDE.CONNECT.SYNODBC.DICT];

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.

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

Note

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

Ignoring transactions invoked for read-only operations

When using privilege-based users (i.e., if the system catalog has the GENESIS_AUTHS and GENESIS_USERS files), you can instruct xfODBC to ignore transactions that are started automatically by an ODBC-enabled application for read-only operations. Most ODBC-enabled applications have settings that enable you to prevent automatic transactions for read-only operations, but if your application dos not have a setting for this, you can set the following in the connect file to prevent these transactions and the resulting file locks:

READ_ONLY yes

Note that when this is set, any attempt to modify the data or system catalog files will result in an error.