Specifying file locations

This topic includes the following sections:

 

Before you can generate a system catalog, you must specify the location of data files (see Specifying the location of data files). If you’ve set any environment variables in an environment setup file, you must also specify the location of that file (see Specifying the location of the environment setup file (SODBC_INIFIL)).

In addition, other file locations must be set before you can open a system catalog in DBA, use a conversion setup file, or access data with an ODBC-enabled application. See the sections below for details.

Specifying the location of DBA and dbcreate

The location of the DBA program is automatically set. Although it’s seldom necessary, you can change this setting with the SODBC_DBA environment variable; see Other environment variables used by xfODBC.

The location of dbcreate is automatically set system-wide when you install xfODBC (except on 64-bit Windows). This enables you to run dbcreate from the directory that contains the system catalog. For client/server configurations, the location of dbcreate should be set on the server.

Specifying the connect file location (GENESIS_HOME)

The GENESIS_HOME environment variable is required and is automatically set when you install xfODBC.

Note

If you change the setting for GENESIS_HOME, xfODBC may not be able to locate the error message file, which is required to generate a system catalog. If the GENESIS_MSG_FILE environment variable is not set, xfODBC looks for the error message file in GENESIS_HOME\lib. See Specifying the error message file (GENESIS_MSG_FILE) below for more information.

This environment variable must be set to the directory that contains the connect files, which specify the location of system catalogs and data files. (See Setting Up a Connect File.) It is used by the xfODBC driver, DBA, and dbcreate, and it’s used when you generate system catalogs, when you modify system catalogs, and when you connect to the database.

Stand-alone configurations

For stand-alone configurations on Windows and UNIX, set GENESIS_HOME in the environment.

For stand-alone configurations on OpenVMS, set GENESIS_HOME in CONNECT_STARTUP.COM.

Client/server configurations

In client/server configurations, GENESIS_HOME must be set in opennet.srv on the server, and it must be set before starting the SQL OpenNet server (which only uses settings made before it’s started and doesn’t use settings in synergy.ini). The distributed opennet.srv file already defines GENESIS_HOME.

GENESIS_HOME must also be set in the environment on the client unless you set GENESIS_MSG_FILE.

Recommendations for Windows

For Windows, we recommend that you change the GENESIS_HOME setting and move files for the sample database and repository to a writable location outside of Program Files so that files can be created and updated.

GENESIS_HOME is set at the system level by the installation. If you install both 32-bit and 64-bit versions of Connectivity Series on the same 64-bit Windows machine, the first version installed determines the GENESIS_HOME setting, unless a user has set at the system level. If a user has set this at the system level, the Connectivity Series installation does not change this setting (during install, upgrade, or uninstall). 

Specifying the error message file (GENESIS_MSG_FILE)

To generate a system catalog, xfODBC must be able to locate the error message file. If the GENESIS_MSG_FILE environment variable is set, dbcreate uses this setting to locate the file. If it is not set, dbcreate attempts to locate the default error message file, sql.msg, in the GENESIS_HOME\lib directory.

When you install Connectivity Series, GENESIS_MSG_FILE is automatically set to sql.msg, the default error message file. If you install both 32-bit and 64-bit versions of Connectivity Series on a 64-bit Windows machine, the last version installed determines which sql.msg file this is set to. (The 32-bit installation and the 64-bit installation each have an sql.msg file.) (For more information on sql.msg, see Editing the SQL error message file.)

If you set GENESIS_MSG_FILE, set it in the environment to the path and filename of the error message file. For client/server configurations, it must be set in the environment on the client and on the server. (For services such as web servers that use the xfODBC driver, you can use the Env. variables field in the xfODBC Setup window to set this on the client. For information, see Adding a user or system DSN.)

Specifying the location of the environment setup file (SODBC_INIFIL)

An environment setup file is a file that you write to define environment variables that are used by xfODBC when locating Synergy data files. It typically has an .ini filename extension and is placed in the GENESIS_HOME directory, although these are not requirements. (For information on environment setup files, see Setting environment variables in an environment setup file.)

The location of the environment setup file is specified by SODBC_INIFIL, which is used by the xfODBC driver when you connect to a database. It is not used by DBA or dbcreate, so it is not used when you create or modify a system catalog.

SODBC_INIFIL is not set during installation. To use an environment setup file, set SODBC_INIFIL to the path and filename of the environment setup file.

Specifying the location of data files

For repository files, you can specify the path and filename

For Synergy data files, you can specify

Note that we recommend using an environment variable to specify the path in Open filename field of the repository rather than relying on dictsource or datasource.

There are two types of environment variable you can use to specify the location of data files:

User-created data location variables

Rather than hard-coding a path in the Open filename field of Repository, you can define your own data-location environment variables from the command line for dbcreate or with the Generate System Catalog window of DBA. User-created data location variables can be defined in the connect file, in an environment setup file, and in the environment. For client/server configurations, user-created data location variables must be defined on the server.

These variables can be used for both system catalog generation and data access. For example, if you use one of these variables at the command line for dbcreate or in the Generate System Catalog window of DBA, the variable is used to locate the repository files used to generate the system catalog. On the other hand, if you use one of these variables in the Open filename field of Repository or in the datasource line of the connect file, xfODBC uses the variable to locate database files for data access.

To access data, xfODBC resolves data-location variables that point to database files in the following manner:

If you use a hard-coded path in the Open filename field of a Repository file definition, at the command line for DBA or dbcreate, or in the Generate System Catalog Window of the DBA, this path is the only one xfODBC considers when attempting to locate the data file.

See Create a connect file for an example data location variable, XFDBTUT, that works with the tutorial. See step 4 for an example used in the Generate System Catalog window of DBA.

Specifying repository file locations

When locating repository files for generating the system catalog, dbcreate and DBA search in different ways:

Note the following: