SQLConnect 関数
準拠
導入されたバージョン: ODBC 1.0 Standards Compliance: ISO 92
まとめ
SQLConnect は、ドライバーとデータ ソースへの接続を確立します。 接続ハンドルは、データ ソースへの接続に関するすべての情報 (状態、トランザクションの状態、エラー情報など) のストレージを参照します。
構文
SQLRETURN SQLConnect(
SQLHDBC ConnectionHandle,
SQLCHAR * ServerName,
SQLSMALLINT NameLength1,
SQLCHAR * UserName,
SQLSMALLINT NameLength2,
SQLCHAR * Authentication,
SQLSMALLINT NameLength3);
引数
ConnectionHandle
[入力] 接続ハンドル。
ServerName
[入力]データ ソース名。 データは、プログラムと同じコンピューター、またはネットワーク上の別のコンピューターに配置されている可能性があります。 アプリケーションでデータ ソースを選択する方法の詳細については、「 データ ソースまたはドライバーの選択」を参照してください。
NameLength1
[入力]文字単位の *ServerName の長さ。
UserName
[入力]ユーザー識別子。
NameLength2
[入力]文字単位の *UserName の長さ。
認証
[入力]認証文字列 (通常はパスワード)。
NameLength3
[入力]文字単位の *認証 の長さ。
戻り値
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_STILL_EXECUTING。
診断
SQLConnect がSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返す場合、関連付けられている SQLSTATE 値を取得するには、SQL_HANDLE_DBCの HandleType と ConnectionHandle のハンドルを指定して SQLGetDiagRec を呼び出します。 次の表に、SQLConnect によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。
| SQLSTATE | エラー | 説明 |
|---|---|---|
| 01000 | 一般的な警告 | ドライバー固有の情報メッセージ。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 01S02 | オプション値の変更 | ドライバーは、SQLSetConnectAttr の ValuePtr 引数の指定された値をサポートしておらず、同様の値を置き換えました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| 08001 | クライアントが接続を確立できない | ドライバーがデータ ソースとの接続を確立できませんでした。 |
| 08002 | 使用中の接続名 | (DM) 指定された ConnectionHandle は、データ ソースとの接続を確立するために既に使用されており、接続がまだ開いているか、ユーザーが接続を参照していました。 |
| 08004 | サーバーが接続を拒否しました | データ ソースは、実装で定義された理由により、接続の確立を拒否しました。 |
| 08S01 | 通信リンクエラー | ドライバーと、ドライバーが接続しようとしていたデータ ソースの間の通信リンクは、関数の処理が完了する前に失敗しました。 |
| 28000 | 承認指定が無効です | 引数 UserName に指定された値、または引数 Authentication に指定された値が、データ ソースによって定義された制限に違反しました。 |
| HY000 | 一般的なエラー | 特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 *MessageText バッファー内の SQLGetDiagRec によって返されるエラー メッセージは、エラーとその原因を説明します。 |
| HY001 | メモリ割り当てエラー | (DM) ドライバー マネージャーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。 |
| HY008 | 操作が取り消されました | ConnectionHandle に対して非同期処理が有効にされました。 SQLConnect 関数が呼び出され、実行が完了する前に、ConnectionHandle で SQLCancelHandle 関数が呼び出され、ConnectionHandle で SQLConnect 関数が再度呼び出されました。 または、SQLConnect 関数が呼び出され、実行が完了する前に、マルチスレッド アプリケーションの別のスレッドから ConnectionHandle で SQLCancelHandle が呼び出されました。 |
| HY010 | 関数シーケンス エラー | (DM) 非同期実行関数 (この関数ではなく) が ConnectionHandle に対して呼び出され、この関数が呼び出されたときにはまだ実行されていました。 |
| HY013 | メモリ管理エラー | メモリ不足の可能性があるため、基になるメモリ オブジェクトにアクセスできなかったため、関数呼び出しを処理できませんでした。 |
| HY090 | 文字列またはバッファーの長さが無効です | (DM) 引数 NameLength1、NameLength2、または NameLength3 に指定された値が 0 未満でしたが、SQL_NTSと等しくありません。 (DM) 引数 NameLength1 に指定された値が、データ ソース名の最大長を超えました。 |
| HYT00 | タイムアウトに達しました | データ ソースへの接続が完了する前に、クエリのタイムアウト期間が期限切れになりました。 タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_LOGIN_TIMEOUT) によって設定されます。 |
| HY114 | ドライバーは、接続レベルの非同期関数の実行をサポートしていません | (DM) アプリケーションは、接続を行う前に、接続ハンドルで非同期操作を有効にしました。 ただし、ドライバーは接続ハンドルに対する非同期操作をサポートしていません。 |
| HYT01 | 接続のタイムアウト | データ ソースが要求に応答する前に、接続タイムアウト期間の有効期限が切れています。 接続タイムアウト期間は、 SQLSetConnectAttr (SQL_ATTR_CONNECTION_TIMEOUT) によって設定されます。 |
| IM001 | ドライバーは、この関数をサポートしていません | (DM) データ ソース名で指定されたドライバーは、 関数をサポートしていません。 |
| IM002 | データ ソースが見つからず、既定のドライバーが指定されていません | (DM) 引数 ServerName で指定されたデータ ソース名がシステム情報に見つかりませんでした。また、既定のドライバー仕様も存在しません。 |
| IM003 | 指定されたドライバーに接続できませんでした | (DM) システム情報のデータ ソース仕様に記載されているドライバーが見つからないか、何らかの理由で に接続できませんでした。 |
| IM004 | SQL_HANDLE_ENVのドライバーの SQLAllocHandle が失敗しました | (DM) SQLConnect 中に、ドライバー マネージャーは、HandleType が SQL_HANDLE_ENV のドライバーの SQLAllocHandle 関数を呼び出し、ドライバーからエラーが返されました。 |
| IM005 | SQL_HANDLE_DBCのドライバーの SQLAllocHandle が失敗しました | (DM) SQLConnect 中、ドライバー マネージャーは、HandleType が SQL_HANDLE_DBC のドライバーの SQLAllocHandle 関数を呼び出し、ドライバーからエラーが返されました。 |
| IM006 | ドライバーの SQLSetConnectAttr が失敗しました | SQLConnect 中、ドライバー マネージャーはドライバーの SQLSetConnectAttr 関数を呼び出し、ドライバーからエラーが返されました。 (関数はSQL_SUCCESS_WITH_INFOを返します。 |
| IM009 | 翻訳 DLL に接続できません | ドライバーは、データ ソースに指定された変換 DLL に接続できませんでした。 |
| IM010 | データ ソース名が長すぎます | (DM) *ServerName がSQL_MAX_DSN_LENGTH文字より長かった。 |
| IM014 | 指定された DSN には、ドライバーとアプリケーションの間のアーキテクチャの不一致が含まれています | (DM) 32 ビット アプリケーションは、64 ビット ドライバーに接続する DSN を使用します。またはその逆。 |
| IM015 | SQL_HANDLE_DBC_INFO_HANDLEのドライバーの SQLConnect が失敗しました | ドライバーが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を設定できません。 |
説明
アプリケーションで SQLConnect を使用する理由については、「 SQLConnectを使用した接続」を参照してください。
ドライバー マネージャーは、アプリケーションがドライバーに接続するための関数 (SQLConnect、 SQLDriverConnect、または SQLBrowseConnect) を呼び出すまで、ドライバーに接続しません。 その時点まで、ドライバー マネージャーは独自のハンドルで動作し、接続情報を管理します。 アプリケーションが接続関数を呼び出すと、ドライバー マネージャーは、指定された ConnectionHandle に対してドライバーが現在接続されているかどうかを確認します。
ドライバーが接続されていない場合、ドライバー マネージャーはドライバーに接続し、HandleType が SQL_HANDLE_ENV の SQLAllocHandle、HandleType が SQL_HANDLE_DBC の SQLAllocHandle、SQLSetConnectAttr (アプリケーションで接続属性が指定されている場合)、およびドライバーの接続関数を呼び出します。 ドライバー マネージャーは、SQLSTATE IM006 (ドライバーの SQLSetConnectOption が失敗しました) を返し、ドライバーが SQLSetConnectAttr のエラーを返した場合に接続関数のSQL_SUCCESS_WITH_INFOします。 詳細については、「 データ ソースまたはドライバーへの接続」を参照してください。
指定したドライバーが ConnectionHandle で既に に接続されている場合、ドライバー マネージャーはドライバー内の接続関数のみを呼び出します。 この場合、ドライバーは ConnectionHandle のすべての接続属性が現在の設定を維持していることを確認する必要があります。
別のドライバーが接続されている場合、ドライバー マネージャーは、SQL_HANDLE_DBC の HandleType を使用して SQLFreeHandle を呼び出し、その環境内に他のドライバーが接続されていない場合は、接続されているドライバーで HandleType のSQL_HANDLE_ENVを使用して SQLFreeHandle を呼び出し、そのドライバーを切断します。 次に、ドライバーが接続されていない場合と同じ操作を実行します。
その後、ドライバーはハンドルを割り当て、それ自体を初期化します。
アプリケーションが SQLDisconnect を呼び出すと、ドライバー マネージャーはドライバーで SQLDisconnect を呼び出します。 ただし、ドライバーは切断されません。 これにより、データ ソースとの接続と切断を繰り返し行うアプリケーションのドライバーがメモリ内に保持されます。 アプリケーションで HandleType が SQL_HANDLE_DBC の SQLFreeHandle を呼び出すと、ドライバー マネージャーは HandleType が SQL_HANDLE_DBC の SQLFreeHandle を呼び出し、次にドライバーで HandleType が SQL_HANDLE_ENV の SQLFreeHandle を呼び出し、ドライバーを切断します。
ODBC アプリケーションは、複数の接続を確立できます。
ドライバー マネージャーのガイドライン
*ServerName の内容は、ドライバー マネージャーとドライバーが連携してデータ ソースへの接続を確立する方法に影響します。
*ServerName に 有効なデータ ソース名が含まれている場合、ドライバー マネージャーはシステム情報で対応するデータ ソース仕様を検索し、関連付けられているドライバーに接続します。 ドライバー マネージャーは、各 SQLConnect 引数をドライバーに渡します。
データ ソース名が見つからない場合、または ServerName が null ポインターである場合、ドライバー マネージャーは既定のデータ ソース仕様を検索し、関連付けられているドライバーに接続します。 ドライバー マネージャーは、 変更されていない UserName 引数と 認証 引数をドライバーに渡し、 ServerName 引数の "DEFAULT" を渡します。
ServerName 引数が "DEFAULT" の場合、ドライバー マネージャーは既定のデータ ソース仕様を検索し、関連付けられているドライバーに接続します。 ドライバー マネージャーは、各 SQLConnect 引数をドライバーに渡します。
データ ソース名が見つからないか 、ServerName が null ポインターで、既定のデータ ソース指定が存在しない場合、ドライバー マネージャーは SQLSTATE IM002 でSQL_ERRORを返します (データ ソース名が見つからず、既定のドライバーが指定されていません)。
ドライバー マネージャーによってに接続された後、ドライバーは、システム情報で対応するデータ ソースの仕様を検索し、仕様のドライバー固有の情報を使用して、必要な接続情報のセットを完了できます。
データ ソースのシステム情報に既定の翻訳ライブラリが指定されている場合、ドライバーはそれに接続します。 SQL_ATTR_TRANSLATE_LIB属性を使用して SQLSetConnectAttr を呼び出すことで、別の翻訳ライブラリに接続できます。 変換オプションは、SQL_ATTR_TRANSLATE_OPTION属性を使用して SQLSetConnectAttr を呼び出すことによって指定できます。
ドライバーが SQLConnect をサポートしている場合、ドライバーのシステム情報のドライバー キーワード セクションには、最初の文字が "Y" に設定された ConnectFunctions キーワードが含まれている必要があります。
接続のプール
接続プールを使用すると、アプリケーションは既に作成されている接続を再利用できます。 接続プールが有効で SQLConnect が呼び出されると、ドライバー マネージャーは、接続プール用に指定された環境の接続プールの一部である接続を使用して接続を確立しようとします。 この環境は、プール内の接続を使用するすべてのアプリケーションによって使用される共有環境です。
SQLSetEnvAttr を呼び出してSQL_ATTR_CONNECTION_POOLINGを SQL_CP_ONE_PER_DRIVER (ドライバーごとに最大 1 つのプールを指定) またはSQL_CP_ONE_PER_HENV (環境ごとに最大 1 つのプールを指定) に設定することで、環境が割り当てられる前に接続プールが有効になります。 この場合、SQLSetEnvAttr は EnvironmentHandle を null に設定して呼び出され、属性はプロセス レベルの属性になります。 SQL_ATTR_CONNECTION_POOLINGが SQL_CP_OFF に設定されている場合、接続プールは無効になります。
接続プールが有効になった後、HandleType が SQL_HANDLE_ENV の SQLAllocHandle が呼び出され、環境が割り当てられます。 接続プールが有効になっているため、この呼び出しによって割り当てられる環境は共有環境です。 ただし、HandleType が SQL_HANDLE_DBC の SQLAllocHandle が呼び出されるまで、使用される環境は決定されません。
HandleType が SQL_HANDLE_DBC の SQLAllocHandle は、接続を割り当てるために呼び出されます。 ドライバー マネージャーは、アプリケーションによって設定された環境属性と一致する既存の共有環境を検索しようとします。 そのような環境が存在しない場合は、暗黙的な 共有環境として作成されます。 一致する共有環境が見つかった場合は、環境ハンドルがアプリケーションに返され、その参照カウントがインクリメントされます。
ただし、使用される接続は、 SQLConnect が呼び出されるまで決定されません。 その時点で、ドライバー マネージャーは、アプリケーションによって要求された条件に一致する接続プール内の既存の接続を検索しようとします。 これらの条件には、SQLConnect の呼び出しで要求された接続オプション (ServerName、UserName、Authentication キーワードの値) と、HandleType が SQL_HANDLE_DBC の SQLAllocHandle 以降に設定された接続属性が含まれます。 ドライバー マネージャーは、プール内の接続内の対応する接続キーワードと属性に対してこれらの条件をチェックします。 一致するものが見つかった場合は、プール内の接続が使用されます。 一致するものが見つからない場合は、新しい接続が作成されます。
SQL_ATTR_CP_MATCH環境属性が SQL_CP_STRICT_MATCH に設定されている場合、プール内の接続を使用するには、一致が完全に一致している必要があります。 SQL_ATTR_CP_MATCH環境属性が SQL_CP_RELAXED_MATCH に設定されている場合、 SQLConnect の呼び出しの接続オプションは一致する必要がありますが、すべての接続属性が一致する必要はありません。
次の規則は、 SQLConnect が呼び出される前にアプリケーションによって設定された接続属性が、プール内の接続の接続属性と一致しない場合に適用されます。
接続を行う前に接続属性を設定する必要がある場合は、次のようにします。
SQL_ATTR_CP_MATCHがSQL_CP_STRICT_MATCH場合、プールされた接続のSQL_ATTR_PACKET_SIZEは、アプリケーションによって設定された属性と同じである必要があります。 SQL_CP_RELAXED_MATCH場合、SQL_ATTR_PACKET_SIZEの値は異なる場合があります。
SQL_ATTR_LOGIN_VALUEの値は一致には影響しません。
接続の前または後に接続属性を設定できる場合は、次のようにします。
接続属性がアプリケーションによって設定されていないが、プール内の接続に対して設定されていて、既定値がある場合、プールされた接続の接続属性は既定値に戻され、一致が宣言されます。 既定値がない場合、プールされた接続は一致とは見なされません。
接続属性がアプリケーションによって設定されていても、プール内の接続で設定されていない場合、プールの接続属性はアプリケーションによって設定された接続属性に変更され、一致が宣言されます。
接続属性がアプリケーションによって設定され、プール内の接続でも設定されているが、値が異なる場合は、アプリケーションの接続属性の値が使用され、一致が宣言されます。
ドライバー固有の接続属性の値が同一ではなく、SQL_ATTR_CP_MATCHがSQL_CP_STRICT_MATCHに設定されている場合、プール内の接続は使用されません。
アプリケーションが SQLDisconnect を呼び出して切断すると、接続は接続プールに返され、再利用できます。
接続プールのパフォーマンスの最適化
分散トランザクションが関係する場合は、SQLUINTEGER ビットマスクである SQL_DTC_TRANSITION_COSTを使用して、接続プールのパフォーマンスを最適化できます。 参照される遷移は、接続属性の遷移SQL_ATTR_ENLIST_IN_DTC値 0 から 0 以外への遷移であり、その逆も同様です。 これは、分散トランザクションに参加していないから分散トランザクションに参加する接続、またはその逆の接続です。 ドライバーが参加リストを実装した方法 (接続属性SQL_ATTR_ENLIST_IN_DTCの設定) によっては、これらの切り替えがコストがかかる可能性があるため、最適なパフォーマンスを得るには避ける必要があります。
ドライバーによって返される値には、次のビットの任意の組み合わせが含まれています。
SQL_DTC_ENLIST_EXPENSIVE、設定すると、0 から 0 以外への遷移は、0 以外から別の 0 以外の値への遷移 (以前に参加していた接続を次のトランザクションに参加させる) よりも大幅にコストが高くなります。
SQL_DTC_UNENLIST_EXPENSIVE、設定すると、0 から 0 への遷移は、SQL_ATTR_ENLIST_IN_DTC属性が既に 0 に設定されている接続を使用する場合よりも大幅にコストが高くなります。
パフォーマンスと接続の使用量のトレードオフがあります。 ドライバーは、これらの遷移の 1 つ以上が高価であることを示す場合、ドライバー マネージャーの接続プーラーは、プール内のより多くの接続を維持することによって、これに応答します。 プール内の一部の接続は、トランザクション以外の使用に適しており、トランザクションの使用に適した接続もあります。 ただし、ドライバーがこれらの遷移が高価ではないことを示す場合は、使用できる接続の数が少なくなり、トランザクション以外の使用とトランザクションの使用が交互になる可能性があります。
SQL_ATTR_ENLIST_IN_DTCをサポートしていないドライバーは、SQL_DTC_TRANSITION_COSTをサポートする必要はありません。 SQL_ATTR_ENLIST_IN_DTCをサポートしているが、SQL_DTC_TRANSITION_COSTをサポートしていないドライバーの場合は、ドライバーがこの値に対して 0 (ビットセットなし) を返したかのように、移行は高価でないと見なされます。
SQL_DTC_TRANSITION_COST ODBC 3.5 (ODBC 2) で導入されました。ドライバー マネージャーはドライバーのバージョンに関係なくこの情報を照会するため、x ドライバーもサポートできます。
コード例
次の例では、アプリケーションによって環境ハンドルと接続ハンドルが割り当てられます。 次に、ユーザー ID JohnS とパスワードゴマを使用して SalesOrders データ ソースに接続し、データを処理します。 データの処理が完了すると、データ ソースから切断され、ハンドルが解放されます。
// SQLConnect_ref.cpp
// compile with: odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);
SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);
// 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, (void*)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);
// Connect to data source
retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
// 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);
}
}
関連する関数
| 対象 | 解決方法については、 |
|---|---|
| ハンドルの割り当て | SQLAllocHandle 関数 |
| データ ソースへの接続に必要な値の検出と列挙 | SQLBrowseConnect 関数 |
| データ ソースからの切断 | SQLDisconnect 関数 |
| 接続文字列またはダイアログ ボックスを使用したデータ ソースへの接続 | SQLDriverConnect 関数 |
| 接続属性の設定を返す | SQLGetConnectAttr 関数 |
| 接続属性の設定 | SQLSetConnectAttr 関数 |