SQLAllocHandle 関数

準拠
導入されたバージョン: ODBC 3.0 標準コンプライアンス: ISO 92

まとめ
SQLAllocHandle は、環境、接続、ステートメント、または記述子ハンドルを割り当てます。

構文

  
SQLRETURN SQLAllocHandle(  
      SQLSMALLINT   HandleType,  
      SQLHANDLE     InputHandle,  
      SQLHANDLE *   OutputHandlePtr);  

引数

HandleType
[入力] SQLAllocHandle によって割り当てられるハンドルの種類。 次のいずれかの値を指定する必要があります。

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN ハンドルは、ドライバー マネージャーとドライバーでのみ使用されます。 アプリケーションでは、このハンドルの種類を使用しないでください。 SQL_HANDLE_DBC_INFO_TOKENの詳細については、「 ODBC ドライバーでのConnection-Pool認識の開発」を参照してください。

InputHandle
[入力]新しいハンドルが割り当てられるコンテキスト内の入力ハンドル。 HandleType がSQL_HANDLE_ENVの場合、これはSQL_NULL_HANDLE。 HandleType がSQL_HANDLE_DBCの場合、これは環境ハンドルである必要があり、SQL_HANDLE_STMTまたはSQL_HANDLE_DESC場合は接続ハンドルである必要があります。

OutputHandlePtr
[出力]新しく割り当てられたデータ構造にハンドルを返すバッファーへのポインター。

戻り値

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_INVALID_HANDLE、またはSQL_ERROR。

環境ハンドル以外のハンドルを割り当てるときに、 SQLAllocHandle がSQL_ERRORを返す場合、 OutputHandlePtr は、output 引数が null ポインターでない限り、 HandleType の値に応じて、SQL_NULL_HDBC、SQL_NULL_HSTMT、またはSQL_NULL_HDESCに設定されます。 その後、アプリケーションは 、InputHandle 引数のハンドルに関連付けられている診断データ構造から追加情報を取得できます。

環境ハンドルの割り当てエラー

環境の割り当ては、ドライバー マネージャー内と各ドライバー内の両方で発生します。 HandleType が SQL_HANDLE_ENV の SQLAllocHandle によって返されるエラーは、エラーが発生したレベルによって異なります。

HandleType が SQL_HANDLE_ENV の SQLAllocHandle が呼び出されたときに、ドライバー マネージャーが *OutputHandlePtr のメモリを割り当てることができない場合、またはアプリケーションが OutputHandlePtr に null ポインターを提供する場合、SQLAllocHandle はSQL_ERRORを返します。 ドライバー マネージャーは、*OutputHandlePtr をSQL_NULL_HENVに設定します (アプリケーションが null ポインターを指定していない限り、SQL_ERRORを返します)。 追加の診断情報を関連付けるハンドルはありません。

ドライバー マネージャーは、アプリケーションが SQLConnect、SQLBrowseConnect、または SQLDriverConnect を呼び出すまで、ドライバー レベルの環境ハンドル割り当て関数を呼び出しません。 ドライバー レベルの SQLAllocHandle 関数でエラーが発生した場合、ドライバー マネージャー レベルの SQLConnect、SQLBrowseConnect、または SQLDriverConnect 関数はSQL_ERRORを返します。 診断データ構造に SQLSTATE IM004 が含まれています (ドライバーの SQLAllocHandle が失敗しました)。 このエラーは、接続ハンドルで返されます。

ドライバー マネージャーとドライバーの間の関数呼び出しのフローの詳細については、「 SQLConnect 関数」を参照してください。

診断

SQLAllocHandle がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合は、適切な HandleType と Handle を InputHandle の値に設定して SQLGetDiagRec を呼び出すことによって、関連付けられた SQLSTATE 値を取得できます。 OutputHandle 引数にSQL_SUCCESS_WITH_INFO (ただし、SQL_ERRORは返されません) を返すことができます。 次の表に、 SQLAllocHandle によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。

説明

SQLAllocHandle は、次のセクションで説明するように、環境、接続、ステートメント、および記述子のハンドルを割り当てるために使用されます。 ハンドルに関する一般的な情報については、「 ハンドル」を参照してください。

ドライバーで複数の割り当てがサポートされている場合は、複数の環境、接続、またはステートメント ハンドルを一度にアプリケーションで割り当てることができます。 ODBC では、一度に割り当てることができる環境、接続、ステートメント、または記述子ハンドルの数に制限は定義されません。 ドライバーは、一度に割り当てることができる特定の種類のハンドルの数に制限を課す場合があります。詳細については、ドライバーのドキュメントを参照してください。

