付録 B: ODBC の状態遷移テーブル

この付録の表は、ODBC 関数が環境、接続、ステートメント、および記述子の状態の遷移を引き起こす方法を示しています。 通常、環境、接続、ステートメント、または記述子の状態によって、対応する種類のハンドル (環境、接続、ステートメント、または記述子) を使用する関数を呼び出すことができるタイミングが決まります。 次の図に示すように、環境、接続、ステートメント、記述子の状態は大まかに重なります。 たとえば、接続状態 C5 と C6 の完全な重複とステートメントの状態 S1 から S12 はデータ ソースに依存します。トランザクションは異なるデータ ソースで異なる時間に開始され、記述子の状態 D1i (暗黙的に割り当てられた記述子) は記述子が関連付けられているステートメントの状態に依存し、状態 D1e (明示的に割り当てられた記述子) はステートメントの状態に依存しないためです。 各状態の説明については、この付録で後述 する「環境の遷移」、「 接続の遷移」、「 ステートメントの遷移」、「記述子の 遷移」を参照してください。

環境と接続の状態は、次のように重複しています。

と重複する

接続とステートメントの状態は、次のように重複しています。

重複する

ステートメントと記述子の状態は、次のように重複しています。

する

接続と記述子の状態は、次のように重複しています。

と重複する

遷移テーブルの各エントリには、次のいずれかの値を指定できます。

• -- -関数の実行後、状態は変更されません。

• E

  n 、 C_n_、 S_n_、または D_n_ - 環境、接続、ステートメント、または記述子の状態が指定された状態に移動します。

• (IH) - 無効なハンドルが関数に渡されました。 ハンドルが null ハンドルであるか、間違った型の有効なハンドルであった場合 (たとえば、ステートメント ハンドルが必要なときに接続ハンドルが渡された場合)、関数は SQL_INVALID_HANDLEを返します。それ以外の場合、動作は未定義であり、おそらく致命的です。 このエラーは、指定された状態の関数を呼び出した場合に唯一考えられる結果である場合にのみ表示されます。 このエラーは状態を変更せず、かっこで示すように常にドライバー マネージャーによって検出されます。

• NS - 次の状態。 ステートメントの遷移は、ステートメントが非同期状態を通過していない場合と同じです。 たとえば、 SQLExecDirect がSQL_STILL_EXECUTINGを返したため、結果セットを作成するステートメントが状態 S1 から状態 S11 に入ったとします。 状態 S11 の NS 表記は、ステートメントの遷移が、結果セットを作成する状態 S1 のステートメントの遷移と同じであることを意味します。 SQLExecDirect がエラーを返した場合、ステートメントは状態 S1 のままです。成功した場合、ステートメントは状態 S5 に移動します。データが必要な場合、ステートメントは状態 S8 に移動します。実行中の場合は、状態 S11 のままです。

• XXXXX または (XXXXX) - 遷移テーブルに関連する SQLSTATE。ドライバー マネージャーによって検出された SQLSTATEs は、かっこで囲まれています。 関数は、SQL_ERRORと指定された SQLSTATE を返しましたが、状態は変更されません。 たとえば、SQLPrepare の前に SQLExecute が呼び出されると、SQLSTATE HY010 (関数シーケンス エラー) が返されます。

Note

テーブルには、状態を変更しない遷移テーブルに関連しないエラーは表示されません。 たとえば、 SQLAllocHandle が環境状態 E1 で呼び出され、SQLSTATE HY001 (メモリ割り当てエラー) を返した場合、環境は状態 E1 のままです。これは、 SQLAllocHandle の環境遷移テーブルには表示されません。

環境、接続、ステートメント、または記述子が複数の状態に移行できる場合は、考えられる各状態が表示され、1 つ以上の脚注で各遷移が行われる条件が説明されます。 次の脚注は、任意のテーブルに表示される場合があります。

脚注	意味
b	前または後。 カーソルは、結果セットの開始前または結果セットの末尾の後に配置されました。
c	現在の関数。 現在の関数は非同期的に実行されていました。
d	データが必要です。 SQL_NEED_DATA返された関数。
e	エラー。 関数がSQL_ERROR返しました。
i	行が無効です。 カーソルが結果セット内の行に配置され、行が削除されたか、行に対する操作でエラーが発生しました。 行ステータス配列が存在する場合は、行の行ステータス配列の値がSQL_ROW_DELETEDまたはSQL_ROW_ERROR。 (行状態配列は、SQL_ATTR_ROW_STATUS_PTR ステートメント属性によって指されます)。
nf	見つかりません。 SQL_NO_DATA返された関数。 これは、 SQLExecDirect、 SQLExecute、または SQLParamData が 、検索された更新または delete ステートメントの実行後に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 Allocated	E2 接続
(IH)	E0	(HY010)

環境状態 E0 で SQLFreeHandle が呼び出され、 HandleType が SQL_HANDLE_ENV に設定されている場合、ドライバー マネージャーはSQL_INVALID_HANDLEを返します。 HandleType が SQL_HANDLE_ENV に設定された状態 E1 で呼び出された場合、関数が成功した場合は環境は状態 E0 に移動し、関数が失敗した場合は状態 E1 のままです。 HandleType が SQL_HANDLE_ENV に設定された状態 E2 で呼び出された場合、ドライバー マネージャーは常に SQL_ERROR と SQLSTATE HY010 (関数シーケンス エラー) を返し、環境は状態 E2 のままです。

状態遷移テーブルを理解するには、それらが参照する項目 (環境、接続、ステートメント、または記述子) を理解する必要があります。 関数が X 型の項目のハンドルを受け入れるとします。その関数の X 状態遷移テーブルでは、X 型の項目のハンドルを使用して関数を呼び出すと、その項目に与える影響について説明します。 たとえば、 SQLDisconnect は 接続ハンドルを受け入れます。 SQLDisconnect の接続状態遷移テーブルでは、SQLDisconnect が呼び出される接続の状態に与える影響について説明します。

Y が X と等しくない Y 型の項目のハンドルを受け入れる関数があるとします。その関数の X 状態遷移テーブルでは、Y 型の項目に関連付けられている型 X のハンドルを使用して関数を呼び出すと、型 Y の項目に与える影響について説明します。たとえば、 SQLDisconnect のステートメント状態遷移テーブルでは、ステートメントが関連付けられている接続のハンドルを使用して呼び出されたときに SQLDisconnect がステートメントの状態に与える影響について説明します。

この付録には、次のトピックが含まれています。

• 環境の遷移

• 接続の遷移

• ステートメントの遷移

• 記述子の遷移