Fungsi SQLGetDiagRec
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLGetDiagRec mengembalikan nilai saat ini dari beberapa bidang rekaman diagnostik yang berisi informasi kesalahan, peringatan, dan status. Tidak seperti SQLGetDiagField, yang mengembalikan satu bidang diagnostik per panggilan, SQLGetDiagRec mengembalikan beberapa bidang catatan diagnostik yang umum digunakan, termasuk SQLSTATE, kode kesalahan asli, dan teks pesan diagnostik.
Sintaks
SQLRETURN SQLGetDiagRec(
SQLSMALLINT HandleType,
SQLHANDLE Handle,
SQLSMALLINT RecNumber,
SQLCHAR * SQLState,
SQLINTEGER * NativeErrorPtr,
SQLCHAR * MessageText,
SQLSMALLINT BufferLength,
SQLSMALLINT * TextLengthPtr);
Argumen
HandleType
[Input] Pengidentifikasi jenis handel yang menjelaskan jenis handel yang diagnostiknya diperlukan. Harus salah satu hal berikut:
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN handel hanya digunakan oleh Driver Manager dan driver. Aplikasi tidak boleh menggunakan jenis handel ini. Untuk informasi selengkapnya tentang SQL_HANDLE_DBC_INFO_TOKEN, lihat Mengembangkan Kesadaran Kumpulan Koneksi di Driver ODBC.
Menangani
[Input] Handel untuk struktur data diagnostik, dari jenis yang ditunjukkan oleh HandleType. Jika HandleType SQL_HANDLE_ENV, Handle dapat berupa handel lingkungan bersama atau yang tidak dibagikan.
RecNumber
[Input] Menunjukkan rekaman status tempat aplikasi mencari informasi. Rekaman status diberi nomor dari 1.
SQLState
[Output] Penunjuk ke buffer untuk mengembalikan kode SQLSTATE lima karakter (dan mengakhiri NULL) untuk rekaman diagnostik RecNumber. Dua karakter pertama menunjukkan kelas ; tiga berikutnya menunjukkan subkelas. Informasi ini terkandung dalam bidang diagnostik SQL_DIAG_SQLSTATE. Untuk informasi selengkapnya, lihat SQLSTATEs.
NativeErrorPtr
[Output] Penunjuk ke buffer untuk mengembalikan kode kesalahan asli, khusus untuk sumber data. Informasi ini terkandung dalam bidang diagnostik SQL_DIAG_NATIVE.
Teks Pesan
[Output] Penunjuk ke buffer untuk mengembalikan string teks pesan diagnostik. Informasi ini terkandung dalam bidang diagnostik SQL_DIAG_MESSAGE_TEXT. Untuk format string, lihat Pesan Diagnostik.
Jika MessageText ADALAH NULL, TextLengthPtr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh MessageText.
BufferLength
[Input] Panjang buffer *MessageText dalam karakter. Tidak ada panjang maksimum teks pesan diagnostik.
TextLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total karakter (tidak termasuk jumlah karakter yang diperlukan untuk karakter penghentian null) yang tersedia untuk dikembalikan dalam *MessageText. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari BufferLength, teks pesan diagnostik di *MessageText dipotong menjadi BufferLength dikurangi panjang karakter penghentian null.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA, atau SQL_INVALID_HANDLE.
Diagnostik
SQLGetDiagRec tidak memposting rekaman diagnostik untuk dirinya sendiri. Ini menggunakan nilai pengembalian berikut untuk melaporkan hasil eksekusinya sendiri:
SQL_SUCCESS: Fungsi berhasil mengembalikan informasi diagnostik.
SQL_SUCCESS_WITH_INFO: Buffer *MessageText terlalu kecil untuk menahan pesan diagnostik yang diminta. Tidak ada catatan diagnostik yang dihasilkan. Untuk menentukan bahwa pemotongan terjadi, aplikasi harus membandingkan BufferLength dengan jumlah byte aktual yang tersedia, yang ditulis ke *TextLengthPtr.
SQL_INVALID_HANDLE: Handel yang ditunjukkan oleh HandleType dan Handle bukan handel yang valid.
SQL_ERROR: Salah satu hal berikut ini terjadi:
RecNumber negatif atau 0.
BufferLength kurang dari nol.
Saat menggunakan pemberitahuan asinkron, operasi asinkron pada handel tidak selesai.
SQL_NO_DATA: RecNumber lebih besar dari jumlah rekaman diagnostik yang ada untuk handel yang ditentukan dalam Handel. Fungsi ini juga mengembalikan SQL_NO_DATA untuk RecNumber positif jika tidak ada rekaman diagnostik untuk Handle.
Komentar
Aplikasi biasanya memanggil SQLGetDiagRec ketika panggilan sebelumnya ke fungsi ODBC telah mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO. Namun, karena fungsi ODBC apa pun dapat memposting nol atau lebih rekaman diagnostik setiap kali dipanggil, aplikasi dapat memanggil SQLGetDiagRec setelah panggilan fungsi ODBC. Aplikasi dapat memanggil SQLGetDiagRec beberapa kali untuk mengembalikan beberapa atau semua rekaman dalam struktur data diagnostik. ODBC tidak memberlakukan batasan jumlah rekaman diagnostik yang dapat disimpan kapan saja.
SQLGetDiagRec tidak dapat digunakan untuk mengembalikan bidang dari header struktur data diagnostik. (Argumen RecNumber harus lebih besar dari 0.) Aplikasi harus memanggil SQLGetDiagField untuk tujuan ini.
SQLGetDiagRec hanya mengambil informasi diagnostik yang terakhir dikaitkan dengan handel yang ditentukan dalam argumen Handel . Jika aplikasi memanggil fungsi ODBC lain, kecuali SQLGetDiagRec, SQLGetDiagField, atau SQLError, informasi diagnostik apa pun dari panggilan sebelumnya pada handel yang sama hilang.
Aplikasi dapat memindai semua rekaman diagnostik dengan mengulang, menaikkan RecNumber, selama SQLGetDiagRec mengembalikan SQL_SUCCESS. Panggilan ke SQLGetDiagRec tidak merusak bidang header dan rekaman. Aplikasi dapat memanggil SQLGetDiagRec lagi di lain waktu untuk mengambil bidang dari rekaman selama tidak ada fungsi lain, kecuali SQLGetDiagRec, SQLGetDiagField, atau SQLError, telah dipanggil sementara. Aplikasi ini juga dapat mengambil hitungan jumlah total rekaman diagnostik yang tersedia dengan memanggil SQLGetDiagField untuk mengambil nilai bidang SQL_DIAG_NUMBER, lalu memanggil SQLGetDiagRec berkali-kali.
Untuk deskripsi bidang struktur data diagnostik, lihat SQLGetDiagField. Untuk informasi selengkapnya, lihat Menggunakan SQLGetDiagRec dan SQLGetDiagField dan Menerapkan SQLGetDiagRec dan SQLGetDiagField.
Memanggil API selain API yang sedang dijalankan secara asinkron akan menghasilkan HY010 "Kesalahan urutan fungsi". Namun, catatan kesalahan tidak dapat diambil sebelum operasi asinkron selesai.
Argumen HandleType
Setiap jenis handel dapat memiliki informasi diagnostik yang terkait dengannya. Argumen HandleType menunjukkan jenis handel argumen Handle .
Beberapa bidang header dan rekaman tidak dapat dikembalikan untuk pegangan lingkungan, koneksi, pernyataan, dan deskriptor. Handel yang bidangnya tidak berlaku ditunjukkan di bagian "Bidang Header" dan "Bidang Rekaman" di SQLGetDiagField.
Panggilan ke SQLGetDiagRec akan mengembalikan SQL_INVALID_HANDLE jika HandleType SQL_HANDLE_SENV, yang menunjukkan handel lingkungan bersama. Namun, jika HandleType SQL_HANDLE_ENV, Handle dapat berupa handel lingkungan bersama atau yang tidak dibagikan.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mendapatkan bidang rekaman diagnostik atau bidang header diagnostik | Fungsi SQLGetDiagField |
Lihat Juga
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