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.