SQLDriverConnect 関数

適合 性
導入版:ODBC 1.0 規格準拠:ODBC

まとめ
SQLDriverConnect は SQLConnectの代替手段です。 SQLConnectの3つの引数よりも多くの接続情報を必要とするデータソース、すべての接続情報を求めるダイアログボックス、システム情報で定義されていないデータソースをサポートしています。 詳細は 「SQLDriverConnectとの接続」をご覧ください。

Syntax

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);  

引数

ConnectionHandle
[入力] 接続ハンドル。

ウィンドウハンドル
[入力]窓の取っ手。 アプリケーションは、親ウィンドウのハンドルを渡すか、ウィンドウハンドルが適用できない場合や SQLDriverConnect がダイアログボックスを表示しない場合はnullポインタを渡すことができます。

InConnectionString
[入力]完全な接続文字列(「Comments」の構文を参照)、部分的な接続文字列、または空の文字列です。

ストリングレングス1
[入力]*InConnectionStringの長さは、文字列がUnicodeの場合は文字数、ANSIまたはDBCSの場合はバイト数です。

アウトコネクションストリング
[出力]完了した接続文字列のバッファへのポインタ。 ターゲットデータソースへの接続が成功すると、このバッファには完了した接続文字列が収まります。 アプリケーションはこのバッファに少なくとも1,024文字を割り当てるべきです。

OutConnectionStringがNULLの場合、StringLength2Ptr はOutConnectionStringが指すバッファ内で返せる文字数(文字データのnull終端文字を除く)を返します。

BufferLength
[入力]*OutConnectionString バッファの長さ(文字数)です。

ストリングレングス2Ptr
[出力]*OutConnectionStringで返せる文字数(null終端文字を除く)を返すバッファへのポインタ。 戻せる文字数がBufferLength以上の場合、*OutConnectionStringの完了した接続文字列はnull終端文字の長さを引いたBufferLengthに切り詰められます。

ドライバーコンピューション
[入力]ドライバーマネージャーかドライバーが接続情報の追加を求める必要があるかを示すフラグ:

SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED、SQL_DRIVER_NOPROMPT。

(詳細は「コメント」をご覧ください。)

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NO_DATA、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_STILL_EXECUTING。

Diagnostics

SQLDriverConnectがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連するSQLSTATE値を、fHandleTypeをSQL_HANDLE_DBC、hHandleをConnectionHandleでSQLGetDiagRec呼び出すことで取得できます。 以下の表は 、SQLDriverConnect が通常返すSQLSTATEの値を一覧にし、この関数の文脈でそれぞれを説明します。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

接続文字列は以下の構文を持ちます:

connection-string ::= empty-string[;] | attribute[;] | 属性; 接続文字列

empty-string ::=attribute := attribute-keyword=attribute-value |DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN |UID |障害者 | ドライバー定義属性キーワード

attribute-value ::= character-string

driver-defined-attribute-keyword ::= identifier

ここで、文字列は0文字以上を持ちます。識別子は1文字以上を持ち、attribute-keywordは大文字を区別しません。属性値は大文字を区別することもあります。DSNキーワードの値は単なる空欄だけではありません。

接続文字列や初期化ファイルの文法、キーワードや属性値が[]{}(),;?)を含むためです。*=!@ ブレースで囲まれていないものは避けるべきです。 DSN キーワードの値はブランクのみで構成することはできません。また、先頭にブランクを含めることはできません。 システム情報の文法のため、キーワードとデータ ソース名に円記号 (\) 文字を含めることはできません。

DRIVERキーワードの後に属性値の囲いに括弧を付ける必要はありません。ただし、属性にセミコロン(;)が含まれている場合は括弧が必要です。 ドライバーが受け取る属性値に中かっこが含まれている場合、ドライバーはそれらを削除しないでくださいが、返される接続文字列の一部である必要があります。

DSNまたは接続文字列の値が括弧({})で囲まれ、[]{}(),;?)のいずれかの文字を含む場合です。*=!@はドライバーにそのまま渡されます。 しかし、これらの文字をキーワードで使うと、ドライバーマネージャーはファイルのDSNを扱う際にエラーを返しますが、通常の接続文字列の場合は接続文字列をドライバーに渡します。 キーワード値に埋め込み中かっこを使用しないでください。

