Fungsi SQLCancelHandle

  • Artikel

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.8: Tidak Ada

Diharapkan sebagian besar driver ODBC 3.8 (dan yang lebih baru) akan menerapkan fungsi ini. Jika driver tidak, panggilan ke SQLCancelHandle dengan handel koneksi dalam parameter Handle akan mengembalikan SQL_ERROR dengan SQLSTATE IM001 dan pesan 'Driver tidak mendukung fungsi ini'' Panggilan ke SQLCancelHandle dengan handel pernyataan karena parameter Handle akan dipetakan ke panggilan ke SQLCancel oleh Driver Manager dan dapat diproses jika driver mengimplementasikan SQLCancel. Aplikasi dapat menggunakan SQLGetFunctions untuk menentukan apakah driver mendukung SQLCancelHandle.

Ringkasan
SQLCancelHandle membatalkan pemrosesan pada koneksi atau pernyataan. Driver Manager memetakan panggilan ke SQLCancelHandle ke panggilan ke SQLCancel saat HandleType SQL_HANDLE_STMT.

Sintaks

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

Argumen

HandleType
[Input] Jenis handel tempat pemrosesan cacel. Nilai yang valid adalah SQL_HANDLE_DBC atau SQL_HANDLE_STMT.

Menangani
[Input] Handel untuk membatalkan pemrosesan.

Jika Handle bukan handel yang valid dari jenis yang ditentukan oleh HandleType, SQLCancelHandle mengembalikan SQL_INVALID_HANDLE.

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Ketika SQLCancelHandle mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan handelpernyataan atau HandleType SQL_HANDLE_DBC dan handel koneksi.

Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLCancelHandle 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 Fungsi terkait pernyataan yang dijalankan secara asinkron dipanggil untuk salah satu handel pernyataan yang terkait dengan Handle, dan HandleType diatur ke SQL_HANDLE_DBC. Fungsi asinkron masih dijalankan ketika SQLCancelHandle dipanggil.

(DM) Argumen HandleType SQL_HANDLE_STMT; fungsi eksekusi asinkron dipanggil pada handel koneksi terkait; dan fungsi masih dijalankan ketika fungsi ini dipanggil.

(DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan Handle dan HandleType diatur ke SQL_HANDLE_DBC, dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan.

SQLBrowseConnect dipanggil untuk ConnectionHandle, dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum proses penjelajahan selesai.
HY013 Kesalahan manajemen memori Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
HY092 Pengidentifikasi atribut/opsi tidak valid HandleType diatur ke SQL_HANDLE_ENV atau SQL_HANDLE_DESC.
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 Handel tidak mendukung fungsi.

Jika SQLCancelHandle dipanggil dengan HandleType diatur ke SQL_HANDLE_STMT, SQLSTATE dapat dikembalikan oleh fungsi SQLCancel.

Komentar

Fungsi ini mirip dengan SQLCancel tetapi dapat mengambil pegangan koneksi atau pernyataan sebagai parameter daripada hanya handel pernyataan. Driver Manager memetakan panggilan ke SQLCancelHandle ke panggilan ke SQLCancel saat HandleType SQL_HANDLE_STMT. Ini memungkinkan aplikasi untuk menggunakan SQLCancelHandle untuk membatalkan operasi pernyataan meskipun driver tidak menerapkan SQLCancelHandle.

Untuk informasi selengkapnya tentang membatalkan operasi pernyataan, lihat Fungsi SQLCancel.

Jika tidak ada operasi yang sedang berlangsung pada Menangani panggilan ke SQLCancelHandle tidak berpengaruh.

SQLCancelHandle pada handel koneksi dapat membatalkan jenis pemrosesan berikut:

  • Fungsi yang berjalan secara asinkron pada koneksi.

  • Fungsi yang berjalan pada handel koneksi pada utas lain.

Ketika SQLCancelHandle dipanggil untuk membatalkan fungsi yang berjalan secara asinkron dalam koneksi, rekaman diagnostik yang diposting oleh SQLCancelHandle ditambahkan ke yang dikembalikan oleh operasi yang dibatalkan; SQLCancelHandle tidak mengembalikan rekaman diagnostik, namun, saat membatalkan fungsi yang berjalan pada koneksi pada utas lain.

Menggunakan SQLCancelHandle untuk membatalkan SQLEndTran dapat menempatkan koneksi dalam status ditangguhkan. Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran.

Catatan

Untuk informasi tentang cara menggunakan SQLCancelHandle dalam aplikasi yang akan disebarkan pada sistem operasi Windows yang lebih lama dari Windows 7, lihat Matriks Kompatibilitas.

Jika fungsi mengembalikan SQL_STILL_EXECUTING, aplikasi dapat memanggil SQLCancelHandle untuk membatalkan operasi. Jika permintaan pembatalan berhasil, SQLCancelHandle mengembalikan SQL_SUCCESS. Ini tidak berarti bahwa fungsi asli dibatalkan; ini menunjukkan bahwa permintaan pembatalan diproses. Driver dan sumber data menentukan kapan atau apakah operasi dibatalkan. Aplikasi harus terus memanggil fungsi asli sampai kode pengembalian tidak SQL_STILL_EXECUTING. Jika fungsi asli dibatalkan, kode pengembalian SQL_ERROR dan SQLSTATE HY008 (Operasi dibatalkan). Jika fungsi asli menyelesaikan pemrosesan normalnya (tidak dibatalkan), kode pengembalian SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO, atau SQL_ERROR dan SQLSTATE selain HY008 (Operasi dibatalkan), jika fungsi asli gagal.

Membatalkan Eksekusi Fungsi pada Utas Lain

Dalam aplikasi multithread, aplikasi dapat membatalkan operasi yang berjalan di utas lain. Untuk membatalkan operasi, aplikasi memanggil SQLCancelHandle dengan handel yang digunakan oleh fungsi, tetapi pada utas yang berbeda. Driver dan sistem operasi menentukan bagaimana operasi dibatalkan. Kode pengembalian SQLCancelHandle menunjukkan apakah driver memproses permintaan, mengembalikan SQL_SUCCESS atau SQL_ERROR (tidak ada informasi diagnostik yang dikembalikan). Jika pemrosesan pada fungsi asli dibatalkan, fungsi asli mengembalikan SQL_ERROR dan SQLSTATE HY008 (Operasi dibatalkan).

Jika fungsi sedang dijalankan ketika SQLCancelHandle dipanggil pada utas lain untuk membatalkan fungsi, fungsi dapat berhasil dan mengembalikan SQL_SUCCESS sebelum pembatalan dapat berlaku. Panggilan ke SQLCancelHandle tidak berpengaruh jika operasi selesai sebelum SQLCancelHandle dapat membatalkan operasi.

Untuk informasi tentang Lihat
Membatalkan fungsi yang berjalan secara asinkron pada handel pernyataan, membatalkan fungsi pada pernyataan yang membutuhkan data, atau membatalkan fungsi yang berjalan pada pernyataan di utas lain. Fungsi SQLCancel

Lihat Juga

Referensi API ODBC
File Header ODBC
Eksekusi Asinkron (Metode Polling)