Fungsi SQLFreeHandle
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLFreeHandle membebaskan sumber daya yang terkait dengan lingkungan, koneksi, pernyataan, atau handel deskriptor tertentu.
Catatan
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 Memetakan Fungsi Penggantian untuk Kompatibilitas Mundur Aplikasi.
Sintaks
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 Kumpulan Koneksi di Driver 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 coba dibebaskan oleh SQLFreeHandle tetapi tidak bisa. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLFreeHandle dan menjelaskan masing-masing 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 HandleType of SQL_HANDLE_DBC harus dipanggil untuk setiap koneksi sebelum memanggil SQLFreeHandle dengan HandleType of 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 dikembalikan SQL_NEED_DATA. 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 | Kesalahan waktu habis 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 of SQL_HANDLE_ENV, aplikasi harus memanggil SQLFreeHandle dengan HandleType of 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 Menangani Lingkungan dan Mengalokasikan Handel 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 dibeberkan. 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 of 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 Handel Koneksi dan Pemutusan sambungan dari Sumber Data atau Driver.
Membebaskan Handel Pernyataan
Panggilan ke SQLFreeHandle dengan HandleType of 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 memiliki hasil yang tertunda, 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 Menangani Pernyataan 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 of 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 pendeskripsi Handle apa pun. 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.
Catatan
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;
}
}
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengalokasikan handel | Fungsi SQLAllocHandle |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCance |
| Mengatur nama kursor | Fungsi SQLSetCursorName |