Set and retrieve environment variables in Windows environments

You might change the settings of environment variables or create new variables to increase the flexibility of an application. Instead of assuming a particular environment configuration, you can define the environment at run time.

This option can benefit your application in the following ways:
  • The application becomes less dependent on a predefined environment.
  • Users can enter their user name and password within an application.
  • Users can run two applications with different network parameters on the same client computer.
  • The same application can run on client computers with different configurations.
The following library functions are available for setting and retrieving environment variables.
ifx_putenv()
Modifies or removes an existing environment variable or creates a variable.
ifx_getenv()
Retrieves the value of an environment variable.
Important: The ifx_putenv() function sets the value of an environment variable in the InetLogin structure, and the ifx_getenv() function retrieves the value of an environment variable from InetLogin. It is recommended that you use these functions to set and retrieve InetLogin field values.

These functions affect only the environment that is local to the current process. The ifx_putenv() function cannot modify the command-level environment. The functions operate only on data structures accessible to the runtime library and not on the environment segment that the operating system creates for the process. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level).

The process cannot directly pass on the modified environment to any new processes that _spawn(), _exec(), or system() creates. These new processes do not receive any new variables that ifx_putenv() added. You can, however, pass on an environment variable to a new process in the following way:
  1. The current process creates an environment variable with the ifx_putenv() function.
  2. The current process uses the C putenv() function to put the environment variable into the operating-system environment segment.
  3. The current process starts a new process.
  4. The new process uses the C getenv() function to retrieve the environment variable from the operating-system environment segment.
  5. The new process uses the ifx_getenv() function to retrieve the variable into the runtime environment segment.

Environment variable guidelines

For environment variable entries, observe the following guidelines:
  • If you plan to set any HCL OneDB™ environment variables with ifx_putenv(), have the application set all of them before it calls any other library routine, including ifx_getenv(), or any SQL statement. The first call to any other library routine or SQL statement requires initialization of the GLS locales. This initialization loads and freezes the values of CLIENT_LOCALE, DB_LOCALE, and the DATE, TIME, and DATETIME formatting values.
  • If Setnet32 sets the HCL OneDB environment variable to a non-null value in the Registry, the ifx_putenv() function cannot change the value of the variable to a null string.

    If you specify a null string for an environment variable in an ifx_putenv() function call, clears any value set for the environment variable from the runtime environment segment. Then the Registry value for the environment variable is available to the application.

  • Do not change an environment variable with setenv in the command line or with the C putenv() function because a change to the operating-system environment segment has no effect on the ESQL client-interface DLL after application execution begins.

    Instead, use ifx_putenv() to change an environment variable in the runtime environment segment.

  • To modify the return value of ifx_getenv() without affecting the environment table, use _strdup() or strcpy() to make a copy of the string.
Restriction: Never free the pointer to an environment entry that ifx_getenv() returns. Also, do not pass ifx_putenv() a pointer to a local variable and then exit the function that declares the variable.