CLI の手引きおよび解説書

SQLDriverConnect - データ・ソースに (拡張) 接続する

目的


仕様: 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 */

関数引き数

表 52. SQLDriverConnect 引き数
データ・タイプ 引き数 使用法 説明
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 がいつ詳細情報をユーザーに要求すべきかを示します。

有効値は次のとおりです。

  • SQL_DRIVER_PROMPT
  • SQL_DRIVER_COMPLETE
  • SQL_DRIVER_COMPLETE_REQUIRED
  • SQL_DRIVER_NOPROMPT

使用法

接続ストリングは、接続を完了するのに必要な 1 つ以上の値を渡すのに使用します。接続ストリングの内容と DriverCompletion の値で、 DB2 CLI がユーザーとダイアログを確立する必要があるかどうかを判別します。

   .-;----------------------------------------------.
   V                                                |
>>-----+-DSN---------------------+--=--attribute----+----------><
       +-UID---------------------+
       +-PWD---------------------+
       +-NEWPWD------------------+
       '-DB2 CLI-defined-keyword-'
 

上記の各キーワードには、以下のような属性があります。

DSN
データ・ソース名。データベースの名前または別名。 DriverCompletion が SQL_DRIVER_NOPROMPT と等しいときに必要です。

UID
許可名 (ユーザー識別子)。

PWD
許可名に対応するパスワード。ユーザー ID のパスワードがないと、空の値が指定されます (PWD=;)。

NEWPWD
パスワード変更要求の一部として使用する新規パスワード。アプリケーションは、使用する新規のストリングを指定することもできますし (NEWPWD=anewpass など)、 NEWPWD=; と指定することにより、DB2 CLI ドライバーにダイアログ・ボックスを生成させて、新規パスワードを求めるプロンプトを表示することもできます (DriverCompletion 引き数には SQL_DRIVER_NOPROMPT 以外の値を指定)。

DB2 CLI 定義のキーワードおよびそれに関連する属性値については、 構成キーワードで論じられます。そのセクションで扱われるキーワードはいずれも、接続ストリングに指定されるものです。キーワードが接続ストリング内で繰り返し指定されると、キーワードの最初のオカレンスに関連した値が使用されます。

CLI 初期設定ファイルにキーワードがある場合、それらのキーワードとそれらに対応する値は、接続ストリング内の DB2 CLI に渡される情報を追加するのに使用されます。 CLI 初期設定ファイル内の情報が接続ストリング内の情報と矛盾するときは、接続ストリング内の値が優先されます。

表示されたダイアログ・ボックスをエンド・ユーザーが取り消す と、 SQL_NO_DATA_FOUND が返されます。

次に示す DriverCompletion の値で、ダイアログがオープンされる時点を判別します。

SQL_DRIVER_PROMPT:
ダイアログは常に開始されます。接続ストリングと CLI 初期設定ファイルからの情報は初期値として使用され、ダイアログ・ボックスでデータ入力して補足できます。

SQL_DRIVER_COMPLETE:
ダイアログは、接続ストリング内の情報が不足しているときだけ開始されます。接続ストリングからの情報は初期値として使用され、ダイアログ・ボックスでデータ入力して補足できます。

SQL_DRIVER_COMPLETE_REQUIRED:
ダイアログは、接続ストリング内の情報が不足しているときだけ開始されます。接続ストリングからの情報は、初期値として使用されます。必須情報しか要求されません。ユーザーは、必要な情報だけを要求されます。

SQL_DRIVER_NOPROMPT:
ユーザーは、情報を要求されません。接続ストリングに含まれている情報を使用して、接続が試行されます。情報が足りない場合、 SQL_ERROR が返されます。

接続が確立されると、完全な接続ストリングが返されます。特定のユーザー 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);  
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]