SQLFreeHandle İşlevi

uyumluluk
Sunulan Sürüm: ODBC 3.0 Standartları Uyumluluğu: ISO 92

Özeti
SQLFreeHandle belirli bir ortam, bağlantı, deyim veya tanımlayıcı tanıtıcı ile ilişkili kaynakları serbestleştirir.

Not

Bu işlev, tanıtıcıları boşaltmaya yönelik genel bir işlevdir. SQLFreeConnect ODBC 2.0 işlevlerinin yerini alır (bağlantı tutamacını boşaltmak için) ve SQLFreeEnv (ortam tanıtıcısını boşaltmak için). SQLFreeConnect ve SQLFreeEnv ODBC 3*.x* içinde kullanım dışıdır. SQLFreeHandle, sqlFreeStmt ODBC 2.0 işlevinin yerine de (SQL_DROP Option) ek olarak deyim tanıtıcısını serbest sağlar. Daha fazla bilgi için bkz. "Açıklamalar." Bir ODBC 3*.x* uygulaması ODBC 2*.x* sürücüsüyle çalışırken Driver Manager'ın bu işlevi neyle eşlediğini öğrenmek için bkz. Uygulamaların Geriye Dönük Uyumluluğu için Değiştirme İşlevleri eşleme.

Sözdizimi

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);  

Bağımsız değişken

HandleType
[Giriş] SQLFreeHandletarafından serbestlenecek tanıtıcı türü. Aşağıdaki değerlerden biri olmalıdır:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN tutamacı yalnızca Sürücü Yöneticisi ve sürücüsü tarafından kullanılır. Uygulamalar bu tanıtıcı türünü kullanmamalıdır. SQL_HANDLE_DBC_INFO_TOKEN hakkında daha fazla bilgi için bkz. ODBC Sürücüsünde Connection-Pool Farkındalığı Geliştirme.

HandleType bu değerlerden biri değilse SQLFreeHandle SQL_INVALID_HANDLE döndürür.

İşle
[Giriş] Serbestlenecek tanıtıcı.

Döndürür

SQL_SUCCESS, SQL_ERROR veya SQL_INVALID_HANDLE.

SQLFreeHandle SQL_ERROR döndürürse, tanıtıcı hala geçerlidir.

Tanılama

SQLFreeHandle SQL_ERROR döndürdüğünde, SQLFreeHandle serbest ancak kurtaramadığı tanıtıcının tanılama veri yapısından ilişkili bir SQLSTATE değeri alınabilir. Aşağıdaki tabloda genellikle SQLFreeHandle tarafından döndürülen SQLSTATE değerleri listelenir ve her biri bu işlev bağlamında açıklanır; "(DM)" gösterimi, Sürücü Yöneticisi tarafından döndürülen SQLSTATEs açıklamalarından önce gelir. Aksi belirtilmediği sürece, her SQLSTATE değeriyle ilişkili dönüş kodu SQL_ERROR.

SQLSTATE	Hata	Açıklama
HY000	Genel hata	Belirli bir SQLSTATE olmayan ve uygulamaya özgü SQLSTATE tanımlanmayan bir hata oluştu. *MessageText arabelleğindeki SQLGetDiagRec tarafından döndürülen hata iletisi, hatayı ve nedenini açıklar.
HY001	Bellek ayırma hatası	Sürücü, işlevin yürütülmesini veya tamamlanmasını desteklemek için gereken belleği ayıramadı.
HY010	İşlev dizisi hatası	(DM) HandleType bağımsız değişkeni SQL_HANDLE_ENV ve en az bir bağlantı ayrılmış veya bağlı durumdaydı. sqldisconnect ve SQLFreeHandle HandleType SQL_HANDLE_DBC , SQL_HANDLE_ENV HandleType SQLFreeHandle çağrılmadan önce her bağlantı için çağrılmalıdır. (DM) HandleType bağımsız değişkeni SQL_HANDLE_DBC ve bağlantı için sqldisconnect çağrılmadan önce işlev çağrıldı. (DM) HandleType bağımsız değişkeni SQL_HANDLE_DBC. Handle ile zaman uyumsuz olarak yürütülen bir işlev çağrıldı ve bu işlev çağrıldığında işlev yürütülüyordu. (DM) HandleType bağımsız değişkeni SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperationsveya SQLSetPos deyimi tanıtıcısıyla çağrıldı ve SQL_NEED_DATA döndürdü. Bu işlev, tüm yürütme sırasında veri parametreleri veya sütunları için veri gönderilmeden önce çağrıldı. (DM) HandleType bağımsız değişkeni SQL_HANDLE_STMT. Zaman uyumsuz olarak yürütülen bir işlev, deyim tanıtıcısında veya ilişkili bağlantı tanıtıcısında çağrıldı ve bu işlev çağrıldığında işlev hala yürütülüyordu. (DM) HandleType bağımsız değişkeni SQL_HANDLE_DESC. İlişkili bağlantı tanıtıcısında zaman uyumsuz olarak yürütülen bir işlev çağrıldı; ve bu işlev çağrıldığında işlev hala yürütülüyordu. (DM) SQLFreeHandle çağrılmadan önce tüm yan tanıtıcılar ve diğer kaynaklar yayımlanmadı. (DM) SQLExecute, SQLExecDirectveya SQLMoreResults, Handle ile ilişkili deyim tanıtıcılarından biri için çağrıldı ve HandleType SQL_HANDLE_STMT veya döndürülen SQL_HANDLE_DESC SQL_PARAM_DATA_AVAILABLE olarak ayarlandı. Bu işlev, tüm akış parametreleri için veri alınmadan önce çağrıldı.
HY013	Bellek yönetimi hatası	HandleType bağımsız değişkeni SQL_HANDLE_STMT veya SQL_HANDLE_DESC ve büyük olasılıkla yetersiz bellek koşulları nedeniyle temel alınan bellek nesnelerine erişilemediğinden işlev çağrısı işlenemedi.
HY017	Otomatik olarak ayrılan tanımlayıcı tutamacının geçersiz kullanımı.	(DM) Tanıtıcı bağımsız değişkeni, otomatik olarak ayrılan bir tanımlayıcı için tanıtıcıya ayarlandı.
HY117	Bilinmeyen işlem durumu nedeniyle bağlantı askıya alındı. Yalnızca bağlantıyı kesme ve salt okunur işlevlere izin verilir.	(DM) Askıya alma durumu hakkında daha fazla bilgi için bkz. SQLEndTran İşlevi.
HYT01	Bağlantı zaman aşımı süresi doldu	Veri kaynağı isteği yanıtlamadan önce bağlantı zaman aşımı süresi doldu. Bağlantı zaman aşımı süresi SQLSetConnectAttrSQL_ATTR_CONNECTION_TIMEOUT üzerinden ayarlanır.
IM001	Sürücü bu işlevi desteklemiyor	(DM) HandleType bağımsız değişkeni SQL_HANDLE_DESC ve sürücü bir ODBC 2*.x* sürücüsü idi. (DM) HandleType bağımsız değişkeni SQL_HANDLE_STMT ve sürücü geçerli bir ODBC sürücüsü değildi.

Yorum

SQLFreeHandle, aşağıdaki bölümlerde açıklandığı gibi ortamlar, bağlantılar, deyimler ve tanımlayıcılar için tanıtıcıları serbest hale getirmek için kullanılır. Tanıtıcılar hakkında genel bilgi için bkz. Tanıtıcılar.

Uygulama serbest bırakılmış bir tanıtıcı kullanmamalıdır; Driver Manager, işlev çağrısındaki bir tanıtıcının geçerliliğini denetlemez.

Ortam Tanıtıcısını Serbest Tutma

SQL_HANDLE_ENV HandleTypeSQLFreeHandle çağırmadan önce, bir uygulamanın ortam altında ayrılan tüm bağlantılar için SQL_HANDLE_DBC HandleTypeSQLFreeHandle çağırması gerekir. Aksi takdirde, SQLFreeHandle çağrısı SQL_ERROR ve ortamı döndürür ve etkin bağlantılar geçerli kalır. Daha fazla bilgi için bkz. Ortam tanıtıcıları ve Ortam Tutamacını Ayırma.

Ortam paylaşılan bir ortamsa, SQLFreeHandle çağıran uygulamanın SQL_HANDLE_ENV HandleType ile artık çağrıdan sonra ortama erişimi yoktur, ancak ortamın kaynakları serbest bırakılmaz. SQLFreeHandle çağrısı ortamın başvuru sayısını azaltmaya neden olur. Başvuru sayısı Sürücü Yöneticisi tarafından korunur. Sıfıra ulaşmazsa, paylaşılan ortam başka bir bileşen tarafından kullanılmaya devam ettiğinden serbest değildir. Başvuru sayısı sıfıra ulaşırsa, paylaşılan ortamın kaynakları serbesttir.

