INFORMIX-ESQL/C Programmer's Manual Programming with INFORMIX-ESQL/C

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 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. The library functions are located in Appendix B, ESQL/C Function Library.

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:

• 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.

If you specify a null string for an environment variable in an ifx_putenv() function call, ESQL/C 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.

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.

Important: Informix supports the InetLogin structure for backward compatibility only. For new development, Informix recommends that you use the ifx_getenv() and ifx_putenv() functions instead.

An ESQL/C client application in a Windows environment can use the InetLogin structure to set dynamically the configuration information that the application needs.

This section provides the following information about InetLogin:

• A description of the InetLogin structure, its fields, and header file
• The precedence of configuration information that the client application sends when it establishes a connection
• How to set the InetLogin fields directly

The InetLogin structure is a global C structure that the login.h header file declares. To use this structure in your ESQL/C program, you must include login.h in your source file (.ec). For more information on login.h, see Figure 1-19 on page 1-40.

Tip: Because login.h does not contain ESQL/C statements, you can include the file with the C #include or the ESQL/C include directive.

Figure 1-20 defines the fields in the InetLogin structure.

All fields in the InetLogin structure, except DbAnsiWarn, Client_Loc, and DB_Loc, are of data type char and are null-terminated strings. The Client_Loc and DB_Loc fields are character pointers whose data space your ESQL/C program must allocate.

Your application must set InetLogin values before it executes the SQL statement or ESQL/C library function that needs the configuration information. Informix recommends that you use the ifx_putenv() and ifx_getenv() functions to set and retrieve InetLogin field values through environment variables, but you can set the values of the InetLogin fields directly.

Figure 1-21 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-21 User Dialog Box for Login Parameters

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

strcpy(InetLogin.InfxServer, "mainsrvr");


case IDOK:

	*szDlgString = '\0';

	GetDlgItemText (hdlg, IDC_HOST, szDlgString, cbSzDlgMax);

	strcpy(InetLogin.Host, szDlgString);



	*szDlgString = '\0';

	GetDlgItemText (hdlg, IDC_USER, szDlgString, cbSzDlgMax);

	strcpy(InetLogin.User, szDlgString);

In Figure 1-22, 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

If the application uses the InetLogin structure, ESQL/C first checks for configuration information in this structure. (To set the value of an environment variable for the application process, the ifx_putenv() function changes the value of an InetLogin field.)

2. The INFORMIX subkey of the Registry

If the application has not set the desired configuration information in InetLogin, ESQL/C checks for this information in its copy of the Registry information. For more information on how to set the Registry, see the Informix Client Products Installation 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 do 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 Guide for Microsoft Windows Environments."