Fungsi SQLCancelHandle

Kesuaian
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 di parameter Handle akan mengembalikan SQL_ERROR dengan SQLSTATE IM001 dan pesan 'Driver tidak mendukung fungsi ini'' Panggilan A untuk SQLCancelHandle dengan handel pernyataan sebagai 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.

Sintaksis

  
SQLRETURN SQLCancelHandle(  
      SQLSMALLINT  HandleType,  
      SQLHANDLE    Handle);

Argumen

HandleType
[Input] Jenis handel untuk membatalkan pemrosesan. 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

Saat SQLCancelHandle mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan pernyataan menangani Menangani atau HandleType SQL_HANDLE_DBC dan handel koneksi Handle.

Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLCancelHandle dan menjelaskan masing-masing nilai 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 mengembalikan 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	Batas waktu 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 Handle tidak mendukung fungsi.

Jika SQLCancelHandle dipanggil dengan HandleType diatur ke SQL_HANDLE_STMT, SQLSTATE dapat mengembalikan SQLSTATE apa pun yang 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 bahkan jika driver tidak menerapkan SQLCancelHandle.

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

Jika tidak ada operasi yang sedang berlangsung pada Handle 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, catatan 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 membuat koneksi dalam status ditangguhkan. Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran.

Nota

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

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 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)

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-01-02