次の方法で共有


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

SQLSTATE エラー 説明
01000 一般的な警告 ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004 文字列データ、右切り捨て バッファー *OutConnectionString が接続文字列全体を返すには十分な大きさではないので、接続文字列が切り捨てられました。 *StringLength2Ptr では、文字列の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S00 接続文字列属性が無効です 接続文字列 (InConnectionString) に無効な属性キーワードが指定されましたが、ドライバーはとにかくデータ ソースに接続できました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S02 オプション値が変更されました ドライバーは、SQLSetConnectAttrValuePtr 引数によって指される指定された値をサポートしておらず、同様の値を置き換えました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S08 ファイル DSN の保存中にエラーが発生しました *InConnectionString の文字列にはFILEDSN キーワードが含まれていましたが、.dsn ファイルは保存されませんでした。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S09 キーワードが無効です (DM) *InConnectionString の 文字列には SAVEFILE キーワードが含まれていましたが、 DRIVER キーワードや FILEDSN キーワードは含まれていません。 (関数はSQL_SUCCESS_WITH_INFOを返します。
08001 クライアントが接続を確立できない ドライバーがデータ ソースとの接続を確立できませんでした。
08002 使用中の接続名 (DM) 指定された ConnectionHandle は、データ ソースとの接続を確立するために既に使用されており、接続はまだ開いています。
08004 サーバーが接続を拒否しました データ ソースは、実装定義の理由で接続の確立を拒否しました。
08S01 通信リンクエラー SQLDriverConnect 関数が処理を完了する前に、ドライバーとドライバーの接続を試みたデータ ソース間の通信リンクが失敗しました。
28000 承認の指定が無効です 接続文字列 (InConnectionString) で指定されているユーザー識別子または承認文字列、またはその両方が、データ ソースによって定義された制限に違反しました。
HY000 一般的なエラー 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *szMessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。
HY000 一般的なエラー: ファイル dsn が無効です (DM) *InConnectionString の文字列には FILEDSN キーワードが含まれていましたが、.dsn ファイルの名前が見つかりませんでした。
HY000 一般的なエラー: ファイル バッファーを作成できません (DM) *InConnectionString 内の文字列には FILEDSN キーワードが含まれていましたが、.dsn ファイルは読み取り不可能でした。
HY001 メモリ割り当てエラー ドライバー マネージャーは、 SQLDriverConnect 関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。

ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY008 操作が取り消されました ConnectionHandle に対して非同期処理が有効になりました。 関数が呼び出され、実行が完了する前に、ConnectionHandle で SQLCancelHandle 関数が呼び出され、ConnectionHandleSQLDriverConnect 関数が再度呼び出されました。

または、SQLDriverConnect 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから ConnectionHandleSQLCancelHandle が呼び出されました。
HY010 関数シーケンス エラー (DM) 別の非同期実行関数 ( SQLDriverConnect ではなく) が ConnectionHandle に対して呼び出され、 SQLDriverConnect 関数が呼び出されたときにまだ実行されていました。
HY013 メモリ管理エラー 基になるメモリ オブジェクトにアクセスできなかったため、 SQLDriverConnect 関数呼び出しを処理できませんでした。メモリが不足している可能性があります。
HY090 文字列またはバッファーの長さが無効です (DM) 引数 StringLength1 に指定された値が 0 未満で、SQL_NTSと等しくありません。

(DM) 引数 BufferLength に指定された値が 0 未満でした。
HY092 属性/オプション識別子が無効です (DM) DriverCompletion 引数がSQL_DRIVER_PROMPTされ、 WindowHandle 引数が null ポインターでした。
HY110 ドライバーの入力候補が無効です (DM) 引数 DriverCompletion に指定された値が、SQL_DRIVER_PROMPT、SQL_DRIVER_COMPLETE、SQL_DRIVER_COMPLETE_REQUIRED、またはSQL_DRIVER_NOPROMPTと等しくありません。

(DM) 接続プールが有効になっており、引数 DriverCompletion に指定された値がSQL_DRIVER_NOPROMPTと等しくありません。
HYC00 省略可能な機能が実装されていません ドライバーは、アプリケーションが要求した ODBC 動作のバージョンをサポートしていません。
HYT00 タイムアウトに達しました データ ソースへの接続が完了する前に、ログイン タイムアウト期間の有効期限が切れています。 タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_LOGIN_TIMEOUT) によって設定されます。
HYT01 接続のタイムアウト データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。
IM001 ドライバーは、この関数をサポートしていません (DM) 指定されたデータ ソース名に対応するドライバーは、 関数をサポートしていません。
IM002 データ ソースが見つからず、既定のドライバーが指定されていません (DM) 接続文字列 (InConnectionString) で指定されたデータ ソース名がシステム情報に見つからず、既定のドライバー仕様が見つかりませんでした。

(DM) ODBC データ ソースと既定のドライバー情報がシステム情報に見つかりませんでした。
IM003 指定されたドライバーを読み込めませんでした (DM) システム情報のデータ ソース仕様に記載されているドライバー、または DRIVER キーワードで指定された ドライバー が見つからないか、他の理由で読み込めませんでした。
IM004 SQL_HANDLE_ENVのドライバーの SQLAllocHandle が失敗しました (DM) SQLDriverConnect 中に、ドライバー マネージャーはドライバーの SQLAllocHandle 関数を呼び出し、 fHandleType が SQL_HANDLE_ENVであり、ドライバーからエラーが返されました。
IM005 SQL_HANDLE_DBCのドライバーの SQLAllocHandle が失敗しました。 (DM) SQLDriverConnect 中に、ドライバー マネージャーはドライバーの SQLAllocHandle 関数を呼び出し、 fHandleType が SQL_HANDLE_DBCであり、ドライバーからエラーが返されました。
IM006 ドライバーの SQLSetConnectAttr が失敗しました (DM) SQLDriverConnect 中に、ドライバー マネージャーがドライバーの SQLSetConnectAttr 関数を呼び出し、ドライバーからエラーが返されました。
IM007 データ ソースまたはドライバーが指定されていない。ダイアログは禁止されています 接続文字列にデータ ソース名またはドライバーが指定されておらず、 DriverCompletion がSQL_DRIVER_NOPROMPTされました。
IM008 ダイアログが失敗しました ドライバーがログイン ダイアログ ボックスを表示しようとしましたが、失敗しました。

