The GetConnect() function (Windows)

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

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

Syntax

void *GetConnect ( )

Usage

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

EXEC SQL connect to '@dbservername' with concurrent transaction;

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:

The ONEDB_SERVER environment variable in the Registry contains the name of the default database server. The Setnet32 utility sets the Registry values.
The InfxServer field in the InetLogin structure can contain the name of the default database server or a specified database server. The client application sets the InetLogin fields.

For more information about 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:

void *cnctHndl;
;
strcpy(InetLogin.InfxServer, "mainsrvr");
;

cnctHndl = GetConnect();
EXEC SQL database stores7;

In the preceding example, if you had omitted the assignment to the InetLogin.InfxServer field, would establish an explicit connection to the stores7 database in the default database server (the database server that the ONEDB_SERVER 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:

EXEC SQL connect to 'stores7@mainsrvr' with concurrent transaction;

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 GetConnect() in Version 5.01 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 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.