接続文字列には、任意の数のドライバー定義キーワードを含めることができます。 DRIVERキーワードはシステム情報の情報を使わないため、ドライバーは接続文字列の情報だけでデータソースに接続できるよう十分なキーワードを定義しなければなりません。 (詳細はこのセクションの後半にある「ドライバーガイドライン」をご覧ください。)ドライバーはデータソースに接続するために必要なキーワードを定義します。

以下の表は、DSN、FILEDSN、DRIVER、UID、PWD、SAVEFILEキーワードの属性値を説明しています。

アプリケーションがどのようにデータソースまたはドライバを選択するかについては、「 データソースまたはドライバの選択」をご覧ください。

接続文字列内でキーワードが繰り返された場合、ドライバーはそのキーワードの最初の出現に対応する値を使用します。 DSNとDRIVERのキーワードが同じ接続文字列に含まれる場合、ドライバーマネージャーとドライバーは先に現れるキーワードを使用します。

FILEDSNとDSNのキーワードは排他的であり、最初に現れるキーワードが使われ、次に現れるものは無視されます。 一方で 、FILEDSN と DRIVER のキーワードは相反するものではありません。 FILEDSNの接続文字列にキーワードが現れた場合、.dsnファイルの同じキーワードの属性値ではなく、その接続文字列内のキーワードの属性値が使われます。

FILEDSNキーワードを使用する場合、.dsnファイルで指定されたキーワードを使って接続文字列を作成します。 (詳細はこの節の後半にある「ファイルデータソース」を参照してください。) UID キーワードは任意です。.dsnファイルは DRIVER キーワードのみで作成可能です。 PWDキーワードは.dsnファイルに保存されていません。 .dsnファイルの保存および読み込みのデフォルトディレクトリは、CommonFileDirが HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersionで指定したパスと「ODBC\DataSources」の組み合わせです。 (もしCommonFileDirが「C:\Program Files\Common Files」であれば、デフォルトのディレクトリは「C:\Program Files\Common Files\ODBC\Data Sources」となります。)

SAVEFILEキーワードを使用する場合、現在の成功した接続に使われたキーワードの属性値は、SAVEFILEキーワードの属性値の名前を付けた.dsnファイルとして保存されます。 SAVEFILEキーワードはDRIVERキーワード、FILEDSNキーワード、または両方と組み合わせて使用しなければならず、そうでなければ関数はSQLSTATE 01S09(Invalid keyword)とSQL_SUCCESS_WITH_INFO返されます。 接続文字列でSAVEFILEキーワードがDRIVERキーワードの前に現れなければならず、そうでなければ結果が定義されません。

ドライバーマネージャーガイドライン

ドライバーマネージャーは、ドライバーのSQLDriverConnect関数のInConnectionString引数でドライバーに渡すための接続文字列を構築します。 ドライバーマネージャーはアプリケーションから渡された InConnectionString 引数を改変しません。

ドライバーマネージャーの動作は DriverCompletion 引数の値に基づいています:

• SQL_DRIVER_PROMPT:接続文字列にDRIVER、DSN、またはFILEDSNのいずれかのキーワードが含まれていない場合、ドライバーマネージャーは「データソース」ダイアログボックスを表示します。 ダイアログボックスから返されるデータソース名と、アプリケーションから渡された他のキーワードから接続文字列を作成します。 ダイアログボックスから返されるデータソース名が空の場合、ドライバーマネージャーはキーワードと値のペアをDSN=Defaultを指定します。 (このダイアログボックスには「Default」という名前のデータソースは表示されません。)

• SQL_DRIVER_COMPLETEまたはSQL_DRIVER_COMPLETE_REQUIRED:アプリケーションが指定した接続文字列にDSNキーワードが含まれている場合、ドライバーマネージャーはアプリケーションが指定した接続文字列をコピーします。 それ以外は 、DriverCompletion がSQL_DRIVER_PROMPTされたときと同じ動作をします。

