Appendix B ODBC State Transition Tables

APPENDIX B ODBC STATE TRANSITION TABLES

The tables in this appendix show how ODBC functions cause transitions of the environment, connection, and statement states. Generally speaking, the state of the environment, connection, or statement dictates when functions that use the corresponding type of handle (henv, hdbc, or hstmt) can be called. The environment, connection, and statement states overlap as follows, although the exact overlap of connection states C5 and C6 and statement states S1 through S12 is data source–dependent, since transactions begin at different times on different data sources. For a description of each state, see "Environment Transitions," "Connection Transitions," and "Statement Transitions," later in this appendix.

Environment:

E0 E1                       E2

Connection:

C0 C1 C2 C3 C4    C5                  C6

Statement:

            S0 S1 S2 S3 S4 S5 S6 S7 S8 S9 S10 S11 S12

Each entry in a transition table can be one of the following values:

--. The state is unchanged after executing the function.

En, Cn, or Sn. The environment, connection, or statement state moves to the specified state.

(IH). The function returned SQL_INVALID_HANDLE. Although this error is possible in any state, it is shown only when it is the only possible outcome of calling the function in the specified state. This error does not change the state and is always detected by the Driver Manager, as indicated by the parentheses.

NS. Next State. The statement transition is the same as if the statement had not gone through the asynchronous states. For example, suppose a statement that creates a result set enters state S11 from state S1 because SQLExecDirect returned SQL_STILL_EXECUTING. The NS notation in state S11 means that the transitions for the statement are the same as those for a statement in state S1 that creates a result set: if SQLExecDirect returns an error; the statement remains in state S1; if it succeeds, the statement moves to state S5; if it needs data, the statement moves to state S8; and if it is still executing, it remains in state S11.

XXXXX or (XXXXX). An SQLSTATE that is related to the transition table; SQLSTATEs detected by the Driver Manager are enclosed in parentheses. The function returned SQL_ERROR and the specified SQLSTATE, but the state does not change. For example, if SQLExecute is called before SQLPrepare, it returns SQLSTATE S1010 (Function sequence error).

Note The tables do not show errors unrelated to the transition tables that do not change the state. For example, when SQLAllocConnect is called in environment state E1 and returns SQLSTATE S1001 (Memory allocation failure), the environment remains in state E1; this is not shown in the environment transition table for SQLAllocConnect.

If the environment, connection, or statement can move to more than one state, each possible state is shown and one or more footnotes explains the conditions under which each transition takes place. The following footnotes may appear in any table:

Footnote	Meaning
b	Before or after. The cursor was positioned before the start of the result set or after the end of the result set.
c	Current function. The current function was executing asynchronously.
d	Need data. The function returned SQL_NEED_DATA.
e	Error. The function returned SQL_ERROR.
I	Invalid row. The cursor was positioned on a row in the result set and the value in the rgfRowStatus array in SQLExtendedFetch for the row was SQL_DELETED or SQL_ERROR.
nf	Not found. The function returned SQL_NO_DATA_FOUND.
np	Not prepared. The statement was not prepared.
nr	No results. The statement will not or did not create a result set.
o	Other function. Another function was executing asynchronously.
p	Prepared. The statement was prepared.
r	Results. The statement will or did create a (possibly empty) result set.
s	Success. The function returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS.
v	Valid row. The cursor was positioned on a row in the result set and the value in the rgfRowStatus array in SQLExtendedFetch for the row was SQL_ADDED, SQL_SUCCESS, or SQL_UPDATED.
x	Executing. The function returned SQL_STILL_EXECUTING.

For example, the environment state transition table for SQLFreeEnv is:

SQLFreeEnv

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	E0	(S1010)

If SQLFreeEnv is called in environment state E0, the Driver Manager returns SQL_INVALID_HANDLE. If it is called in state E1, the environment moves to state E0 if the function succeeds and remains in state E1 if the function fails. If it is called in state E2, the Driver Manager always returns SQL_ERROR and SQLSTATE S1010 (Function sequence error) and the environment remains in state E2.

Environment Transitions

The ODBC environment has the following three states:

State	Description
E0	Unallocated henv
E1	Allocated henv, unallocated hdbc
E2	Allocated henv, allocated hdbc

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

SQLAllocConnect

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	E2	-- ¹
1 Calling SQLAllocConnect with a pointer to a valid hdbc overwrites that hdbc. This may be an application programming error.

SQLAllocEnv

E0 Unallocated	E1 Allocated	E2 *hdbc*
E1	-- ¹	E1 ¹
1 Calling SQLAllocEnv with a pointer to a valid henv overwrites that henv. This may be an application programming error.

SQLDataSources and SQLDrivers

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	--	--

SQLError

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH) ¹	--	--
1 This row shows transitions when henv was non-null, hdbc was SQL_NULL_HDBC, and hstmt was SQL_NULL_HSTMT.

SQLFreeConnect

E0
Unallocated

E1
Allocated

E2
hdbc

(IH)

(IH)

-- ¹
E1 ²

1 There were other allocated hdbcs.

2 The hdbc was the only allocated hdbc.

SQLFreeEnv

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	E0	(S1010)

SQLTransact

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	-- ¹	-- ¹
1 The hdbc argument was SQL_NULL_HDBC.

All Other ODBC Functions

E0 Unallocated	E1 Allocated	E2 *hdbc*
(IH)	(IH)	--

Connection Transitions

ODBC connections have the following states:

State	Description
C0	Unallocated henv, unallocated hdbc
C1	Allocated henv, unallocated hdbc
C2	Allocated henv, allocated hdbc
C3	Connection function needs data
C4	Connected hdbc
C5	Connected hdbc, allocated hstmt
C6	Connected hdbc, transaction in progress

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

SQLAllocConnect

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	C2	-- ¹	C2 ¹	C2 ¹	C2 ¹	C2 ¹
1 Calling SQLAllocConnect with a pointer to a valid hdbc overwrites that hdbc. This may be an application programming error.

SQLAllocEnv

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
C1	-- ¹	C1 ¹	C1 ¹	C1 ¹	C1 ¹	C1 ¹
1 Calling SQLAllocEnv with a pointer to a valid henv overwrites that henv. This may be an application programming error.

SQLAllocStmt

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	(08003)	(08003)	C5	-- ¹	C5 ¹
1 Calling SQLAllocStmt with a pointer to a valid hstmt overwrites that hstmt. This may be an application programming error.

SQLBrowseConnect

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	C3 ^d C4 ^s	-- ^d C2 ^e C4 ^s	(08002)	(08002)	(08002)

SQLColumnPrivileges

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
C6 ²

1 The data source was in auto-commit mode or did not begin a transaction.

2 The data source was in manual-commit mode and began a transaction.

SQLColumns: see SQLColumnPrivileges

SQLConnect and SQLDriverConnect

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	C4	(08002)	(08002)	(08002)	(08002)

SQLDataSources and SQLDrivers

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	--	--	--	--	--	--

SQLDisconnect

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	(08003)	C2	C2	C2	25000

SQLDriverConnect: see SQLConnect

SQLDrivers: see SQLDataSources

SQLError

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH) ¹	(IH)	--	--	--	--	--
1 This row shows transitions when hdbc was non-null and hstmt was SQL_NULL_HSTMT.

SQLExecDirect and SQLExecute

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
C6 ²

1 The data source was in auto-commit mode or did not begin a transaction.

2 The data source was in manual-commit mode and began a transaction.

SQLExecute: see SQLExecDirect

SQLForeignKeys: see SQLColumnPrivileges

SQLFreeConnect

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	C1	(S1010)	(S1010)	(S1010)	(S1010)

SQLFreeEnv

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

C0 ¹
(S1010) ²

(S1010)

1 The hdbc was the only allocated hdbc.

2 There were other allocated hdbcs.

SQLFreeStmt

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
C4 ²

1 The fOption argument was SQL_CLOSE, SQL_UNBIND, or SQL_RESET_PARAMS.

2 The fOption argument was SQL_DROP.

SQLGetConnectOption

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
(08003) ²

(S1010)

1 The fOption argument was SQL_ACCESS_MODE or SQL_AUTOCOMMIT, or a value had been set for the connection option.

2 The fOption argument was not SQL_ACCESS_MODE or SQL_AUTOCOMMIT, and a value had not been set for the connection option.

SQLGetFunctions

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	(S1010)	(S1010)	--	--	--

SQLGetInfo

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
(08003) ²

(08003)

1 The fInfoType argument was SQL_ODBC_VER.

2 The fInfoType argument was not SQL_ODBC_VER

SQLGetTypeInfo: see SQLColumnPrivileges

