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

Lihat Juga

Referensi API ODBC
File Header ODBC