informix
INFORMIX-ESQL/C Programmer's Manual
ESQL/C Function Library

GetConnect()

The GetConnect() function is available only in Windows environments 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:

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


INFORMIX-ESQL/C Programmer's Manual, Version 9.21
Copyright © 1999, Informix Software, Inc. All rights reserved