SQLNativeSql

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	(08003)	(08003)	--	--	--

SQLPrepare

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
C6 ²

1 The data source was in auto-commit mode or did not begin a transaction.

2 The data source was in manual commit mode and began a transaction.

SQLPrimaryKeys: see SQLColumnPrivileges

SQLProcedureColumns: see SQLColumnPrivileges

SQLProcedures: see SQLColumnPrivileges

SQLSetConnectOption

C0
No henv

C1
Unallo-
cated

C2
Allo-
cated

C3
Need Data

C4
Con-
nected

C5
hstmt

C6
Trans-
action

(IH)

(IH)

-- ¹
(08003) ²

(S1010)

-- ³
(08002) ⁴

-- ^{3 and 5}
C5 ⁶
(08002) ⁴
S1011 ⁷

1 The fOption argument was not SQL_TRANSLATE_DLL or SQL_TRANSLATE_OPTION.

2 The fOption argument was SQL_TRANSLATE_DLL or SQL_TRANSLATE_OPTION.

3 The fOption argument was not SQL_ODBC_CURSORS.

4 The fOption argument was SQL_ODBC_CURSORS.

5 If the fOption argument was SQL_AUTOCOMMIT, then the data source was in manual-commit mode or the vParam argument was SQL_AUTOCOMMIT_OFF.

6 The data source was in manual-commit mode, the fOption argument was SQL_AUTOCOMMIT, and the vParam argument was SQL_AUTOCOMMIT_ON.

7 The data source was in manual-commit mode and the fOption argument was SQL_TXN_ISOLATION.

SQLSpecialColumns: see SQLColumnPrivileges

SQLStatistics: see SQLColumnPrivileges

SQLTablePrivileges: see SQLColumnPrivileges

SQLTables: see SQLColumnPrivileges

SQLTransact

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH) ¹	(IH)	(IH)	(IH)	(IH)	(IH)	(IH)
(IH) ²	--	(08003)	(08003)	--	--	--^{e and 4} C5^{s or 5}
(IH) ³	(IH)	(08003)	(08003)	--	--	--^e C5^s
1 This row shows transitions when henv was SQL_NULL_HENV and hdbc was SQL_NULL_HDBC. 2 This row shows transitions when henv was a valid environment handle and hdbc was SQL_NULL_HDBC. 3 This row shows transitions when hdbc was a valid connection handle. 4 The commit or rollback failed on the connection. 5 The function returned SQL_ERROR but the commit or rollback succeeded on the connection.

All Other ODBC Functions

C0 No *henv*	C1 Unallo- cated	C2 Allo- cated	C3 Need Data	C4 Con- nected	C5 *hstmt*	C6 Trans- action
(IH)	(IH)	(IH)	(IH)	(IH)	--	--

Statement Transitions

ODBC statements have the following states:

State	Description
S0	Unallocated hstmt. (The connection state must be C4. For more information, see "Connection Transitions.")
S1	Allocated hstmt.
S2	Prepared statement. No result set will be created.
S3	Prepared statement. A (possibly empty) result set will be created.
S4	Statement executed and no result set was created.
S5	Statement executed and a (possibly empty) result set was created. The cursor is open and positioned before the first row of the result set.
S6	Cursor positioned with SQLFetch.
S7	Cursor positioned with SQLExtendedFetch.
S8	Function needs data. SQLParamData has not been called.
S9	Function needs data. SQLPutData has not been called.
S10	Function needs data. SQLPutData has been called.
S11	Still executing.
S12	Asynchronous execution canceled. In S12, an application must call the canceled function until it returns a value other than SQL_STILL_EXECUTING. The function was canceled successfully only if the function returns SQL_ERROR and SQLSTATE S1008 (Operation canceled). If it returns any other value, such as SQL_SUCCESS, the cancel operation failed and the function executed normally.

States S2 and S3 are known as the prepared states, states S5 through S7 as the cursor states, states S8 through S10 as the need data states, and states S11 and S12 as the asynchronous states. In each of these groups, the transitions are shown separately only when they are different for each state in the group; generally, the transitions for each state in each a group are the same.

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

SQLAllocConnect

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
-- ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹
1 Calling SQLAllocConnect with a pointer to a valid hdbc overwrites that hdbc. This may be an application programming error. Furthermore, this returns the connection state to C2; the connection state must be C4 before the statement state is S0.

