This topic describes the methods you can use to set environment variables for xfODBC. The method you should use depends on your operating system, the configuration of xfODBC (client/server or stand-alone), and which programs you want the setting to affect.
On Windows and OpenVMS, environment variables for use by xfODBC must be set system-wide; Unix, however, does not support system-wide settings so you must set environment variables before starting the program or service that uses them, such as with a shell script.
You can set environment variables in the following ways:
- At a command prompt. See Setting environment variables from a command prompt.
- In a batch file, shell script, or DCL command file. See Setting environment variables in a batch file, shell script, or DCL command file.
- In the connect file. (This is especially useful for data file locations.) See Setting environment variables in a connect file.
- In the xfODBC Setup window. See Setting environment variables in the xfODBC Setup window.
- In an environment setup file and then setting SODBC_INIFIL to point to it. See Setting environment variables in an environment setup file.
- In synergy.ini. See Setting environment variables in synergy.ini (Windows).
- In net.ini. See Setting SQL OpenNet client options in net.ini.
- In opennet.srv. See Setting environment variables in opennet.srv (Windows).
- In System Properties on Windows. See Setting environment variables in System Properties (Windows).
- In a log-in file on Unix and OpenVMS. See Setting environment variables in log-in files (Unix and OpenVMS).
For client/server configurations, set environment variables only on the server. Environment variables set on the client are not recognized.
This topic includes the following sections:
- Setting environment variables from a command prompt
- Setting environment variables in a batch file, shell script, or DCL command file
- Setting environment variables in a connect file
- Setting environment variables in the xfODBC Setup window
- Setting environment variables in an environment setup file
- Setting environment variables in synergy.ini (Windows)
- Setting environment variables in opennet.srv (Windows)
- Setting environment variables in System Properties (Windows)
- Setting environment variables in log-in files (Unix and OpenVMS)
This topic describes the methods you can use to set environment variables. The method you should use depends on your operating system, the configuration of xfODBC (client/server or stand-alone), and which programs you want the setting to affect.
|
|
For a full list of xfODBC environment variables, see Appendix A: Environment Variables. |
On Windows and OpenVMS, environment variables for services and ODBC-enabled applications must be set system wide. On Unix, which doesn’t support system-wide environment variables, you must set environment variables before starting the program or service that uses them. (Often it’s convenient to do this with a shell script.)
To set a system-wide environment variable,
- on Windows, set it in the Environment Variables dialog. See Setting environment variables in System Properties (Windows).
- on OpenVMS, use the /SYS command. For an example, see Setting environment variables in a batch file, shell script, or DCL command file.
Setting variables in the environment
When we use the term “the environment” to describe where an environment variable should be set, it could be any of the following:
- At a command prompt
- In a batch file, shell script, or DCL command file
- In a log-in file on Unix or OpenVMS
- In the Environment Variables dialog on Windows. See Setting environment variables in System Properties (Windows).
Environment variables set in a connect file, environment setup file, synergy.ini, or opennet.srv are available only to the Connectivity Series products that use them. They’re not available to other programs running in the environment.
Setting environment variables from a command prompt
Environment variables set at a command prompt are temporary. They exist only in the current environment and do not apply when you leave the environment. In the following examples, the environment variable DATA is set to a directory named “dat”, a subdirectory of the GENESIS_HOME directory.
- At a Windows prompt,
SET DATA=%GENESIS_HOME%\dat
- At a Unix prompt,
DATA=$GENESIS_HOME/dat; export DATA
- At an OpenVMS prompt,
DEFINE DATA GENESIS_HOME:[DAT]
Setting environment variables in a batch file, shell script, or DCL command file
For dbcreate and DBA, you can set environment variables from a batch file (Windows), shell script (Unix), or DCL command file (OpenVMS). The advantage of this method is that the variables are set only when necessary. Moreover, they are no longer in effect once the current process terminates—for example, when you close a Command Prompt window in Windows, log off in OpenVMS, or exit a shell on Unix. (Note that on Unix, an environment variable must be exported to the shell for it to be available to additional programs run from the shell.) This is a particularly good way to store variables that need to be set only for system catalog generation.
| 1. | Using a text editor, create a batch file, shell script, or DCL command file and define xfODBC environment variables in the file using the standard syntax. For example: |
- Windows:
set SODBC_CNVOPT=1
- Unix:
SODBC_CNVOPT=1 ;export SODBC_CNVOPT
- OpenVMS:
DEFINE/SYS SODBC_CNVOPT 1
(/SYS is optional. It sets the environment variable as a system-wide logical on OpenVMS.)
| 2. | From the command line, run the batch file, script, or DCL command file. |
| 3. | After running the file, run dbcreate or DBA from the command line in the same environment. |
On Unix and OpenVMS, your xfODBC distribution includes shell scripts (setodbc and startnet) or a DCL command file (STARTNET.COM) you can use to specify environment variables. Note the following:
- These files are replaced every time you install Connectivity Series. So if you set an environment variable in one of these files, you’ll have to reset it after installing.
- To use setodbc on Unix, you must have configured your session for Synergy/DE by sourcing setsde. For information, see SQL Connection and xfODBC on Unix.
- If you use startnet or STARTNET.COM, environment variable settings should precede the line that starts the SQL OpenNet server. On Unix, this is the vtxnetd command. On OpenVMS, it is the command that runs NET.COM. For example:
SODBC_ODBCNAME=1; export SODBC_ODBCNAME nohup vtxnetd -p1958 log & sleep 1
Setting environment variables in a connect file
You can use your connect file to define environment variables for the xfODBC driver. These definitions are read by the xfODBC driver when connecting to a database and remain in effect for the duration of the connection. Environment variables set in the connect file are used to locate data files and set some data access options. Note the following:
- Do not include the SET (Windows), EXPORT (Unix), or DEFINE (OpenVMS) commands in the environment variable definition, and do not use other environment variables in the definition. For example, the following illustrates the syntax used to set an environment variable on a Windows system.
XFDBTUT=C:\Program Files\Synergex\SynergyDE\connect\synodbc\dat
- If SODBC_INIFIL is set in the environment, xfODBC won’t use environment variable settings in the connect file. If SODBC_INIFIL is set in the connect file, xfODBC looks to the connect file for environment variable definitions before it looks in the environment setup file. (See Specifying the location of the environment setup file (SODBC_INIFIL) for more information.)
- Put each environment variable on a separate line. For example:
CUST=c:\data\customer.ism ORDER=c:\data\orders.ism PLANTS=c:\data\plants.ism
The following connect file examples set an environment variable named XFDBTUT (which is used in the sample Synergy database and set in the sample connect file):
- Windows:
dictsource "C:\Program Files\Synergex\SynergyDE\connect\synodbc\dict\" datasource ";C:\\Program Files\\Synergex\\SynergyDE\\connect\\synodbc\\dat;" XFDBTUT=C:\Program Files\Synergex\SynergyDE\connect\synodbc\dat
- Unix:
dictsource /usr/synergyde/connect/synodbc/dict datasource ;/usr/synergyde/connect/synodbc/dat; XFDBTUT=/usr/synergyde/connect/synodbc/dat
- OpenVMS:
dictsource DKA300:[SYNERGYDE.CONNECT.SYNODBC.DICT] datasource ;DKA300:[SYNERGYDE.CONNECT.SYNODBC.DATA]; XFDBTUT=DKA300:[SYNERGYDE.CONNECT.SYNODBC.DATA]
|
|
If you set SYNCENTURY and SYNBASEDATE, you must set them in the connect file if the connect file is on the server. |
For more information on connect files, see Setting Up a Connect File.
Setting environment variables in the xfODBC Setup window
The xfODBC Setup window has two fields you can use to set environment variables used for data access (not system catalog generation).
- The “Appended to connect string” field, which enables you to define environment variables used by the target database on a server. Note that to use this field, you must use SQL OpenNet (i.e., you must select Net in the “Vortex driver” field of the xfODBC Setup window).
- The “Env. variables” field, which enables you to set environment variables used by the xfODBC driver on the client. This is the only place these environment variables can be set for services such as web servers that use the xfODBC driver.
For information on the xfODBC Setup window and the syntax for setting environment variables in these fields, see Adding a user or system DSN.
Setting environment variables in an environment setup file
An environment setup file is one way to store and activate all the data environment variables you need when connecting to a Synergy database. An environment setup file is a text file you write; it typically has an .ini file extension and is placed in the GENESIS_HOME directory, though these are not requirements. Note the following:
- Define environment variables in the same way you define them in a connect file (except that you can use environment variables in the definition)—for example:
XFDBTUT=%CONNECTDIR%synodbc\dat
- Assign the environment setup file’s path and filename to SODBC_INIFIL in the environment. For stand-alone configurations, it can also be set in the connect file. For client/server configurations, it must be set on the server in the environment or in the opennet.srv file (Windows only). xfODBC is coded to look for a file assigned to this variable and to read it for data environment variables.
Setting environment variables in synergy.ini (Windows)
Because the DBA program, xfdba.dbr, is a Synergy application, you can set environment variables used by DBA in synergy.ini. Synergy.ini is read every time you run dbr.
|
|
The xfODBC driver and dbcreate don’t recognize environment variables set in synergy.ini. |
Below is an example of an environment variable set in synergy.ini. Note an environment variable can be used as part of another environment variable’s definition.
SODBC_DBA=%CONNECTDIR%synodbc\dba
Setting environment variables in opennet.srv (Windows)
Environment variables used by the SQL OpenNet server can be defined in the opennet.srv file. For example, the distributed opennet.srv file defines GENESIS_HOME before starting the Synergy/DE OpenNet Server service (SynSQL):
GENESIS_HOME=%CONNECTDIR%synodbc\ . . . vtxnetd.exe -k67834 -p1958 log
This sets the environment variable and then launches the service, overriding any system-set variable. For more information on opennet.srv, see Customizing the opennet.srv file.
Setting environment variables in System Properties (Windows)
On Windows, you can set system-wide environment variables from the System Properties dialog. From Windows Control Panel, select System, then select Advanced System Settings to display the System Properties dialog. On the Advanced tab, click the Environment Variables button, and then click the New button below the System variables area.
Setting environment variables in log-in files (Unix and OpenVMS)
On Unix, you can set environment variables in the log-in file (.profile if you’re using Bourne or Korn shell, .login if you’re using C shell). After setting an environment variable on Unix, you must export it unless you have the “auto-export” feature turned on in your shell. (Refer to your Unix reference manual for details on auto-export. Not all Unix systems offer this option.)
For example:
GENESIS_HOME=$CONNECTDIR/synodbc export PATH GENESIS_HOME
On OpenVMS, you can set environment variables (logicals) in your user log-in file or in the system-wide log-in file located in SYS$MANAGER. You can also set system-wide environment variables in SYS$MANAGER:CONNECT_STARTUP.COM, but remember that this file is replaced every time you install Synergy. The following is an example of an environment variable set in a log-in file:
$ DEFINE GENESIS_HOME SYNERGYDE$ROOT:[CONNECT.SYNODBC]