• SQL_DRIVER_NOPROMPT:ドライバーマネージャーはアプリケーションが指定した接続文字列をコピーします。

アプリケーションが指定した接続文字列にDRIVERキーワードが含まれている場合、ドライバーマネージャーはアプリケーションが指定した接続文字列をコピーします。

Driver Managerは構築した接続文字列を使い、どのドライバーを使うかを決定し、そのドライバーに接続して構築した接続文字列をドライバに渡します。Driver Managerとドライバの相互作用の詳細については、SQLConnect関数の「Comments」セクションを参照してください。 もし接続文字列にDRIVERキーワードが含まれていない場合、ドライバーマネージャーは以下のようにどのドライバーを使用するかを決定します。

1. 接続文字列にDSNキーワードが含まれている場合、ドライバーマネージャーはシステム情報からデータソースに関連付けられたドライバーを取得します。

2. 接続文字列にDSNキーワードが含まれていなかったり、データソースが見つからない場合、ドライバーマネージャーはシステム情報からデフォルトデータソースに関連付けられたドライバーを取得します。 (詳細は「デフォルトサブキー」を参照してください。)ドライバーマネージャーは接続文字列内のDSNキーワードの値を「DEFAULT」に変更します。

3. 接続文字列内のDSNキーワードが「DEFAULT」に設定されている場合、ドライバーマネージャーはシステム情報からデフォルトデータソースに関連付けられたドライバーを取得します。

4. データソースが見つからず、デフォルトデータソースも見つからない場合、ドライバーマネージャーはSQLSTATE IM002(データソースが見つからず、デフォルトドライバーが指定されていない)でSQL_ERROR返します。

[ファイル データ ソース]

アプリケーションがSQLDriverConnectに呼び出す際に指定した接続文字列にFILEDSNキーワードが含まれており、このキーワードがDSNまたはDRIVERキーワードに置き換えられていない場合、Driver Managerは.dsnファイルの情報とInConnectionString引数を使って接続文字列を作成します。 ドライバーマネージャーは以下の通りに進めます。

1. .dsnファイルのファイル名が有効かどうかを確認します。 そうでなければ、SQLSTATE IM014(ファイルDSNの無効名)でSQL_ERRORを返します。 ファイル名が空文字列("")でSQL_DRIVER_NOPROMPTが指定されていない場合は、「 ファイル開き 」ダイアログボックスが表示されます。 ファイル名に有効なパスが含まれているがファイル名がないか、無効なファイル名がSQL_DRIVER_NOPROMPT指定されていない場合、 ファイルオープン ダイアログボックスが表示され、現在のディレクトリはファイル名で指定されたものに設定されています。 ファイル名が空文字列("")であるか、パスは有効でファイル名が存在しないか、または無効なファイル名で、SQL_DRIVER_NOPROMPTが指定されている場合、SQL_ERRORはSQLSTATE IM014(ファイルDSNの無効名)で返されます。

2. .dsnファイルの[ODBC]セクション内のすべてのキーワードを読み取ります。 DRIVERキーワードが存在しない場合は、SQLSTATE IM012(Driverキーワード構文エラー)でSQL_ERROR返されますが、.dsnファイルが共有不可でDSNキーワードのみを含む場合は例外です。

   ファイルデータソースが共有不可の場合、ドライバーマネージャーは DSN キーワードの値を読み取り、共有不可ファイルソースが指すユーザーまたはシステムデータソースに接続します。 ステップ3から5までのステップは実施されません。

3. ドライバー用の接続文字列を構築します。 ドライバーの接続文字列は、.dsnファイルで指定されたキーワードと元のアプリケーション接続文字列で指定されたキーワードの合併です。 キーワードが重複するドライバー接続文字列の構築ルールは以下の通りです:

   • もしDRIVERキーワードがアプリケーションの接続文字列に存在し、DRIVERキーワードで指定されたドライバーが.dsnファイルとアプリケーションの接続文字列で一致しない場合、.dsnファイルのドライバー情報は無視され、アプリケーションの接続文字列内のドライバー情報が使用されます。 もしDRIVERキーワードで指定されたドライバが.dsnファイルとアプリケーションの接続文字列で同一であれば、すべてのキーワードが重複する場合、アプリケーションの接続文字列で指定されたものが.dsnファイルで指定されたものよりも優先されます。

   • 新しい接続文字列では、FILEDSNキーワードが削除されます。