SQLAllocEnv

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
-- ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹
1 Calling SQLAllocEnv with a pointer to a valid henv overwrites that henv. This may be an application programming error. Furthermore, this returns the connection state to C1; the connection state must be C4 before the statement state is S0.

SQLAllocStmt

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
S1	-- ¹	S1 ¹	S1 ¹	S1 ¹	S1 ¹	S1 ¹
1 Calling SQLAllocStmt with a pointer to a valid hstmt overwrites that hstmt. This may be an application programming error.

SQLBindCol

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	--	--	--	--	(S1010)	(S1010)

SQLBindParameter

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	--	--	--	--	(S1010)	(S1010)

SQLBrowseConnect, SQLConnect, and SQLDriverConnect

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(08002)	(08002)	(08002)	(08002)	(08002)	(08002)	(08002)

SQLCancel ¹

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

S1 ^np
S2 ^p

S1 ^np
S3 ^p

S1 ²
S2 ^{nr and 3}
S3 ^{r and 3}
S7 ⁴

S12

1 This table does not cover cancellation of a function running synchronously on one thread when an application calls SQLCancel on a different thread with the same hstmt. In this case, the driver must note that SQLCancel was called and return the correct return code and SQLSTATE (if any) from the synchronous function. The statement transition when that function finishes is NS (Next State). That is, the statement transition is the same as if the function completed processing normally; the only difference is that it is possible for the function to return SQL_ERROR and SQLSTATE S1008 (Operation canceled).

2 SQLExecDirect returned SQL_NEED_DATA.

3 SQLExecute returned SQL_NEED_DATA.

4 SQLSetPos returned SQL_NEED_DATA.

SQLColAttributes

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	see below	24000	-- ^s S11 ^x	(S1010)	NS ^c (S1010) ^o

SQLColAttributes (Prepared states)

S2 No Results	S3 Results
24000	-- ^s S11 ^x

SQLColumnPrivileges

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	S5 ^s S11 ^x	S1 ^e S5 ^s S11 ^x	S1 ^e S5 ^s S11 ^x	see below	(S1010)	NS ^c (S1010) ^o

SQLColumnPrivileges

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
24000	(24000)	(24000)

SQLColumns: see SQLColumnPrivileges

SQLConnect: see SQLBrowseConnect

SQLDataSources and SQLDrivers

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
--	--	--	--	--	--	--

SQLDescribeCol

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	see below	24000	-- ^s S11 ^x	(S1010)	NS ^c (S1010) ^o

SQLDescribeCol (Prepared states)

S2 No Results	S3 Results
24000	-- ^s S11 ^x

SQLDescribeParam

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	-- ^s S11 ^x	-- ^s S11 ^x	-- ^s S11 ^x	(S1010)	NS ^c (S1010) ^o

SQLDisconnect

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
-- ¹	S0 ¹	S0 ¹	S0 ¹	S0 ¹	(S1010)	(S1010)
1 Calling SQLDisconnect frees all hstmts associated with the hdbc. Furthermore, this returns the connection state to C2; the connection state must be C4 before the statement state is S0.

SQLDriverConnect: see SQLBrowseConnect

SQLDrivers: see SQLDataSources

SQLError

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH) ¹	--	--	--	--	--	--
1 This row shows transitions when hstmt was non-null.

SQLExecDirect

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	S4 ^{s and nr} S5 ^{s and r} S8 ^d S11 ^x	S1 ^e S4 ^{s and nr} S5 ^{s and r} S8 ^d S11 ^x	S1 ^e S4 ^{s and nr} S5 ^{s and r} S8 ^d S11 ^x	see below	(S1010)	NS ^c (S1010) ^o

