SQLDriverConnect 関数

準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ODBC

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

構文

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

引数

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

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

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

StringLength1
[入力]文字列が Unicode の場合は *InConnectionString、文字列が ANSI または DBCS の場合はバイト単位の長さ。

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

OutConnectionString が NULL の場合でも、StringLength2Ptr は、OutConnectionString が指すバッファーで返すために使用できる文字数 (文字データの null 終端文字を除く) を返します。

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

StringLength2Ptr
[出力]*OutConnectionString で返すために使用できる文字数 (null 終了文字を除く) の合計数を返すバッファーへのポインター。 返される文字数が BufferLength 以上の場合、*OutConnectionString の完成した接続文字列は BufferLength から null 終端文字の長さを引いた値に切り捨てられます。

DriverCompletion
[入力]ドライバー マネージャーまたはドライバーがより多くの接続情報を求める必要があるかどうかを示すフラグ。

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。

診断

SQLDriverConnect が SQL_ERROR または SQL_SUCCESS_WITH_INFO を返す場合は、fHandleType が SQL_HANDLE_DBC で ConnectionHandle の hHandle を使用して SQLGetDiagRec を呼び出すことによって、関連付けられた SQLSTATE 値を取得できます。 次の表に、 SQLDriverConnect によって一般的に返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。"(DM)" という表記は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられた戻りコードはSQL_ERRORされます。

説明

接続文字列には、次の構文があります。

connection-string ::= empty-string[;] | attribute[;] | 属性。 connection-string

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

attribute-keyword ::= DSN |UID |PWD | driver-defined-attribute-keyword

attribute-value ::= character-string

driver-defined-attribute-keyword ::= identifier

ここで、character-string には 0 個以上の文字が含まれます。identifier には 1 つ以上の文字があります。attribute-keyword では大文字と小文字は区別されません。属性値では大文字と小文字が区別される場合があります。DSN キーワードの値は空白のみで構成されるわけではありません。

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

属性にセミコロン (;)が含まれていない限り、アプリケーションは 、DRIVER キーワードの後に属性値の前後に中かっこを追加する必要はありません。この場合、中かっこが必要です。 ドライバーが受け取る属性値に中かっこが含まれている場合、ドライバーはそれらを削除しませんが、返される接続文字列の一部である必要があります。

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

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

次の表では、DSN、FILEDSN、DRIVER、UID、PWD、SAVEFILE キーワードの属性値について説明します。

アプリケーションでデータ ソースまたはドライバーを選択する方法については、「データ ソースまたはドライバーの選択」を参照してください。

接続文字列でキーワードが繰り返される場合、ドライバーは キーワードの最初の出現に関連付けられた値を使用します。 DSN キーワードと DRIVER キーワードが同じ接続文字列に含まれている場合、ドライバー マネージャーとドライバーは、最初に表示されるキーワードを使用します。

FILEDSN キーワードと DSN キーワードは相互に排他的です。最初に出現するキーワードが使用され、2 番目に表示されるキーワードは無視されます。 一方、 FILEDSN キーワードと DRIVER キーワードは相互に排他的ではありません。 FILEDSN を含む接続文字列にキーワードが含まれている場合は、.dsn ファイル内の同じキーワードの属性値ではなく、接続文字列内のキーワードの属性値が使用されます。

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

SAVEFILE キーワードを使用すると、現在の正常な接続を行うために使用されるキーワードの属性値は、SAVEFILE キーワードの属性値の名前を持つ .dsn ファイルとして保存されます。 SAVEFILE キーワードは、DRIVER キーワード、FILEDSN キーワード、またはその両方と組み合わせて使用する必要があります。または、関数は SQLSTATE 01S09 (Invalid キーワード) で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 キーワードが含まれている場合、ドライバー マネージャーは、アプリケーションで指定された接続文字列をコピーします。

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

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

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

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

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

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

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

1. .dsn ファイルのファイル名が有効かどうかを確認します。 そうでない場合は、SQLSTATE IM014 でSQL_ERRORを返します (ファイル DSN の名前が無効です)。 ファイル名が空の文字列 ("") で、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 キーワードでドライバー名>が指定されているレジストリ エントリHKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>\Driver <を調べることでドライバーを読み込みます。

5. ドライバーに新しい接続文字列を渡します。

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

SAVEFILE キーワード

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

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

2. ドライバーがSQL_SUCCESSを返し、ファイル名が空の文字列でない場合、ドライバー マネージャーは、 OutConnectionString 引数で返された接続情報を、このセクションの前の「接続文字列」セクションで指定した形式で指定されたファイルに書き込みます。

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" に設定されている場合、ドライバーは 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 をサポートしている場合、ドライバーのシステム情報の driver キーワード セクションには、2 番目の文字が "Y" に設定された ConnectFunctions キーワードが含まれている必要があります。

接続プールが有効になっている場合の接続

接続プールを使用すると、アプリケーションは既に作成されている接続を再利用できます。 SQLDriverConnect が呼び出されると、ドライバー マネージャーは、接続プール用に指定された環境の接続プールの一部である接続を使用して接続を試行します。 接続プールの詳細については、「 SQLConnect 関数」を参照してください。

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

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

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

• 接続プールが有効になっている場合、SQLDriverConnect は、SQL_DRIVER_NOPROMPTの DriverCompletion 引数でのみ呼び出すことができます。他の DriverCompletion で SQLDriverConnect が呼び出された場合は、SQLSTATE HY110 (無効なドライバーの完了) が返されます。

接続属性

SQLSetConnectAttr を使用して設定されたSQL_ATTR_LOGIN_TIMEOUT接続属性は、アプリケーションに戻る前に、ドライバーによる正常な接続でログイン要求が完了するまで待機する秒数を定義します。 ユーザーが接続文字列を完了するように求められた場合、ドライバーが接続プロセスを開始すると、各ログイン要求の待機期間が開始されます。

ドライバーは、既定でアクセス モード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 ヘッダー ファイル