次の方法で共有

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

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

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

SQL_HANDLE_ENVの HandleType 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を使用してSQLGetDiagRecを呼び出して、関連付けられた SQLSTATE 値InputHandleを取得できます。 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 に対して呼び出され、 SQLAllocHandle 関数が HandleType SQL_HANDLE_STMT または SQL_HANDLE_DESC に設定されたときに、まだ実行されていました。
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 は、次のセクションで説明するように、環境、接続、ステートメント、および記述子のハンドルを割り当てるために使用されます。 ハンドルに関する一般的な情報については、「 Handles」を参照してください。

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

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

Note

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

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

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

標準準拠アプリケーションの場合、 SQLAllocHandle はコンパイル時に SQLAllocHandleStd にマップされます。 これら 2 つの関数の違いは、 SQLAllocHandleStd HandleType 引数をSQL_HANDLE_ENVに設定して呼び出されたときに、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に設定します。

環境ハンドルの割り当て

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

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

ドライバー マネージャーの環境ハンドルの下に既にドライバーの環境ハンドルが存在する場合は、接続が確立されたときにSQL_HANDLE_ENVのHandleTypeを持つ SQLAllocHandle は呼び出されません。HandleType のSQLAllocHandleのみSQL_HANDLE_DBC。 ドライバー マネージャーの環境ハンドルの下にドライバーの環境ハンドルが存在しない場合、環境の最初の接続ハンドルがドライバーに接続されると、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 に設定して呼び出され、属性がプロセス レベルの属性になります。

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

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

接続ハンドルの割り当て

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

コード例

SQLBrowseConnect 関数、SQLBrowseConnect 関数、SQLConnect 関数、および SQLSetCursorName 関数を参照してください。

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

参照

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