SQLSetConnection() - 接続ハンドルを設定する

SQLSetConnection() が必要となるのは、アプリケーションが実行を続ける前に、特定の接続に どうしても切り替えなければならない場合です。この関数は、アプリケーションが Db2® ODBC 関数呼び出しと組み込み SQL 関数を混合使用して、複数データベース接続を行う場合のみ、使用してください。

SQLSetConnection() の ODBC 仕様

表 1. SQLSetConnection() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
なし なし なし

構文

SQLRETURN  SQLSetConnection  (SQLHDBC           hdbc);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLSetConnection() の引数
データ・タイプ 引数 使用法 説明
SQLHDBC hdbc 入力 アプリケーションが切り替えようとする接続に関連した接続ハンドル。

使用法

ODBC では、複数の同時接続が可能です。このため、呼び出されたときに、 組み込み SQL ルーチンがどの接続を使用するかは明確ではありません。 実際には、組み込みルーチンは最新のネットワーク活動に関連した接続を使用します。 しかし、アプリケーションの立場からすれば、これを判別することは必ずしも容易ではなく、 この情報を把握しておくことは困難です。SQLSetConnection() を使用すると、アプリケーション はどの接続をアクティブにするかを 明示的に 指定することができます。これによって、アプリケーションは、組み込み SQL ルーチンを呼び出すことができます。

アプリケーションが単に Db2 ODBC 呼び出しのみを行う場合は、SQLSetConnection() はまったく必要ありません。 これは、それぞれのステートメント・ハンドルが接続ハンドルと暗黙的に 関連しているため、特定の Db2 ODBC 関数がどの接続に 適用するかについて混乱を起こすことはあり得ないからです。

重要: Db2 ODBC と組み込み SQL を混合使用する場合は、 複数コンテキストの Db2 ODBC サポートを有効にしないでください。 混合使用するアプリケーションの初期化ファイルでは、MULTICONTEXT=0 を指定するか、 キーワード MULTICONTEXT を除外する必要があります。

戻りコード

SQLSetConnection() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLSetConnection() の SQLSTATE
SQLSTATE 説明 説明
08003 接続はクローズされています。 指定されている接続ハンドルは現在、データベース・サーバーへ のオープン接続に関連付けられていません。
HY000 一般エラー。 具体的な SQLSTATE のない、しかもこのインプリメンテーションはで SQLSTATE が 定義されていないエラーが発生しました。SQLGetDiagRec() が、エラーとその原因を示したエラー・ メッセージを引数 szErrorMsg に戻します。

例

トピック『配列を使用してパラメーター値を入力する』には、SQLSetConnection() を呼び出す方法を示した例が記載されています。