既に存在する環境、接続、ステートメント、または記述子ハンドルに設定された *OutputHandlePtr を使用してアプリケーションが SQLAllocHandle を呼び出す場合、アプリケーションが接続プールを使用していない限り、ドライバーはハンドルに関連付けられている情報を上書きします (このセクションで後述する「接続プール用の環境属性の割り当て」を参照してください)。 ドライバー マネージャーは、*OutputHandlePtr に入力されたハンドルが既に使用されているかどうかを確認したり、上書きする前にハンドルの以前の内容を確認したりしません。

複数のスレッドをサポートするオペレーティング システムでは、アプリケーションは異なるスレッドで同じ環境、接続、ステートメント、または記述子ハンドルを使用できます。 したがって、ドライバーは、この情報への安全なマルチスレッド アクセスをサポートする必要があります。これを実現する 1 つの方法は、たとえば、クリティカル セクションまたはセマフォを使用する方法です。 スレッド処理の詳細については、「 マルチスレッド」を参照してください。

SQLAllocHandle では、環境ハンドルを割り当てるために呼び出されたときに、SQL_ATTR_ODBC_VERSION環境属性は設定されません。環境属性はアプリケーションで設定する必要があります。接続ハンドルを割り当てるために SQLAllocHandle が呼び出されると、SQLSTATE HY010 (関数シーケンス エラー) が返されます。

標準準拠アプリケーションの場合、 SQLAllocHandle はコンパイル時に SQLAllocHandleStd にマップされます。 これら 2 つの関数の違いは、HandleType 引数を SQL_HANDLE_ENV に設定して呼び出されたときに、SQLAllocHandleStd によって SQL_ATTR_ODBC_VERSION 環境属性がSQL_OV_ODBC3に設定される点です。 これは、標準に準拠したアプリケーションは常に ODBC 3 であるためです。x アプリケーション。 また、標準では、アプリケーションのバージョンを登録する必要はありません。 これは、これら 2 つの関数の唯一の違いです。それ以外の場合は、同じです。 SQLAllocHandleStd は、ドライバー マネージャー内の SQLAllocHandle にマップされます。 そのため、サード パーティ製ドライバーは SQLAllocHandleStd を実装する必要はありません。

ODBC 3.8 アプリケーションでは、次のものを使用する必要があります。

• 環境ハンドルを割り当てるための SQLAllocHandleStd ではなく、SQLAllocHandle。

• SQLSetEnvAttr を使用して、SQL_ATTR_ODBC_VERSION環境属性を SQL_OV_ODBC3_80 に設定します。

環境ハンドルの割り当て

環境ハンドルは、有効な接続ハンドルやアクティブな接続ハンドルなどのグローバル情報へのアクセスを提供します。 環境ハンドルに関する一般的な情報については、「 環境ハンドル」を参照してください。

環境ハンドルを要求するために、アプリケーションは、HandleType が SQL_HANDLE_ENV、InputHandle が SQL_NULL_HANDLE の SQLAllocHandle を呼び出します。 ドライバーは、環境情報のメモリを割り当て、 *OutputHandlePtr 引数に関連付けられているハンドルの値を渡します。 アプリケーションは、環境ハンドル引数を必要とする後続のすべての呼び出しで *OutputHandle 値を渡します。 詳細については、「 環境ハンドルの割り当て」を参照してください。

ドライバー マネージャーの環境ハンドルの下に、ドライバーの環境ハンドルが既に存在する場合は、接続が確立されたときに、そのドライバーで HandleType が SQL_HANDLE_ENV の SQLAllocHandle は呼び出されず、HandleType が SQL_HANDLE_DBC の SQLAllocHandle のみが呼び出されます。 ドライバー マネージャーの環境ハンドルの下にドライバーの環境ハンドルが存在しない場合は、環境の最初の接続ハンドルがドライバーに接続されている場合、SQL_HANDLE_DBC SQL_HANDLE_ENV ドライバーで呼び出されます。

ドライバー マネージャーは、SQL_HANDLE_ENVの HandleType を使用して SQLAllocHandle 関数を処理するときに、システム情報の [ODBC] セクションで Trace キーワードを確認します。 1 に設定されている場合、ドライバー マネージャーは、現在のアプリケーションのトレースを有効にします。 トレース フラグが設定されている場合、トレースは最初の環境ハンドルが割り当てられるときに開始され、最後の環境ハンドルが解放されると終了します。 詳細については、「 データ ソースの構成」を参照してください。

