Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Summary
SQLFreeStmt menghentikan pemrosesan yang terkait dengan pernyataan tertentu, menutup kursor terbuka yang terkait dengan pernyataan tersebut, membuang hasil yang tertunda, atau, secara opsional, membebaskan semua sumber daya yang terkait dengan handle pernyataan tersebut.
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
StatementHandle
[Input] Handle pernyataan
Option
[Input] Salah satu opsi berikut:
SQL_ TUTUP: Menutup kursor yang terkait dengan StatementHandle (jika sudah didefinisikan) 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 pada aplikasi. SQLCloseCursor juga dapat dipanggil untuk menutup kursor. Untuk informasi lebih lanjut, lihat Menutup Kursor.
SQL_DROP: Opsi ini sudah tidak digunakan. Pemanggilan ke SQLFreeStmt dengan Opsi SQL_DROP dipetakan di Driver Manager ke SQLFreeHandle.
SQL_UNBIND: Mengatur field SQL_DESC_COUNT ARD ke 0, melepaskan semua buffer kolom yang terikat oleh SQLBindCol untuk StatementHandle yang diberikan. Ini tidak membuka ikatan kolom bookmark; untuk melakukan itu, bidang SQL_DESC_DATA_PTR pada ARD untuk kolom bookmark diatur ke NULL. Perhatikan bahwa jika operasi ini dilakukan pada deskriptor yang dialokasikan secara eksplisit dan dibagikan oleh lebih dari satu pernyataan, operasi ini akan memengaruhi pengikatan semua pernyataan yang berbagi deskriptor tersebut. Untuk informasi lebih lanjut, lihat Ikhtisar Pengambilan Hasil (Dasar).
SQL_RESET_PARAMS: Mengatur field 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 dan dibagikan oleh lebih dari satu pernyataan, operasi ini akan memengaruhi pengikatan semua pernyataan yang berbagi deskriptor tersebut. Untuk informasi lebih lanjut, lihat Parameter Pengikatan.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostics
Ketika SQLFreeStmt mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE yang terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan HandleStatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLFreeStmt dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATE 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 berjalan saat SQLFreeStmt dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil dengan Option diatur ke SQL_RESET_PARAMS sebelum data diambil untuk semua parameter streaming. (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 | Tipe opsi di luar jangkauan | (DM) Nilai yang ditentukan untuk argumen Opsi bukan: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | Waktu tunggu koneksi habis | 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 SQLFreeStmt dengan SQL_CLOSE tidak memengaruhi aplikasi jika tidak ada kursor yang terbuka pada pernyataan. Jika tidak ada kursor yang terbuka, pemanggilan ke SQLCloseCursor mengembalikan SQLSTATE 24000 (Status kursor tidak valid).
Sebuah aplikasi tidak boleh menggunakan handle pernyataan setelah dibebaskan; Driver Manager tidak memeriksa validitas handle dalam panggilan fungsi.
Example
Ini adalah praktik pemrograman yang baik untuk membebaskan handle. Namun, untuk memudahkan, contoh berikut tidak menyertakan kode yang membebaskan handle yang dialokasikan. Untuk contoh cara membebaskan handle, 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 mengenai | Lihat |
|---|---|
| Mengalokasikan pegangan | Fungsi SQLAllocHandle |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Menutup kursor | Fungsi SQLCloseCursor |
| Membebaskan pegangan | Fungsi SQLFreeHandle |
| Mengatur nama kursor | Fungsi SQLSetCursorName |