Bağlantı Tutamacını Serbest Tutma

SQL_HANDLE_DBC HandleType SQLFreeHandle çağırmadan önce, uygulamanın bu tanıtıcıda bir bağlantı varsa bağlantı için SQLDisconnect çağırması gerekir*.* Aksi takdirde SQLFreeHandle çağrısı SQL_ERROR döndürür ve bağlantı geçerli kalır.

Daha fazla bilgi için bkz. Bağlantı tanıtıcıları ve Veri Kaynağı veya Sürücü bağlantısı.

Deyim Tanıtıcısını Serbest Tutma

SQL_HANDLE_STMT HandleType ile SQLFreeHandle çağrısı, SQL_HANDLE_STMT HandleType ile SQLAllocHandle çağrısıyla ayrılan tüm kaynakları serbest bırakılır. Bir uygulama sqlfreehandle çağırdığında bekleyen sonuçları içeren bir deyimi serbest, bekleyen sonuçlar silinir. Bir uygulama bir deyim tanıtıcısını serbest ettiğinde, sürücü bu tanıtıcıyla ilişkili otomatik olarak ayrılan dört tanımlayıcıyı serbesttir. Daha fazla bilgi için bkz. Deyimi tanıtıcıları ve Serbest.

SQLDisconnect bağlantıda açık olan tüm deyimleri ve tanımlayıcıları otomatik olarak bırakır.

Tanımlayıcı Tutamacını Serbest Tutma

SQL_HANDLE_DESC HandleType ile SQLFreeHandle çağrısı, Tanıtıcıiçindeki tanımlayıcı tutamacını serbest bırakıyor. SQLFreeHandle çağrısı, Tanıtıcıherhangi bir tanımlayıcı kaydının işaretçi alanı (SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR ve SQL_DESC_OCTET_LENGTH_PTR dahil) tarafından başvurulabilecek uygulama tarafından ayrılan belleği serbest bırakmaz. sürücü tarafından işaretçi alanı olmayan alanlar için ayrılan bellek, tanıtıcı serbest bırakıldıklarında serbesttir. Kullanıcı tarafından ayrılan tanımlayıcı tanıtıcısı serbest bırakıldıysa, serbest bırakılmış tanıtıcının ilişkilendirildiği tüm deyimler ilgili otomatik olarak ayrılan tanımlayıcı tanıtıcı tanıtıcılarına geri döndürülür.

Not

ODBC 2*.x* sürücüleri, tanımlayıcı tanıtıcı tanıtıcıları ayırmayı desteklemedikleri gibi tanımlayıcı tanıtıcıların serbest bırakılmalarını desteklemez.

SQLDisconnect bağlantıda açık olan tüm deyimleri ve tanımlayıcıları otomatik olarak bırakır. Bir uygulama bir deyim tutamacını serbest oluşturduğunda, sürücü bu tanıtıcıyla ilişkili otomatik olarak oluşturulan tüm tanımlayıcıları serbesttir.

Tanımlayıcılar hakkında daha fazla bilgi için bkz. Tanımlayıcılar.

Kod Örneği

Ek kod örnekleri için bkz. SQLBrowseConnect ve SQLConnect.

Kod

// SQLFreeHandle.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <stdio.h>  
  
int main() {  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   // Initialize the environment, connection, statement handles.  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   // Allocate the environment.  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set environment attributes.  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
  
   // Allocate the connection.  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
   // Set the login timeout.  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
  
   // Let the user select the data source and connect to the database.  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // Free handles, and disconnect.     
   if (hstmt) {   
      SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
      hstmt = NULL;   
   }  
   if (hdbc) {   
      SQLDisconnect(hdbc);  
      SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
      hdbc = NULL;   
   }  
   if (henv) {   
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
      henv = NULL;   
   }  
}  

İlgili İşlevler

Hakkında bilgi için	Görmek
Tanıtıcı ayırma	SQLAllocHandle İşlevi
Deyim işlemeyi iptal etme	SQLCancel İşlevi
İmleç adı ayarlama	SQLSetCursorName İşlevi

Ayrıca Bkz.

ODBC API Başvurusu
ODBC Üst Bilgi Dosyaları
Örnek ODBC Programı