SQLConnect İşlevi

Uygunluk
Kullanıma Sunulan Sürüm: ODBC 1.0 Standartları Uyumluluğu: ISO 92

Özet
SQLConnect, bir sürücü ve veri kaynağına bağlantılar kurar. Bağlantı tutumu, veri kaynağına bağlantı hakkındaki tüm bilgilerin, durum, işlem durumu ve hata bilgileri dahil olmak üzere depolanmasını referans verir.

Syntax

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

Arguments

ConnectionHandle
[Giriş] Bağlantı tutamacı.

SunucuAdı
[Giriş] Veri kaynağı adı. Veriler programla aynı bilgisayarda veya ağdaki başka bir bilgisayarda bulunabilir. Bir uygulamanın veri kaynağını nasıl seçtiğine dair bilgi için Veri Kaynağı veya Sürücü Seçme bölümüne bakınız.

NameLength1
[Giriş] *Sunucu Adı karakter cinsinden.

UserName
[Giriş] Kullanıcı tanımlayıcısı.

NameLength2
[Giriş] *UserName karakter boyunca.

Authentication
[Giriş] Kimlik doğrulama dizisi (genellikle şifre).

NameLength3
[Giriş] *Kimlik doğrulama süresi karakter cinsinden.

İadeler

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ya da SQL_STILL_EXECUTING.

Diagnostics

SQLConnect SQL_ERROR veya SQL_SUCCESS_WITH_INFO döndürdüğünde, ilişkili bir SQLSTATE değeri, SQL_HANDLE_DBC HandleType ve ConnectionHandle ile SQLGetDiagRec çağrılarak elde edilebilir. Aşağıdaki tablo, genellikle SQLConnect tarafından duygulanan SQLSTATE değerlerini listeler ve her birini bu fonksiyonun bağlamında açıklar; "(DM)" gösterimi, Sürücü Yöneticisi tarafından döndürülen SQLSTATE açıklamalarından önce gelir. Aksi belirtilmediği sürece, her SQLSTATE değeriyle ilişkili dönüş kodu SQL_ERROR.

Comments

Bir uygulamanın neden SQLConnect kullandığına dair bilgi için bkz. SQLConnect ile bağlantı kurmak.

Sürücü Yöneticisi, uygulama bir fonksiyonu (SQLConnect, SQLDriverConnect veya SQLBrowseConnect) çağırana kadar bir sürücüye bağlanmaz. O ana kadar Sürücü Yöneticisi kendi kullanıcı adlarıyla çalışır ve bağlantı bilgilerini yönetir. Uygulama bir bağlantı fonksiyonu çağırdığında, Sürücü Yöneticisi belirtilen ConnectionHandle için şu anda bir sürücüye bağlı olup olmadığını kontrol eder:

• Bir sürücüye bağlı değilse, Driver Manager sürücüye bağlanır ve SQL_HANDLE_ENV HandleType ile SQLAllocHandle, SQL_HANDLE_DBC HandleTypeile SQLAllocHandle, SQL ConnectAttr (uygulama herhangi bir bağlantı özelliği belirttiyse) ve sürücüdeki bağlantı fonksiyonu ile çağrılır. Sürücü Yöneticisi, SQLSTATE IM006 (Sürücünün SQLSetConnectOption başarısız oldu) ve sürücü SQLSetConnectAttr için hata dönerse bağlantı fonksiyonu için SQL_SUCCESS_WITH_INFO döndürür. Daha fazla bilgi için Veri Kaynağı veya Sürücüye Bağlanma bölümüne bakınız.

• Belirtilen sürücü zaten ConnectionHandle'da bağlıysa, Driver Manager sadece sürücüdeki bağlantı fonksiyonunu çağırır. Bu durumda, sürücü ConnectionHandle için tüm bağlantı özelliklerinin güncel ayarlarını korumasından emin olmalıdır.

• Farklı bir sürücüye bağlıysa, Driver Manager SQLFreeHandle'ı SQL_HANDLE_DBC HandleType ile çağırır ve o ortamda başka bir sürücüye bağlı değilse, bağlı sürücüde SQL_HANDLE_ENV HandleTypeile SQLFreeHandle çağırır ve ardından o sürücüyü keser. Daha sonra bir sürücü bağlı olmadığında uygulanan işlemleri gerçekleştirir.

Sürücü daha sonra tutamaçları ayırır ve kendini başlatır.

Uygulama SQLDisconnect'i çağırdığında, Driver Manager sürücüde SQLDisconnect'i çağırır. Ancak, sürücünün bağlantısını kesmez. Bu, bir veri kaynağına tekrar tekrar bağlanan ve bağlantıyı kesen uygulamalar için sürücüyü bellekte tutar. Uygulama SQL_HANDLE_DBC HandleTypeile SQLFreeHandle çağırdığında, Driver Manager SQL_HANDLE_DBC HandleTypeile SQLFreeHandle çağırır ve ardından sürücüde SQL_HANDLE_ENV HandleTypeile SQLFreeHandle çağırır ve sürücüyü kopar.

Bir ODBC uygulaması birden fazla bağlantı kurabilir.

Sürücü Yöneticisi Yönergeleri

*ServerName içeriği, Sürücü Yöneticisi ve sürücünün bir veri kaynağına bağlantı kurmak için birlikte çalışma biçimini etkiler.

• *ServerName geçerli bir veri kaynağı adı içeriyorsa, Sürücü Yöneticisi ilgili veri kaynağı spesifikasyonunu sistem bilgilerinde bulur ve ilgili sürücüye bağlanır. Sürücü Yöneticisi, her SQLConnect argümanını sürücüye iletir.

• Veri kaynağı adı bulunamazsa veya ServerName bir null işaretçiyse, Sürücü Yöneticisi varsayılan veri kaynağı spesifikasyonunu bulur ve ilgili sürücüye bağlanır. Sürücü Yöneticisi, sürücüye UserName ve Authentication argümanlarını değiştirilmeden veDEFAULT "" argümanlarını ServerName argümanı için iletir.

• ServerName argümanı "DEFAULT" ise, Sürücü Yöneticisi varsayılan veri kaynağı spesifikasyonunu bulur ve ilgili sürücüye bağlanır. Sürücü Yöneticisi, her SQLConnect argümanını sürücüye iletir.

• Veri kaynağı adı bulunamazsa veya ServerName bir null işaretçiyse ve varsayılan veri kaynağı belirtimi yoksa, Sürücü Yöneticisi SQL_ERROR ile skalstür IM002 (Veri kaynak adı bulunmadı ve varsayılan sürücü belirtilmedi) döndürür.

Sürücü Yöneticisi tarafından bağlandıktan sonra, sürücü sistem bilgilerinde ilgili veri kaynağı spesifikasyonunu bulabilir ve gereksinim olan bağlantı bilgisini tamamlamak için spesifikasyondan sürücüye özgü bilgileri kullanabilir.

Eğer veri kaynağı için sistem bilgilerinde varsayılan bir çeviri kütüphanesi belirtiliyorsa, sürücü ona bağlanır. Farklı bir çeviri kütüphanesine SQL_ATTR_TRANSLATE_LIB özniteliğine sahip SQLSetConnectAttr çağrılarak bağlanabilir. Bir çeviri seçeneği, SQL_ATTR_TRANSLATE_OPTION özniteliğiyle SQLSetConnectAttr çağrılarak belirtilebilir.

Bir sürücü SQLConnect'i destekliyorsa, sürücünün sistem bilgisinin sürücü anahtar kelime bölümü, ilk karakter ayarı "Y" olan ConnectFunctions anahtar kelimesini içermelidir.

Bağlantı Havuzu

Bağlantı havuzu, bir uygulamanın zaten oluşturulmuş bir bağlantıyı yeniden kullanmasına olanak tanır. Bağlantı havuzu etkinleştirildiğinde ve SQLConnect çağrıldığında, Sürücü Yöneticisi, bağlantı havuzu için belirlenmiş bir ortamdaki bağlantı havuzunun parçası olan bir bağlantı kullanarak bağlantıyı kurmaya çalışır. Bu ortam, havuzdaki bağlantıları kullanan tüm uygulamalar tarafından kullanılan paylaşılan bir ortamdır.

