Fungsi SQLGetDescRec
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLGetDescRec mengembalikan pengaturan atau nilai saat ini dari beberapa bidang rekaman deskriptor. Bidang yang dikembalikan menjelaskan nama, jenis data, dan penyimpanan data kolom atau parameter.
Sintaks
SQLRETURN SQLGetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLCHAR * Name,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLengthPtr,
SQLSMALLINT * TypePtr,
SQLSMALLINT * SubTypePtr,
SQLLEN * LengthPtr,
SQLSMALLINT * PrecisionPtr,
SQLSMALLINT * ScalePtr,
SQLSMALLINT * NullablePtr);
Argumen
DescriptorHandle
[Input] Handel deskriptor.
RecNumber
[Input] Menunjukkan catatan deskriptor tempat aplikasi mencari informasi. Rekaman deskriptor diberi nomor dari 1, dengan nomor rekaman 0 menjadi catatan marka buku. Argumen RecNumber harus kurang dari atau sama dengan nilai SQL_DESC_COUNT. Jika RecNumber kurang dari atau sama dengan SQL_DESC_COUNT tetapi baris tidak berisi data untuk kolom atau parameter, panggilan ke SQLGetDescRec akan mengembalikan nilai default bidang. (Untuk informasi selengkapnya, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField.)
Nama
[Output] Penunjuk ke buffer untuk mengembalikan bidang SQL_DESC_NAME untuk catatan deskriptor.
Jika Nama NULL, StringLengthPtr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang diacu oleh Nama.
BufferLength
[Input] Panjang *Buffer nama , dalam karakter.
StringLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah karakter data yang tersedia untuk dikembalikan dalam buffer *Nama , tidak termasuk karakter penghentian null. Jika jumlah karakter lebih besar dari atau sama dengan BufferLength, data dalam *Nama dipotong menjadi BufferLength dikurangi panjang karakter penghentian null, dan dihentikan null oleh driver.
TypePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_TYPE untuk catatan deskriptor.
SubTypePtr
[Output] Untuk rekaman yang jenisnya SQL_DATETIME atau SQL_INTERVAL, ini adalah penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_DATETIME_INTERVAL_CODE.
LengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_OCTET_LENGTH untuk rekaman deskriptor.
PresisiPtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_PRECISION untuk catatan deskriptor.
ScalePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_SCALE untuk catatan deskriptor.
NullablePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai bidang SQL_DESC_NULLABLE untuk catatan deskriptor.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA, atau SQL_INVALID_HANDLE.
SQL_NO_DATA dikembalikan jika RecNumber lebih besar dari jumlah rekaman deskriptor saat ini.
SQL_NO_DATA dikembalikan jika DescriptorHandle adalah handel IRD dan pernyataan dalam status siap atau dijalankan tetapi tidak ada kursor terbuka yang terkait dengannya.
Diagnostik
Saat SQLGetDescRec mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DESC dan Handle of DescriptorHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLGetDescRec 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.) |
| 01004 | Data string, terpotong kanan | Buffer *Nama tidak cukup besar untuk mengembalikan seluruh bidang deskriptor. Oleh karena itu, bidang dipotong. Panjang bidang deskriptor yang tidak terpotong dikembalikan dalam *StringLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 07009 | Indeks deskriptor tidak valid | Argumen FieldIdentifier adalah bidang rekaman, argumen RecNumber diatur ke 0, dan argumen DescriptorHandle adalah handel IPD. (DM) Argumen RecNumber diatur ke 0, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_OFF, dan argumen DescriptorHandle adalah handel IRD. Argumen RecNumber kurang dari 0. |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 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 *MessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY007 | Pernyataan terkait tidak disiapkan | DescriptorHandle dikaitkan dengan IRD, dan handel pernyataan terkait tidak dalam status disiapkan atau dijalankan. |
| HY010 | Kesalahan urutan fungsi | (DM) DescriptorHandle dikaitkan dengan StatementHandle tempat fungsi eksekusi asinkron (bukan yang ini) dipanggil dan masih dijalankan ketika fungsi ini dipanggil. (DM) DescriptorHandle dikaitkan dengan StatementHandle tempat SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan DescriptorHandle. Fungsi asinkron ini masih dijalankan ketika SQLGetDescRec dipanggil. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| 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 | 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 DescriptorHandle tidak mendukung fungsi. |
Komentar
Aplikasi dapat memanggil SQLGetDescRec untuk mengambil nilai bidang deskriptor berikut untuk satu kolom atau parameter:
SQL_DESC_NAME
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE (untuk rekaman yang jenisnya SQL_DATETIME atau SQL_INTERVAL)
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_NULLABLE
SQLGetDescRec tidak mengambil nilai untuk bidang header.
Aplikasi dapat mencegah pengembalian pengaturan bidang dengan mengatur argumen yang sesuai dengan bidang ke penunjuk null.
Ketika aplikasi memanggil SQLGetDescRec untuk mengambil nilai bidang yang tidak ditentukan untuk jenis deskriptor tertentu, fungsi mengembalikan SQL_SUCCESS tetapi nilai yang dikembalikan untuk bidang tidak terdefinisi. Misalnya, memanggil SQLGetDescRec untuk bidang SQL_DESC_NAME atau SQL_DESC_NULLABLE APD atau ARD akan mengembalikan SQL_SUCCESS tetapi nilai yang tidak ditentukan untuk bidang tersebut.
Ketika aplikasi memanggil SQLGetDescRec untuk mengambil nilai bidang yang ditentukan untuk jenis deskriptor tertentu tetapi tidak memiliki nilai default dan belum ditetapkan, fungsi mengembalikan SQL_SUCCESS tetapi nilai yang dikembalikan untuk bidang tidak ditentukan. Untuk informasi selengkapnya, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField.
Nilai bidang juga dapat diambil satu per satu dengan panggilan ke SQLGetDescField. Untuk deskripsi bidang di header atau rekaman deskriptor, lihat SQLSetDescField. Untuk informasi selengkapnya tentang deskriptor, lihat Deskriptor.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat kolom | Fungsi SQLBindCol |
| Mengikat parameter | Fungsi SQLBindParameter |
| Mendapatkan bidang deskriptor | Fungsi SQLGetDescField |
| Mengatur beberapa bidang deskriptor | Fungsi SQLSetDescRec |