WindowHandle が null ポインターであり、 DriverCompletion がSQL_DRIVER_NO_PROMPTされませんでした。
IM009 翻訳 DLL を読み込むことができません ドライバーは、データ ソースまたは接続に指定された変換 DLL を読み込めませんでした。
IM010 データ ソース名が長すぎます (DM) DSN キーワードの属性値がSQL_MAX_DSN_LENGTH文字より長かった。
IM011 ドライバー名が長すぎます (DM) DRIVER キーワードの属性値が 255 文字を超えています。
IM012 DRIVER キーワード構文エラー (DM) DRIVER キーワードのキーワードと値のペアに構文エラーが含まれていました。

(DM) *InConnectionString の 文字列には FILEDSN キーワードが含まれていましたが、.dsn ファイルに DRIVER キーワードまたは DSN キーワードが含まれていませんでした。
IM014 指定された DSN には、ドライバーとアプリケーションの間のアーキテクチャの不一致が含まれています (DM) 32 ビット アプリケーションは、64 ビット ドライバーに接続する DSN を使用します。またはその逆。
IM015 SQL_HANDLE_DBC_INFO_HANDLEのドライバーの SQLDriverConnect が失敗しました ドライバーがSQL_ERRORを返した場合、ドライバー マネージャーはアプリケーションにSQL_ERRORを返し、接続は失敗します。

SQL_HANDLE_DBC_INFO_TOKENの詳細については、「 ODBC ドライバーでのConnection-Pool認識の開発」を参照してください。
IM017 非同期通知モードでポーリングが無効になっている 通知モデルが使用されるたびに、ポーリングは無効になります。
IM018 SQLCompleteAsync は、このハンドルで前の非同期操作を完了するために呼び出されていません。 ハンドルの前の関数呼び出しがSQL_STILL_EXECUTINGを返し、通知モードが有効になっている場合は、処理後に処理を実行して操作を完了するために、 SQLCompleteAsync をハンドルで呼び出す必要があります。
S1118 ドライバーは非同期通知をサポートしていません ドライバーが非同期通知をサポートしていない場合は、SQL_ATTR_ASYNC_DBC_EVENTまたはSQL_ATTR_ASYNC_DBC_RETCODE_PTRを設定できません。

説明

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

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

次の表では、DSNFILEDSNDRIVERUID、PWDSAVEFILE キーワードの属性値について説明します。

Keyword 属性値の説明
DSN SQLDataSources によって返されるデータ ソースの名前、または SQLDriverConnect の [データ ソース] ダイアログ ボックス。
FILEDSN データ ソースの接続文字列の作成元となる .dsn ファイルの名前。 これらのデータ ソースは、ファイル データ ソースと呼ばれます。
ドライバー SQLDrivers 関数によって返されるドライバーの説明。 たとえば、Rdb や SQL Serverなどです。
UID ユーザー ID。
PWD ユーザー ID に対応するパスワード、またはユーザー ID のパスワードがない場合は空の文字列 (PWD=;)。
Savefile 現在の正常な接続を行う際に使用されるキーワードの属性値を保存する .dsn ファイルのファイル名。

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

接続文字列でキーワードが繰り返される場合、ドライバーは キーワードの最初の出現に関連付けられた値を使用します。 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" になります)。

Note

.dsn ファイルは、インストーラー DLL で SQLReadFileDSN 関数と SQLWriteFileDSN 関数を呼び出すことによって直接操作できます。

SAVEFILE キーワードを使用すると、現在の正常な接続を行うために使用されるキーワードの属性値は、SAVEFILE キーワードの属性値の名前を持つ .dsn ファイルとして保存されます。 SAVEFILE キーワードは、DRIVER キーワード、FILEDSN キーワード、またはその両方と組み合わせて使用する必要があります。または、関数は SQLSTATE 01S09 (Invalid キーワード) でSQL_SUCCESS_WITH_INFOを返します。 SAVEFILE キーワードは、接続文字列の DRIVER キーワードの前に指定する必要があります。または、結果は未定義になります。

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

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

ドライバー マネージャーのアクションは、 DriverCompletion 引数の値に基づいています。

  • SQL_DRIVER_PROMPT: 接続文字列に DRIVERDSN、または 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: ドライバーは、接続文字列とシステム情報 (存在する場合) の値を初期値として使用して、ダイアログ ボックスを表示します。 ユーザーがダイアログ ボックスを終了すると、ドライバーはデータ ソースに接続します。 また、*InConnectionStringDSN または 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 引数でのみ呼び出すことができます。他の DriverCompletionSQLDriverConnect が呼び出された場合は、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 プログラム」も参照してください。

対象 解決方法については、
ハンドルの割り当て SQLAllocHandle 関数
データ ソースへの接続に必要な値の検出と列挙 SQLBrowseConnect 関数
データ ソースに接続する SQLConnect 関数
データ ソースからの切断 SQLDisconnect 関数
ドライバーの説明と属性を返す SQLDrivers 関数
ハンドルの解放 SQLFreeHandle 関数
接続属性の設定 SQLSetConnectAttr 関数

参照

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