Fungsi SQLGetDiagRec

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92

Summary
SQLGetDiagRec mengembalikan nilai saat ini dari beberapa bidang dalam catatan diagnostik yang berisi informasi kesalahan, peringatan, dan status. Berbeda dengan SQLGetDiagField, yang mengembalikan satu bidang diagnostik per panggilan, SQLGetDiagRec mengembalikan beberapa bidang yang umum digunakan dalam catatan diagnostik, termasuk SQLSTATE, kode kesalahan asli, dan teks pesan diagnostik.

Syntax

  
SQLRETURN SQLGetDiagRec(  
     SQLSMALLINT     HandleType,  
     SQLHANDLE       Handle,  
     SQLSMALLINT     RecNumber,  
     SQLCHAR *       SQLState,  
     SQLINTEGER *    NativeErrorPtr,  
     SQLCHAR *       MessageText,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   TextLengthPtr);

Arguments

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 Connection-Pool dalam Driver ODBC.

Handel
[Input] Handel untuk struktur data diagnostik, dari jenis yang ditunjukkan oleh HandleType. Jika HandleType SQL_HANDLE_ENV, Handle dapat menjadi 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 NULL yang mengakhiri) untuk rekaman diagnostik RecNumber. Dua karakter pertama menunjukkan kelas; Tiga berikutnya menunjukkan subkelas. Informasi ini terdapat dalam bidang diagnostik SQL_DIAG_SQLSTATE. Untuk informasi selengkapnya, lihat SQLSTATEs.

NativeErrorPtr
[Output] Penunjuk ke buffer untuk mengembalikan kode kesalahan asli, spesifik untuk sumber data. Informasi ini terdapat dalam bidang diagnostik SQL_DIAG_NATIVE.

Teks Pesan
[Output] Penunjuk ke buffer untuk mengembalikan string teks pesan diagnostik. Informasi ini terdapat dalam bidang diagnostik SQL_DIAG_MESSAGE_TEXT. Untuk format string, lihat Pesan Diagnostik.

Jika MessageText bernilai NULL, TextLengthPtr tetap akan mengembalikan jumlah total karakter (tidak termasuk karakter null-terminasi untuk data karakter) yang tersedia untuk dikembalikan di buffer yang ditunjuk oleh MessageText.

BufferLength
[Input] Panjang buffer *MessageText dalam karakter. Tidak ada panjang maksimum teks pesan diagnostik.

TextLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan total jumlah karakter (tidak termasuk jumlah karakter yang diperlukan untuk karakter null-terminasi) yang tersedia untuk dikembalikan di *MessageText. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari BufferLength, teks pesan diagnostik dalam *MessageText dipotong menjadi BufferLength dikurangi panjang karakter null-terminasi.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA, atau SQL_INVALID_HANDLE.

Diagnostics

SQLGetDiagRec tidak memposting catatan 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 menampung pesan diagnostik yang diminta. Tidak ada rekam diagnostik yang dibuat. Untuk menentukan bahwa pemotongan terjadi, aplikasi harus membandingkan BufferLength dengan jumlah byte 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 Handle. Fungsi ini juga mengembalikan SQL_NO_DATA untuk RecNumber positif jika tidak ada rekaman diagnostik untuk Handle.

Komentar

Sebuah aplikasi biasanya memanggil SQLGetDiagRec ketika panggilan sebelumnya ke fungsi ODBC telah mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO. Namun, karena setiap fungsi ODBC dapat memposting nol atau lebih catatan diagnostik setiap kali dipanggil, sebuah aplikasi dapat memanggil SQLGetDiagRec setelah setiap panggilan fungsi ODBC. Sebuah aplikasi dapat memanggil SQLGetDiagRec beberapa kali untuk mengembalikan sebagian atau seluruh catatan dalam struktur data diagnostik. ODBC tidak memberlakukan batasan jumlah rekaman diagnostik yang dapat disimpan pada satu waktu.

SQLGetDiagRec tidak dapat digunakan untuk mengembalikan field 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 terkait dengan handle yang ditentukan dalam argumen Handle . Jika aplikasi memanggil fungsi ODBC lain, kecuali SQLGetDiagRec, SQLGetDiagField, atau SQLError, informasi diagnostik dari panggilan sebelumnya pada handle yang sama akan hilang.

Sebuah aplikasi dapat memindai semua catatan diagnostik dengan melakukan looping, menambah RecNumber, selama SQLGetDiagRec mengembalikan SQL_SUCCESS. Pemanggilan ke SQLGetDiagRec tidak merusak bidang header dan catatan. Aplikasi dapat memanggil SQLGetDiagRec lagi di kemudian hari untuk mengambil field dari sebuah catatan selama tidak ada fungsi lain, kecuali SQLGetDiagRec, SQLGetDiagField, atau SQLError, yang dipanggil di antara waktu tersebut. Aplikasi juga dapat mengambil jumlah total catatan diagnostik yang tersedia dengan memanggil SQLGetDiagField untuk mengambil nilai field SQL_DIAG_NUMBER, lalu memanggil SQLGetDiagRec sebanyak itu.

Untuk deskripsi bidang dalam 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 tipe handle dari argumen Handle .

Beberapa bidang header dan rekaman tidak dapat dikembalikan untuk pegangan lingkungan, koneksi, pernyataan, dan deskriptor. Pegangan yang tidak memiliki bidang akan ditandai pada bagian "Header Fields" dan "Record Fields" di SQLGetDiagField.

Pemanggilan ke SQLGetDiagRec akan mengembalikan SQL_INVALID_HANDLE jika HandleType SQL_HANDLE_SENV, yang menunjukkan handle lingkungan bersama. Namun, jika HandleType SQL_HANDLE_ENV, Handle dapat berupa handle lingkungan bersama atau tidak dibagikan.

Untuk informasi mengenai	Lihat
Mendapatkan field dari rekaman diagnostik atau field dari header diagnostik	Fungsi SQLGetDiagField

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-24