4. Setting Environment Variables

Vector has a set of environmental variables through which you can define various file names and other values. For a list of the basic Vector environment variables, see Environment Variables.

Vector uses the following types of operating-system dependent environment variables:

• Linux environment variables

• Installation-wide environment variables

Vector environment variables in Linux are active only when you are using Vector. A small subset of these environment variables can be reset in the local environment by the user.

Most Vector environment variables are set in the Vector symbol table (symbol.tbl) and are visible only with the user command ingprenv.

When setting, unsetting, or changing environment variables, a backup of the symbol.tbl file, called symbol.bak, is maintained. If the original symbol.tbl file becomes corrupted, you can use the backup symbol table file to restore it.

A history of updates to the symbol.tbl file is maintained in the symbol.log file. The symbol.log file contains information on the types of updates performed as well as some application information.

The symbol.bak and symbol.log files are located in the II_CONFIG location.

Linux environment variables are set at the shell level. These are in effect before, during, and after Vector is invoked. There are several variables required for Vector. These variables are set by the .ingXXsh script, which is generated in the home directory of the administrative user (typically actian).

To make the environment global, you can copy/link the script to /etc/profile.d and remove the "." so it is not hidden.

To source the environment automatically for the actian user, add . ~/.ingXXsh to the .bashrc file.

Vector environment variables that are defined at the Vector system or installation-wide level affect all users in an installation. These are usually defined during the install procedure. However, the system administrator can reset some manually.

To view all installation-wide environment variables from the command line, enter the following command at the operating system prompt:

To manually register or to remove an environment variable from the symbol table, use the ingsetenv and ingunset commands. Never edit the symbol table file directly.

For example, to change the value of II_DECIMAL (character used to separate fractional and non-fractional parts of a number) from a period to a comma, issue this command:

A similar set of system administrator commands are available to set, print, and unset installation-wide Vector environment variables simultaneously for all clients of a server installation. These commands are ingsetall, ingprall, and ingunsetall.

Some Vector environment variables can be set or reset by individual users in their local environment using operating system commands. Those set in a user’s local environment supersede the Vector environment variables set system-wide.

A good place to set user-defined environment variables is the user’s .bashrc or profile file.

For example, an environment variable typically set in the user’s local environment is TERM_INGRES. It specifies the termcap definition to be used by the forms system. It can be redefined locally by entering commands at the operating system prompt:

In general, only the following Vector environment variables must be set in your local environment:

The following Vector environment variables can be reset by users in their local operating system shell:

• II_PRINTSCREEN_FILE

• II_TIMEZONE_NAME

• II_TM_EXIT_ON_ERROR

IMPORTANT! II_TIMEZONE_NAME can be reset for client installations only. Server installations must not reset this variable because it may affect date conversions from the local system time to the internal GMT-based value.

• II_CONNECT_RETRIES

• II_XA_TRACE_FILE

These environment variables must not be visible using the env or printenv command.

Most aspects of the environment in which queries execute can be customized at runtime for a particular session. This can be done by executing one or more SET statements to customize the environment before query execution begins.

• Reduce execution memory requirements when running read-only queries, as for reports:

• Display the text of the query as it is executed:

Vector makes customization flexible by permitting most components of the query environment to be set by means of SET statements at the startup of individual queries (sessions). This can be done by using various Vector environment variables and startup files that let you control both the target and duration of SET statement customization.

A full list of SET statements can be found in your query language reference guide.

Keep the following general syntax rules in mind while setting up startup files and environment variables:

• SET statements in startup files cannot contain more than one SET statement per line. Each statement must be on a line by itself.

• SET statements that are read from a file but executed only by the line-based terminal monitor, must be terminated with “\g”.

• SET statements defined directly inside Vector environment variables (not written in a file) never contain the string “\g”.

• SET statements defined directly inside Vector environment variables (not written in a file) can contain multiple SET statements separated by a semicolon up to a total length of 64 characters.

