Fungsi SQLFreeHandle

Kesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92

Ringkasan
SQLFreeHandle membebaskan sumber daya yang terkait dengan lingkungan, koneksi, pernyataan, atau handel deskriptor tertentu.

Nota

Fungsi ini adalah fungsi generik untuk mengosongkan handel. Ini menggantikan fungsi ODBC 2.0 SQLFreeConnect (untuk membebaskan handel koneksi) dan SQLFreeEnv (untuk membebaskan handel lingkungan). SQLFreeConnect dan SQLFreeEnv keduanya tidak digunakan lagi di ODBC 3*.x*. SQLFreeHandle juga menggantikan fungsi ODBC 2.0 SQLFreeStmt (dengan opsi SQL_DROP ) untuk membebaskan handel pernyataan. Untuk informasi selengkapnya, lihat "Komentar." Untuk informasi selengkapnya tentang apa manajer driver memetakan fungsi ini ketika aplikasi ODBC 3*.x* bekerja dengan driver ODBC 2*.x*, lihat Fungsi Penggantian Pemetaan untuk Kompatibilitas Mundur Aplikasi.

Sintaksis

  
SQLRETURN SQLFreeHandle(  
     SQLSMALLINT   HandleType,  
     SQLHANDLE     Handle);

Argumen

HandleType
[Input] Jenis handel yang akan dibebaskan oleh SQLFreeHandle. Harus salah satu nilai berikut:

SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handel hanya digunakan oleh Driver Manager dan driver. Aplikasi tidak boleh menggunakan jenis handel ini. Untuk informasi selengkapnya tentang SQL_HANDLE_DBC_INFO_TOKEN, lihat Mengembangkan kesadaran Connection-Pool dalamDriver ODBC .

Jika HandleType bukan salah satu nilai ini, SQLFreeHandle mengembalikan SQL_INVALID_HANDLE.

Menangani
[Input] Handel yang akan dibebaskan.

Kembali

SQL_SUCCESS, SQL_ERROR, atau SQL_INVALID_HANDLE.

Jika SQLFreeHandle mengembalikan SQL_ERROR, handel masih valid.

Diagnostik

Ketika SQLFreeHandle mengembalikan SQL_ERROR, nilai SQLSTATE terkait dapat diperoleh dari struktur data diagnostik untuk handel yang SQLFreeHandle mencoba membebaskan tetapi tidak bisa. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLFreeHandle dan menjelaskan masing-masing nilai dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATEs yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.

SQLSTATE	Kesalahan	Deskripsi
HY000	Kesalahan umum	Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLGetDiagRec di buffer *MessageText menjelaskan kesalahan dan penyebabnya.
HY001	Kesalahan alokasi memori	Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi.
HY010	Kesalahan urutan fungsi	(DM) Argumen HandleType SQL_HANDLE_ENV, dan setidaknya satu koneksi berada dalam status dialokasikan atau tersambung. SQLDisconnect dan SQLFreeHandle dengan SQL_HANDLE_DBC HandleType harus dipanggil untuk setiap koneksi sebelum memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_ENV . (DM) Argumen HandleType SQL_HANDLE_DBC, dan fungsi dipanggil sebelum memanggil SQLDisconnect untuk koneksi. (DM) Argumen HandleType SQL_HANDLE_DBC. Fungsi eksekusi asinkron dipanggil dengan Handle dan fungsi masih dijalankan ketika fungsi ini dipanggil. (DM) Argumen HandleType SQL_HANDLE_STMT. SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil dengan handel pernyataan dan SQL_NEED_DATA yang dikembalikan. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. (DM) Argumen HandleType SQL_HANDLE_STMT. Fungsi eksekusi asinkron dipanggil pada handel pernyataan atau pada handel koneksi terkait dan fungsi masih dijalankan ketika fungsi ini dipanggil. (DM) Argumen HandleType SQL_HANDLE_DESC. Fungsi eksekusi asinkron dipanggil pada handel koneksi terkait; dan fungsi masih dijalankan ketika fungsi ini dipanggil. (DM) Semua handel anak perusahaan dan sumber daya lainnya tidak dirilis sebelum SQLFreeHandle dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan Handle dan HandleType diatur ke SQL_HANDLE_STMT atau SQL_HANDLE_DESC dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan.
HY013	Kesalahan manajemen memori	Argumen HandleType SQL_HANDLE_STMT atau SQL_HANDLE_DESC, dan panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
HY017	Penggunaan handel deskriptor yang dialokasikan secara otomatis tidak valid.	(DM) Argumen Handle diatur ke handel untuk deskriptor yang dialokasikan secara otomatis.
HY117	Koneksi ditangguhkan karena status transaksi yang tidak diketahui. Hanya fungsi putuskan sambungan dan baca-saja yang diizinkan.	(DM) Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran.
HYT01	Batas waktu koneksi kedaluwarsa	Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver tidak mendukung fungsi ini	(DM) Argumen HandleType SQL_HANDLE_DESC, dan drivernya adalah driver ODBC 2.x. (DM) Argumen HandleType SQL_HANDLE_STMT, dan driver bukan driver ODBC yang valid.

