Fungsi SQLEndtran
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLEndTran meminta operasi penerapan atau pembatalan untuk semua operasi aktif pada semua pernyataan yang terkait dengan koneksi. SQLEndTran juga dapat meminta agar operasi penerapan atau pembatalan dilakukan untuk semua koneksi yang terkait dengan lingkungan.
Catatan
Untuk informasi selengkapnya tentang apa Manajer Driver memetakan fungsi ini ketika ODBC 3.aplikasi x bekerja dengan ODBC 2.x driver, lihat Memetakan Fungsi Penggantian untuk Kompatibilitas Aplikasi Mundur.
Sintaks
SQLRETURN SQLEndTran(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT CompletionType);
Argumen
HandleType
[Input] Menangani pengidentifikasi jenis. Berisi SQL_HANDLE_ENV (jika Handel adalah handel lingkungan) atau SQL_HANDLE_DBC (jika Handel adalah handel koneksi).
Menangani
[Input] Handel, dari jenis yang ditunjukkan oleh HandleType, menunjukkan cakupan transaksi. Lihat "Komentar" untuk informasi selengkapnya.
CompletionType
[Input] Salah satu dari dua nilai berikut:
SQL_COMMIT SQL_ROLLBACK
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, atau SQL_STILL_EXECUTING.
Diagnostik
Saat SQLEndTran mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType dan Handle yang sesuai. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLEndTran 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.) |
| 08003 | Koneksi tidak terbuka | (DM) HandleType SQL_HANDLE_DBC, dan Handel tidak dalam status tersambung. |
| 08007 | Kegagalan koneksi selama transaksi | HandleType SQL_HANDLE_DBC, dan koneksi yang terkait dengan Handle gagal selama eksekusi fungsi, dan tidak dapat ditentukan apakah COMMIT atau ROLLBACK yang diminta terjadi sebelum kegagalan. |
| 25S01 | Status transaksi tidak diketahui | Satu atau beberapa koneksi dalam Handle gagal menyelesaikan transaksi dengan hasil yang ditentukan, dan hasilnya tidak diketahui. |
| 25S02 | Transaksi masih aktif | Driver tidak dapat menjamin bahwa semua pekerjaan dalam transaksi global dapat diselesaikan secara atomik, dan transaksi masih aktif. |
| 25S03 | Transaksi digulung balik | Driver tidak dapat menjamin bahwa semua pekerjaan dalam transaksi global dapat diselesaikan secara atomik, dan semua pekerjaan dalam transaksi aktif di Handle digulung balik. |
| 40001 | Kegagalan serialisasi | Transaksi digulung balik karena kebuntuan sumber daya dengan transaksi lain. |
| 40002 | Pelanggaran batasan integritas | CompletionType SQL_COMMIT, dan komitmen perubahan menyebabkan pelanggaran batasan integritas. Akibatnya, transaksi digulung balik. |
| 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 *szMessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY008 | Operasi dibatalkan | Pemrosesan asinkron diaktifkan untuk ConnectionHandle. Fungsi ini dipanggil, dan sebelum selesai menjalankan Fungsi SQLCancelHandle dipanggil pada ConnectionHandle. Kemudian fungsi dipanggil lagi pada ConnectionHandle. Fungsi ini dipanggil, dan sebelum selesai menjalankan SQLCancelHandle dipanggil pada ConnectionHandle dari utas yang berbeda dalam aplikasi multithread. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel pernyataan yang terkait dengan ConnectionHandle dan masih dijalankan ketika SQLEndTran dipanggil. (DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk ConnectionHandle dan masih dijalankan ketika fungsi ini dipanggil. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk handel pernyataan yang terkait dengan ConnectionHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. (DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk Handle with HandleType yang diatur ke SQL_HANDLE_DBC dan masih dijalankan ketika fungsi ini dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan Handle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. |
| HY012 | Kode operasi transaksi tidak valid | (DM) Nilai yang ditentukan untuk argumen CompletionType tidak SQL_COMMIT atau SQL_ROLLBACK. |
| 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 | (DM) Nilai yang ditentukan untuk argumen HandleType tidak SQL_HANDLE_ENV atau SQL_HANDLE_DBC. |
| HY115 | SQLEndTran tidak diizinkan untuk lingkungan yang berisi koneksi dengan eksekusi fungsi asinkron diaktifkan | (DM) HandleType tidak dapat diatur ke SQL_HANDLE_ENV jika eksekusi asinkron fungsi koneksi diaktifkan untuk koneksi di lingkungan. |
| 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 bagian Komentar dari topik ini. |
| HYC00 | Fitur opsional tidak diimplementasikan | Driver atau sumber data tidak mendukung operasi ROLLBACK . |
| 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 ConnectionHandle tidak mendukung fungsi. |
| IM017 | Polling dinonaktifkan dalam mode pemberitahuan asinkron | Setiap kali model pemberitahuan digunakan, polling dinonaktifkan. |
| IM018 | SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini. | Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi. |
Komentar
Untuk ODBC 3.driver x , jika HandleType SQL_HANDLE_ENV dan Handle adalah handel lingkungan yang valid, maka Driver Manager akan memanggil SQLEndTran di setiap driver yang terkait dengan lingkungan. Argumen Handel untuk panggilan ke driver akan menjadi handel lingkungan driver. Untuk ODBC 2.driver x , jika HandleType SQL_HANDLE_ENV dan Handle adalah handel lingkungan yang valid, dan ada beberapa koneksi dalam keadaan terhubung di lingkungan tersebut, maka Manajer Driver akan memanggil SQLTransact di driver sekali untuk setiap koneksi dalam status terhubung di lingkungan tersebut. Argumen Handel di setiap panggilan akan menjadi handel koneksi. Dalam kedua kasus, driver akan mencoba untuk menerapkan atau mengembalikan transaksi, tergantung pada nilai CompletionType, pada semua koneksi yang berada dalam status terhubung pada lingkungan tersebut. Koneksi yang tidak aktif tidak memengaruhi transaksi.
Catatan
SQLEndTran tidak dapat digunakan untuk menerapkan atau mengembalikan transaksi pada lingkungan bersama. SQLSTATE HY092 (Pengidentifikasi atribut/opsi tidak valid) akan dikembalikan jika SQLEndTran dipanggil dengan Handle yang diatur ke handel lingkungan bersama atau handel koneksi pada lingkungan bersama.
Driver Manager akan mengembalikan SQL_SUCCESS hanya jika menerima SQL_SUCCESS untuk setiap koneksi. Jika Driver Manager menerima SQL_ERROR pada satu atau beberapa koneksi, Driver Manager mengembalikan SQL_ERROR ke aplikasi, dan informasi diagnostik ditempatkan dalam struktur data diagnostik lingkungan. Untuk menentukan koneksi atau koneksi mana yang gagal selama operasi penerapan atau pembatalan, aplikasi dapat memanggil SQLGetDiagRec untuk setiap koneksi.
Catatan
Driver Manager tidak mensimulasikan transaksi global di semua koneksi dan oleh karena itu tidak menggunakan protokol penerapan dua fase.
Jika CompletionType SQL_COMMIT, SQLEndTran mengeluarkan permintaan penerapan untuk semua operasi aktif pada pernyataan apa pun yang terkait dengan koneksi yang terpengaruh. Jika CompletionType SQL_ROLLBACK, SQLEndTran mengeluarkan permintaan pembatalan untuk semua operasi aktif pada pernyataan apa pun yang terkait dengan koneksi yang terpengaruh. Jika tidak ada transaksi yang aktif, SQLEndTran mengembalikan SQL_SUCCESS tanpa berpengaruh pada sumber data apa pun. Untuk informasi selengkapnya, lihat Menerapkan dan Menggulung Balik Transaksi.
Jika driver dalam mode penerapan manual (dengan memanggil SQLSetConnectAttr dengan atribut SQL_ATTR_AUTOCOMMIT diatur ke SQL_AUTOCOMMIT_OFF), transaksi baru secara implisit dimulai ketika pernyataan SQL yang dapat dimuat dalam transaksi dijalankan terhadap sumber data saat ini. Untuk informasi selengkapnya, lihat Mode Penerapan.
Untuk menentukan bagaimana operasi transaksi memengaruhi kursor, aplikasi memanggil SQLGetInfo dengan opsi SQL_CURSOR_ROLLBACK_BEHAVIOR dan SQL_CURSOR_COMMIT_BEHAVIOR. Untuk informasi selengkapnya, lihat paragraf berikut dan juga lihat Efek Transaksi pada Kursor dan Pernyataan yang Disiapkan.
Jika nilai SQL_CURSOR_ROLLBACK_BEHAVIOR atau SQL_CURSOR_COMMIT_BEHAVIOR sama dengan SQL_CB_DELETE, SQLEndTran menutup dan menghapus semua kursor terbuka pada semua pernyataan yang terkait dengan koneksi dan membuang semua hasil yang tertunda. SQLEndTran meninggalkan pernyataan apa pun yang ada dalam status dialokasikan (tidak siap) ; aplikasi dapat menggunakannya kembali untuk permintaan SQL berikutnya atau dapat memanggil SQLFreeStmt atau SQLFreeHandle dengan HandleType SQL_HANDLE_STMT untuk membatalkan alokasinya.
Jika nilai SQL_CURSOR_ROLLBACK_BEHAVIOR atau SQL_CURSOR_COMMIT_BEHAVIOR sama dengan SQL_CB_CLOSE, SQLEndTran menutup semua kursor terbuka pada semua pernyataan yang terkait dengan koneksi. SQLEndTran meninggalkan pernyataan apa pun yang ada dalam keadaan siap; aplikasi dapat memanggil SQLExecute untuk pernyataan yang terkait dengan koneksi tanpa terlebih dahulu memanggil SQLPrepare.
Jika nilai SQL_CURSOR_ROLLBACK_BEHAVIOR atau SQL_CURSOR_COMMIT_BEHAVIOR sama dengan SQL_CB_PRESERVE, SQLEndTran tidak memengaruhi kursor terbuka yang terkait dengan koneksi. Kursor tetap berada di baris yang mereka arahkan sebelum panggilan ke SQLEndTran.
Untuk driver dan sumber data yang mendukung transaksi, memanggil SQLEndTran dengan SQL_COMMIT atau SQL_ROLLBACK ketika tidak ada transaksi yang aktif mengembalikan SQL_SUCCESS (menunjukkan bahwa tidak ada pekerjaan yang harus dilakukan atau digulung balik) dan tidak berpengaruh pada sumber data.
Ketika driver dalam mode autocommit, Driver Manager tidak memanggil SQLEndTran di driver. SQLEndTran selalu mengembalikan SQL_SUCCESS terlepas dari apakah itu dipanggil dengan CompletionType SQL_COMMIT atau SQL_ROLLBACK.
Driver atau sumber data yang tidak mendukung transaksi (opsi SQLGetInfoSQL_TXN_CAPABLE SQL_TC_NONE) secara efektif selalu dalam mode autocommit dan oleh karena itu selalu mengembalikan SQL_SUCCESS untuk SQLEndTran apakah mereka dipanggil dengan CompletionType SQL_COMMIT atau SQL_ROLLBACK atau tidak. Driver dan sumber data tersebut tidak benar-benar mengembalikan transaksi ketika diminta untuk melakukannya.
Status Ditangguhkan
Di Driver Manager yang dirilis sebelum Windows 7, transaksi aktif jika SQLEndTran mengembalikan SQL_ERROR dari driver. Namun, ada kemungkinan bahwa transaksi telah berhasil dilakukan di server, tetapi driver pada klien belum diberi tahu (misalnya, karena terjadi kesalahan jaringan). Ini akan meninggalkan koneksi dalam keadaan buruk. Dimulai dengan Windows 7, ketika SQLEndTran kembali SQL_ERROR, koneksi mungkin dalam status ditangguhkan. Dalam status ditangguhkan, dimungkinkan untuk memanggil fungsi baca-saja. Akhirnya, aplikasi harus memanggil SQLDisconnect pada koneksi yang ditangguhkan untuk merilis sumber daya.
Jika semua kondisi berikut ini benar, koneksi akan dimasukkan ke dalam status ditangguhkan:
Driver mengembalikan SQL_ERROR dari SQLEndTran.
Driver adalah ODBC versi 3.8, atau yang lebih baru.
Versi aplikasi adalah 3.8 atau yang lebih baru; atau aplikasi ODBC 2.x atau 3.x yang dikompilasi ulang berhasil membatalkan fungsi SQLEndTran melalui SQLCancelHandle.
Driver tidak mengembalikan salah satu pesan berikut, yang mengonfirmasi bahwa transaksi tidak selesai:
25S03: Transaksi digulung balik
40001: Kegagalan serialisasi
40002: Batasan integritas
HYC00: Fitur opsional tidak diimplementasikan
Jika SQLEndTran dipanggil pada handel lingkungan dan salah satu koneksinya memenuhi kondisi di atas, semua koneksi yang terhubung ke driver yang sama akan dimasukkan ke dalam status ditangguhkan.
Setelah aplikasi memanggil SQLDisconnect pada koneksi yang ditangguhkan, koneksi dapat digunakan untuk menyambungkan kembali ke sumber data lain atau sumber data yang sama.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Membatalkan fungsi yang berjalan secara asinkron pada handel koneksi. | Fungsi SQLCancelHandle |
| Mengembalikan informasi tentang driver atau sumber data | Fungsi SQLGetInfo |
| Mengosongkan handel | Fungsi SQLFreeHandle |
| Membebaskan handel pernyataan | Fungsi SQLFreeStmt |
Lihat Juga
Referensi API ODBC
File Header ODBC
Eksekusi Asinkron (Metode Polling)
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk