Bagikan melalui


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

Handel
[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

Mengembalikan

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 SQLGetInfo SQL_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.

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)