SQLBrowseConnect İşlevi

Uygunluk
Tanıtılan Sürüm: ODBC 1.0 Standartlar Uyumu: ODBC

Özet
SQLBrowseConnect , bir veri kaynağına bağlanmak için gereken nitelikleri ve nitelik değerlerini keşfedip sayan yinelemeli bir yöntemi destekler. SQLBrowseConnect'e yapılan her çağrı, ardışık özellikler ve nitelik değerleri seviyelerini döndürür. Tüm seviyeler sayıldıktan sonra, veri kaynağına bağlantı tamamlanır ve SQLBrowseConnect tarafından tam bir bağlantı dizesi döner. SQL_SUCCESS veya SQL_SUCCESS_WITH_INFO dönüş kodu, tüm bağlantı bilgilerinin belirlendiğini ve uygulamanın artık veri kaynağına bağlı olduğunu gösterir.

Syntax

  
SQLRETURN SQLBrowseConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr);  

Arguments

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

InConnectionString
[Giriş] Request bağlantı dizesi'e göz atın ("Yorumlar" bölümünde "InConnectionString Argümanı"na bakınız).

StringLength1
[Giriş] *InConnectionString'in karakter cinsinden.

OutConnectionString
[Çıkış] Göz atma sonucu bağlantı dizesi'i geri dönmek için bir karakter tamponuna işaret (bkz. "OutConnectionString Argument" (Yorumlar) bölümünde "OutConnectionString Argümanı").

OutConnectionString NULL ise, StringLength2Ptr yine de OutConnectionString tarafından işaret edilen tamponda döndürülebilecek toplam karakter sayısını (karakter verisi için null-terminasyon karakteri hariç) döndürecektir.

BufferLength
[Giriş] *OutConnectionString tamponunun uzunluğu, karakter cinsinden.

StringLength2Ptr
[Çıkış] *OutConnectionString'de geri döndürülebilecek toplam karakter sayısı (null-terminasyon hariç). Eğer döndürülebilecek karakter sayısı BufferLength'den büyük veya eşitse, *OutConnectionString'deki bağlantı dizesi BufferLength olarak kısılır, null-termination karakterinin uzunluğu çıkarılır.

İadeler

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE veya SQL_STILL_EXECUTING.

Diagnostics

SQLBrowseConnect SQL_ERROR, SQL_SUCCESS_WITH_INFO veya SQL_NEED_DATA döndürdüğünde, ilişkili bir SQLSTATE değeri, SQL_HANDLE_STMT HandleType ve ConnectionHandleile SQLGetDiagRec çağrılarak elde edilebilir. Aşağıdaki tablo, SQLBrowseConnect tarafından sıkça 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.

InConnectionString Argümanı

Bir gezinme isteği bağlantı dizesi aşağıdaki sözdizimine sahiptir:

connection-string ::= öznitelik[;] | Öznitelik;bağlantı dizisi;
attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]
attribute-keyword ::= DSN | | UID | PWDsürücü-tanımlı-öznitelik-anahtar kelime
öznitelik-değeri ::= karakter-dizisi
driver-defined-attribute-keyword ::= tanımlayıcı

burada karakter-dizisi sıfır veya daha fazla karaktere sahiptir; tanımlayıcı bir veya daha fazla karakterden oluşur; öznitelik-anahtar kelime büyük harf duyarlı değildir; öznitelik-değeri beve duyarlı olabilir; ve DSN anahtar kelimesinin değeri sadece boşluklardan oluşmaz. bağlantı dizesi ve başlatma dosyası dilbilgisi, anahtar kelimeler ve öznitelik değerleri nedeniyle []{}(),;? karakterlerini içerir. *=!@ kaçınılmalıdır. Sistem bilgilerindeki dilbilgisi nedeniyle, anahtar kelimeler ve veri kaynağı isimleri ters eğik çizgi (\) karakterini içeremez. ODBC 2 için. x sürücü, DRIVER anahtar kelimesinin öznitelik değeri etrafında destekler gereklidir.

Eğer herhangi bir anahtar kelime gezinme isteği bağlantı dizesi'inde tekrarlanırsa, sürücü anahtar kelimenin ilk kez gerçekleştiği değeri kullanır. DSN ve DRIVER anahtar kelimeleri aynı gezinme isteği bağlantı dizesi'e dahil ediliyorsa, Driver Manager ve sürücü ilk görünen anahtar kelimeyi kullanır.

Bir uygulamanın veri kaynağı veya sürücü seçme şekli hakkında bilgi için Veri Kaynağı veya Sürücü Seçme bölümüne bakınız.

OutConnectionString Argümanı

Göz atma sonucu bağlantı dizesi, bağlantı özniteliklerinin bir listesidir. Bir bağlantı özniteliği, bir öznitelik anahtar kelimesi ve ona karşılık gelen bir özellik değerinden oluşur. Göz atma sonucu bağlantı dizesi'in şu sözdizimi vardır:

connection-string ::= öznitelik[;] | Öznitelik;bağlantı dizisi
öznitelik ::= [*]öznitelik-anahtar sözcüğü=öznitelik-değeri
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attributed-keyword anahtar kelime
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= {attribute-value-list} | ? (Braketler literal; sürücü tarafından döndürülür.)
attribute-value-list ::= karakter-dizisi [:yerelleştirilmiş karakter dizisi] | karakter-dizisi [:yerelleştirilmiş karakter dizisi] ,öznitelik-değer-listesi

burada karakter dizisi ve yerelleştirilmiş karakter dizisinin sıfır veya daha fazla karakteri vardır; tanımlayıcı ve yerelleştirilmiş tanımlayıcı bir veya daha fazla karakterden oluşur; öznitelik-anahtar kelime büyük harf duyarlı değildir; ve öznitelik değeri büyük harf duyarlı olabilir. Çünkü bağlantı dizesi ve başlatma dosyası dilbilgisi, anahtar kelimeler, yerel tanımlayıcılar ve []{}(),;? karakterlerini içeren öznitelik değerleri *=!@ kaçınılmalıdır. Sistem bilgilerindeki dilbilgisi nedeniyle, anahtar kelimeler ve veri kaynağı isimleri ters eğik çizgi (\) karakterini içeremez.

Browse result bağlantı dizesi sözdizimi aşağıdaki anlamsal kurallara göre kullanılır:

• Bir özellik-anahtar kelimesinden önce bir yıldız (*) varsa, bu nitelik isteğe bağlıdır ve SQLBrowseConnect'e yapılan bir sonraki çağrıda çıkarılabilir.

• UID ve PWD özellik anahtar kelimeleri, SQLDriverConnect'te tanımlanan anlamla aynı anlamaya sahiptir.

• Sürücü-tanımlamış-öznitelik-anahtar kelime, bir öznitelik değerinin sağlanabileceği öznitelik türünü belirtir. Örneğin, SERVER, DATABASEHOST veya DBMS olabilir.

• ODBC-attribute-keywords ve driver-determined-attributed-keywords , anahtar kelimenin yerel veya kullanıcı dostu bir versiyonunu içerir. Bu, uygulamalar tarafından bir diyalog kutusunda bir etiket olarak kullanılabilir. Ancak, sürücüye gezinme isteği dizisi iletilirken UID, PWD veya yalnızca tanımlayıcı kullanılmalıdır.

• {attribute-value-list}, ilgili öznitelik-anahtar kelimesi için geçerli olan gerçek değerlerin bir sayımıdır. Braketlerin ({}) bir seçim listesini göstermediğine dikkat edin; sürücü tarafından geri gönderilir. Örneğin, sunucu adları listesi veya veritabanı isimleri listesi olabilir.

• Öznitelik değeri tek bir soru işareti (?) ise, tek bir değer öznitelik-anahtar kelimesine karşılık gelir. Örneğin, UID=JohnS; PWD=Susam.

• SQLBrowseConnect'e yapılan her çağrı, yalnızca bağlantı sürecinin bir sonraki seviyesini karşılamak için gereken bilgileri geri döndürür. Sürücü, durum bilgisini bağlantı koluna ilişkilendirir ki her çağrıda bağlam her zaman belirlenebilsin.

SQLBrowseConnect kullanımı

SQLBrowseConnect tahsis edilmiş bir bağlantı gerektirir. Sürücü Yöneticisi, ilk gezinme isteği bağlantı string'inde belirtilen veri kaynağı adına karşılık gelen veya belirtilen sürücüyü yükler; bunun ne zaman gerçekleştiğine dair bilgi için SQLConnect Fonksiyonu'ndaki "Yorumlar" bölümüne bakınız. Sürücü, gezinme sürecinde veri kaynağına bağlantı kurabilir. Eğer SQLBrowseConnect SQL_ERROR dönerse, bekleyen bağlantılar sonlandırılır ve bağlantı bağlanmamış bir duruma geri döner.

SQLBrowseConnect bir bağlantıda ilk kez çağrıldığında, gezinme isteği bağlantı dizesi DSN anahtar kelimesini veya DRIVER anahtar kelimesini içermelidir. Eğer gezinme isteği bağlantı dizesi DSN anahtar kelimesini içeriyorsa, Driver Manager sistem bilgilerinde ilgili bir veri kaynağı spesifikasyonunu bulur:

• Sürücü Yöneticisi ilgili veri kaynağı spesifikasyonunu bulursa, ilgili sürücü DLL'sini yükler; sürücü, sistem bilgilerinden veri kaynağı hakkında bilgi alabilir.

• Sürücü Yöneticisi ilgili veri kaynağı spesifikasyonunu bulamazsa, varsayılan veri kaynağı spesifikasyonunu bulur ve ilgili sürücü DLL'sini yükler; sürücü, sistem bilgilerinden varsayılan veri kaynağı hakkında bilgi alabilir. "DEFAULT" DSN için sürücüye iletiliyor.

• Sürücü Yöneticisi ilgili veri kaynağı spesifikasyonunu bulamazsa ve varsayılan veri kaynağı belirtimi yoksa, SQL_ERROR ile birlikte SQL state IM002 (Veri kaynağı bulunmadı ve varsayılan sürücü belirtilmedi) döner.

Eğer gezinme isteği bağlantı dizesi DRIVER anahtar kelimesini içeriyorsa, Driver Manager belirtilen sürücüyü yükler; sistem bilgilerinde veri kaynağı bulmaya çalışmaz. DRIVER anahtar kelimesi sistem bilgisinden bilgi kullanmadığından, sürücü sadece gezinme isteği bağlantı dizilerindeki bilgileri kullanarak bir veri kaynağına bağlanabilmesi için yeterli anahtar kelime tanımlamalıdır.

SQLBrowseConnect'e yapılan her çağrıda, uygulama gezinme isteği bağlantı dizesi'deki bağlantı öznitelik değerlerini belirtir. Sürücü, gezinme sonucunda ardışık özellikler ve nitelik değerleri seviyelerini döndürür bağlantı dizesi; bağlantı dizesi gezinme isteğinde henüz listelenmemiş bağlantı özellikleri olduğu sürece SQL_NEED_DATA döndürür. Uygulama, bir sonraki SQL RowseConnect çağrısı için browse request bağlantı dizesi'i oluşturmak amacıyla browse result bağlantı dizesi'in içeriğini kullanır. Tüm zorunlu öznitelikler ( OutConnectionString argümanında yıldız işareti gelmeyenler) SQLBrowseConnect'e yapılan bir sonraki çağrıda dahil edilmelidir. Uygulamanın mevcut gezinme isteği bağlantı dizesi'i oluştururken önceki gezinme sonucu bağlantı dizileri içeriğini kullanamadığını unutmayın; yani, önceki seviyelerde belirlenen öznitelikler için farklı değerler belirleyemez.

Tüm bağlantı seviyeleri ve ilgili özellikler sayıldığında, sürücü SQL_SUCCESS döner, veri kaynağına bağlantı tamamlanmış olur ve uygulamaya tam bir bağlantı dizesi döner. bağlantı dizesi, SQLDriverConnect ile birlikte kullanılmaya uygundur ve başka bir bağlantı kurma SQL_DRIVER_NOPROMPT seçeneği vardır. Ancak tam bağlantı dizesi, SQLBrowseConnect çağrısında kullanılamaz; eğer SQLBrowseConnect tekrar çağrılırsa, tüm çağrı dizisi tekrarlanmalıdır.

SQLBrowseConnect ayrıca gezinme sürecinde kurtarılabilir, ölümcül olmayan hatalar varsa SQL_NEED_DATA döner; örneğin, uygulama tarafından sağlanan geçersiz bir şifre veya öznitelik anahtar kelimesi. SQL_NEED_DATA dönerken ve bağlantı dizesi gezinme sonucu değişmediğinde, bir hata oluşur ve uygulama, gezinme zamanı hataları için SQLSTATE'i döndürmek için SQLGetDiagRec'i çağırabilir. Bu, uygulamanın özniteliği düzeltmesini ve gezinmeye devam etmesini sağlar.

Bir uygulama, SQLDisconnect'i çağırarak gezinme sürecini istediğiniz zaman sonlandırabilir. Sürücü, beklemeyen bağlantıları sonlandırır ve bağlantıyı bağlanmamış bir duruma geri döndürür.

Bağlantı kolunda asenkron işlemler etkinleştirilmişse, SQLBrowseConnect SQL_STILL_EXECUTING de döndürebilir. SQL_NEED_DATA döndürdüğünde, bir uygulama gezinme sürecini iptal etmek için SQLDisconnect kullanmak zorundadır. Eğer SQLBrowseConnect SQL_STILL_EXECUTING dönerse, bir uygulama devam eden işlemi iptal etmek için SQLCancelHandle kullanmalıdır. Fonksiyon dönerken SQLCancelHandle çağrısı SQL_NEED_DATA bir etki yaratmaz.

Daha fazla bilgi için SQLBrowseConnect ile Bağlantı bölümünü inceleyebilirsiniz.

Bir sürücü SQLBrowseConnect'i destekliyorsa, sürücünün sistem bilgilerindeki sürücü anahtar kelime bölümünde üçüncü karakter "Y" olarak ayarlanmış ConnectFunctions anahtar kelimesi olmalıdır.

Kod Örneği

Aşağıdaki örnekte, bir uygulama SQLBrowseConnect'i defalarca çağırır. SQLBrowseConnect her SQL_NEED_DATA döndürdüğünde, *OutConnectionString'de ihtiyaç duyduğu verilerle ilgili bilgileri geri iletir. Uygulama, OutConnectionString'irutini olan GetUserInput'a (gösterilmemiş) iletir. GetUserInput bilgiyi ayrıştırır, bir iletişim kutusu oluşturur ve gösterir, ayrıca kullanıcının *InConnectionString'e girdiği bilgileri geri getirir. Uygulama, kullanıcının bilgilerini bir sonraki çağrıda SQLBrowseConnect'e göndererek sürücüye iletir. Uygulama, sürücünün veri kaynağına bağlanması için gerekli tüm bilgileri sağladıktan sonra, SQLBrowseConnect SQL_SUCCESS döndürür ve uygulama devam eder.

SQLBrowseConnect çağrısı ile SQL Server sürücüsüne bağlanmanın daha ayrıntılı bir örneği için bkz. SQL Server Gezinme Örneği.

Örneğin, veri kaynağı Satış'a bağlanmak için aşağıdaki işlemler gerçekleşebilir. İlk olarak, uygulama aşağıdaki diziyi SQLBrowseConnect'e iletir:

"DSN=Sales"  

Sürücü Yöneticisi, veri kaynağı Sales ile ilişkili sürücüyü yükler. Daha sonra sürücünün SQLBrowseConnect fonksiyonunu uygulamadan aldığı aynı argümanlarla çağırır. Sürücü, *OutConnectionString içinde aşağıdaki diziyi döndürür:

"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"  

Uygulama, bu diziyi GetUserInput rutinine iletir; bu rutin, kullanıcıdan kırmızı, mavi veya yeşil sunucuyu seçmesini ve kullanıcı kimliği ile şifre girmesini isteyen bir diyalog kutusu oluşturur. Rutin, aşağıdaki kullanıcı tarafından belirtilen bilgileri *InConnectionString'e geri iletir ve uygulama bunu SQLBrowseConnect'e iletir:

"HOST=red;UID=Smith;PWD=Sesame"  

SQLBrowseConnect bu bilgiyi kullanarak Smith olarak Sesame şifresiyle kırmızı sunucuya bağlanır ve ardından *OutConnectionString içinde aşağıdaki diziyi döndürür:

"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"  

Uygulama bu diziyi GetUserInput rutinine iletir; bu rutin kullanıcıdan bir veritabanı seçmesini isteyen bir diyalog kutusu oluşturur. Kullanıcı empdata seçer ve uygulama son kez SQLBrowseConnect'i bu diziyle çağırır:

"DATABASE=SalesOrders"  

Bu, sürücünün veri kaynağına bağlanması için gereken son bilgidir; SQLBrowseConnect SQL_SUCCESS döndürür ve *OutConnectionString tamamlanmış bağlantı dizesi içerir:

// SQLBrowseConnect_Function.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define BRWS_LEN 100  
SQLHENV henv;  
SQLHDBC hdbc;  
SQLHSTMT hstmt;  
SQLRETURN retcode;  
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];  
SQLSMALLINT cbConnStrOut;  
  
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}  
  
int main() {  
   // Allocate the environment handle.  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);        
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
      // Set the version environment attribute.  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
         // Allocate the connection handle.  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            // Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA   
            // (pass data source name the first time).  If SQL_NEED_DATA is returned, call GetUserInput   
            // (not shown) to build a dialog from the values in szConnStrOut.  The user-supplied values   
            // are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.  
  
            strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");  
            do {  
               retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,  
                  szConnStrOut, BRWS_LEN, &cbConnStrOut);  
               if (retcode == SQL_NEED_DATA)  
                  GetUserInput(szConnStrOut, szConnStrIn);  
            } while (retcode == SQL_NEED_DATA);  
  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
               // Allocate the statement handle.  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                  // Process data after successful connection  
                  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ı