Fungsi SQLGetDescField
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLGetDescField mengembalikan pengaturan atau nilai saat ini dari satu bidang rekaman deskriptor.
Sintaks
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumen
DescriptorHandle
[Input] Handel deskriptor.
RecNumber
[Input] Menunjukkan catatan deskriptor tempat aplikasi mencari informasi. Rekaman deskriptor diberi nomor dari 0, dengan nomor rekaman 0 menjadi catatan bookmark. Jika argumen FieldIdentifier menunjukkan bidang header, RecNumber diabaikan. Jika RecNumber kurang dari atau sama dengan SQL_DESC_COUNT tetapi baris tidak berisi data untuk kolom atau parameter, panggilan ke SQLGetDescField akan mengembalikan nilai default bidang. (Untuk informasi selengkapnya, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField.)
Pengidentifikasi Bidang
[Input] Menunjukkan bidang deskriptor yang nilainya akan dikembalikan. Untuk informasi selengkapnya, lihat bagian "Argumen FieldIdentifier " di SQLSetDescField.
ValuePtr
[Output] Arahkan ke buffer untuk mengembalikan informasi deskriptor. Jenis data tergantung pada nilai FieldIdentifier.
Jika ValuePtr adalah jenis bilangan bulat, aplikasi harus menggunakan buffer SQLULEN dan menginisialisasi nilai ke 0 sebelum memanggil fungsi ini karena beberapa driver hanya dapat menulis buffer 32-bit atau 16-bit yang lebih rendah dan membiarkan bit berurutan lebih tinggi tidak berubah.
Jika ValuePtr adalah NULL, StringLengthPtr masih akan mengembalikan jumlah total byte (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh ValuePtr.
BufferLength
[Input] Jika FieldIdentifier adalah bidang yang ditentukan ODBC dan ValuePtr menunjuk ke string karakter atau buffer biner, argumen ini harus panjang *ValuePtr. Jika FieldIdentifier adalah bidang yang ditentukan ODBC dan *ValuePtr adalah bilangan bulat, BufferLength diabaikan. Jika nilai dalam *ValuePtr adalah jenis data Unicode (saat memanggil SQLGetDescFieldW), argumen BufferLength harus berupa angka genap.
Jika FieldIdentifier adalah bidang yang ditentukan driver, aplikasi menunjukkan sifat bidang ke Driver Manager dengan mengatur argumen BufferLength . BufferLength dapat memiliki nilai berikut:
Jika *ValuePtr adalah penunjuk ke string karakter, maka BufferLength adalah panjang string atau SQL_NTS.
Jika *ValuePtr adalah penunjuk ke buffer biner, maka aplikasi menempatkan hasil makro SQL_LEN_BINARY_ATTR(length) di BufferLength. Ini menempatkan nilai negatif di BufferLength.
Jika *ValuePtr adalah penunjuk ke nilai selain string karakter atau string biner, maka BufferLength harus memiliki nilai SQL_IS_POINTER.
Jika *ValuePtr berisi jenis data dengan panjang tetap, maka BufferLength adalah SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, atau SQL_IS_USMALLINT, sebagaimana mewajibkan.
StringLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total byte (tidak termasuk jumlah byte yang diperlukan untuk karakter penghentian null) yang tersedia untuk dikembalikan dalam *ValuePtr.
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
Ketika SQLGetDescField mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLGetDescField 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 *ValuePtr tidak cukup besar untuk mengembalikan seluruh bidang deskriptor, sehingga bidang terpotong. Panjang bidang deskriptor yang tidak terpotong dikembalikan dalam *StringLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 07009 | Indeks deskriptor tidak valid | (DM) Argumen RecNumber sama dengan 0, atribut pernyataan SQL_ATTR_USE_BOOKMARK SQL_UB_OFF, dan argumen DescriptorHandle adalah handel IRD. (Kesalahan ini dapat dikembalikan untuk deskriptor yang dialokasikan secara eksplisit hanya jika deskriptor dikaitkan dengan handel pernyataan.) Argumen FieldIdentifier adalah bidang rekaman, argumen RecNumber adalah 0, dan argumen DescriptorHandle adalah handel IPD. 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 StatementHandle sebagai IRD, dan handel pernyataan terkait belum 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 fungsi SQLGetDescField dipanggil. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY021 | Informasi deskriptor yang tidak konsisten | Bidang SQL_DESC_TYPE dan SQL_DESC_DATETIME_INTERVAL_CODE tidak membentuk jenis ODBC SQL yang valid, jenis SQL khusus driver yang valid (untuk IPD), atau jenis ODBC C yang valid (untuk APD atau ARD). |
| HY090 | String atau panjang buffer tidak valid | (DM) *ValuePtr adalah string karakter, dan BufferLength kurang dari nol. |
| HY091 | Pengidentifikasi bidang deskriptor tidak valid | FieldIdentifier bukan bidang yang ditentukan ODBC dan bukan nilai yang ditentukan implementasi. FieldIdentifier tidak terdefinisi untuk DescriptorHandle. |
| 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 SQLGetDescField untuk mengembalikan nilai satu bidang rekaman deskriptor. Panggilan ke SQLGetDescField dapat mengembalikan pengaturan bidang apa pun dalam jenis deskriptor apa pun, termasuk bidang header, bidang rekaman, dan bidang bookmark. Aplikasi dapat memperoleh pengaturan beberapa bidang dalam deskriptor yang sama atau berbeda, dalam urutan arbitrer, dengan melakukan panggilan berulang ke SQLGetDescField. SQLGetDescField juga dapat dipanggil untuk mengembalikan bidang deskriptor yang ditentukan driver.
Untuk alasan performa, aplikasi tidak boleh memanggil SQLGetDescField untuk IRD sebelum menjalankan pernyataan.
Pengaturan beberapa bidang yang menjelaskan nama, jenis data, dan penyimpanan data kolom atau parameter juga dapat diambil dalam satu panggilan ke SQLGetDescRec. SQLGetStmtAttr dapat dipanggil untuk mengembalikan pengaturan satu bidang di header deskriptor yang juga merupakan atribut pernyataan. SQLColAttribute, SQLDescribeCol, dan SQLDescribeParam mengembalikan bidang rekaman atau marka buku.
Ketika aplikasi memanggil SQLGetDescField 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 SQLGetDescField 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 SQLGetDescField 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 terdefinisi. Untuk informasi selengkapnya tentang inisialisasi bidang deskriptor dan deskripsi bidang, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField. Untuk informasi selengkapnya tentang deskriptor, lihat Deskriptor.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mendapatkan beberapa bidang deskriptor | Fungsi SQLGetDescRec |
| Mengatur bidang deskriptor tunggal | Fungsi SQLSetDescField |
| Mengatur beberapa bidang deskriptor | Fungsi SQLSetDescRec |