Setting environment variables and initialization settings

You can set environment variables by

You can obtain the value of most environment variables using the GETLOG routine. For a list of exceptions on Windows, see Synergy initialization files.

We recommend that you place the environment variable commands in your log‑in file, so that your development environment is set up automatically each time you log in. The log‑in file you use and the commands you enter depend on what operating system you are running.

To set up the environment variables you need for your system, see the following:

Settings on Windows

You can set environment variables in one of three ways:

Note

Any environment variables set for use by xfServer or xfServerPlus must be set in the Windows registry. You can set environment variables in the registry using the Synergy Configuration Program.

Note

When setting environment variables marked “environment” for services such as dbssvc, xfServerPlus, xfServer, or the SQL Connection OpenNet server, the system environment must be updated and the system rebooted before the service is started.

Synergy initialization files

Synergy.ini and synuser.ini are the initialization files that contain environment variables affecting the Synergy runtime, Synergy/DE development tools, and Synergy applications on Windows. The synergy.ini file contains system‑ or application‑specific settings for multiple users and Visual Studio projects. The synuser.ini file contains user‑specific settings (for example, personal preferences such as colors, fonts, the state of the application window, the position and size of the print preview window, and any overrides to system‑specific settings).

When a system administrator or application provider changes a setting in the system initialization file (synergy.ini), all users get the new setting unless they have overridden the setting in their user file (synuser.ini). When a user modifies a setting in his or her synuser.ini file, the change only applies to that user. Changes to the synuser.ini file do not affect the general behavior of the application or the settings of any other user.

Variables in synergy.ini can be set for individual Synergy/DE tools (dbl, dbr, dblink, and dblibr) and can be changed at any time. With the exception of a few special startup parameters, the settings are in effect for the duration of the executable that loaded them, but after the executable has finished running, the original environment variable settings once again take effect. For the runtime, synuser.ini can also be used; synuser.ini settings override synergy.ini settings. Although variables in these files can also be set for individual Synergy programs (.dbr), they are only interpreted for the first .dbr program executed by dbr.exe, and then they stay in effect for all subsequent programs that are chained to. The initialization files are not reread for the chained‑to programs.

Note

The Synergy .NET non‑device runtime, the non‑interactive runtimes (dbs, dbssvc, and dbspriv), and Visual Studio only look in the environment for environment variables, with two exceptions. If SFWINIPATH is set, it uses the synergy.ini file identified by the location specified. If SFWINIPATH is not set, it uses the default synergy.ini file. If SFWUSRINIPATH is set in the environment at startup, the Synergy .NET non‑device runtime and the non‑interactive runtimes will read the synuser.ini file.

Environment variables such as DBLDIR, SYNERGYDE, and RPS should not be set in the system environment.

Most Synergy environment variables can be set in a Synergy initialization file. Refer to the documentation for each environment variable to determine whether or not it can be set there. Note that on the individual environment variable pages, we only list synergy.ini (and not synuser.ini) as a setting location. This is because we do not recommend that you manually edit the synuser.ini file, but instead let it be created or updated by the Synergy/DE tools or programmatically by your Synergy application.

Note

For Visual Studio projects that affect the build system, we recommend adding environment variables as common properties rather than setting them in synergy.ini.

On Windows, all settings in the [synergy], [dbr], and [myprog] sections of synergy.ini and synuser.ini are put into the environment, with the exception of the following:

Settings in the [colors] or [fonts] section, or in any section that you add (with the exception of [myprog]), are not set in the environment.

Although you can set PATH in the synergy.ini file, this file is only recognized after the executables have started. PATH should be set with the System icon from Control Panel.

Creating synergy.ini and synuser.ini

The installation program places a default synergy.ini file in the synergyde\dbl directory when you install Synergy/DE. If the environment variable SFWINIPATH is not set, or if the synergy.ini file referenced by SFWINIPATH cannot be accessed, the synergy.ini file in synergyde\dbl will be used. However, since this is just a default file that will be removed during an upgrade or uninstallation, we recommend that you copy this file elsewhere and specify the path to the copied file with SFWINIPATH.

The synuser.ini file is created the first time an entry is written to it. Synergy/DE tools write to synuser.ini at runtime when they save your user settings. The synuser.ini file is created in the Synergex subdirectory of your local application data directory (Documents and Settings\username\Local Settings\Application Data).

To determine the exact location of the synergy.ini and synuser.ini files being used by Synergy, you can run the synckini utility in the dbl\bin directory.

Organization of synergy.ini and synuser.ini

Initialization files are organized into one or more sections, with section headings enclosed in square brackets and beginning in the left‑most column of the file. For example:

[synergy]

Settings in initialization files use the following format:

ini_variable=value

For example, a synergy.ini file containing the DBLDIR, ISAMC_REV, and SHELL initialization settings might look like this:

[synergy]
DBLDIR=c:\synwin\dbl
ISAMC_REV=3
SHELL=c:\dos\command.com

Different initialization file sections affect different things:

Initialization File Sections

Initialization settings in

Affect

[synergy]a

All Synergy/DE development tools and the runtime

[dbr]

Only the runtime

[myprog]
(myprog is the name of any .dbr file)

Only the runtime when myprog.dbr is run