• The terminal monitor dayfile cannot contain SET statements. It contains informational startup messages only.

• Vector environment variables set with the following command are global for the installation and affect the target of the environment variable for all users in an installation:

• Vector environment variables set from the local user environment apply only to the user setting them. Other users are not affected. This is the case, for example, when Vector environment variables are set interactively or from a user's .profile, or .bashrc file.

Dayfile contains text messages only (not SET statements), which appear as an informational header whenever the Terminal Monitor is started. It is located in $II_SYSTEM/ingres/files directory. The message header can be suppressed with the -d command line flag.

This variable applies to the line-based SQL Terminal Monitor only. DBNAME_SQL_INIT points to SET statements within a file that are executed whenever this Vector environment variable takes effect.

DBNAME_SQL_INIT affects users who connect to the database specified by DBNAME through the SQL Terminal Monitor. If set globally, it affects all users of DBNAME. If set interactively or locally, it affects only this user.

Global setting is with ingsetenv, or locally in the user’s .login, .profile, or .cshrc file.

Setting the DBNAME_SQL_INIT environment variable is equivalent to executing \i filename in the SQL Terminal Monitor each time you connect to DBNAME.

Multiple SET statements must be separated with a semicolon (;). The entire file must end with “\g”.

This name applies to the line-based SQL Terminal Monitor only. II_SQL_INIT points to SET statements within a file that are executed whenever this Vector environment variable takes effect.

II_SQL_INIT affects users who connect to the SQL Terminal Monitor. If set globally, it affects all users. If set interactively or locally, it affects only this user.

Global setting is with ingsetenv, or locally in the user’s .login, .profile or .cshrc file

Setting this environment variable is equivalent to executing \i filename in the SQL Terminal Monitor each time you connect to a database.

Multiple SET statements must be separated with a semicolon (;). The entire file must end with “\g”.

This name applies to the line-based SQL Terminal Monitor and tools such as ABF, VIFRED, embedded SQL, QBF, and ISQL. ING_SET points to SET statements that are executed whenever this Vector environment variable takes effect.

ING_SET affects users who connect to an application, a Vector tool, or a terminal monitor. If set globally, it affects all users. If set interactively or locally, it affects only this user.

Global setting is with ingsetenv, or locally in the user’s .login, .profile, or .cshrc file.

ING_SET is set to a string surrounded by quotes. The string must be 64 characters or less, or it is invalid. The string can contain either:

• One or more set statements totaling no more than 64 characters

• The word include followed by the full path name to a file containing any number of SET statements

For the include format, the file specified by path_to_file contains the SET statements. Multiple SET statements must be separated with a semicolon (;). Place each SET statement on a separate line. For example:

SET AUTOCOMMIT ON;
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK;
SET RESULT_STRUCTURE VECTORWISE_ROW;

This name applies to the line-based SQL Terminal Monitor and tools such as ABF, VIFRED, embedded SQL, QBF, and ISQL. ING_SET_DBNAME points to SET statements that are executed whenever this Vector environment variable takes effect.

ING_SET_DBNAME affects users who connect to the database specified by DBNAME through an application, a Vector tool, or terminal monitor. If set globally, it affects all users of DBNAME. If set interactively or locally, it affects only this user.

Global setting is with ingsetenv, or locally in the user’s .login, .profile or .cshrc file.

ING_SET_DBNAME is set to a string surrounded by quotes. The string must be 64 characters or less, or it is invalid. The string can contain either:

• One or more set statements totaling no more than 64 characters

• The word include followed by the full path name to a file containing any number of SET statements

ING_SET_MYDB='SET LOCKMODE SESSION WHERE READLOCK=NOLOCK'export ING_SET_MYDB

SET AUTOCOMMIT ON;
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK;
SET RESULT_STRUCTURE VECTORWISE_ROW;

