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されます。

説明

アプリケーションで 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);  
   }  
}  

関連する関数

参照

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