INFORMIX
Informix-ESQL/C Programmer's Manual
Chapter 12: Working with the Database Server
Home Contents Index Master Index New Book
WIN NT/95

Using ESQL/C Connection Library Functions in a Windows Environment

 To establish an explicit connection (sometimes called a direct connection), ESQL/C supports the SQL connection statements. For a complete description of the SQL connection statements, see the Informix Guide to SQL: Syntax. ESQL/C also supports the connection library functions that Figure 12-11 lists for establishing an explicit connection from a Windows environment.

Figure 12-11
ESQL/C Connection Library Functions and Their SQL Equivalents
ESQL/C for Windows Library Function Description SQL Equivalent

GetConnect()

Requests an explicit connection and returns a pointer to the connection information

CONNECT TO '@dbservername' WITH CONCURRENT TRANSACTION

SetConnect()

Switches the connection to an established (dormant) explicit connection

SET CONNECT TO
(without the DEFAULT option)

ReleaseConnect()

Closes an established explicit connection

DISCONNECT
(without the DEFAULT,
CURRENT, or ALL options)

Important: ESQL/C supports the connection library functions for backward compatibility with Version 5.01 ESQL/C for Windows applications. When you write new ESQL/C applications for Windows environments, use the SQL connection statements (CONNECT, DISCONNECT, and SET CONNECTION) instead of the ESQL/C connection library functions.
ESQL/C uses an internal structure that contains the handle for the connection and other connection information. The ESQL/C connection library functions use the connection handle, together with the information in the internal structure, to pass connection information to and from the application. The application can use the connection handle to identify an explicit connection.

If you use these connection functions to establish explicit connections, keep the following restrictions in mind:

Warning: If an application uses the wrong connection handle, the application could modify the wrong database without the knowledge of the user.
When you compile your ESQL/C program, the esql command processor automatically links the ESQL/C connection functions to your program. The following pages describe each of these connection functions.

WIN NT/95

GetConnect()

The GetConnect() function is available only in the Windows environment and establishes a new explicit connection to a database server.

Important: ESQL/C supports the GetConnect() connection library function for backward compatibility with Version 5.01 ESQL/C for Windows applications. When you write new ESQL/C applications for Windows environments, use the SQL CONNECT statement to establish an explicit connection.

Syntax

Usage

 The GetConnect() function call by itself is equivalent to the following SQL statement:

In this example, dbservername is the name of a defined database server. All database servers that the client application specifies must be defined in at least one of the following places:

WIN NT/95
For more information on the default and specified database server, see "Sources of Connection Information in a Windows Environment".

For example, the following code fragment uses GetConnect() to establish an explicit connection to the stores7 database on the mainsrvr database server:

In the preceding example, if you had omitted the assignment to the InetLogin.InfxServer field, ESQL/C would establish an explicit connection to the stores7 database in the default database server (the database server that the INFORMIXSERVER environment variable in the Registry indicates).

After any call to GetConnect(), use the SQL DATABASE statement (or some other SQL statement that opens a database) to open the desired database. In the previous code fragment, the combination of the GetConnect() function and the DATABASE statement is equivalent to the following CONNECT statement:

Important: Because the GetConnect() function maps to a CONNECT statement, it sets the SQLCODE and SQLSTATE status codes to indicate the success or failure of the connection request. This behavior differs from that of GetConnect() in Version 5.01 ESQL/C for Windows, in which this function did not set the SQLCODE and SQLSTATE values.
The following table shows the differences between the use of the GetConnect() function and the SQL CONNECT statement.

Situation GetConnect() Library Function SQL CONNECT Statement

Connection name

Internally generated and stored in the connection handle structure for the connection

Internally generated unless CONNECT includes the AS clause; therefore, to switch to other connections, specify the AS clause when you create the connection.

Opening a database

Only establishes an explicit connection to a database server; therefore, the application must use DATABASE (or some other valid SQL statement) to open the database.

Can establish an explicit connection to a database server and open a database when provided with names of both the database server and the database

Important: Because the GetConnect() function maps to a CONNECT statement with the WITH CONCURRENT TRANSACTION clause, it allows an explicit connection with open transactions to become dormant. Your ESQL/C application does not need to ensure that the current transaction has been committed or rolled back before it calls the SetConnect() function to switch to another explicit connection.
For each connection that you establish with GetConnect(), call ReleaseConnect() to close the connection and deallocate resources.

Return Codes

CnctHndl