4. <Driver Name>がDRIVERキーワードで指定されているレジストリエントリ HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\< Driver Name>\Driverを見てドライバーを読み込みます。

5. ドライバーに新しい接続ストリングを渡します。

.dsnファイルの例については、「 ファイルデータソースを使って接続する」を参照してください。

SAVEFILE キーワード

アプリケーションが指定した接続文字列にSAVEFILEキーワードが含まれている場合、ドライバーマネージャーはその接続文字列を.dsnファイルに保存します。 ドライバーマネージャーは以下の通りに進めます。

1. SAVEFILEキーワードの属性値として含まれている.dsnファイルのファイル名が有効かどうかを確認します。 そうでなければ、SQLSTATE IM014(ファイルDSNの無効名)でSQL_ERRORを返します。 ファイル名の有効性は標準的なシステム命名ルールによって決定されます。 ファイル名が空文字列("")で、 DriverCompletion 引数がSQL_DRIVER_NOPROMPTされていない場合、そのファイル名は有効です。 ファイル名がすでに存在している場合、 DriverCompletion がSQL_DRIVER_NOPROMPTされている場合、そのファイルは上書きされます。 DriverCompletionがSQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、またはSQL_DRIVER_COMPLETE_REQUIREDの場合、ダイアログボックスでユーザーがファイルを上書きすべきかどうかを指定するよう促されます。 「いいえ」と入力すると、「 ファイル保存 」ダイアログボックスが表示されます。

2. もしドライバがSQL_SUCCESSを返し、ファイル名が空文字列でなければ、ドライバマネージャーは OutConnectionString 引数で返された接続情報を、本節の「Connection Strings」セクションで指定されたフォーマットで指定されたファイルに書き込みます。

3. ドライバーがSQL_SUCCESSを返し、ファイル名が空の文字列("")であれば、ドライバーマネージャーはファイル セーブ 共通ダイアログボックスを呼び出し、 hwnd を指定したファイル保存ダイアログボックスを呼び出し、 OutConnectionString で返された接続情報を、前述の「接続文字列」セクションで指定したフォーマットで、File-Save 共通ダイアログボックスで指定されたファイルに書き込みます。

4. ドライバーがSQL_SUCCESSを返す場合、接続文字列を含むOutConnectionString引数をアプリケーションに返します。

5. もしドライバがSQL_SUCCESS_WITH_INFOまたはSQL_ERRORを返した場合、ドライバマネージャーはSQLSTATEをアプリケーションに返します。

ドライバーガイドライン

ドライバーは、ドライバーマネージャーから渡される接続文字列にDSNまたはDRIVERキーワードが含まれているかどうかを確認します。 接続文字列にDRIVERキーワードが含まれている場合、ドライバーはシステム情報からデータソースの情報を取得できません。 もし接続文字列にDSNキーワードが含まれているか、DSNまたはDRIVERキーワードのいずれも含まれていない場合、ドライバーはシステム情報からデータソースに関する情報を以下のように取得できます。

1. もし接続文字列にDSNキーワードが含まれている場合、ドライバーは指定されたデータソースの情報を取得します。

2. 接続文字列にDSNキーワードが含まれていなかったり、指定されたデータソースが見つからなかったり、DSNキーワードが「DEFAULT」に設定されている場合、ドライバーはデフォルトデータソースの情報を取得します。

ドライバーはシステム情報から取得した情報を、接続文字列で受け継がれる情報を補強するために使います。 システム情報の情報が接続文字列の情報と重複した場合、ドライバーは接続文字列の情報を使用します。

DriverCompletionの値に基づき、ドライバーはユーザーにユーザーIDやパスワードなどの接続情報を入力し、データソースに接続します。

• SQL_DRIVER_PROMPT:ドライバーはダイアログボックスを表示します。接続文字列の値やシステム情報(あれば)を初期値として使用します。 ユーザーがダイアログボックスを終了すると、ドライバーはデータソースに接続します。 また、*InConnectionString内のDSNまたはDRIVERキーワードの値とダイアログボックスから返される情報から接続文字列も構成します。 この接続文字列は*OutConnectionStringバッファに置きます。

