This topic includes the following sections:
- Specifying the location of DBA and dbcreate
- Specifying the connect file location (GENESIS_HOME)
- Specifying the error message file (GENESIS_MSG_FILE)
- Specifying the location of the environment setup file (SODBC_INIFIL)
- Specifying the location of data files
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.
- On 32-bit Windows and on UNIX, the location of dbcreate is added to the PATH setting.
- On OpenVMS, dbcreate is set as a DCL command when xfODBC is installed.
Specifying the connect file location (GENESIS_HOME)
The GENESIS_HOME environment variable is required and is automatically set when you install xfODBC.
|
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 it at the system level, in which case it is not changed.
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 the GENESIS_MSG_FILE setting. (Both the 32-bit and the 64-bit installation 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.
- In a stand-alone configuration, set SODBC_INIFIL in a connect file or in the environment.
- In a client/server configuration, set SODBC_INIFIL in the environment on the server or in the opennet.srv file (Windows only).
If SODBC_INIFIL is set in the environment when you access your Synergy data, xfODBC will ignore environment variables set in the connect file. To use environment variables set in the connect file, either make sure SODBC_INIFIL is not set or is set in the connect file.
Specifying the location of data files
For repository files, you can specify the path and filename
- at the command line for dbcreate. (See dbcreate utility.)
- in the Generate System Catalog window of the DBA program. (See Using DBA to generate a system catalog with level-based users.)
For Synergy data files, you can specify
- the filename or the path and filename in the Open filename field of Repository. If the path is not specified there, xfODBC uses the path in the datasource line of the connect file.
- the path in the dictsource or datasource line of the connect file. Settings in these lines are used if no path is specified in the Repository Open filename field, and the datasource setting is used only if no data files exist in the dictsource directory. xfODBC always gets the data file name from the “Open filename” field. (See Specifying the location of the system catalog and data files.)
We recommend using an environment variable to specify the path in the “Open filename” field of Repository rather than relying on dictsource or datasource.
There are two types of environment variables you can use to specify the location of data files:
- User-created data location variables. These are environment variables you create and use in the place of hard-coded paths and filenames.
- Repository file location variables. These are RPSDAT, RPSMFIL, and RPSTFIL. These environment variables are set by the installation (except on 64-bit Windows), and in some cases xfODBC automatically uses their settings.
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 SODBC_INIFIL is not set or is set in the connect file, xfODBC first considers variables defined in the connect file. (If SODBC_INIFIL is set in the environment, xfODBC ignores environment variables set in the connect file.)
- Next, xfODBC searches the environment setup file for variable definitions.
- xfODBC then considers variables defined in the current environment.
- xfODBC then considers variables defined system-wide (for both stand-alone and client/server configurations).
- Finally, if xfODBC is still not able to resolve the variable after checking the connect file, the environment setup file, and the environment and system-wide definitions, it returns a “file not found” error message.
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 in that topic 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:
- The dbcreate utility looks first to the command line and uses any repository files specified by the -r option. If -r is not passed, dbcreate uses the RPSMFIL and RPSTFIL environment variable settings. If these aren’t set, dbcreate looks for the rpsmain.ism and rpstext.ism files in the directory specified by the RPSDAT environment variable. If the files don’t exist in this location, dbcreate returns an error.
- DBA looks first to the RPSMFIL and RPSTFIL environment variable settings. If these have been set, DBA uses the settings to pre-fill the Main repository and Text repository fields of the Generate System Catalog input window. If you change these fields, the new values will override the RPSMFIL and RPSTFIL settings. If RPSMFIL and RPSTFIL are blank, the Main repository and Text repository fields will be blank when the Generate System Catalog input window opens.
Note the following:
- RPSDAT specifies the location (path only, not filename) of the repository files. This variable works only if the repository files are named rpsmain.ism and rpstext.ism. dbcreate uses this variable, but DBA does not.
- RPSMFIL specifies the path and filename of the repository main file. Both dbcreate and DBA use this variable.
- RPSTFIL specifies the path and filename of the repository text file. Both dbcreate and DBA use this variable.
- The installation automatically sets RPSDAT, RPSMFIL, and RPSTFIL (except on 64-bit Windows), but they’re not required for xfODBC. If your repository files are not in one of these directories, you must hand code the paths to the repository files to generate or modify the system catalog.
- On Windows, these variables must be set in the environment or in synergy.ini. (Note that dbcreate doesn’t use environment variables set in synergy.ini.)
- For UNIX and OpenVMS, these variables must be set in the environment.
