SQLDriverConnect 関数

[アーティクル]
05/23/2023

準拠
導入されたバージョン: 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されます。

SQLSTATE	エラー	説明
01000	一般的な警告	ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01004	文字列データ、右切り捨て	バッファー *OutConnectionString が接続文字列全体を返すには十分な大きさではないので、接続文字列が切り捨てられました。 *StringLength2Ptr では、文字列の長さが返されます。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S00	接続文字列属性が無効です	接続文字列 (InConnectionString) に無効な属性キーワードが指定されましたが、ドライバーはとにかくデータソースに接続できました。 (関数はSQL_SUCCESS_WITH_INFOを返します。
01S02	オプション値が変更されました	ドライバーは、SQLSetConnectAttr の ValuePtr 引数によって指される指定された値をサポートしておらず、同様の値を置き換えました。 (関数は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 関数が呼び出され、ConnectionHandle で SQLDriverConnect 関数が再度呼び出されました。または、SQLDriverConnect 関数が呼び出され、実行が完了する前に、マルチスレッドアプリケーションの別のスレッドから ConnectionHandle で SQLCancelHandle が呼び出されました。
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 キーワードはシステム情報の情報を使用しないため、ドライバーは、接続文字列内の情報のみを使用してデータソースに接続できるように、十分なキーワードを定義する必要があります。 (詳細については、このセクションで後述する「ドライバーのガイドライン」を参照してください)。ドライバーは、データソースに接続するために必要なキーワードを定義します。

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

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: 接続文字列に DRIVER、 DSN、または FILEDSN キーワードが含まれていない場合、ドライバーマネージャーに [データソース] ダイアログボックスが表示されます。ダイアログボックスによって返されるデータソース名と、アプリケーションによって渡されるその他のキーワードから接続文字列を構築します。ダイアログボックスによって返されるデータソース名が空の場合、ドライバーマネージャーはキーワードと値のペア DSN=Default を指定します。 (このダイアログボックスには、"Default" という名前のデータソースは表示されません)。
SQL_DRIVER_COMPLETEまたはSQL_DRIVER_COMPLETE_REQUIRED: アプリケーションで指定された接続文字列に DSN キーワードが含まれている場合、ドライバーマネージャーはアプリケーションで指定された接続文字列をコピーします。それ以外の場合は、 DriverCompletion がSQL_DRIVER_PROMPTされている場合と同じアクションが実行されます。
SQL_DRIVER_NOPROMPT: ドライバーマネージャーは、アプリケーションで指定された接続文字列をコピーします。

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

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

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

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

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

.dsn ファイルのファイル名が有効かどうかを確認します。そうでない場合は、SQLSTATE IM014 でSQL_ERRORを返します (ファイル DSN の名前が無効です)。ファイル名が空の文字列 ("") で、SQL_DRIVER_NOPROMPTが指定されていない場合は、[ ファイルを開く ] ダイアログボックスが表示されます。ファイル名に有効なパスが含まれていますが、ファイル名または無効なファイル名が指定されておらず、SQL_DRIVER_NOPROMPTが指定されていない場合は、[ ファイルを開く ] ダイアログボックスが表示され、現在のディレクトリはファイル名で指定されたディレクトリに設定されます。ファイル名が空の文字列 ("") であるか、ファイル名に有効なパスが含まれていますが、ファイル名または無効なファイル名が指定されておらず、SQL_DRIVER_NOPROMPTが指定されている場合、SQL_ERRORは SQLSTATE IM014 (ファイル DSN の無効な名前) で返されます。
.dsn ファイルの [ODBC] セクションのすべてのキーワードを読み取ります。 DRIVER キーワードが存在しない場合は、SQLSTATE IM012 (Driver キーワード構文エラー) でSQL_ERRORが返されます。ただし、.dsn ファイルは共有できないため、DSN キーワードのみが含まれます。

ファイルデータソースが共有できない場合、ドライバーマネージャーは DSN キーワードの値を読み取り、必要に応じて、共有不可能なファイルデータソースが指すユーザーまたはシステムデータソースに接続します。手順 3 から 5 は実行されません。
ドライバーの接続文字列を構築します。ドライバー接続文字列は、.dsn ファイルで指定されたキーワードと、元のアプリケーション接続文字列で指定されたキーワードの和集合です。キーワードが重複するドライバー接続文字列の構築に関する規則は次のとおりです。
- DRIVER キーワードがアプリケーション接続文字列に存在し、DRIVER キーワードで指定されたドライバーが .dsn ファイルとアプリケーション接続文字列で同じでない場合、.dsn ファイル内のドライバー情報は無視され、アプリケーション接続文字列内のドライバー情報が使用されます。 DRIVER キーワードで指定されたドライバーが .dsn ファイルとアプリケーションの接続文字列で同じである場合、すべてのキーワードが重複している場合、アプリケーション接続文字列で指定されたドライバーは、.dsn ファイルで指定されたものよりも優先されます。
- 新しい接続文字列では、 FILEDSN キーワードは削除されます。
Driver キーワードでドライバー名>が指定されているレジストリエントリHKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>\Driver <を調べることでドライバーを読み込みます。
ドライバーに新しい接続文字列を渡します。

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

SAVEFILE キーワード

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

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の場合、ファイルを上書きするかどうかを指定するダイアログボックスが表示されます。 [いいえ] を入力すると、[ ファイルの保存 ] ダイアログボックスが表示されます。
ドライバーがSQL_SUCCESSを返し、ファイル名が空の文字列でない場合、ドライバーマネージャーは、 OutConnectionString 引数で返された接続情報を、このセクションの前の「接続文字列」セクションで指定した形式で指定されたファイルに書き込みます。
ドライバーがSQL_SUCCESSを返し、ファイル名が空の文字列 ("") の場合、ドライバーマネージャーは hwnd を指定して [ファイルの保存] 共通ダイアログボックスを呼び出し、OutConnectionString で返された接続情報を、このセクションの前の「接続文字列」セクションで指定した形式でFile-Save共通ダイアログボックスで指定したファイルに書き込みます。
ドライバーがSQL_SUCCESSを返す場合は、接続文字列を含む OutConnectionString 引数をアプリケーションに返します。
ドライバーがSQL_SUCCESS_WITH_INFOまたはSQL_ERRORを返す場合、ドライバーマネージャーは SQLSTATE をアプリケーションに返します。

ドライバーのガイドライン

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

接続文字列に DSN キーワードが含まれている場合、ドライバーは指定されたデータソースの情報を取得します。
接続文字列に 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 プログラム」も参照してください。

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

参照

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

SQLDriverConnect 関数

構文

引数

戻り値

診断

説明

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

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

SAVEFILE キーワード

ドライバーのガイドライン

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

接続属性

参照

フィードバック

フィードバック

その他のリソース

SQLDriverConnect 関数

構文

引数

戻り値

診断

説明

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

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

SAVEFILE キーワード

ドライバーのガイドライン

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

接続属性

関連する関数

参照

フィードバック

フィードバック

その他のリソース

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

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