Informix-ESQL/C Programmer's Manual

Informix-ESQL/C Programmer's Manual
Chapter 1: Programming with INFORMIX-ESQL/C

Home Contents Index Master Index New Book

Setting and Retrieving Environment Variables in Windows Environments

You might change the settings of environment variables or create new ones to increase the flexibility of an application. Instead of assuming a particular environment configuration, you can define the environment at runtime. 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 ESQL/C library functions are available for setting and retrieving environment variables.


Function Name	Description
ifx_putenv()	Modifies or removes an existing environment variable or creates a new one
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. Informix recommends that you use these functions to set and retrieve InetLogin field values. For more information about InetLogin fields, see "Fields of the InetLogin Structure".

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 ESQL/C 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 ESQL/C 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 ESQL/C ifx_getenv() function to retrieve the variable into the runtime environment segment.

For environment variable entries, observe the following guidelines:

GLS

If you plan to set any Informix environment variables with ifx_putenv(), have the application set all of them before it calls any other ESQL/C library routine, including ifx_getenv(), or any SQL statement. The first call to any other ESQL/C 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 an Informix 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.

ifx_putenv()

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.

ifx_putenv()

To modify the return value of ifx_getenv() without affecting the environment table, use _strdup() or strcpy() to make a copy of the string.

Warning: 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.

ifx_putenv()

Purpose

The ifx_putenv() function changes the value of an existing environment variable, creates a new environment variable, or removes a variable from the runtime environment.

Syntax

int ifx_putenv( envstring );

	const  char *envstring; 


envstring  
is a pointer to a string of the form varname=string, in which varname is the name of the environment variable to add or modify and string is the variable value.

Usage

The ifx_putenv() function adds new environment variables or modifies the values of existing environment variables in the InetLogin structure. These variables define the environment in which a process executes. If varname is already part of the environment, ifx_putenv() replaces the existing value with string; otherwise, ifx_putenv() adds varname to the environment, with the value string.

To remove a variable from the runtime environment, specify only varname= (a null string).

The ifx_putenv() function sets Informix variables first and then non-Informix variables. For a list of Informix environment variables, see "Fields of the InetLogin Structure".

The following call to the ifx_putenv() function changes the value of the INFORMIXDIR environment variable:

ifx_putenv( "informixdir=c:\informix" );

This function affects only the environment variable of the current process. The environment of the command processor does not change.

Return Codes

0
The call to ifx_putenv() was successful.

-1
The call to ifx_putenv() was not successful.

ifx_getenv()

Purpose

The ifx_getenv() function retrieves the value of a current environment variable.

Syntax

char *ifx_getenv( varname );

	 const char *varname; 


varname  
is a pointer to a buffer that contains the name of an environment variable.

Usage

The ifx_getenv() function searches for the environment variable in the following order:

1. Table of Informix environment variables that the application has modified or defined with the ifx_putenv() function or directly (the InetLogin structure)

2. Table of Informix environment variables that the user has defined in the Registry with the Setnet32 utility

3. Non-Informix environment variables retrieved from the C runtime environment variables

4. Table of defined defaults for Informix environment variables

The ifx_getenv() function is not case sensitive. You can specify the name of the environment variable in any case.

The ifx_getenv() function operates only on the data structures accessible to the C runtime library and not on the environment segment that the operating system creates for the process. Therefore, programs that use ifx_getenv() might retrieve invalid information.

The ifx_putenv() and ifx_getenv() functions use the copy of the environment to which the global variable _environ points to access the environment.

The following program fragment uses ifx_getenv() to retrieve the current value of the INFORMIXDIR environment variable:

char InformixDirVal[100];


/* Get current value of INFORMIXDIR */
InformixDirVal = ifx_getenv( "informixdir" );
/* Check if INFORMIXDIR is set */
If( InformixDirVal != NULL )
	printf( "Current INFORMIXDIR value is  %\n", InformixDirVal );

Figure 1-29 shows a dialog box that a client application might use to obtain network parameters from an end user. This application takes the account information that the user enters and sets the appropriate network values in the InetLogin structure.

Figure 1-29
User Dialog Box for Login Parameters

Figure 1-30 shows a code fragment that sets login values in the InetLogin structure. The application could obtain these values from the end user through a dialog box (such as the one in Figure 1-29).

Figure 1-30
Code to Prompt the User for InetLogin Values

In Figure 1-30, if the user enters host information, the fragment sets the InetLogin.Host and InetLogin.User fields for the mainsrvr database server to the user-specified names of the host name and user name, respectively. If the user does not enter host information, ESQL/C uses the HOST and USER Registry values from the subkey for the mainsrvr database server.

Tip: For another example of how to set the InetLogin fields, see the ILOGIN demo program in the %INFORMIXDIR%\demo\ilogin directory.

Precedence of Configuration Values

When a client application in a Windows environment requires configuration information, ESQL/C obtains it from the following locations:

1. The InetLogin structure

InetLogin

ifx_putenv()

InetLogin

2. The INFORMIX subkey of the Registry

not

InetLogin

Informix Client Products Installation and Configuration Guide for Microsoft Windows Environments

You do not need to define all the values in the InetLogin structure. The application uses the configuration information in the Registry for any values it cannot find in InetLogin. If you have not set the corresponding Registry value, the application uses its default value.

Important: The first time that the application requires configuration information, ESQL/C reads this information from the Registry and stores it in memory. For subsequent references to Registry information, ESQL/C accesses this in-memory copy and does not reread the Registry.

This hierarchy of configuration information is valuable if, for example, you want the application user to provide a user name and password at runtime, or if an application has some configuration information that differs from the general values in the Registry. For example, suppose the application sets the ConRetry field of InetLogin to 2 but does not set the ConTime field, as the following code fragment shows:

strcpy(InetLogin.ConRetry, "2");

EXEC SQL connect to 'accnts';

When ESQL/C establishes the connection to the accnts database, it tries to establish the connection twice (instead of the default value of once) but it still uses a connection time of 15 seconds (the default value from the in-memory copy of the Registry information). If Setnet32 has modified the connection values, ESQL/C uses the modified Registry values instead of the default values.

Tip: Use the Setnet32 utility to define configuration information in the Registry. For more information about Setnet32, refer to the "Informix Client Products Installation and Configuration Guide for Microsoft Windows Environments."

Informix-ESQL/C Programmer's ManualChapter 1: Programming with INFORMIX-ESQL/C Home Contents Index Master Index New Book

Setting and Retrieving Environment Variables in Windows Environments

ifx_putenv()

Purpose

Syntax

Usage

Return Codes 0 The call to ifx_putenv() was successful. -1 The call to ifx_putenv() was not successful.

ifx_getenv()

Purpose

Syntax

Usage

Return Codes

InetLogin Structure

Fields of the InetLogin Structure

InetLogin Field Values

Precedence of Configuration Values

Informix-ESQL/C Programmer's Manual
Chapter 1: Programming with INFORMIX-ESQL/C

Home Contents Index Master Index New Book

Return Codes

0
The call to ifx_putenv() was successful.

-1
The call to ifx_putenv() was not successful.