Fungsi SQLCancel
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLCancel membatalkan pemrosesan pada pernyataan.
Untuk membatalkan pemrosesan pada koneksi atau pernyataan, gunakan Fungsi SQLCancelHandle.
Sintaks
SQLRETURN SQLCancel(
SQLHSTMT StatementHandle);
Argumen
StatementHandle
[Input] Handel pernyataan.
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLCancel 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 umumnya dikembalikan oleh SQLCancel 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 dalam argumen *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 fungsi SQLCancel dipanggil. (DM) Operasi pembatalan gagal karena operasi asinkron sedang berlangsung pada handel koneksi yang terkait dengan StatementHandle. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY018 | Permintaan pembatalan yang ditolak server | Server menolak permintaan pembatalan. |
| 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) Driver yang terkait dengan StatementHandle tidak mendukung fungsi. |
Komentar
SQLCancel dapat membatalkan jenis pemrosesan berikut pada pernyataan:
Fungsi yang berjalan secara asinkron pada pernyataan.
Fungsi pada pernyataan yang membutuhkan data.
Fungsi yang berjalan pada pernyataan pada utas lain.
Di ODBC 2.x, jika aplikasi memanggil SQLCancel ketika tidak ada pemrosesan yang dilakukan pada pernyataan, SQLCancel memiliki efek yang sama dengan SQLFreeStmt dengan opsi SQL_CLOSE; perilaku ini ditentukan hanya untuk kelengkapan dan aplikasi harus memanggil SQLFreeStmt atau SQLCloseCursor untuk menutup kursor .
Ketika SQLCancel dipanggil untuk membatalkan fungsi yang berjalan secara asinkron dalam pernyataan atau fungsi pada pernyataan yang membutuhkan data, catatan diagnostik yang diposting oleh fungsi yang dibatalkan dihapus, dan SQLCancel memposting catatan diagnostiknya sendiri; ketika SQLCancel dipanggil untuk membatalkan fungsi yang berjalan pada pernyataan pada utas lain, namun, itu tidak menghapus catatan diagnostik dari fungsi yang dibatalkan dan tidak memposting catatan diagnostiknya sendiri.
Membatalkan Pemrosesan Asinkron
Setelah aplikasi memanggil fungsi secara asinkron, aplikasi memanggil fungsi berulang kali untuk menentukan apakah telah selesai diproses. Jika fungsi masih diproses, fungsi akan mengembalikan SQL_STILL_EXECUTING. Jika fungsi telah selesai diproses, fungsi mengembalikan kode yang berbeda.
Setelah panggilan apa pun ke fungsi yang mengembalikan SQL_STILL_EXECUTING, aplikasi dapat memanggil SQLCancel untuk membatalkan fungsi. Jika permintaan pembatalan berhasil, driver akan mengembalikan SQL_SUCCESS. Pesan ini tidak menunjukkan bahwa fungsi benar-benar dibatalkan; ini menunjukkan bahwa permintaan pembatalan diproses. Kapan atau jika fungsi benar-benar dibatalkan bergantung pada driver dan bergantung pada sumber data. Aplikasi harus terus memanggil fungsi asli sampai kode pengembalian tidak SQL_STILL_EXECUTING. Jika fungsi berhasil dibatalkan, kode pengembalian SQL_ERROR dan SQLSTATE HY008 (Operasi dibatalkan). Jika fungsi menyelesaikan pemrosesan normalnya, kode pengembalian SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO jika fungsi berhasil atau SQL_ERROR dan SQLSTATE selain HY008 (Operasi dibatalkan) jika fungsi gagal.
Catatan
Dalam ODBC 3.5, panggilan ke SQLCancel ketika tidak ada pemrosesan yang dilakukan pada pernyataan tidak diperlakukan sebagai SQLFreeStmt dengan opsi SQL_CLOSE, tetapi tidak berpengaruh sama sekali. Untuk menutup kursor, aplikasi harus memanggil SQLCloseCursor, bukan SQLCancel.
Untuk informasi selengkapnya tentang pemrosesan asinkron, lihat Eksekusi Asinkron.
Membatalkan Fungsi yang Membutuhkan Data
Setelah SQLExecute atau SQLExecDirect mengembalikan SQL_NEED_DATA dan sebelum data dikirim untuk semua parameter data-at-execution, aplikasi dapat memanggil SQLCancel untuk membatalkan eksekusi pernyataan. Setelah pernyataan dibatalkan, aplikasi dapat memanggil SQLExecute atau SQLExecDirect lagi. Untuk informasi selengkapnya, lihat SQLBindParameter.
Setelah SQLBulkOperations atau SQLSetPos mengembalikan SQL_NEED_DATA dan sebelum data dikirim untuk semua kolom data yang sedang dieksekusi, aplikasi dapat memanggil SQLCancel untuk membatalkan operasi. Setelah operasi dibatalkan, aplikasi dapat memanggil SQLBulkOperations atau SQLSetPos lagi; membatalkan tidak memengaruhi status kursor atau posisi kursor saat ini. Untuk informasi selengkapnya, lihat SQLBulkOperations atau SQLSetPos.
Membatalkan Eksekusi Fungsi pada Utas Lain
Dalam aplikasi multithread, aplikasi dapat membatalkan fungsi yang berjalan di utas lain. Untuk membatalkan fungsi, aplikasi memanggil SQLCancel dengan handel pernyataan yang sama dengan yang digunakan oleh fungsi target, tetapi pada utas yang berbeda. Bagaimana fungsi dibatalkan tergantung pada driver dan sistem operasi. Seperti dalam membatalkan fungsi yang berjalan secara asinkron, kode pengembalian SQLCancel hanya menunjukkan apakah driver berhasil memproses permintaan. Hanya SQL_SUCCESS atau SQL_ERROR yang dapat dikembalikan; tidak ada informasi diagnostik yang dikembalikan. Jika fungsi asli dibatalkan, fungsi mengembalikan SQL_ERROR dan SQLSTATE HY008 (Operasi dibatalkan).
Jika pernyataan SQL dijalankan ketika SQLCancel dipanggil pada utas lain untuk membatalkan eksekusi pernyataan, eksekusi dapat berhasil dan mengembalikan SQL_SUCCESS sementara pembatalan juga berhasil. Dalam hal ini, Driver Manager mengasumsikan bahwa kursor yang dibuka oleh eksekusi pernyataan ditutup oleh pembatalan, sehingga aplikasi tidak akan dapat menggunakan kursor.
Untuk informasi selengkapnya tentang utas, lihat Multithreading.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke parameter | Fungsi SQLBindParameter |
| Melakukan operasi penyisipan massal atau pembaruan | Fungsi SQLBulkOperations |
| Membatalkan fungsi yang berjalan secara asinkron pada handel koneksi, selain fungsionalitas SQLCancel. | Fungsi SQLCancelHandle |
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Membebaskan handel pernyataan | SQLFreeStmt |
| Mendapatkan bidang rekaman diagnostik atau bidang header diagnostik | Fungsi SQLGetDiagField |
| Mendapatkan beberapa bidang struktur data diagnostik | Fungsi SQLGetDiagRec |
| Mengembalikan parameter berikutnya untuk mengirim data | Fungsi SQLParamData |
| Mengirim data parameter pada waktu eksekusi | Fungsi SQLPutData |
| Memosisikan kursor dalam himpunan baris, menyegarkan data di himpunan baris, atau memperbarui atau menghapus data dalam kumpulan hasil | Fungsi SQLSetPos |