• SQL_DRIVER_COMPLETEまたはSQL_DRIVER_COMPLETE_REQUIRED:接続文字列に十分な情報が含まれていて、その情報が正しい場合、ドライバはデータソースに接続し、*InConnectionStringを*OutConnectionStringにコピーします。 情報が欠落または誤りの場合、ドライバーは DriverCompletion がSQL_DRIVER_PROMPTされた時と同じ操作を行いますが、 DriverCompletion がSQL_DRIVER_COMPLETE_REQUIREDされた場合は、データソースに接続する必要のない情報の制御を無効にします。

• SQL_DRIVER_NOPROMPT:接続文字列に十分な情報が含まれている場合、ドライバはデータソースに接続し、*InConnectionStringを*OutConnectionStringにコピーします。 それ以外の場合は 、ドライバーがSQLDriverConnectのSQL_ERRORを返します。

データソースへの接続が成功すると、ドライバーは*StringLength2Ptr を *OutConnectionString で返せる出力 接続文字列 の長さにも設定します。

ユーザーがドライバーマネージャーやドライバーから提示されたダイアログボックスをキャンセルすると、 SQLDriverConnect はSQL_NO_DATAを返します。

接続プロセス中にドライバーマネージャーとドライバーがどのように相互作用するかについては、 SQLConnect関数を参照してください。

ドライバが SQLDriverConnectをサポートしている場合、ドライバのシステム情報のドライバーキーワードセクションには、2文字目が「Y」に設定された ConnectFunctions キーワードが含まれなければなりません。

接続プーリングが有効の場合の接続

接続プーリングは、すでに作成された接続を再利用することを可能にします。 SQLDriverConnectが呼び出されると、ドライバーマネージャーは接続プーリングに指定された環境内の接続プールの一部である接続を試みます。 接続プーリングの詳細については、 SQLConnect関数を参照してください。

アプリケーションはプーリングが有効な接続でSQLDisconnectを呼び出す前にSQL_ATTR_RESET_CONNECTIONを設定することができます。 詳細については、「 SQLSetConnectAttr 関数を参照してください。

アプリケーションが SQLDriverConnect を呼び出してプール接続に接続する場合、以下の制限が適用されます。

• 接続文字列にSAVEFILEキーワードが指定されている場合、接続プーリング処理は行われません。

• 接続プーリングが有効の場合、 SQLDriverConnect は DriverCompletion 引数がSQL_DRIVER_NOPROMPTでしか呼び出せません。 SQLDriverConnect が他の DriverCompletionで呼び出された場合、SQLSTATE HY110(Invalid driver completion)が返されます。

接続属性

SQL_ATTR_LOGIN_TIMEOUT接続属性は SQLSetConnectAttrで設定され、ドライバが成功裏に接続してログインリクエストを待つまでの秒数を定義します。 ユーザーが接続文字列の完了を促されると、ドライバーが接続プロセスを開始した時点で、各ログインリクエストに対して待機期間が始まります。

ドライバーはデフォルトでSQL_MODE_READ_WRITEアクセスモードで接続を開きます。 アクセスモードをSQL_MODE_READ_ONLYに設定するには、アプリケーションはSQLDriverConnectを呼び出す前にSQL_ATTR_ACCESS_MODE属性でSQLSetConnectAttrを呼び出す必要があります。

データソースのシステム情報にデフォルトの翻訳ライブラリが指定されている場合、ドライバーがそれを読み込みます。 別の翻訳ライブラリは、SQL_ATTR_TRANSLATE_LIB属性で SQLSetConnectAttr を呼び出すことで読み込むことができます。 翻訳オプションは 、SQL_ATTR_TRANSLATE_OPTIONオプションでSQLSetConnectAttr を呼び出しることで指定できます。

詳細は 「SQLDriverConnectとの接続」をご覧ください。

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {                 
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

また、 サンプルODBCプログラムも参照してください。

関連関数

こちらもご覧ください

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