The SetConnect() function (Windows)

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

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

Syntax

void *SetConnect ( void *CnctHndl)

CnctHndl: A connection handle that a previous GetConnect() call has returned.

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:

EXEC SQL set connection db_connection;

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):

void *cnctHndl1, *cnctHndl2, *prevHndl;
;

lish connection ’cnctHndl1’ to customers@mainsrvr */
strcpy(InetLogin.InfxServer, "mainsrvr");
cnctHndl1 = GetConnect();
EXEC SQL database customers;
;

/* Establish connection ’cnctHndl2’ to accounts@acctsrvr */
strcpy(InetLogin.InfxServer, "acctsrvr");
cnctHndl2 = GetConnect();
EXEC SQL database accounts;
;

prevHndl = SetConnect( 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 SetConnect() in Version 5.01 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 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.

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