附錄 B：ODBC 狀態轉換資料表

本附錄中的資料表顯示 ODBC 函式如何造成環境、連接、語句和描述項狀態的轉換。 環境、連接、語句或描述元的狀態通常會指定何時可以呼叫使用對應控制碼類型的函式（環境、連接、語句或描述元）。 環境、連接、語句和描述元狀態大致重迭，如下圖所示。 例如，線上狀態 C5 和 C6 和 語句的確切重迭狀態為 S1 到 S12 與資料來源相依，因為交易在不同的時間在不同的資料來源上開始，而描述元狀態 D1i （隱含配置描述元）取決於描述元相關聯的語句狀態，而狀態 D1e （明確配置的描述元） 與任何語句的狀態無關。 如需每個狀態的描述，請參閱 本附錄稍後的環境轉換、 連接轉換 、 語句轉換 和 描述元轉換 。

環境和線上狀態會重迭，如下所示：

連線和語句狀態會重迭，如下所示：

語句和描述項狀態會重迭，如下所示：

連線和描述項狀態會重迭，如下所示：

轉換資料表中的每個專案都可以是下列其中一個值：

• -- -執行函式之後的狀態不會變更。

• E

  n 、 C_n_ 、 S_n_ 或 D_n_ - 環境、連接、語句或描述元狀態會移至指定的狀態。

• （IH） - 傳遞至函式的控制碼無效。 如果控制碼是 Null 控制碼，或是錯誤型別的有效控制碼，例如，當需要語句控制碼時傳遞連接控制碼，則函式會傳回SQL_INVALID_HANDLE;否則，行為未定義且可能致命。 只有在呼叫指定狀態的函式的唯一可能結果時，才會顯示此錯誤。 此錯誤不會變更狀態，而且一律由驅動程式管理員偵測，如括弧所示。

• NS - 下一個狀態。 語句轉換與語句未通過非同步狀態相同。 例如，假設建立結果集的語句會從狀態 S1 進入狀態 S11，因為 SQLExecDirect 傳回SQL_STILL_EXECUTING。 狀態 S11 中的 NS 標記法標記法，表示語句的轉換與建立結果集之狀態 S1 中語句的轉換相同。 如果 SQLExecDirect 傳回錯誤，語句會維持在狀態 S1 中;如果成功，語句會移至狀態 S5;如果需要資料，語句會移至狀態 S8;如果語句仍在執行中，則會維持在狀態 S11 中。

• XXXXX 或 （ XXXXX ） - 與轉換資料表相關的 SQLSTATE;驅動程式管理員偵測到的 SQLSTATE 會以括弧括住。 函式傳回SQL_ERROR和指定的 SQLSTATE，但狀態不會變更。 例如，如果在 SQLPrepare 之前 呼叫 SQLExecute ，則會傳回 SQLSTATE HY010 （函數順序錯誤）。

注意

資料表不會顯示與未變更狀態之轉換資料表無關的錯誤。 例如，在 環境狀態 E1 中呼叫 SQLAllocHandle 並傳回 SQLSTATE HY001 （記憶體配置錯誤），環境會維持在狀態 E1 中;這不會顯示在 SQLAllocHandle 的環境轉換資料表 中。

如果環境、連接、語句或描述項可以移至多個狀態，則會顯示每個可能的狀態，並顯示一或多個註腳來說明每個轉換發生的條件。 下列註腳可能會出現在任何資料表中。

註腳	意義
b	前後。 游標位於結果集的開頭之前或結果集結尾之後。
c	目前的函式。 目前的函式是以非同步方式執行。
日	需要資料。 函式傳回SQL_NEED_DATA。
e	Error。 函式傳回SQL_ERROR。
i	不正確資料列。 資料指標位於結果集中的資料列上，而且資料列已刪除，或資料列上的作業發生錯誤。 如果資料列狀態陣列存在，則資料列的資料列狀態陣列中的值SQL_ROW_DELETED或SQL_ROW_ERROR。 （資料列狀態陣列是由 SQL_ATTR_ROW_STATUS_PTR 語句屬性所指向。
nf	找不到。 函式傳回SQL_NO_DATA。 當 SQLExecDirect 、 SQLExecute 或 SQLParamData 在執行搜尋的更新或刪除語句之後傳回SQL_NO_DATA時，這不適用。
np	未備妥。 聲明尚未備妥。
nr	無結果。 語句將不會或未建立結果集。
o	其他函式。 另一個函式是以非同步方式執行。
p	準備。 聲明已備妥。
r	結果。 語句會或確實建立一個（可能空白）的結果集。
s	成功。 函式會傳回SQL_SUCCESS_WITH_INFO或SQL_SUCCESS。
v	有效的資料列。 資料指標位於結果集中的資料列上，且資料列已成功插入、成功更新，或資料列上的另一個作業已順利完成。 如果資料列狀態陣列存在，則資料列的資料列狀態陣列中的值SQL_ROW_ADDED、SQL_ROW_SUCCESS或SQL_ROW_UPDATED。 （資料列狀態陣列是由 SQL_ATTR_ROW_STATUS_PTR 語句屬性所指向。
x	執行。 函式傳回SQL_STILL_EXECUTING。

SQLFreeHandle

在此範例中，當 HandleType 為 SQL_HANDLE_ENV 時 ，SQLFreeHandle 環境狀態轉換資料表 中的資料列如下所示。

E0 未配置	E1 已配置	E2 連線
（IH）	E0	（HY010）

如果在 環境狀態 E0 中呼叫 SQLFreeHandle ，且 HandleType 設定為 SQL_HANDLE_ENV，驅動程式管理員會傳回SQL_INVALID_HANDLE。 如果在狀態 E1 中呼叫，並將 HandleType 設定為 SQL_HANDLE_ENV，則如果函式成功，環境會移至狀態 E0，如果函式失敗，則會維持在狀態 E1 中。 如果在狀態 E2 中呼叫，並將 HandleType 設定為 SQL_HANDLE_ENV，驅動程式管理員一律會傳回 SQL_ERROR 和 SQLSTATE HY010 （函式順序錯誤），而環境仍會維持在狀態 E2 中。

若要瞭解狀態轉換資料表，必須瞭解所參考的專案（環境、連接、語句或描述元）。 假設函式接受 X 類型專案的控制碼。該函式的 X 狀態轉換資料表描述呼叫函式的方式，以及類型為 X 的專案控制碼，會影響該專案。 例如， SQLDisconnect 接受連接控制碼。 SQLDisconnect 的 線上狀態轉換表描述 SQLDisconnect 如何影響 呼叫連線的狀態。

假設函式接受類型為 Y 的專案控制碼，其中 Y 不等於 X。該函式的 X 狀態轉換資料表描述如何呼叫函式，以及與 Y 類型專案相關聯的 X 型別控制碼，會影響類型 Y 的專案。例如，SQLDisconnect 的 語句狀態轉換資料表會描述 SQLDisconnect 如何 透過與語句相關聯之連接控制碼呼叫時影響語句的狀態。

本附錄包含下列主題。

• 環境轉換

• 連線轉換

• 語句轉換

• 描述項轉換