Bağlantı havuzu, ortam tahsis edilmeden önce SQLSetEnvAttr çağrılıp, SQL_ATTR_CONNECTION_POOLING'yi SQL_CP_ONE_PER_DRIVER (sürücü başına en fazla bir havuz belirtir) veya SQL_CP_ONE_PER_HENV (her ortam başına en fazla bir havuz belirtir) olarak ayarlayarak etkinleştirilir. Bu durumda SQLSetEnvAttr çağrılır ve EnvironmentHandle null olarak ayarlanır, bu da özniteliği süreç düzeyinde bir öznitelik yapar. Eğer SQL_ATTR_CONNECTION_POOLING SQL_CP_OFF olarak ayarlanmışsa, bağlantı havuzu devre dışı bırakılır.

Bağlantı havuzu etkinleştirildikten sonra, SQL_HANDLE_ENV HandleTypeile SQLAllocHandle çağrılarak bir ortam tahsis edilir. Bu çağrı tarafından tahsis edilen ortam, bağlantı havuzu etkinleştirildiği için paylaşılan bir ortamdır. Ancak, kullanılacak ortam, SQLAllocHandle ile SQL_HANDLE_DBC HandleType çağrılana kadar belirlenmez.

SQLAllocHandle ile HandleType SQL_HANDLE_DBC bir bağlantı tahsis etmek için çağrılır. Sürücü Yöneticisi, uygulama tarafından belirlenen ortam nitelikleriyle eşleşen mevcut paylaşılan bir ortam bulmaya çalışır. Böyle bir ortam yoksa, örtük paylaşılan bir ortam olarak oluşturulur. Eşleşen bir paylaşılan ortam bulunursa, ortam tutamacı uygulamaya geri döner ve referans sayısı artırılır.

Ancak, kullanılacak bağlantı SQLConnect çağrılana kadar belirlenmez. O noktada, Sürücü Yöneticisi, uygulamanın talep ettiği kriterlere uyan bağlantı havuzunda mevcut bir bağlantı bulmaya çalışır. Bu kriterler arasında, SQLConnect çağrısında istenen bağlantı seçenekleri ( ServerName, UserName ve Authentication anahtar kelimelerinin değerleri) ve SQLAllocHandle ile HandleType SQL_HANDLE_DBC çağrıldığından beri belirlenen bağlantı özellikleri yer alır. Sürücü Yöneticisi, bu kriterleri havuzdaki bağlantılardaki ilgili bağlantı anahtar kelimeleri ve nitelikleriyle karşılaştırır. Eşleşme bulunursa, havuzdaki bağlantı kullanılır. Eşleşme bulunmazsa yeni bir bağlantı oluşturulur.

Eğer SQL_ATTR_CP_MATCH ortam özniteliği SQL_CP_STRICT_MATCH olarak ayarlanmışsa, havuzdaki bir bağlantının kullanılabilmesi için eşleşme tam olarak olmalıdır. Eğer SQL_ATTR_CP_MATCH ortam özniteliği SQL_CP_RELAXED_MATCH olarak ayarlanmışsa, SQLConnect çağrısındaki bağlantı seçenekleri eşleşmeli ancak tüm bağlantı özellikleri eşleşmemelidir.

Aşağıdaki kurallar, SQLConnect çağrılmadan önce uygulama tarafından belirlenen bir bağlantı özniteliği, havuzdaki bağlantının bağlantı özniteliğiyle eşleşmediğinde uygulanır:

• Bağlantı kurulmadan önce bağlantı özniteliği ayarlanması gerekiyorsa:

  Eğer SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH ise, havuzlu bağlantıdaki SQL_ATTR_PACKET_SIZE uygulamanın oluşturduğu öznitelikle aynı olmalıdır. Eğer SQL_CP_RELAXED_MATCH, SQL_ATTR_PACKET_SIZE değerleri farklı olabilir.

  SQL_ATTR_LOGIN_VALUE değeri eşleşmeyi etkilemez.

• Bağlantı özniteliği, bağlantı kurulmadan önce veya sonra ayarlanabilirse:

  Bağlantı özniteliği uygulama tarafından ayarlanmamış ancak havuzdaki bağlantıda ayarlanmışsa ve varsayılan varsa, havuzlu bağlantıdaki bağlantı özniteliği varsayılana geri döndürülür ve eşleşme ilan edilir. Varsayılan bir bağlantı yoksa, havuzlu bağlantı eşleşme sayılmaz.

  Bağlantı özniteliği uygulama tarafından belirlenmişse ancak havuzdaki bağlantıda ayarlanmamışsa, havuzdaki bağlantı özelliği uygulama tarafından belirlenen hale değiştirilir ve eşleşme ilan edilir.

  Bağlantı özniteliği uygulama tarafından ayarlanmış ve havuzdaki bağlantıda da ayarlanmışsa ancak değerler farklıysa, uygulamanın bağlantı özniteliğinin değeri kullanılır ve eşleşme ilan edilir.