This name applies to the line-based SQL Terminal Monitor and tools such as ABF, VIFRED, embedded SQL, QBF, and ISQL. ING_SYSTEM_SET points to SET statements that are executed whenever this Vector environment variable takes effect.

ING_SYSTEM_SET affects all users who connect to a DBMS Server through an application, a Vector tool, or terminal monitor. It is always effective globally and can be set only by a privileged user.

ING_SYSTEM_SET is set to a string surrounded by quotes. The string must be 64 characters or less, or it is invalid. The string can contain either:

• One or more SET statements totaling no more than 64 characters

• The word include followed by the full path name to a file containing any number of SET statements

SET AUTOCOMMIT ON;
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK;
SET RESULT_STRUCTURE VECTORWISE_ROW

Startsql affects all users of the SQL Terminal Monitor. It is a customizable file located at: II_SYSTEM/ingres/files/startsql.

Users with permission to edit this file can add statements of the following example:

The values for the following Vector variables are established at the time of installation:

Some of these values can be easily changed, and some require unloading of the installation.

Before changing an existing installation location, be sure that the change is necessary: ask yourself what needs to be moved, and why.

• The installation needs space for future growth.

• Existing databases are outgrowing their present disk partitions.

Vector provides the capability of creating new locations and placing any new databases, tables, or indexes in these new locations. If the requirement is space for new tables or databases, you do not need to change existing locations.

Instead, create the necessary new locations for these future tables and databases and use the available location flags of createdb (-d, -c, -j, -b, and -w) to create the data, checkpoint, journal, dump, and work files for the newly created database in some other location.

For more information on creating new databases, see the createdb command in the Command Reference.

When you need to change the value of an installation location variable, the procedure depends to some extent on the underlying operating system. On Linux, the procedure also depends on whether the change requires unloading the database.

You can change the ING_ABFDIR location value without unloading the installation.

The values of the following locations are stored in the configuration file “aaaaaaaa.cnf” of each database at the time it is created and can only be changed by unloading each database, re-installing Vector and reloading the databases (thus creating a new configuration file):

Note: Application developers who do not want to use the installation default can redefine ING_ABFDIR in their local user environment.

Follow these steps in Linux to change the value of II_SYSTEM, II_DATABASE, II_CHECKPOINT, II_JOURNAL II_DUMP, or II_WORK. “II_SYSTEM” is used as the example location being changed:

1. Unload each database. For details, see the unloaddb command in the User Guide.

2. Remove the old installation files by removing everything under the old II_SYSTEM/ingres directory and any extended locations.

3. Set the value of II_SYSTEM and PATH to the desired new values, just as if you were installing Vector for the first time.

Follow the instructions in the Getting Started guide for a new (not upgrade) installation.

As part of the installation procedure, the program prompts you for the new values of Vector location variables II_DATABASE, II_CHECKPOINT, II_JOURNAL, II_DUMP, and II_WORK.

Reload each database by appropriately editing and running the reload.ing script.

6. Once you have reinstalled Vector and recreated the databases in the new location, take new checkpoints of each of the databases. Checkpoints taken in old locations are no longer valid. For details, see the User Guide.

Vector does not support or recommend the use of symbolic links to change locations in Linux. (This is possible with the Linux ln command, which allows the Linux system administrator to create symbolic links to new directories so that files are found in another directory even though the values of Vector installation location variables remain unchanged.)

Common problems that arise from the misuse of symbolic links are as follows:

• Any files to which Vector writes must reside on a file system that is local to the machine on which the writing process is running. This is necessary because of the operating system’s inability to guarantee network writes. If symbolic links are used, writable directories can mistakenly be mounted from remote machines. This can cause write errors and data corruption.

• Occasionally Vector executables reside on NFS file systems that have been exported with the nosuid option. The permissions appear normal when the ls -l command is issued, but setuid programs fails with permission errors.

The rm command does not remove files that are symbolic links. Instead, the symbolic link itself is broken, but the original file remains. This can cause cleanup routines to fail in some circumstances.