The call to GetConnect() was successful, and the function has returned a connection handle for the new connection.

null pointer

The call to GetConnect() was unsuccessful.

WIN NT/95

ReleaseConnect()

 The ReleaseConnect() function is available only in the Windows environment. It releases, or terminates, the explicit connection and clears all allocated memory.

Important: ESQL/C supports the ReleaseConnect() connection library function for backward compatibility with Version 5.01 ESQL/C for Windows applications. When you write new ESQL/C applications for Windows environments, use the SQL DISCONNECT statement to terminate an established explicit connection.

Syntax

Usage

 The ReleaseConnect() function maps to a simple SQL DISCONNECT statement (one without an ALL, CURRENT, or DEFAULT option). The ReleaseConnect() call by itself is equivalent to the following SQL statement:

In this example, db_connection is the name of an existing connection that the GetConnect() function has established. You pass this db_connection name to
ReleaseConnect() as an argument; it is a connection handle for the desired connection.

For example, the following code fragment uses ReleaseConnect() to close an explicit connection to the stores7 database on the default database server:

Call ReleaseConnect() once for each connection that GetConnect() has established. The ReleaseConnect() function closes any open database before it terminates the current connection. It fails if any transactions are open in the current connection.

It is good programming practice to close the database explicitly with the SQL CLOSE DATABASE statement before the call to ReleaseConnect().

Important: Because the ReleaseConnect() function maps to a DISCONNECT statement, it sets the SQLCODE and SQLSTATE status codes to indicate the success or failure of the connection termination request. This behavior differs from that of ReleaseConnect() in Version 5.01 ESQL/C for Windows, in which this function did not set the SQLCODE and SQLSTATE values.
The ReleaseConnect() function differs from the DISCONNECT statement in the way that it obtains the connection name. ReleaseConnect() uses an internally generated name that is stored in the connection handle; you must specify this handle as an argument to the ReleaseConnect() call. The DISCONNECT statement uses an internally generated connection name only for a connection that a CONNECT statement without an AS clause has established; if the connection has a user-defined connection name (which the AS clause of the CONNECT statement specifies), DISCONNECT uses this name.

Return Codes

CnctHndl

The call to ReleaseConnect() was successful if the function has returned a connection handle that matches the one passed to it.

WIN NT/95

SetConnect()

 The SetConnect() function is available only in the Windows environment. It switches the connection to a specified explicit connection.

Important: ESQL/C supports the SetConnect() connection library function for backward compatibility with Version 5.01 ESQL/C for Windows applications. When you write new ESQL/C applications for Windows environments, use the SQL SET CONNECTION statement to switch to another active connection.

Syntax

Usage

 The SetConnect() function maps to a simple SQL SET CONNECTION statement (one without a DEFAULT option). The SetConnect() call is equivalent to the following SQL statement:

In this example, db_connection is the name of an existing connection that the GetConnect() function has established. You pass this db_connection name to the SetConnect() function as an argument. It is a connection handle for the connection that you want to make active.

If you pass a null handle, the SetConnect() function returns the current connection handle and does not change the current connection. If no current connection exits when you pass a null handle, SetConnect() returns null.

For example, the following code fragment uses SetConnect() to switch from a connection to the accounts database on the acctsrvr database server (cnctHndl2) to a customers database on the mainsrvr database server (cnctHndl1):

Important: Because the SetConnect() function maps to a SET CONNECTION statement, it sets the SQLCODE and SQLSTATE status codes to indicate the success or failure of the connection switch request. This behavior differs from that of SetConnect() in Version 5.01 ESQL/C for Windows, in which this function did not set the SQLCODE and SQLSTATE values.
The SetConnect() function differs from the SET CONNECTION statement in the way that it obtains the connection name. SetConnect() uses an internally generated name that is stored in the connection handle.You must specify this handle as an argument to the SetConnect() call. The SET CONNECTION statement uses the user-defined connection name that the AS clause of the CONNECT statement specifies.

Important: Because the GetConnect() function maps to a CONNECT statement with the WITH CONCURRENT TRANSACTION clause, it allows an explicit connection with open transactions to become dormant. Your ESQL/C application does not need to ensure that the current transaction has been committed or rolled back before it calls the SetConnect() function to switch to another explicit connection.

Return Codes

CnctHndl

The call to SetConnect() was successful if the function has returned a connection handle of the connection that is now dormant.

null pointer

The call to SetConnect() was not successful, indicating that no explicit connection has been established.



Informix-ESQL/C Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.