• Sürücüye özgü bağlantı özniteliklerinin değerleri aynı değilse ve SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH olarak ayarlanmışsa, havuzdaki bağlantı kullanılmaz.

Uygulama bağlantıyı kesmek için SQLDisconnect'i çağırdığında, bağlantı bağlantı havuzuna geri döner ve yeniden kullanılabilir hale gelir.

Bağlantı Havuzlama Performansının Optimize Edilmesi

Dağıtık işlemler söz konusu olduğunda, SQL_DTC_TRANSITION_COST (SQLUINTEGER bitmaskesi) kullanılarak bağlantı havuzu performansını optimize etmek mümkündür. Bahsedilen geçişler, bağlantı özniteliğinin 0 değerden sıfır olmayana geçiş SQL_ATTR_ENLIST_IN_DTC ve tam tersidir. Bu, dağıtık bir işlemde dahil edilmemişten, dağıtık bir işlemde kayıtlı olmaya ve tam tersi bir bağlantıya geçiştir. Sürücünün katılımı nasıl uyguladığına (bağlantı özelliğini SQL_ATTR_ENLIST_IN_DTC ayarlama) bağlı olarak, bu geçişler pahalı olabilir ve en iyi performans için kaçınılmalıdır.

Sürücünün döndürdüğü değer, aşağıdaki bitlerin herhangi bir kombinasyonunu içerir:

• SQL_DTC_ENLIST_EXPENSIVE ayarlandığında, sıfırdan sıfır olmayan bir değere geçişin (bir sonraki işlemde daha önce listelenen bir bağlantının dahil edilmesi) sıfırdan sıfır olmayan başka bir değere geçişten çok daha pahalı olduğunu ima eder.

• SQL_DTC_UNENLIST_EXPENSIVE, ayarlandığında, sıfırdan sıfıra geçişin, SQL_ATTR_ENLIST_IN_DTC özniteliği zaten sıfıra ayarlanmış bir bağlantıdan çok daha pahalı olduğunu gösterir.

Performans ile bağlantı kullanımı arasında bir denge vardır. Bir sürücü bu geçişlerden birinin veya birkaçının pahalı olduğunu belirtirse, sürücü yöneticisinin bağlantı havuzu buna daha fazla bağlantıyı havuzda tutar. Havuzdaki bazı bağlantılar işlem dışı kullanım için tercih edilirken, bazıları işlemsel kullanım için tercih edilir. Ancak, sürücü bu geçişlerin pahalı olmadığını belirtirse, daha az bağlantı kullanılabilir; belki işlem dışı ve işlem amaçlı kullanım arasında dönüşümlü olabilir.

SQL_ATTR_ENLIST_IN_DTC desteklemeyen sürücülerin SQL_DTC_TRANSITION_COST desteklemesi gerekmez. SQL_ATTR_ENLIST_IN_DTC destekleyen ama SQL_DTC_TRANSITION_COST desteklemeyen sürücüler için, geçişlerin pahalı olmadığı varsayılır; sanki sürücü bu değer için 0 (bit ayarlanmamış değil) döndürüyormuş gibi.

Her ne kadar SQL_DTC_TRANSITION_COST ODBC 3.5'te tanıtılmış olsa da, bir ODBC 2. X sürücüsü ayrıca destekleyebilir çünkü sürücü yöneticisi bu bilgileri sürücü sürümü ne olursa olsun sorgular.

Kod Örneği

Aşağıdaki örnekte, bir uygulama ortam ve bağlantı tutamaçlarını tahsis eder. Daha sonra kullanıcı kimliği JohnS ve Sesame şifresiyle SalesOrders veri kaynağına bağlanır ve verileri işler. Veri işlenmeyi bitirdiğinde, veri kaynağından bağlantıyı koparır ve tutamaçları serbest bırakır.

// 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);  
   }  
}  

İlgili Fonksiyonlar

Ayrıca Bkz.

ODBC API Referansı
ODBC Üst Bilgi Dosyaları