SQLConnect 関数

適合 性
導入されたバージョン: ODBC 1.0 標準コンプライアンス: ISO 92

まとめ
SQLConnect はドライバーとデータソースへの接続を確立します。 接続ハンドルは、接続に関するすべての情報の保存を参照します。これにはステータス、トランザクション状態、エラー情報が含まれます。

Syntax

  
SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);  

引数

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

ServerName
[入力]データソース名。 データは、プログラムと同じコンピューターにあったり、ネットワーク上のどこか別のコンピューターにあったりします。 アプリケーションがどのようにデータソースを選択するかについては、「 データソースまたはドライバーの選択」を参照してください。

NameLength1
[入力]*ServerName の文字数。

UserName
[入力]ユーザー識別子。

NameLength2
[入力]*ユーザー名 (文字数)の長さ。

Authentication
[入力]認証文字列(通常はパスワード)。

NameLength3
[入力]*文字数での認証 時間。

返品

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_INVALID_HANDLE、またはSQL_STILL_EXECUTING。

Diagnostics

SQLConnectがSQL_ERRORまたはSQL_SUCCESS_WITH_INFOを返すと、SQLGetDiagRecを呼び出し、HandleTypeをSQL_HANDLE_DBC、HandleをConnectionHandleで呼び出すことで関連するSQLSTATE値を取得できます。 以下の表は 、通常SQLConnectが返すSQLSTATE 値を一覧にし、この関数の文脈でそれぞれを説明します。「(DM)」という表記は、ドライバーマネージャーが返すSQLstateの記述の前に記載されます。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERROR。

Comments

アプリケーションがなぜ SQLConnectを使用するのかについては、「 SQLConnectとの接続」をご覧ください。

ドライバーマネージャーは、アプリケーションが関数(SQLConnect、 SQLDriverConnect、 またはSQLBrowseConnect)を呼び出してドライバーに接続するまで、ドライバーに接続しません。 それまでは、ドライバーマネージャーは独自のハンドルを操作し、接続情報を管理します。 アプリケーションが接続関数を呼び出すと、ドライバーマネージャーは指定された ConnectionHandleに対して現在ドライバが接続されているかどうかを確認します。

• ドライバが接続されていない場合、ドライバマネージャーはそのドライバに接続し、HandleTypeをSQL_HANDLE_ENV、SQLAllocHandleをSQL_HANDLE_DBCのHandleTypeで、SQLSetConnectAttr(アプリケーションが接続属性を指定した場合)、およびドライバ内の接続関数を呼び出します。 ドライバーマネージャーはSQLSTATE IM006(ドライバーの SQLSetConnectOption 失敗)を返し、 SQLSetConnectAttrのエラーを返した場合、接続関数としてSQL_SUCCESS_WITH_INFOを表示します。 詳細については、「 データソースまたはドライバーへの接続」をご覧ください。

• 指定されたドライバがすでに ConnectionHandleに接続されている場合、ドライバマネージャーはドライバ内の接続関数のみを呼び出します。 この場合、ドライバーは ConnectionHandle のすべての接続属性が現在の設定を維持していることを確認する必要があります。

• もし別のドライバーが接続されている場合、ドライバーマネージャーはHandle SQL_HANDLE_DBC Typeの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とAuthenticationの引数を変更せずにドライバに渡し、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ドライバーあたり最大1つのプールを指定する)またはSQL_CP_ONE_PER_HENV(環境あたり最大1つのプールを指定する)に設定することで、接続プーリングが有効化されます。 この場合、SQLSetEnvAttrはEnvironmentHandleをnullに設定した状態で呼び出され、この属性はプロセスレベルの属性となります。 SQL_ATTR_CONNECTION_POOLINGがSQL_CP_OFFに設定されている場合、接続プーリングは無効になります。

接続プーリングが有効化された後、HandleTypeのSQLAllocHandleがSQL_HANDLE_ENVを割り当てるために呼び出されます。 この呼び出しによって割り当てられた環境は、接続プーリングが有効化されたため共有環境です。 しかし、使用される環境は、HandleTypeがSQL_HANDLE_DBCのSQLAllocHandleを呼び出しるまで決定されません。

SQLAllocHandle は HandleTypeのHandle SQL_HANDLE_DBCを割り当てるために呼び出されます。 ドライバーマネージャーは、アプリケーションが設定した環境属性に一致する既存の共有環境を探そうとします。 そのような環境が存在しない場合は、暗黙の 共有環境として作成されます。 一致する共有環境が見つかれば、環境ハンドルがアプリケーションに返され、その参照数が増加します。

しかし、使用する接続は 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 を呼び出して切断すると、接続は接続プールに戻り、再利用可能になります。

接続プーリング性能の最適化

分散トランザクションが関与する場合、 SQL_DTC_TRANSITION_COST(SQLUINTEGER bitmask)を使用することで接続プーリング性能を最適化することが可能です。 ここで言及されている遷移は、接続属性SQL_ATTR_ENLIST_IN_DTC値0から0から0でない値へ、またはその逆に移行する遷移です。 これは、分散トランザクションに登録されていない状態から分散トランザクションに登録された状態、またはその逆に移行する接続を指します。 ドライバーがエンリストメントをどのように実装しているか(接続属性SQL_ATTR_ENLIST_IN_DTCの設定)によっては、これらの遷移はコストがかかる場合があり、最良のパフォーマンスを得るためには避けるべきです。

ドライバーが返す値は、以下のビットのいずれかの組み合わせを含みます。

• SQL_DTC_ENLIST_EXPENSIVEが設定されると、ゼロからゼロでない遷移への遷移は、ゼロでない値から別のゼロでない値への遷移(以前に登録された接続を次のトランザクションに巻き込む)よりもかなりコストがかかることを意味します。

• SQL_DTC_UNENLIST_EXPENSIVEが設定されると、ゼロでない移行は、SQL_ATTR_ENLIST_IN_DTC属性がすでにゼロに設定されている接続を使うよりもかなりコストがかかることを意味します。

パフォーマンスと接続使用量のトレードオフがあります。 ドライバーがこれらの遷移のうち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 ドライバーも対応可能です。なぜなら、ドライバーマネージャーがこの情報をドライバのバージョンに関係なく問い合わせるからです。

コード例

以下の例では、アプリケーションが環境と接続ハンドルを割り当てます。 その後、ユーザーIDJohnSとパスワードSesameで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 ヘッダー ファイル