Fungsi SQLFreeStmt
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLFreeStmt berhenti memproses yang terkait dengan pernyataan tertentu, menutup kursor terbuka yang terkait dengan pernyataan, membuang hasil yang tertunda, atau, secara opsional, membebaskan semua sumber daya yang terkait dengan handel pernyataan.
Sintaks
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Argumen
StatementHandle
[Input] Handel pernyataan
Opsi
[Input] Salah satu opsi berikut:
SQL_ TUTUP: Menutup kursor yang terkait dengan StatementHandle (jika ditentukan) dan membuang semua hasil yang tertunda. Aplikasi dapat membuka kembali kursor ini nanti dengan menjalankan pernyataan SELECT lagi dengan nilai parameter yang sama atau berbeda. Jika tidak ada kursor yang terbuka, opsi ini tidak berpengaruh untuk aplikasi. SQLCloseCursor juga dapat dipanggil untuk menutup kursor. Untuk informasi selengkapnya, lihat Menutup Kursor.
SQL_DROP: Opsi ini tidak digunakan lagi. Panggilan ke SQLFreeStmt dengan Opsi SQL_DROP dipetakan di Driver Manager ke SQLFreeHandle.
SQL_UNBIND: Mengatur bidang SQL_DESC_COUNT ARD ke 0, melepaskan semua buffer kolom yang terikat oleh SQLBindCol untuk StatementHandle yang diberikan. Ini tidak mengikat kolom marka buku; untuk melakukannya, bidang SQL_DESC_DATA_PTR ARD untuk kolom bookmark diatur ke NULL. Perhatikan bahwa jika operasi ini dilakukan pada deskriptor yang dialokasikan secara eksplisit yang dibagikan oleh lebih dari satu pernyataan, operasi akan memengaruhi pengikatan semua pernyataan yang berbagi deskriptor. Untuk informasi selengkapnya, lihat Gambaran Umum Pengambilan Hasil (Dasar).
SQL_RESET_PARAMS: Mengatur bidang SQL_DESC_COUNT APD ke 0, melepaskan semua buffer parameter yang ditetapkan oleh SQLBindParameter untuk StatementHandle yang diberikan. Jika operasi ini dilakukan pada deskriptor yang dialokasikan secara eksplisit yang dibagikan oleh lebih dari satu pernyataan, operasi ini akan memengaruhi pengikatan semua pernyataan yang berbagi deskriptor. Untuk informasi selengkapnya, lihat Parameter Pengikatan.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLFreeStmt mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLFreeStmt 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 |
|---|---|---|
| 01000 | Peringatan umum | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 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) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika SQLFreeStmt dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil dengan Opsi diatur ke SQL_RESET_PARAMS sebelum data diambil untuk semua parameter yang dialirkan. (DM) Fungsi eksekusi asinkron dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY092 | Jenis opsi di luar rentang | (DM) Nilai yang ditentukan untuk argumen Opsi bukan: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| 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) Driver yang terkait dengan StatementHandle tidak mendukung fungsi. |
Komentar
Memanggil SQLFreeStmt dengan opsi SQL_CLOSE setara dengan memanggil SQLCloseCursor, kecuali bahwa SQLFreeStmt dengan SQL_CLOSE tidak memengaruhi aplikasi jika tidak ada kursor yang terbuka pada pernyataan. Jika tidak ada kursor yang terbuka, panggilan ke SQLCloseCursor mengembalikan SQLSTATE 24000 (Status kursor tidak valid).
Aplikasi tidak boleh menggunakan handel pernyataan setelah dibeskan; Driver Manager tidak memeriksa validitas handel dalam panggilan fungsi.
Contoh
Ini adalah praktik pemrograman yang baik untuk handel gratis. Namun, untuk kesederhanaan, sampel berikut tidak menyertakan kode yang membebaskan handel yang dialokasikan. Untuk contoh cara mengosongkan handel, lihat Fungsi SQLFreeHandle.
// SQLFreeStmt.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
// declare and initialize the environment, connection, statement handles
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retCode = SQLFreeStmt(hstmt, SQL_CLOSE);
retCode = SQLFreeStmt(hstmt, SQL_UNBIND);
retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);
}
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengalokasikan handel | Fungsi SQLAllocHandle |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Menutup kursor | Fungsi SQLCloseCursor |
| Mengosongkan handel | Fungsi SQLFreeHandle |
| Mengatur nama kursor | Fungsi SQLSetCursorName |