| Specification: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLDisconnect() closes the connection associated with the database connection handle.
SQLEndTran() must be called before calling SQLDisconnect() if an outstanding transaction exists on this connection.
After calling this function, either call SQLConnect() to connect to another database, or call SQLFreeHandle().
Syntax
SQLRETURN SQLDisconnect (SQLHDBC ConnectionHandle;) /* hdbc */
Function Arguments
Table 50. SQLDisconnect Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHDBC | ConnectionHandle | input | Connection handle |
Usage
If an application calls SQLDisconnect() before it has freed all the statement handles associated with the connection, DB2 CLI frees them after it successfully disconnects from the database.
If SQL_SUCCESS_WITH_INFO is returned, it implies that even though the disconnect from the database is successful, additional error or implementation specific information is available. For example, a problem was encountered on the clean up subsequent to the disconnect, or if there is no current connection because of an event that occurred independently of the application (such as communication failure).
After a successful SQLDisconnect() call, the application can re-use ConnectionHandle to make another SQLConnect() or SQLDriverConnect() request.
An application should not rely on SQLDisconnect() to close cursors (with both stored procedures and regular client applications). In both cases the cursor should be closed using SQLCloseCursor(), then the statement handle freed with a call to SQLFreeHandle() with a HandleType of SQL_HANDLE_STMT.
Return Codes
Diagnostics
Table 51. SQLDisconnect SQLSTATEs
| SQLSTATE | Description | Explanation | ||
|---|---|---|---|---|
| 01002 | Disconnect error. | An error occurred during the disconnect. However, the disconnect succeeded. (Function returns SQL_SUCCESS_WITH_INFO.) | ||
| 08003 | Connection is closed. | The connection specified in the argument ConnectionHandle was not open. | ||
| 25000 25501 | Invalid transaction state. | There was a transaction in process on the connection specified by the
argument ConnectionHandle. The transaction remains active, and
the connection cannot be disconnected.
| ||
| 25501 | Invalid transaction state. | There was a transaction in process on the connection specified by the argument ConnectionHandle. The transaction remains active, and the connection cannot be disconnected. | ||
| 58004 | Unexpected system failure. | Unrecoverable system error. | ||
| HY001 | Memory allocation failure. | DB2 CLI is unable to allocate memory required to support execution or completion of the function. | ||
| HY010 | Function sequence error. | The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation. | ||
| HY013 | Unexpected memory handling error. | DB2 CLI was unable to access memory required to support execution or completion of the function. |
Restrictions
None.
(The complete sample utilcli.c is also available here .)
/* From the CLI sample utilcli.c */
/* ... */
printf( "\nDisconnecting from the database nb. %d ...\n", db_nb + 1) ;
sqlrc = SQLDisconnect( a_hdbc[db_nb] ) ;
rc = HandleInfoPrint( SQL_HANDLE_DBC, a_hdbc[db_nb],
sqlrc, __LINE__, __FILE__);
if( rc == 0)
{ printf( "Disconnected from the database nb. %d.\n", db_nb + 1 ) ;
}
References