環境ハンドルを割り当てた後、アプリケーションは環境ハンドルで SQLSetEnvAttr を呼び出して、SQL_ATTR_ODBC_VERSION環境属性を設定する必要があります。 環境に接続ハンドルを割り当てるために SQLAllocHandle が呼び出される前にこの属性が設定されていない場合、接続を割り当てる呼び出しは SQLSTATE HY010 (関数シーケンス エラー) を返します。 詳細については、「 アプリケーションの ODBC バージョンの宣言」を参照してください。

接続プール用の共有環境の割り当て

環境は、1 つのプロセスで複数のコンポーネント間で共有できます。 共有環境は、複数のコンポーネントで同時に使用できます。 コンポーネントが共有環境を使用する場合は、プールされた接続を使用できます。これにより、その接続を再作成せずに既存の接続を割り当てて使用できます。

接続プールに使用できる共有環境を割り当てる前に、アプリケーションで SQLSetEnvAttr を呼び出して、SQL_ATTR_CONNECTION_POOLING環境属性をSQL_CP_ONE_PER_DRIVERまたはSQL_CP_ONE_PER_HENVに設定する必要があります。 この場合、SQLSetEnvAttr は EnvironmentHandle を null に設定して呼び出され、属性はプロセス レベルの属性になります。

接続プールが有効になった後、アプリケーションは、HandleType 引数を SQL_HANDLE_ENV に設定して SQLAllocHandle を呼び出します。 接続プールが有効になっているため、この呼び出しによって割り当てられた環境は暗黙的な共有環境になります。

共有環境が割り当てられると、HandleType がSQL_HANDLE_DBCの SQLAllocHandle が呼び出されるまで、使用される環境は決定されません。 その時点で、ドライバー マネージャーは、アプリケーションによって要求された環境属性と一致する既存の環境を検索しようとします。 そのような環境が存在しない場合は、共有環境として作成されます。 ドライバー マネージャーは、共有環境ごとに参照カウントを保持します。環境が最初に作成されるときに、カウントは 1 に設定されます。 一致する環境が見つかった場合、その環境のハンドルがアプリケーションに返され、参照カウントがインクリメントされます。 この方法で割り当てられた環境ハンドルは、入力引数として環境ハンドルを受け入れる任意の ODBC 関数で使用できます。

接続ハンドルの割り当て

接続ハンドルは、接続の有効なステートメントハンドルや記述子ハンドル、トランザクションが現在開いているかどうかなどの情報へのアクセスを提供します。 接続ハンドルに関する一般的な情報については、「 接続ハンドル」を参照してください。

接続ハンドルを要求するために、アプリケーションは HandleType が SQL_HANDLE_DBCの SQLAllocHandle を呼び出します。 InputHandle 引数は、そのハンドルを割り当てた SQLAllocHandle の呼び出しによって返された環境ハンドルに設定されます。 ドライバーは、接続情報のメモリを割り当て、 *OutputHandlePtr に関連付けられているハンドルの値を渡します。 アプリケーションは、接続ハンドルを必要とする後続のすべての呼び出しで *OutputHandlePtr 値を渡します。 詳細については、「 接続ハンドルの割り当て」を参照してください。

ドライバー マネージャーは、SQLAllocHandle 関数を処理し、アプリケーションが SQLConnect、SQLBrowseConnect、または SQLDriverConnect を呼び出すときに、ドライバーの SQLAllocHandle 関数を呼び出します。 (詳細については、「 SQLConnect 関数」を参照してください)。

環境に接続ハンドルを割り当てるために SQLAllocHandle が呼び出される前に、SQL_ATTR_ODBC_VERSION環境属性が設定されていない場合、接続を割り当てる呼び出しは SQLSTATE HY010 (関数シーケンス エラー) を返します。

InputHandle 引数を SQL_HANDLE_DBCに設定して SQLAllocHandle を呼び出し、共有環境ハンドルにも設定すると、ドライバー マネージャーは、アプリケーションによって設定された環境属性に一致する既存の共有環境を検索しようとします。 このような環境が存在しない場合は、参照カウント (ドライバー マネージャーによって管理) が 1 で作成されます。 一致する共有環境が見つかった場合、そのハンドルがアプリケーションに返され、その参照カウントがインクリメントされます。