Komentar

SQLFreeHandle digunakan untuk mengosongkan handel untuk lingkungan, koneksi, pernyataan, dan deskriptor, seperti yang dijelaskan di bagian berikut. Untuk informasi umum tentang handel, lihat Menangani.

Aplikasi tidak boleh menggunakan handel setelah dibekukan; Driver Manager tidak memeriksa validitas handel dalam panggilan fungsi.

Membebaskan Handel Lingkungan

Sebelum memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_ENV, aplikasi harus memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_DBC untuk semua koneksi yang dialokasikan di bawah lingkungan. Jika tidak, panggilan ke SQLFreeHandle mengembalikan SQL_ERROR dan lingkungan dan koneksi aktif apa pun tetap valid. Untuk informasi selengkapnya, lihat Environment Handles dan MengalokasikanHandel Lingkungan .

Jika lingkungan adalah lingkungan bersama, aplikasi yang memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_ENV tidak lagi memiliki akses ke lingkungan setelah panggilan, tetapi sumber daya lingkungan belum tentu dibebesarkan. Panggilan ke SQLFreeHandle mengurangi jumlah referensi lingkungan. Jumlah referensi dipertahankan oleh Driver Manager. Jika tidak mencapai nol, lingkungan bersama tidak dibeberkan, karena masih digunakan oleh komponen lain. Jika jumlah referensi mencapai nol, sumber daya lingkungan bersama dibeberkan.

Mengosongkan Handel Koneksi

Sebelum memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_DBC, aplikasi harus memanggil SQLDisconnect untuk koneksi jika ada koneksi pada handel ini*.* Jika tidak, panggilan ke SQLFreeHandle mengembalikan SQL_ERROR dan koneksi tetap valid.

Untuk informasi selengkapnya, lihat Handle Koneksi dan Terputus dari Sumber Data atau Driver.

Membebaskan Handel Pernyataan

Panggilan ke SQLFreeHandle dengan HandleType SQL_HANDLE_STMT membebaskan semua sumber daya yang dialokasikan oleh panggilan ke SQLAllocHandle dengan HandleType SQL_HANDLE_STMT. Ketika aplikasi memanggil SQLFreeHandle untuk membebaskan pernyataan yang telah menunggu hasil, hasil yang tertunda akan dihapus. Ketika aplikasi membebaskan handel pernyataan, driver membebaskan empat deskriptor yang dialokasikan secara otomatis yang terkait dengan handel tersebut. Untuk informasi selengkapnya, lihat Pernyataan Menangani dan Membebaskan Handel Pernyataan.

Perhatikan bahwa SQLDisconnect secara otomatis menghilangkan pernyataan dan deskriptor apa pun yang terbuka pada koneksi.

Mengosongkan Handel Deskriptor

Panggilan ke SQLFreeHandle dengan HandleType SQL_HANDLE_DESC membebaskan handel deskriptor di Handle. Panggilan ke SQLFreeHandle tidak merilis memori apa pun yang dialokasikan oleh aplikasi yang dapat direferensikan oleh bidang pointer (termasuk SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, dan SQL_DESC_OCTET_LENGTH_PTR) dari catatan deskriptor apa pun dari Handle. Memori yang dialokasikan oleh driver untuk bidang yang bukan bidang penunjuk dibebaskan ketika handel dibebaskan. Ketika handel deskriptor yang dialokasikan pengguna dikosongkan, semua pernyataan bahwa handel yang dibeberkan telah dikaitkan dengan kembali ke handel deskriptor yang dialokasikan secara otomatis.

Nota

Driver ODBC 2*.x* tidak mendukung pengosongan handel deskriptor, sama seperti mereka tidak mendukung pengalokasian handel deskriptor.

Perhatikan bahwa SQLDisconnect secara otomatis menghilangkan pernyataan dan deskriptor apa pun yang terbuka pada koneksi. Ketika aplikasi membebaskan handel pernyataan, driver membebaskan semua deskriptor yang dihasilkan secara otomatis yang terkait dengan handel tersebut.

Untuk informasi selengkapnya tentang deskriptor, lihat Deskriptor.

Contoh Kode

Untuk sampel kode tambahan, lihat SQLBrowseConnect dan SQLConnect.

Kode

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

Untuk informasi tentang	Lihat
Mengalokasikan handel	Fungsi SQLAllocHandle
Membatalkan pemrosesan pernyataan	Fungsi SQLCancel
Mengatur nama kursor	Fungsi SQLSetCursorName

Lihat Juga

Referensi API ODBC
File Header ODBC
Program ODBC Sampel

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-01-02