This topic includes the following sections:
- Creating the connect file
- Specifying the location of the system catalog and data files
- Specifying handling of invalid dates
- Enabling Synergy driver logging
- Ignoring transactions invoked for read-only operations
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.
|
|
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:
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.
- 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 user-defined 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). |
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.
