次の方法で共有

SQLAllocHandle 関数

  • [アーティクル]

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

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

Note

この関数は、ODBC 2.0 関数 SQLAllocConnect、SQLAllocEnv、および SQLAllocStmt を置き換えるハンドルを割り当てる汎用関数です。 SQLAllocHandle を呼び出すアプリケーションが ODBC 2 を操作できるようにするため。x ドライバー、SQLAllocHandle への呼び出しは、必要に応じて、ドライバー マネージャーで SQLAllocConnect、SQLAllocEnv、または SQLAllocStmt にマップされます。 詳細については、「コメント」を参照してください。ドライバー マネージャーが ODBC 3 の場合にこの関数をマップする方法について詳しくは、x アプリケーションが ODBC 2 で動作しています。x ドライバーについては、「アプリケーションの下位互換性のための置換関数のマッピング」を参照してください。

構文

  
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 ドライバーでの接続プール認識の開発」を参照してください。

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 は、出力引数が null ポインターでない限り、HandleType の値に応じて、SQL_NULL_HDBC、SQL_NULL_HSTMT、またはSQL_NULL_HDESCに設定されます。 その後、アプリケーションは、InputHandle 引数のハンドルに関連付けられている診断データ構造から追加情報を取得できます。

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

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

SQL_HANDLE_ENVの HandleType を持つ SQLAllocHandle が呼び出されたとき、またはアプリケーションが OutputHandlePtr に null ポインターを提供するときに、ドライバー マネージャーが *OutputHandlePtr のメモリを割り当てることができない場合、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。

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
08003 接続が開かない (DM) HandleType 引数がSQL_HANDLE_STMTまたはSQL_HANDLE_DESCされましたが、InputHandle 引数で指定された接続が開いていません。 ドライバーがステートメントまたは記述子ハンドルを割り当てるには、接続プロセスが正常に完了する必要があります (接続を開く必要があります)。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージには、エラーとその原因が記述されています。
HY001 メモリ割り当てエラー (DM) ドライバー マネージャーは、指定されたハンドルのメモリを割り当てませんでした。

ドライバーは、指定されたハンドルのメモリを割り当てることができませんでした。
HY009 null ポインターの使用が無効です (DM) OutputHandlePtr 引数が null ポインターでした。
HY010 関数シーケンス エラー (DM) HandleType 引数がSQL_HANDLE_DBCされ 、sqlSetEnvAttr がSQL_ODBC_VERSION環境属性を設定するために呼び出されていません。

(DM) 非同期実行関数が InputHandle に対して呼び出され、HandleType が SQL_HANDLE_STMT または SQL_HANDLE_DESC に設定された状態で SQLAllocHandle 関数が呼び出されたときに、まだ実行されていました。
HY013 メモリ管理エラー HandleType 引数はSQL_HANDLE_DBC、SQL_HANDLE_STMT、またはSQL_HANDLE_DESCでした。基になるメモリ オブジェクトにアクセスできなかったため、メモリの状態が低いために関数呼び出しを処理できませんでした。
HY014 ハンドルの数の制限を超えました HandleType 引数によって示されるハンドルの種類に割り当てることができるハンドルの数のドライバー定義の制限に達しました。
HY092 無効な属性/オプション識別子 (DM) HandleType 引数は、SQL_HANDLE_ENV、SQL_HANDLE_DBC、SQL_HANDLE_STMT、またはSQL_HANDLE_DESCではありません。
HY117 不明なトランザクション状態のため、接続が中断されます。 切断関数と読み取り専用関数のみが許可されます。 (DM) 中断状態の詳細については、「SQLEndTran 関数」を参照してください。
HYC00 省略可能な機能が実装されていません HandleType 引数はSQL_HANDLE_DESCされ、ドライバーは ODBC 2 でした。x ドライバー。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、SQL_ATTR_CONNECTION_TIMEOUT SQLSetConnectAttr を使用して設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) HandleType 引数がSQL_HANDLE_STMTされ、ドライバーが有効な ODBC ドライバーではありません。

(DM) HandleType 引数がSQL_HANDLE_DESCされ、ドライバーは記述子ハンドルの割り当てをサポートしていません。

Comments

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

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

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

Note

SQLFreeHandle を呼び出さずに *OutputHandlePtr に対して定義された同じアプリケーション変数を使用して SQLAllocHandle を 2 回呼び出し、ハンドルを再割り当てする前に解放するのは、ODBC アプリケーション プログラミングでは正しくありません。 このような方法で ODBC ハンドルを上書きすると、ODBC ドライバーの動作やエラーの一貫性が失われます。

複数のスレッドをサポートするオペレーティング システムでは、アプリケーションは異なるスレッドで同じ環境、接続、ステートメント、または記述子ハンドルを使用できます。 したがって、ドライバーは、この情報への安全なマルチスレッド アクセスをサポートする必要があります。たとえば、これを実現する 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。

  • SQL_ATTR_ODBC_VERSION環境属性をSQL_OV_ODBC3_80に設定する SQLSetEnvAttr 。

環境ハンドルの割り当て

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

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

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

ドライバー マネージャーは、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 を呼び出します。 接続プールが有効になっているため、この呼び出しによって割り当てられる環境は暗黙的な共有環境になります。

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

接続ハンドルの割り当て

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

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

ドライバー マネージャーは、SQLConnect、SQLBrowseConnect、または SQLDriverConnect を呼び出すときに、SQLAllocHandle 関数を処理し、ドライバーの SQLAllocHandle 関数を呼び出します。 (詳細については、 SQLConnect 関数)。)

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

アプリケーションが sqlAllocHandle を呼び出し、InputHandle 引数を SQL_HANDLE_DBC に設定し、共有環境ハンドルにも設定すると、ドライバー マネージャーは、アプリケーションによって設定された環境属性に一致する既存の共有環境を検索しようとします。 このような環境が存在しない場合は、参照カウント (ドライバー マネージャーによって管理) が 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 関数呼び出しで実装記述子を指定することもできません。

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

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

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

コード例

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

情報 参照トピック
SQL ステートメントの実行 SQLExecDirect 関数
準備された SQL ステートメントの実行 SQLExecute 関数
環境、接続、ステートメント、または記述子ハンドルの解放 SQLFreeHandle 関数
実行のためのステートメントの準備 SQLPrepare 関数
接続属性の設定 SQLSetConnectAttr 関数
記述子フィールドの設定 SQLSetDescField 関数
環境属性の設定 SQLSetEnvAttr 関数
ステートメント属性の設定 SQLSetStmtAttr 関数

参照

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