Connection Transitions

ODBC connections have the following states.

State Description
C0 Unallocated environment, unallocated connection
C1 Allocated environment, unallocated connection
C2 Allocated environment, allocated connection
C3 Connection function needs data
C4 Connected connection
C5 Connected connection, allocated statement
C6 Connected connection, transaction in progress. It is possible for a connection to be in state C6 with no statements allocated on the connection. For example, suppose the connection is in manual commit mode and is in state C4. If a statement is allocated, executed (starting a transaction), and then freed, the transaction remains active but there are no statements on the connection.

The following tables show how each ODBC function affects the connection state.

SQLAllocHandle

C0

No Env.
C1 Unallocated C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
C1[1] --[5] --[5] --[5] --[5] --[5] --[5]
(IH)[2] C2 --[5] --[5] --[5] --[5] --[5]
(IH)[3] (IH) (08003) (08003) C5 --[5] --[5]
(IH)[4] (IH) (08003) (08003) --[5] --[5] --[5]

[1] This row shows transitions when HandleType was SQL_HANDLE_ENV.

[2] This row shows transitions when HandleType was SQL_HANDLE_DBC.

[3] This row shows transitions when HandleType was SQL_HANDLE_STMT.

[4] This row shows transitions when HandleType was SQL_HANDLE_DESC.

[5] Calling SQLAllocHandle with OutputHandlePtr pointing to a valid handle overwrites that handle without regard for the previous contents ofthat handle, and might cause problems for ODBC drivers. It is incorrect ODBC application programming to call SQLAllocHandle twice with the same application variable defined for *OutputHandlePtr without calling SQLFreeHandle to free the handle before reallocating it. Overwriting ODBC handles in such a manner can lead to inconsistent behavior or errors on the part of ODBC drivers.

SQLBrowseConnect

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) C3 [d] C4 [s] -- [d] C2 [e] C4 [s] (08002) (08002) (08002)

SQLCloseCursor

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) -- --[1] C5[2]

[1] The connection was in manual-commit mode.

[2] The connection was in auto-commit mode.

SQLColumnPrivileges, SQLColumns, SQLForeignKeys, SQLGetTypeInfo, SQLPrimaryKeys, SQLProcedureColumns, SQLProcedures, SQLSpecialColumns, SQLStatistics, SQLTablePrivileges, and SQLTables

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) --[1] C6[2] --

[1] The connection was in auto-commit mode, or the data source did not begin a transaction.

[2] The connection was in manual-commit mode, and the data source began a transaction.

SQLConnect

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) C4 (08002) (08002) (08002) (08002)

SQLCopyDesc, SQLGetDescField, SQLGetDescRec, SQLSetDescField, and SQLSetDescRec

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) --[1] -- --

[1] In this state, the only descriptors available to the application are explicitly allocated descriptors.

SQLDataSources and SQLDrivers

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) -- -- -- -- -- --

SQLDisconnect

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (08003) C2 C2 C2 25000

SQLDriverConnect

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) C4 s -- n[f] (08002) (08002) (08002) (08002)

SQLEndTran

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH)[1] --[3] --[3] --[3] -- -- --[4] or ([5], [6], and [8]) C4[5] and [7] C5[5], [6], and [9]
(IH)[2] (IH) (08003) (08003) -- -- C5

[1] This row shows transitions when HandleType was SQL_HANDLE_ENV.

[2] This row shows transitions when HandleType was SQL_HANDLE_DBC.

[3] Because the connection is not in a connected state, it is unaffected by the transaction.

[4] The commit or rollback failed on the connection. The function returns SQL_ERROR in this case.

[5] The commit or rollback succeeded on the connection. The function returns SQL_ERROR if the commit or rollback failed on another connection, or the function returns SQL_SUCCESS if the commit or rollback succeeded on all connections.

[6] There was at least one statement allocated on the connection.

[7] There were no statements allocated on the connection.

[8] The connection had at least one statement for which there was an open cursor, and the data source preserves cursors when transactions are committed or rolled back, whichever applies (depending on whether CompletionType was SQL_COMMIT or SQL_ROLLBACK). For more information, see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR attributes in SQLGetInfo.

[9] If the connection had any statements for which there were open cursors, the cursors were not preserved when the transaction was committed or rolled back.

SQLExecDirect and SQLExecute

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) --[1] C6[2] C6[3] --

[1] The connection was in auto-commit mode, and the statement executed was not a cursor specification (such as a SELECT statement); or the connection was in manual-commit mode, and the statement executed did not begin a transaction.

[2] The connection was in auto-commit mode, and the statement executed was a cursor specification (such as a SELECT statement).

[3] The connection was in manual-commit mode, and the data source began a transaction.

SQLFreeHandle

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH)[1] C0 (HY010) (HY010) (HY010) (HY010) (HY010)
(IH)[2] (IH) (C1) (HY010) (HY010) (HY010) (HY010)
(IH)[3] (IH) (IH) (IH) (IH) C4[5] --[6] --[7] C4[5] and [8] C5[6] and [8]
(IH)[4] (IH) (IH) (IH) -- -- --

[1] This row shows transitions when HandleType was SQL_HANDLE_ENV.

[2] This row shows transitions when HandleType was SQL_HANDLE_DBC.

[3] This row shows transitions when HandleType was SQL_HANDLE_STMT.

[4] This row shows transitions when HandleType was SQL_HANDLE_DESC.

[5] There was only one statement allocated on the connection.

[6] There were multiple statements allocated on the connection.

[7] The connection was in manual-commit mode.

[8] The connection was in auto-commit mode.

SQLFreeStmt

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH)[1] (IH) (IH) (IH) (IH) -- C5[3] --[4]
(IH)[2] (IH) (IH) (IH) (IH) -- --

[1] This row shows transactions when the Option argument is SQL_CLOSE.

[2] This row shows transactions when the Option argument is SQL_UNBIND or SQL_RESET_PARAMS.

[3] The connection was in auto-commit mode, and no cursors were open on any statements except this one.

[4] The connection was in manual-commit mode, or it was in auto-commit mode and a cursor was open on at least one other statement.

SQLGetConnectAttr

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
IH IH --[1] 08003[2] HY010 -- -- --

[1] The Attribute argument was SQL_ATTR_ACCESS_MODE, SQL_ATTR_AUTOCOMMIT, SQL_ATTR_LOGIN_TIMEOUT, SQL_ATTR_ODBC_CURSORS, SQL_ATTR_TRACE, or SQL_ATTR_TRACEFILE, or a value had been set for the connection attribute.

[2] The Attribute argument was not SQL_ATTR_ACCESS_MODE, SQL_ATTR_AUTOCOMMIT, SQL_ATTR_LOGIN_TIMEOUT, SQL_ATTR_ODBC_CURSORS, SQL_ATTR_TRACE, or SQL_ATTR_TRACEFILE, and a value had not been set for the connection attribute.

SQLGetDiagField and SQLGetDiagRec

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH)[1] -- -- -- -- -- --
(IH)[2] (IH) -- -- -- -- --
(IH)[3] (IH) (IH) (IH) (IH) -- --
(IH)[4] (IH) (IH) (IH) -- -- --

[1] This row shows transitions when HandleType was SQL_HANDLE_ENV.

[2] This row shows transitions when HandleType was SQL_HANDLE_DBC.

[3] This row shows transitions when HandleType was SQL_HANDLE_STMT.

[4] This row shows transitions when HandleType was SQL_HANDLE_DESC.

SQLGetEnvAttr

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
IH -- -- -- -- -- --

SQLGetFunctions

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
IH IH HY010 HY010 -- -- --

SQLGetInfo

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
IH IH --[1] 08003[2] 08003 -- -- --

[1] The InfoType argument was SQL_ODBC_VER.

[2] The InfoType argument was not SQL_ODBC_VER.

SQLMoreResults

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) --[1] C6[2] --[3] C5[1]

[1] The connection was in auto-commit mode, and the call to SQLMoreResults has not initialized the processing of a result set of a cursor specification.

[2] The connection was in auto-commit mode, and the call to SQLMoreResults has initialized the processing of a result set of a cursor specification.

[3] The connection was in manual-commit mode.

SQLNativeSql

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (08003) (08003) -- -- --

SQLPrepare

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) --[1] C6[2] --

[1] The connection was in auto-commit mode, or the data source did not begin a transaction.

[2] The connection was in manual-commit mode, and the data source began a transaction.

SQLSetConnectAttr

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
IH IH --[1] 08003[2] HY010 --[3] 08002[4] HY011[5] --[3] 08002[4] HY011[5] --[3] and [6] C5[8] 08002[4] HY011[5] or [7]

[1] The Attribute argument was not SQL_ATTR_TRANSLATE_LIB or SQL_ATTR_TRANSLATE_OPTION.

[2] The Attribute argument was SQL_ATTR_TRANSLATE_LIB or SQL_ATTR_TRANSLATE_OPTION.

[3] The Attribute argument was not SQL_ATTR_ODBC_CURSORS or SQL_ATTR_PACKET_SIZE.

[4] The Attribute argument was SQL_ATTR_ODBC_CURSORS.

[5] The Attribute argument was SQL_ATTR_PACKET_SIZE.

[6] The Attribute argument was not SQL_ATTR_AUTOCOMMIT, or the Attribute argument was SQL_ATTR_AUTOCOMMIT and setting this attribute did not commit the transaction.

[7] The Attribute argument was SQL_ATTR_TXN_ISOLATION.

[8] The Attribute argument was SQL_ATTR_AUTOCOMMIT, and setting this attribute committed the transaction.

SQLSetEnvAttr

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) -- -- (HY010) -- -- --

All Other ODBC Functions

C0

No Env.
C1

Unallocated
C2

Allocated
C3

Need Data
C4

Connected
C5

Statement
C6

Transaction
(IH) (IH) (IH) (IH) (IH) -- --