SQLExecDirect (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
24000	(24000)	(24000)

SQLExecute

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	see below	S2 ^{e and p} S4 ^{s, p, and nr} S8 ^{d and p} S11 ^{x and p} (S1010) ^np	see below	(S1010)	NS ^c (S1010) ^o

SQLExecute (Prepared states)

S2 No Results	S3 Results
S4 ^s S8 ^d S11 ^x	S5 ^s S8 ^d S11 ^x

SQLExecute (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
24000 ^p (S1010) ^np	(24000) ^p (S1010) ^np	(24000) ^p (S1010) ^np

SQLExtendedFetch

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	24000	see below	(S1010)	NS ^c (S1010) ^o

SQLExtendedFetch (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
S7 ^{s or nf} S11 ^x	(S1010)	-- ^{s or nf} S11 ^x

SQLFetch

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	24000	see below	(S1010)	NS ^c (S1010) ^o

SQLFetch (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
S6 ^{s or nf} S11 ^x	-- ^{s or nf} S11 ^x	(S1010)

SQLForeignKeys: see SQLColumnPrivileges

SQLFreeConnect

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(S1010)	(S1010)	(S1010)	(S1010)	(S1010)	(S1010)	(S1010)

SQLFreeEnv

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(S1010)	(S1010)	(S1010)	(S1010)	(S1010)	(S1010)	(S1010)

SQLFreeStmt

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH) ¹	--	--	S1 ^np S2 ^p	S1 ^np S3 ^p	(S1010)	(S1010)
(IH) ²	S0	S0	S0	S0	(S1010)	(S1010)
(IH) ³	--	--	--	--	(S1010)	(S1010)
1 This row shows transitions when fOption was SQL_CLOSE. 2 This row shows transitions when fOption was SQL_DROP. 3 This row shows transitions when fOption was SQL_UNBIND or SQL_RESET_PARAMS.

SQLGetConnectOption

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
--	--	--	--	--	--	--

SQLGetCursorName

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

-- ¹
(S1015) ²

(S1010)

1 A cursor name had been set by calling SQLSetCursorName or by creating a result set.

2 A cursor name had not been set by calling SQLSetCursorName or by creating a result set.

SQLGetData

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	(24000)	see below	(S1010)	NS ^c (S1010) ^o

SQLGetData (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
(24000)	-- ^{s or nf} S11 ^x 24000 ³	-- ^{s or nf} S11 ^x 24000 ^b S1109 ⁱ S1C00 ^{v and 1}
1 The rowset size was greater than 1 and the SQLGetInfo did not return the SQL_GD_BLOCK bit for the SQL_GETDATA_EXTENSIONS information type.

SQLGetFunctions

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
--	--	--	--	--	--	--

SQLGetInfo

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
--	--	--	--	--	--	--

SQLGetStmtOption

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

-- ¹
(24000) ²

see below

(S1010)

1 The statement option was not SQL_ROW_NUMBER or SQL_GET_BOOKMARK.

2 The statement option was SQL_ROW_NUMBER or SQL_GET_BOOKMARK.

SQLGetStmtOption (Cursor states)

S5
Opened

S6
SQLFetch

S7
SQLExtendedFetch

-- ¹
(24000) ^{2 or 3}

-- ^{1 or (v and 3)}
24000 ^{b and 3}
S1011 ²
S1109 ^{i and 3}

-- ^{1 or (v and (2 or 3))}
24000 ^{b and (2 or 3)}
S1109 ^{i and (2 or 3)}

1 The fOption argument was not SQL_GET_BOOKMARK or SQL_ROW_NUMBER.

2 The fOption argument was SQL_GET_BOOKMARK.

3 The fOption argument was SQL_ROW_NUMBER.

SQLGetTypeInfo: see SQLColumnPrivileges

SQLMoreResults

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

-- ²

S1 ^{nf and np}
S2 ^{nf and p}
S11 ^x

-- ^s
S1 ^{nf and np}
S3 ^{nf and p}
S11 ^x

(S1010)

NS ^c
(S1010) ^o

1 For SQLMoreResults, the cursor states are somewhat modified. A batch statement, statement submitted with an array of parameters, or procedure can return result sets and INSERT, UPDATE, or DELETE row counts; these are collectively known as results. After the statement is executed, it moves to the S4 state if there are no results and the S5 state if there are results. In the S5 state, SQLFetch or SQLExtendedFetch returns SQLSTATE 24000 (Invalid cursor state) if the next result is a row count; the application must call SQLMoreResults to stop processing the current result and proceed to the next result. After the last result is processed, SQLMoreResults returns the statement to the allocated or prepared state.

2 The function always returns SQL_NO_DATA_FOUND in this state.

SQLNativeSql

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
--	--	--	--	--	--	--

SQLNumParams

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	-- ^s S11 ^x	-- ^s S11 ^x	-- ^s S11 ^x	(S1010)	NS ^c (S1010) ^o

SQLNumResultCols

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	-- ^s S11 ^x	-- ^s S11 ^x	-- ^s S11 ^x	(S1010)	NS ^c (S1010) ^o

SQLParamData

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	(S1010)	(S1010)	see below	NS ^c (S1010) ^o

SQLParamData (Need Data states)

S8
Need Data

S9
Must Put

S10
Can Put

S1 ^{e and 1}
S2 ^{e, nr, and 2}
S3 ^{e, r, and 2}
S7 ^{e and 3}
S9 ^s
S11 ^x

S1010

S1 ^{e and 1}
S2 ^{e, nr, and 2}
S3 ^{e, r, and 2}
S4 ^{s, nr, and (1 or 2)}
S5 ^{s, r, and (1 or 2)}
S7 ^{(s or e) and 3}
S9 ^d
S11 ^x

1 SQLExecDirect returned SQL_NEED_DATA.

2 SQLExecute returned SQL_NEED_DATA.

3 SQLSetPos returned SQL_NEED_DATA.

SQLParamOptions

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	--	--	--	--	(S1010)	(S1010)

SQLPrepare

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

S2 ^{s and nr}
S3 ^{s and r}
S11 ^x

-- ^{s or (e and 1)}
S1 ^{e and 2}
S11 ^x

S1 ^e
S2 ^{s and nr}
S3 ^{s and r}
S11 ^x

see below

(S1010)

NS ^c
(S1010) ^o

1 The preparation fails for a reason other than validating the statement (in other words, the SQLSTATE was S1009 (Invalid argument value) or S1090 (Invalid string or buffer length)).

2 The preparation fails while validating the statement (in other words, the SQLSTATE was not S1009 (Invalid argument value) or S1090 (Invalid string or buffer length)).

SQLPrepare (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
24000	(24000)	(24000)

SQLPrimaryKeys: see SQLColumnPrivileges

SQLProcedureColumns: see SQLColumnPrivileges

SQLProcedures: see SQLColumnPrivileges

SQLPutData

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	(S1010)	(S1010)	see below	NS ^c (S1010) ^o

SQLPutData (Need Data states)

S8
Need Data

S9
Must Put

S10
Can Put

S1010

S1 ^{e and 1}
S2 ^{e, nr, and 2}
S3 ^{e, r, and 2}
S7 ^{e and 3}
S10 ^s
S11 ^x

-- ^s
S1 ^{e and 1}
S2 ^{e, nr, and 2}
S3 ^{e, r, and 2}
S7 ^{e and 3}
S11 ^x

1 SQLExecDirect returned SQL_NEED_DATA.

2 SQLExecute returned SQL_NEED_DATA.

3 SQLSetPos returned SQL_NEED_DATA.

SQLRowCount

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	--	--	(S1010)	(S1010)

SQLSetConnectOption

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
-- ¹	--	--	--	--	(S1010)	(S1010)
1 This row shows transitions when fOption was a connection option. For transitions when fOption was a statement option, see the statement transition table for SQLSetStmtOption.

SQLSetCursorName

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	--	--	(24000)	(24000)	(S1010)	(S1010)

SQLSetPos

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	(S1010)	(S1010)	(24000)	see below	(S1010)	NS ^c (S1010) ^o

SQLSetPos (Cursor states)

S5 Opened	S6 SQLFetch	S7 SQLExtendedFetch
(24000)	(S1010)	-- ^s S8 ^d S11 ^x 24000 ^b S1109 ⁱ

SQLSetScrollOptions

S0 Unallo- cated	S1 Alloca- ted	S2 – S3 Prepa- red	S4 Execu- ted	S5 – S7 Cursor	S8 – S10 Need Data	S11 – S12 Async
(IH)	--	(S1010)	(S1010)	(S1010)	(S1010)	(S1010)

SQLSetStmtOption

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

(IH)

-- ¹
(S1011) ²

-- ¹
(24000) ²

(S1010) ^{np or 1}
(S1011) ^{p and 2}

1 The fOption argument was not SQL_CONCURRENCY, SQL_CURSOR_TYPE, SQL_SIMULATE_CURSOR, or SQL_USE_BOOKMARKS.

2 The fOption argument was SQL_CONCURRENCY, SQL_CURSOR_TYPE, SQL_SIMULATE_CURSOR, or SQL_USE_BOOKMARKS.

SQLSpecialColumns: see SQLColumnPrivileges

SQLStatistics: see SQLColumnPrivileges

SQLTablePrivileges: see SQLColumnPrivileges

SQLTables: see SQLColumnPrivileges

SQLTransact

S0
Unallo-
cated

S1
Alloca-
ted

S2 – S3
Prepa-
red

S4
Execu-
ted

S5 – S7
Cursor

S8 – S10
Need Data

S11 – S12
Async

--

-- ^{2 or 3}
S1 ¹

-- ³
S1 ^{np and(1 or 2)}
S1 ^{p and 1}
S2 ^{p and 2}

-- ³
S1 ^{np and(1 or 2)}
S1 ^{p and 1}
S3 ^{p and 2}

(S1010)

1 The fType argument is SQL_COMMIT and SQLGetInfo returns SQL_CB_DELETE for the SQL_CURSOR_COMMIT_BEHAVIOR information type, or the fType argument is SQL_ROLLBACK and SQLGetInfo returns SQL_CB_DELETE for the SQL_CURSOR_ROLLBACK_BEHAVIOR information type.

2 The fType argument is SQL_COMMIT and SQLGetInfo returns SQL_CB_CLOSE for the SQL_CURSOR_COMMIT_BEHAVIOR information type, or the fType argument is SQL_ROLLBACK and SQLGetInfo returns SQL_CB_CLOSE for the SQL_CURSOR_ROLLBACK_BEHAVIOR information type.

3 The fType argument is SQL_COMMIT and SQLGetInfo returns SQL_CB_PRESERVE for the SQL_CURSOR_COMMIT_BEHAVIOR information type, or the fType argument is SQL_ROLLBACK and SQLGetInfo returns SQL_CB_PRESERVE for the SQL_CURSOR_ROLLBACK_BEHAVIOR information type.

APPENDIX B ODBC STATE TRANSITION TABLES

SQLFreeEnv

Environment Transitions

SQLAllocConnect

SQLAllocEnv

SQLDataSources and SQLDrivers

SQLError

SQLFreeConnect

SQLFreeEnv

SQLTransact

All Other ODBC Functions

Connection Transitions

SQLAllocConnect

SQLAllocEnv

SQLAllocStmt

SQLBrowseConnect

SQLColumnPrivileges

SQLColumns: see SQLColumnPrivileges

SQLConnect and SQLDriverConnect

SQLDataSources and SQLDrivers

SQLDisconnect

SQLDriverConnect: see SQLConnect

SQLDrivers: see SQLDataSources

SQLError

SQLExecDirect and SQLExecute

SQLExecute: see SQLExecDirect

SQLForeignKeys: see SQLColumnPrivileges

SQLFreeConnect

SQLFreeEnv

SQLFreeStmt

SQLGetConnectOption

SQLGetFunctions

SQLGetInfo

SQLGetTypeInfo: see SQLColumnPrivileges

SQLNativeSql

SQLPrepare

SQLPrimaryKeys: see SQLColumnPrivileges

SQLProcedureColumns: see SQLColumnPrivileges

SQLProcedures: see SQLColumnPrivileges

SQLSetConnectOption

SQLSpecialColumns: see SQLColumnPrivileges

SQLStatistics: see SQLColumnPrivileges

SQLTablePrivileges: see SQLColumnPrivileges

SQLTables: see SQLColumnPrivileges

SQLTransact

All Other ODBC Functions

Statement Transitions

SQLAllocConnect

SQLAllocEnv

SQLAllocStmt

SQLBindCol

SQLBindParameter

SQLBrowseConnect, SQLConnect, and SQLDriverConnect

SQLCancel 1

SQLColAttributes

SQLColAttributes (Prepared states)

SQLColumnPrivileges

SQLColumnPrivileges

SQLColumns: see SQLColumnPrivileges

SQLConnect: see SQLBrowseConnect

SQLDataSources and SQLDrivers

SQLDescribeCol

SQLDescribeCol (Prepared states)

SQLDescribeParam

SQLDisconnect

SQLDriverConnect: see SQLBrowseConnect

SQLDrivers: see SQLDataSources

SQLError

SQLExecDirect

SQLExecDirect (Cursor states)

SQLExecute

SQLExecute (Prepared states)

SQLExecute (Cursor states)

SQLExtendedFetch

SQLExtendedFetch (Cursor states)

SQLFetch

SQLFetch (Cursor states)

SQLForeignKeys: see SQLColumnPrivileges

SQLFreeConnect

SQLFreeEnv

SQLCancel ¹