[dbl]

Only the compiler

[dblink]

Only the linker

[dblibr]

Only the librarian

[listdbo]

Only the listdbo utility

[listelb]

Only the listelb utility

[listdbr]

Only the listdbr utility

[fonts]

Fonts in Synergy/DE executables

[colors]a

Colors in Synergy/DE executables

[fconvert]

Only the fconvert utility

[isutl]

Only the isutl utility

a. [synergy] and [colors] are the only sections used by Synergy .NET.

Priority of synergy.ini and synuser.ini settings

On all Windows systems, initialization settings included in the Synergy initialization files override any previous settings (such as those set in the system environment at startup). For example, if you set DBLDIR and ISAMC_REV in the environment, and your synergy.ini file contains a setting for DBLDIR but has no setting for ISAMC_REV, Synergy/DE products will use the DBLDIR setting in synergy.ini and the ISAMC_REV setting specified in the environment.

The two initialization files themselves are read according to the following hierarchy:

1. [synergy] section of synergy.ini
2. [synergy] section of synuser.ini
3. [dbr] section of synergy.ini (also [dbl], [dblink], and [dblibr])
4. [dbr] section of synuser.ini (also [dbl], [dblink], and [dblibr])
5. [myprog] section of synergy.ini (where myprog is any .dbr file)
6. [myprog] section of synuser.ini (where myprog is the same .dbr file)
7. Other sections of the initialization files, such as [fonts], [colors], etc., following the same precedence (synergy.ini is read first, followed by synuser.ini)

The last specification overrides the first in any conflict. For example, if the same font or color is defined in both files, the specification in the synuser.ini file prevails. If a font or color is defined in only one of the files, the definitions are additive.

The following table illustrates the hierarchy of interpreting environment variables on Windows.

Global environmenta

synergy.ini

synuser.ini

Final result

DBLDIR=c:\synergyde\dbl

DBLDIR=c:\mysynergy

 

DBLDIR=c:\mysynergy

 

[fonts]

DEFAULT=Fixedsys;9;A

[fonts]

DEFAULT=Arial;10;A

[fonts]

DEFAULT=Arial;10;A

ISAMC_REV=4

 

 

ISAMC_REV=4

a. Setting environment variables in the global environment means setting them from the System icon in Control Panel.

Modifying the synergy.ini file

You can add additional initialization settings or change existing settings in your synergy.ini file by editing the file using any text editor.

Important

If you use a word processing program or any other program that formats text, the formatting characters may make the synergy.ini file unreadable to Synergy/DE. Be sure to save the changed file as a text file, without formatting information.

Alternately, you can use the synckini utility which prompts you to edit the synergy.ini file in the registered editor for .ini files (Notepad by default)..

Modifying the synuser.ini file

Although you can locate and manually edit your synuser.ini file, we do not recommend it. The synuser.ini file is updated programmatically by a few Synergy/DE tools and can be updated programmatically by your Synergy application. For example, Composer updates the [fonts] and [colors] sections of synuser.ini. The Synergy Windows printing API updates the synuser.ini file with the print preview environment variables (for example, PRINT_PREVIEW_ZOOM). A number of UI Toolkit routines give you the option of updating the synuser.ini file rather than synergy.ini (for example, U_EDITREND, U_SAVELOG, U_SAVESETTINGS, and %U_WNDFONT).

Settings on UNIX

On UNIX systems, you can place environment variables in your log‑in file. The log‑in file for UNIX systems is .profile if you are using Bourne or Korn shell or .login if you are 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:

DBLDIR=/usr/synergy/dbl ;export DBLDIR 

If any file specifications in your programs or command files contain directory specifications, you should define these names as search list environment variables. These assignments are case sensitive, and spaces are significant. (See DBLCASE.) For example:

Bourne shell:

SRC=/usr/mine/source,/usr/progs 
OBJ=/usr/mine/object 
export SRC OBJ 

C shell:

setenv SRC /usr/mine/source,/usr/progs 
setenv OBJ /usr/mine/objeclt 

You’ll find more information about search list environment variables in Synergy DBL files.

Settings on OpenVMS

OpenVMS doesn’t use the term “environment variables.” You should substitute a logical name anywhere the Synergy/DE manuals use the term “environment variables.” On OpenVMS systems, you can place logicals in your log‑in file, login.com, or the system‑wide log‑in file located in SYS$MANAGER.

If any file specifications in your programs or command files contain directory specifications, you should define logical names to reference those locations, and use the logical name in the program or command file.

The OpenVMS operating system has the concept of search list logicals. These are logical names that have multiple translation values. When you specify a search list logical in an OPEN statement, the operating system scans all the locations listed to find the named file.

Some of the environment variables described in the following pages require a list of comma‑separated values. These are not search lists, they are just comma‑delimited values used and parsed by the compiler and runtime. When we use the term “search list” in the following pages, it means a comma‑delimited value. Use quotation marks to prevent commas from creating multiple translation values.

To define a search list logical, use the following format:

$ DEFINE DATA_LOCATION DKA100:[DATA],DKA200:[BACKUP_DATA]

To define a comma‑delimited value, use the following format:

$ DEFINE DBLOPT "7,35,43"