The Client-Server Connection
An ESQL/C application can establish a connection to any valid database environment. A database environment can be a database, a database server, or a database and a database server. Every database must have a database server to manage its information. To establish connections, the client application must be able to locate information about the available database servers. This information is in the sqlhosts file. At runtime, the application must also be able to access information about environment variables relevant for connection. The following environment variables are accessed:
Specifies that the client should try connection attempts for the minimum of seconds specified
Defines the number of connection attempts made by the client during the time specified by INFORMIXCONTIME
Defines where to find the sqlhosts information. The sqlhosts information contains a list of valid database servers that the client can connect to, the type of connection to be used, and the server machine name on which each database server resides. On a UNIX operating system, this will be a path to a file. In a Windows environment, this is the name of the machine on the network that contains the central registry which is accessible to the client application.
Specifies the name of the default database server that the client should connect to. This value identifies which entry in the sqlhosts file to use to establish the database connection.
The client application connects to the default database server when the application does not explicitly specify a database server for the connection. For more information, see "The Default Database Server".
The client also sends environment variables so that the database server can determine the server-processing locale. For more information on how the database server establishes the server-processing locale, see the Informix Guide to GLS Functionality.
The database server uses appropriate environment information when it processes the application requests. It ignores any information that is not relevant. For example, if the application sends environment variables for a database with Asian Language Support (ALS), but it connects to a non-ALS database, the database server ignores the ALS information. 
For information on how to set environment variables, see the Informix Guide to SQL: Reference for your operating system.
Sources of Connection Information on a UNIX Operating System
Many other environment variables can customize the database environment. For more information, refer to the Informix Guide to SQL: Reference and to the Administrator's Guide for your database server.
Accessing the sqlhosts File
To establish a connection to a database server, the application process must be able to locate an entry for the database server in the sqlhosts file. The sqlhosts file defines database server connections that are valid for the client-server environment. For each database server, this file defines the following information:
The application expects to find the sqlhosts file in the $INFORMIXDIR/etc directory; however, you can change this location or the name of the file with the INFORMIXSQLHOSTS environment variable. If the database server does not reside on the computer where the client program runs, an sqlhosts file must reside on the host computers of both the ESQL/C client program and the database server.
The client application can connect to any database server that the sqlhosts file defines. If your application needs to connect to a database server that sqlhosts does not define, you might need assistance from your database administrator (DBA) to create the necessary entries in this file. In addition to the sqlhosts file, you might also need to configure system network files to support connections. The Administrator's Guide for your database server describes how to create a database server entry in the sqlhosts file.
Specifying the Default Database Server
For your ESQL/C application to communicate with any database server, you must set the INFORMIXSERVER environment variable to specify the name of the default database server. Therefore, the name of the default database server must exist in the sqlhosts file and sqlhosts must exist on the computer that runs the application. For more information on sqlhosts, see "Accessing the sqlhosts File".
Sources of Connection Information in a Windows Environment
To establish a connection to a database server, an ESQL/C application in a Windows environment can perform the following tasks:
In Windows environments, ESQL/C obtains the configuration information from the InetLogin structure or the in-memory copy of the Registry.
If the application has initialized a field in InetLogin, ESQL/C sends this value to the database server. For any field the application has not set in the InetLogin structure, ESQL/C uses the corresponding information in the Informix subkey of the Registry. (For more information, see "Setting and Retrieving Environment Variables in Windows Environments" and "Precedence of Configuration Values".)
In Windows environments, the Registry contains the following configuration information:
When a client ESQL/C application establishes a connection to a database server (usually with the SQL statements CONNECT or DATABASE. See "Connecting to a Database Server"), it sends the configuration information to the database server.
Setting Environment Variables for Connection in a Windows Environment
The Registry provides default values for most environment variables. For a description of environment variables and their default values, refer to the Informix Guide to SQL: Reference and the Informix Guide to GLS Functionality. To change the value of an environment variable, use the Environment tab of the Setnet32 utility, which the Informix Client Products Installation Guide describes.
To change the value of an environment variable in the Registry, use the Environment tab of the Setnet32 utility, which the Informix Client Products Installation Guide describes. For more information on how to change the environment variable for the current process, use the ifx_putenv() function. See "Setting and Retrieving Environment Variables in Windows Environments". For more information on InetLogin, see "InetLogin Structure".
sqlhosts Information in a Windows Environment
The Registry contains the following connection information:
This information includes the name of the host computer, the type of protocol to use, and the name of the connection. The Registry stores the sqlhosts information in the SqlHosts subkey of the Informix key. To store sqlhosts information in the Registry, use the Server Information tab of the Setnet32 utility.
On UNIX operating systems, this file resides in the home directory of the user and specifies the name and password for the user account. In Windows environments, the NETRC subkey of the Informix key in the Registry stores the same account information. To store .netrc information in the Registry, use the Host Information tab of the Setnet32 utility.
The client sends network parameters to establish a connection to a database server. The first step in establishing a connection is to log onto the correct host computer. The protocol software uses the network parameters for the current database server. The client locates the network parameters for the current database server in either of the following ways:
1. If the SQL statement that requests the connection (such as a CONNECT or DATABASE) specifies the name of a database server, the client sends the network parameters for this specified database server.
If the InfxServer field of InetLogin contains the name of the specified database server, the client checks InetLogin for the network parameters. Otherwise, the client obtains network parameters for that database server from the in-memory copy of the Registry.
2. If the SQL statement does not specify a database server, the client sends the network parameters for the default database server.
If the InfxServer field of InetLogin contains the name of a database server, the client checks InetLogin for the network parameters. Otherwise, the client determines the default database server from the INFORMIXSERVER value in the in-memory copy of the Registry. It then sends network parameter values from the Registry for that database server.
ESQL/C checks the network parameter fields of InetLogin for any of these network parameters that the application has currently set. For any fields (including the name of the default database server) that are not set, ESQL/C obtains the values from the in-memory copy of the Registry. (For more information, see "Precedence of Configuration Values".)
For example, the code fragment in Figure 12-3 initializes the InetLogin structure with information for the mainsrvr database server; mainsrvr is the default database server.
When execution reaches the first CONNECT statement in Figure 12-3, the client application requests a connection to the accounts database on the mainsrvr database server. The CONNECT statement does not specify a database server, so the client sends the following network parameters for default database server:
The second CONNECT statement in Figure 12-3 requests a connection to the custhist database on the bcksrvr database server. For this connection, the client sends the network parameters for the specified database server, bcksrvr. Because the InetLogin structure currently contains network parameters for mainsrvr, the client must obtain all these parameters from the in-memory copy of the Registry. Therefore, the application does not use the finance user account for this second connection (unless the Registry specifies User and Password values of finance and in2money, respectively, for the bcksrvr database server).
Using a Central Registry
You can specify the sqlhosts information in one of the following locations:
The central registry can be on the Domain Server or on any Windows NT or Windows 95 workstation on the Microsoft network. It might be local to one application and remote to all others. A central registry enables you to maintain a single copy of the sqlhosts information for use by all ESQL/C applications in Windows environments.
To use a central registry in Windows 95, you must install special Microsoft software to support remote registry services. For more information, see your Informix Release Notes for ESQL/C and your Microsoft documentation.
To use a central registry, you must set the INFORMIXSQLHOSTS environment variable on your computer. This environment variable specifies the name of the computer on which the central registry resides. To set this environment variable, you can use Setnet32, the ifx_putenv() function ("Setting and Retrieving Environment Variables in Windows Environments"), or the Inetlogin structure ("InetLogin Structure").
In a Windows environment, an ESQL/C application uses the following precedence to locate sqlhosts information when it requests a connection:
1. The sqlhosts information in the central registry, on computer that the INFORMIXSQLHOSTS environment variable indicates (if INFORMIXSQLHOSTS is set)
2. The sqlhosts information in the local registry
Connection Authentication Functionality in a Windows Environment
Once an ESQL/C application has obtained the information about the connection (from either the Registry or the InetLogin structure), the ESQL client-interface DLL performs the following steps:
1. It copies connection information from the InetLogin structure (or from the Registry for undefined InetLogin fields) into a HostInfoStruct structure (see Figure 12-4).
2. It passes a pointer to the HostInfoStruct to the sqlauth() function in the esqlauth.dll to verify connection authentication.
If sqlauth() returns TRUE, the connection is verified and the user can access the server computer. However, if sqlauth() returns FALSE, the connection is refused and access denied. By default, the sqlauth() function returns a value of TRUE.
The parameter passed to sqlauth() is a pointer to a HostInfoStruct structure, which the login.h header file defines. This structure contains the subset of the InetLogin fields that Figure 12-4 shows.
Figure 12-4
Fields of the HostInfoStruct Structure
Within sqlauth(), you can access the fields of HostInfoStruct with the pHostInfo pointer, as follows:
You can edit all the HostInfoStruct field values. ESQL/C, however, checks only the User and Pass fields of HostInfoStruct.
Figure 12-5 shows the default sqlauth() function, which the esqlauth.c file contains.
This default action of sqlauth() means that ESQL/C performs no authentication verification when it establishes a connection. To provide verification, you can customize the sqlauth() function. You might want to customize sqlauth() to perform one of the following verification tasks:
The function can compare the current user name against a list of valid or invalid user names.
The function can check the value of the AskPassAtConnect field in the HostInfoStruct structure when this field is set to Y or y. You can code sqlauth() to display a window that prompts the user to enter a password.
The following steps describe how to create a customized sqlauth() function:
1. Bring up the esqlauth.c source file in your system editor. This file is located in the %INFORMIXDIR%\demo\esqlauth directory.
2. Add to the body of the sqlauth() function the code that performs the desired connection verification. Of the fields in Figure 12-4, the sqlauth() function can modify only the User and Pass fields. Make sure that sqlauth() returns TRUE or FALSE to indicate whether to continue with the connection request. Do not modify other code in this file.
3. Create a new version of the esqlauth.dll by compiling the esqlauth.c file and specifying the -target:dll (or -wd) command-line option of the esql command processor.
For an example of how to define the sqlauth() function, see the ESQLAUTH demo program in the %INFORMIXDIR%\demo\esqlauth directory.
Connecting to a Database Server
When an ESQL/C application begins execution, it has no connections to any database server. For SQL statements to execute, however, such a connection must exist. To establish a connection to a database server, the ESQL/C program must take the following actions:
Establishing a Connection
The following two groups of SQL statements can establish connections to a database environment:
The type of connection that the application establishes depends on which of these types of statements executes first in the application:
The following sections briefly describe explicit and implicit connections. For more information, see the entries for the CONNECT and DISCONNECT statements in the Informix Guide to SQL: Syntax.
The Explicit Connection
When you use the CONNECT statement to connect to a database environment, you establish an explicit connection. The application connects directly to the database server that you specify. If you do not specify the name of a database server in the CONNECT statement, the application establishes an explicit connection to the default database server (that the INFORMIXSERVER environment variable identifies).
An explicit connection enables an application to support multiple connections to one or more database environments. Although the application can connect to several database environments during its execution, only one connection can be current at a time. Dormant connections are connections that the application has established but is not currently using. The application must have a current connection to execute SQL statements.
The following SQL connection statements establish and manage explicit connections:
These connection statements provide the following benefits, which allow you to create more portable applications:
Because the CONNECT, DISCONNECT, and SET CONNECTION statements include Informix extensions to ANSI-standard syntax, these statements generate ANSI-extension warning messages at the following times:
The ESQL/C application, not the database server, processes these connection statements. Therefore, the application cannot use them in a PREPARE or an EXECUTE IMMEDIATE statement.
The Implicit Connection
When one of the following SQL statements is the first SQL statement that the application executes, the statement establishes an implicit connection:
When you execute one of the preceding statements, the application first connects to the default database server (that the INFORMIXSERVER environment variable indicates). The default database server parses the database statement. If the statement specifies the name of a database server, the application then connects to the specified database server. To establish an implicit connection to a specified database server, an application must therefore connect to two database servers. An explicit connection only requires a connection to a single database server, and therefore involves less overhead.
If an implicit connection already exists, these database statements close it before they establish the new connection. The new implicit connection remains open after the SQL statement completes. This behavior contrasts with explicit connections (page 12-17), which allow multiple connections to the same or to a different database environment.
The CLOSE DATABASE statement closes the database and, in pre-Version 6.0 applications, also closes the implicit connection to the database. If you precede these statements with a CONNECT, each can also operate in the context of the current explicit connection.
Use of an implicit connection provides a smooth migration path for older applications into the connection-oriented environment that CONNECT, DISCONNECT, and SET CONNECTION statements support. For more information on implicit connections, see the CONNECT statement in the Informix Guide to SQL: Syntax.
Summary of Connection Types
Figure 12-6 summarizes the methods that ESQL/C supports to connect to a database server.
Figure 12-6
Statements and Functions That Start the Database Server
For information on the sqlstart() library function, see page 12-68.
Establishing an Explicit Connection in a Windows Environment
This section provides the following information specific to Windows environments:
When to Use an Explicit Connection in a Windows Environment
With an implicit connection, one connection to the database server can exist for each ESQL/C module and this connection cannot be shared. An explicit connection allows multiple connections within a client application. You might want to design an application that needs to perform multiple connections for one of the following reasons:
Figure 12-7 shows scenarios in which multiple applications use the same connection to a database server.
Figure 12-8 shows a single application that establishes connections to multiple database servers.
Figure 12-7 shows the following two scenarios in which multiple applications share a single connection to the database server:
You can also use explicit connections if you want one application to establish connections to two separate database servers at the same time, as Figure 12-8 shows.
Using Multiplexed Connections
A multiplexed connection enables an ESQL/C application to establish multiple connections to different databases on the same database server, using a minimum amount of communications resources. When you initiate a multiplexed connection, the database server uses a single connection to the client for multiple SQL connections (CONNECT statement). Without multiplexing, each SQL connection (CONNECT statement) creates a new database-server connection.
Client Requirements for Execution
To implement a multiplexed connection, set the multiplexing option, in the client sqlhosts file, on the dbservername parameter of the database server to which you will connect. To specify multiplexing, set the m option to 1. The following dbservername parameter specifies a multiplexed connection to the personnel database server:
Setting the multiplexing option to zero (m = 0), which is the default, disables multiplexing for the specified database server.
To use multiplexed connections for any application that was compiled prior to version 9.13 of ESQL/C, you must relink it. Applications that you compiled prior to version 9.13 of ESQL/C can connect to a multiplexing database server, however. The database server establishes a non-multiplexed connection in this case.
For information on the requirements to implement multiplexing on the database server, see the Administrator's Guide for your database server.
Limitations for Multiplexed Connections
ESQL/C imposes the following limitations on multiplexed connections:
Identifying the Database Server
To connect to a database environment (with, for example, a CONNECT statement), the ESQL/C application can identify the database server in one of two ways:
A Specific Database Server
An ESQL/C application can establish a connection to a specific database server when it lists the database server name, and optionally the database name, in an SQL statement, as follows:
Each of the following CONNECT statements establishes an explicit connection to a database server that is called valley:
EXEC SQL connect to 'stores7@valley';
EXEC SQL connect to '@valley';
Each of the following SQL statements establishes an implicit connection to the stores7 database in a specific database server that is called valley:
EXEC SQL database '//valley/stores7';
EXEC SQL database stores7@valley;
EXEC SQL database '/usr/dbapps/stores7@valley'; (On a UNIX system)
EXEC SQL database 'C:\usr\dbapps\stores@valley'; (On a Windows system)
For more information about connections to a specific database server, see the CONNECT and DATABASE statements in the Informix Guide to SQL: Syntax.
The Default Database Server
An ESQL/C application can establish a connection to a default database server when it omits the database server name from the database environment in an SQL statement, as follows:
Each of the following CONNECT statements establishes an explicit default connection:
EXEC SQL connect to 'stores7';
EXEC SQL connect to default;
EXEC SQL connect to '/usr/dbapps/stores7'; (On a UNIX system)
EXEC SQL connect to 'C:\usr\dbapps\stores7'; (ON a Windows system)
Each of the following SQL statements establishes an implicit default connection to a database that is called stores7 on the default database server:
EXEC SQL database stores7;
EXEC SQL start database stores7 with no log;
The INFORMIXSERVER environment variable determines the name of the database server. For more information, see "Specifying the Default Database Server".
You can also use the DBPATH environment variable to specify a list of database server names to use as default database servers. The application searches for these database servers after it searches for the database server that INFORMIXSERVER specifies. For instructions on how to set the INFORMIXSERVER or DBPATH environment variable with the name of the default database server, see the Informix Guide to SQL: Reference.
|