使用される実際の接続は、SQLConnect または SQLDriverConnect が呼び出されるまで、ドライバー マネージャーによって決定されません。 ドライバー マネージャーは、SQLConnect の呼び出し (または SQLDriverConnect の呼び出しの接続キーワード) と接続の割り当て後に設定された接続属性の接続オプションを使用して、プール内のどの接続を使用するかを決定します。 詳細については、「 SQLConnect 関数」を参照してください。

ステートメント ハンドルの割り当て

ステートメント ハンドルを使用すると、SQL ステートメント処理のエラー メッセージ、カーソル名、状態情報などのステートメント情報にアクセスできます。 ステートメント ハンドルの一般的な情報については、「ステートメント ハンドル」を参照してください。

ステートメント ハンドルを要求するために、アプリケーションはデータ ソースに接続し、SQL ステートメントを送信する前に SQLAllocHandle を呼び出します。 この呼び出しでは、 HandleType を SQL_HANDLE_STMT に設定し 、InputHandle を、そのハンドルを割り当てた SQLAllocHandle の呼び出しによって返された接続ハンドルに設定する必要があります。 ドライバーは、ステートメント情報のメモリを割り当て、ステートメント ハンドルを指定された接続に関連付け、関連付けられているハンドルの値 を *OutputHandlePtr に戻します。 アプリケーションは、ステートメント ハンドルを必要とする後続のすべての呼び出しで *OutputHandlePtr 値を渡します。 詳細については、「 ステートメント ハンドルの割り当て」を参照してください。

ステートメント ハンドルが割り当てられると、ドライバーは 4 つの記述子のセットを自動的に割り当て、これらの記述子のハンドルをSQL_ATTR_APP_ROW_DESC、SQL_ATTR_APP_PARAM_DESC、SQL_ATTR_IMP_ROW_DESC、およびステートメント属性SQL_ATTR_IMP_PARAM_DESC割り当てます。 これらは 、暗黙的に 割り当てられた記述子と呼ばれます。 アプリケーション記述子を明示的に割り当てるには、次のセクション「記述子ハンドルの割り当て」を参照してください。

記述子ハンドルの割り当て

アプリケーションで HandleType が SQL_HANDLE_DESC の SQLAllocHandle を呼び出すと、ドライバーはアプリケーション記述子を割り当てます。 これらは、 明示的に 割り当てられた記述子と呼ばれます。 アプリケーションは、SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC 属性を使用して SQLSetStmtAttr 関数を呼び出すことによって、特定のステートメント ハンドルに対して自動的に割り当てられた記述子ではなく、明示的に割り当てられたアプリケーション記述子を使用するようにドライバーに指示します。 実装記述子を明示的に割り当てることはできません。 また、SQLSetStmtAttr 関数呼び出しで実装記述子を指定することもできません。

明示的に割り当てられた記述子は、ステートメント ハンドルではなく接続ハンドルに関連付けられます (自動的に割り当てられた記述子と同様)。 記述子は、アプリケーションが実際にデータベースに接続されている場合にのみ割り当てられたままになります。 明示的に割り当てられた記述子は接続ハンドルに関連付けられているため、アプリケーションは、明示的に割り当てられた記述子を接続内の複数のステートメントに関連付けることができます。 一方、暗黙的に割り当てられたアプリケーション記述子は、複数のステートメント ハンドルに関連付けることはできません。 (割り当てられたステートメント ハンドル以外のステートメント ハンドルに関連付けることはできません)。明示的に割り当てられた記述子ハンドルは、アプリケーションによって明示的に解放することも、HandleType が SQL_HANDLE_DESCの SQLFreeHandle を呼び出すか、接続が閉じられたときに暗黙的に解放できます。

明示的に割り当てられた記述子が解放されると、暗黙的に割り当てられた記述子がステートメントに再び関連付けられます。 (そのステートメントのSQL_ATTR_APP_ROW_DESCまたはSQL_ATTR_APP_PARAM_DESC属性は、暗黙的に割り当てられた記述子ハンドルに再び設定されます)。これは、接続で明示的に割り当てられた記述子に関連付けられたすべてのステートメントに当てはまります。

記述子の詳細については、「 記述子」を参照してください。

コード例

「 サンプル ODBC プログラム、 SQLBrowseConnect 関数、 SQLConnect 関数、 および SQLSetCursorName 関数」を参照してください。

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル