仕様: | DB2 CLI 2.1 | ODBC 1.0 |
SQLDriverConnect() は、SQLConnect() の代わりの関数です。両方の関数とも宛先データベースに対する接続を確立しますが、 SQLDriverConnect() は追加接続パラメーターと、接続情報をユーザーに入力要求する機能をサポートします。
SQLConnect() でサポートされる 3 つの入力引き数 (データ・ソース名、ユーザー ID、およびパスワード) 以外のパラメーターがデータ・ソースに必要な場合、または DB2 CLI のグラフィカル・ユーザー・インターフェースを使用してユーザーに必須の接続情報を入力要求したい場合に、 SQLDriverConnect() を使用します。
接続が確立されると、完全な接続ストリングが返されます。アプリケーションは、以後の接続要求のためにこのストリングを保管することができます。
構文
総称
SQLRETURN SQLDriverConnect ( SQLHDBC ConnectionHandle, /* hdbc */ SQLHWND WindowHandle, /* hwnd */ SQLCHAR *FAR InConnectionString, /* szConnStrIn */ SQLSMALLINT StringLength1, /* cbConnStrIn */ SQLCHAR *FAR OutConnectionString,/* szConnStrOut */ SQLSMALLINT BufferLength, /* cbConnStrOutMax */ SQLSMALLINT *FAR StringLength2Ptr, /* pcbConnStrOut */ SQLUSMALLINT DriverCompletion); /* fDriverCompletion */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHDBC | ConnectionHandle | 入力 | 接続ハンドル |
SQLHWND | hwindow | 入力 | ウィンドウ・ハンドル (プラットフォーム従属): Windows では、これは親 Windows ハンドルです。
OS/2 では、これは親 PM ウィンドウ・ハンドルです。
AIX では、これは親 MOTIF ウィジェット・ウィンドウ・ハンドルです。
NULL が渡されると、ダイアログは表示されません。 |
SQLCHAR * | InConnectionString | 入力 | 完全、一部、または空 (ヌル・ポインター) の接続ストリング (次の構文と説明を参照)。 |
SQLSMALLINT | StringLength1 | 入力 | InConnectionString の長さ。 |
SQLCHAR * | OutConnectionString | 出力 | 完全な接続ストリングのバッファーを指すポインター。
接続が正常に確立されると、このバッファーには完全な接続ストリングが入れられます。アプリケーションは、このバッファー用に少なくとも SQL_MAX_OPTION_STRING_LENGTH バイトを割り振る必要があります。 |
SQLSMALLINT | BufferLength | 入力 | OutConnectionString で指定されたバッファーの最大サイズ。
|
SQLCHAR * | StringLength2Ptr | 出力 | OutConnectionString バッファーに返すために使用できるバイト数を指すポインター。
StringLength2Ptr の値が BufferLength 以上である場合、 OutConnectionString 内の完全接続ストリングは BufferLength - 1 バイトに切り捨てられます。 |
SQLUSMALLINT | DriverCompletion | 入力 | DB2 CLI がいつ詳細情報をユーザーに要求すべきかを示します。
有効値は次のとおりです。
|
使用法
接続ストリングは、接続を完了するのに必要な 1 つ以上の値を渡すのに使用します。接続ストリングの内容と DriverCompletion の値で、 DB2 CLI がユーザーとダイアログを確立する必要があるかどうかを判別します。
.-;----------------------------------------------. V | >>-----+-DSN---------------------+--=--attribute----+---------->< +-UID---------------------+ +-PWD---------------------+ +-NEWPWD------------------+ '-DB2 CLI-defined-keyword-'
上記の各キーワードには、以下のような属性があります。
DB2 CLI 定義のキーワードおよびそれに関連する属性値については、 構成キーワードで論じられます。そのセクションで扱われるキーワードはいずれも、接続ストリングに指定されるものです。キーワードが接続ストリング内で繰り返し指定されると、キーワードの最初のオカレンスに関連した値が使用されます。
CLI 初期設定ファイルにキーワードがある場合、それらのキーワードとそれらに対応する値は、接続ストリング内の DB2 CLI に渡される情報を追加するのに使用されます。 CLI 初期設定ファイル内の情報が接続ストリング内の情報と矛盾するときは、接続ストリング内の値が優先されます。
表示されたダイアログ・ボックスをエンド・ユーザーが取り消す と、 SQL_NO_DATA_FOUND が返されます。
次に示す DriverCompletion の値で、ダイアログがオープンされる時点を判別します。
接続が確立されると、完全な接続ストリングが返されます。特定のユーザー ID で 1 つのデータベースに複数の接続を設定する必要がないアプリケーションでは、この出力接続ストリングを保管するようにします。次いで、このストリングを将来の SQLDriverConnect() 呼び出しの際の入力接続ストリング値として使用することができます。
戻りコード
診断
SQLConnect - データ・ソースに接続するで生成されるすべての診断を、ここでも返すことができます。次の表は、返すことのできる追加の診断を示したものです。
表 53. SQLDriverConnect SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01004 | データが切り捨てられました。 | バッファー szConnstrOut は、接続ストリング全体を保留できるほど大きくありませんでした。引き数 StringLength2Ptr には、戻りに使用できる接続ストリングの実際の長さが含まれています。 (関数は、SQL_SUCCESS_WITH_INFO を返します。) |
01S00 | 接続ストリング属性が無効です。 | 入力接続ストリングに無効なキーワードまたは属性値を指定し、次のうちの 1 つが発生しましたが、データ・ソースへの接続は成功しました。
(関数は、SQL_SUCCESS_WITH_INFO を返します。) |
HY000 | 一般的なエラーです。
ダイアログの失敗 | 接続ストリングに指定された情報は接続要求を行うには不十分でしたが、
fCompletion を SQL_DRIVER_NOPROMPT に設定してダイアログを禁止していました。
ダイアログを表示する試行が失敗しました。 |
HY090 | ストリングまたはバッファー長が無効です。 | StringLength1 に指定された値は 0 より小さい値でしたが、
SQL_NTS と等しくありませんでした。
引き数 BufferLength に指定された値は、0 より小さい値でした。 |
HY110 | ドライバーの完了が無効です。 | 引き数 fCompletion に指定された値は、有効値のいずれとも等しくありませんでした。 |
制約
なし。
(ここで完全サンプル dbconn.c を使用することもできます 。)
/* From the CLI sample DBCONN.C */ /* ... */ sqlrc = SQLDriverConnect(hdbc, (SQLHWND) NULL, connStr, SQL_NTS, NULL, 0, NULL, SQL_DRIVER_NOPROMPT);
参照