Setting Environment Variables
Scope of 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 on page 203.
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.
Symbol Table
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
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.
Installation-Wide Environment Variables
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.
View Environment Variables
To view all installation-wide environment variables from the command line, enter the following command at the operating system prompt:
ingprenv
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:
ingsetenv II_DECIMAL ,
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.
User-definable Environment Variables
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.
To set an environment variable in the local environment
Use the command appropriate to your environment.
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:
export TERM_INGRES=konsolel
To display the values set in your user environment
Enter the following command at the operating system prompt:
printenv
Environment Variables that Can be Reset Locally
In general, only the following Vector environment variables must be set in your local environment:
• II_SYSTEM
• PATH
The following Vector environment variables can be reset by users in their local operating system shell:
• DBNAME_SQL_INIT
• II_DATE_FORMAT
• II_DBMS_SERVER
• II_DECIMAL
• II_EMBED_SET
• II_GC_REMOTE
• II_GCA_LOG
• II_GCx_TRACE
• II_LANGUAGE
• II_MONEY_FORMAT
• II_MONEY_PREC
• II_NULL_STRING
• II_PRINTSCREEN_FILE
• II_SQL_INIT
• II_SYSTEM
• II_TEMPORARY
• II_TERMCAP_FILE
• II_TIMEZONE_NAME
• II_TM_EXIT_ON_ERROR
• II_TM_ON_ERROR
• II_VNODE_PATH
• II_WORK
• IIDLDIR
• ING_EDIT
• ING_PRINT
• ING_SET
• ING_SET_DBNAME
• ING_SHELL
• INGRES_KEYS
• INIT_INGRES
• TERM
• TERM_INGRES
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.
Environment Variables that Cannot Be Reset
The following Vector environment variables must not be reset by users:
• II_BIND_SVC_xx
• II_C_COMPILER
• II_CHARSETxx
• II_CHECKPOINT
• II_CLIENT
• II_CONFIG
• II_CONNECT_RETRIES
• II_DATABASE
• II_DBMS_LOG
• II_DIRECT_IO
• II_DUMP
• II_ERSEND
• II_GCNxx_PORT
• II_INSTALLATION
• II_JOURNAL
• II_LOG_DEVICE
• II_MSGDIR
• II_NUM_SLAVES
• II_TUXEDO_LOC
• II_TUX_SHARED
• II_TUX_AS_MAX
• II_TUX_XN_MAX
• II_XA_TRACE_FILE
• ING_SYSTEM_SET
These environment variables must not be visible using the env or printenv command.
Customization of Query Runtime Environment
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.
Here are some examples:
• Reduce execution memory requirements when running read-only queries, as for reports:
SET SESSION READ ONLY
• Display the text of the query as it is executed:
SET PRINTQRY
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.
Syntax Rules for Startup Files and Environment Variables
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:
ingsetenv
• 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
This name affects all users of the line-based SQL Terminal Monitor.
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.
DBNAME_SQL_INIT
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.
To define the Vector environment variable DBNAME_SQL_INIT
Use the following command syntax at the operating system prompt:
DBNAME_SQL_INIT=path_to_file export DBNAME_SQL_INIT
For example:
MYDB_SQL_INIT=/usr/george/mystartfile export MYDB_SQL_INIT
where DBNAME is the name of the database and must be in uppercase.
The initialization file contains lines in the following format:
SET SESSION READ ONLY \g
Multiple SET statements must be separated with a semicolon (;). The entire file must end with “\g”.
II_SQL_INIT
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.
To define II_SQL_INIT
Use the following command syntax at the operating system prompt:
II_SQL_INIT=path_to_file export II_SQL_INIT
For example:
II_SQL_INIT=/usr/george/mystartfile export II_SQL_INIT
The file contains lines in the following format:
SET LOCKMODE SESSION WHERE READLOCK = NOLOCK \g
Multiple SET statements must be separated with a semicolon (;). The entire file must end with “\g”.
ING_SET
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
To define ING_SET
Use the following command syntax at the operating system prompt:
ING_SET='set-statement {; set-statement}'
or:
ING_SET='include path_to_file' export ING_SET
Examples:
ING_SET='SET LOCKMODE SESSION WHERE READLOCK=NOLOCK' export ING_SET
ING_SET='include /usr/george/mystartfile' export ING_SET
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 X100_ROW;
ING_SET_DBNAME
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
To define ING_SET_DBNAME
Use the following command entered at the operating system prompt:
ING_SET_DBNAME='set-statement {; set-statement}'
or:
ING_SET_DBNAME='include path_to_file' export ING_SET_DBNAME
For example:
ING_SET_MYDB='SET LOCKMODE SESSION WHERE READLOCK=NOLOCK'export ING_SET_MYDB
ING_SET_MYDB='include /usr/george/mystartfile'export ING_SET_MYDB
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 in the file. For example:
SET AUTOCOMMIT ON;
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK;
SET RESULT_STRUCTURE X100_ROW;
ING_SYSTEM_SET
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
To define ING_SYSTEM_SET
Use the following command entered at the operating system prompt:
ING_SYSTEM_SET='set-statement {; set-statement}'
or:
ING_SYSTEM_SET='include path_to_file'
export ING_SYSTEM_SET
For example:
ING_SYSTEM_SET=’set autocommit on’
export ING_SYSTEM_SET
ING_SYSTEM_SET=’include \ /usr/ingres/ourstartfile’
export ING_SYSTEM_SET
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 in the file. For example:
SET AUTOCOMMIT ON;
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK;
SET RESULT_STRUCTURE X100_ROW
Startsql
This name affects the line-based SQL Terminal Monitor only.
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:
SET LOCKMODE SESSION WHERE READLOCK=NOLOCK \g
Installation Locations
The values for the following Vector variables are established at the time of installation:
• II_SYSTEM
• II_DATABASE
• II_CHECKPOINT
• II_JOURNAL
• II_DUMP
• II_WORK
• II_TEMPLATE
• ING_ABFDIR
Some of these values can be easily changed, and some require unloading of the installation.
When Not to Change Installation Locations
Before changing an existing installation location, be sure that the change is necessary: ask yourself what needs to be moved, and why.
Installation locations do not need to be changed if:
• The installation needs space for future growth.
• Existing databases are outgrowing their present disk partitions.
Allocation of Space for Future Growth
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.
Location Variables that Do and Do Not Require Unloading
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):
• II_SYSTEM
• II_DATABASE
• II_CHECKPOINT
• II_JOURNAL
• II_DUMP
• II_WORK
Change the Value of the ING_ABFDIR Variable
To change the installation default for ING_ABFDIR:
1. Shut down Vector with ingstop.
2. Change the value of ING_ABFDIR with the ingsetenv command.
3. Restart the installation with ingstart.
Note: Application developers who do not want to use the installation default can redefine ING_ABFDIR in their local user environment.
Change an Installation Location with Unloading
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.
4. Reinstall Vector.
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.
5. Recreate each of the databases. For details, see the User Guide.
Use the createdb dbname command to recreate a database.
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.
Use of Symbolic Links
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.