Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Summary
SQLGetDescField mengembalikan pengaturan atau nilai saat ini dari satu field dalam catatan deskriptor.
Syntax
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
DescriptorHandle
[Masukan] Pegangan deskriptor.
RecNumber
[Input] Menunjukkan catatan deskriptor dari mana aplikasi mencari informasi. Catatan deskriptor diberi nomor dari 0, dengan catatan nomor 0 menjadi catatan bookmark. Jika argumen FieldIdentifier menunjukkan bidang header, RecNumber diabaikan. Jika RecNumber kurang dari atau sama dengan SQL_DESC_COUNT tetapi baris tersebut tidak berisi data untuk kolom atau parameter, pemanggilan ke SQLGetDescField akan mengembalikan nilai default dari field tersebut. (Untuk informasi lebih lanjut, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField.)
Pengidentifikasi Bidang
[Input] Menunjukkan bidang deskriptor yang nilainya akan dikembalikan. Untuk informasi lebih lanjut, lihat bagian "FieldIdentifier Argument" di SQLSetDescField.
ValuePtr
[Output] Penunjuk ke buffer untuk mengembalikan informasi deskriptor. Jenis data bergantung pada nilai FieldIdentifier.
Jika ValuePtr bertipe bilangan bulat, aplikasi harus menggunakan buffer SQLULEN dan menginisialisasi nilainya ke 0 sebelum memanggil fungsi ini karena beberapa driver mungkin hanya menulis buffer 32-bit atau 16-bit yang lebih rendah dan membiarkan bit orde lebih tinggi tetap tidak berubah.
Jika ValuePtr bernilai NULL, StringLengthPtr tetap akan mengembalikan total jumlah byte (tidak termasuk karakter null-termination untuk data karakter) yang tersedia untuk dikembalikan di buffer yang ditunjuk oleh ValuePtr.
BufferLength
[Masukan] Jika FieldIdentifier adalah bidang yang ditentukan ODBC dan ValuePtr menunjuk ke string karakter atau buffer biner, argumen ini harus berupa panjang *ValuePtr. Jika FieldIdentifier adalah bidang yang didefinisikan ODBC dan *ValuePtr adalah bilangan bulat, BufferLength diabaikan. Jika nilai dalam *ValuePtr adalah tipe 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 pointer ke string karakter, maka BufferLength adalah panjang string atau SQL_NTS tersebut.
Jika *ValuePtr adalah pointer ke buffer biner, maka aplikasi menempatkan hasil makro SQL_LEN_BINARY_ATTR(length) ke BufferLength. Ini menempatkan nilai negatif di BufferLength.
Jika *ValuePtr adalah penunjuk ke nilai selain string karakter atau string biner, maka BufferLength seharusnya memiliki nilai SQL_IS_POINTER.
Jika *ValuePtr berisi tipe data dengan panjang tetap, maka BufferLength adalah SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT, atau SQL_IS_USMALLINT, sesuai kebutuhan.
StringLengthPtr
[Output] Penunjuk ke buffer tempat mengembalikan total jumlah byte (tidak termasuk jumlah byte yang dibutuhkan untuk karakter null-terminasi) yang tersedia untuk dikembalikan dalam *ValuePtr.
Returns
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 catatan deskriptor saat ini.
SQL_NO_DATA dikembalikan jika DescriptorHandle adalah handle IRD dan pernyataan tersebut dalam status prepared atau execute tetapi tidak ada kursor terbuka yang terkait dengannya.
Diagnostics
Ketika SQLGetDescField mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan HandleStatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umum dikembalikan oleh SQLGetDescField dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATE 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 tersebut dipotong. Panjang bidang deskriptor tanpa 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 adalah SQL_UB_OFF, dan argumen DescriptorHandle adalah handle IRD. (Kesalahan ini hanya dapat dikembalikan untuk deskriptor yang dialokasikan secara eksplisit jika deskriptor tersebut terkait dengan handle pernyataan.) Argumen FieldIdentifier adalah field record, argumen RecNumber adalah 0, dan argumen DescriptorHandle adalah handle 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 diasosiasikan dengan StatementHandle sebagai IRD, dan handle pernyataan terkait belum disiapkan atau dieksekusi. |
| HY010 | Kesalahan urutan fungsi | (DM) DescriptorHandle dikaitkan dengan StatementHandle yang fungsi eksekusi asinkron (bukan yang ini) dipanggil dan masih berjalan saat fungsi ini dipanggil. (DM) DescriptorHandle dikaitkan dengan StatementHandle yang dipanggil dan dikembalikan SQL_NEED_DATA SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. (DM) Fungsi yang dijalankan secara asinkron dipanggil untuk pegangan koneksi yang terkait dengan DescriptorHandle. Fungsi asinkron ini masih berjalan saat 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 tipe SQL ODBC yang valid, tipe SQL khusus driver yang valid (untuk IPD), atau tipe 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 bukanlah bidang yang didefinisikan ODBC dan bukan nilai yang didefinisikan oleh implementasi. FieldIdentifier tidak didefinisikan 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 yang ditangguhkan, lihat Fungsi SQLEndTran. |
| HYT01 | Waktu tunggu koneksi habis | 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 tersebut. |
Komentar
Sebuah aplikasi dapat memanggil SQLGetDescField untuk mengembalikan nilai satu bidang dari catatan deskriptor. Pemanggilan ke SQLGetDescField dapat mengembalikan pengaturan bidang apa pun dalam jenis deskriptor apa pun, termasuk bidang header, field record, dan field bookmark. Sebuah aplikasi dapat memperoleh pengaturan beberapa bidang dalam deskriptor yang sama atau berbeda, secara berurutan sembarang, dengan melakukan panggilan berulang ke SQLGetDescField. SQLGetDescField juga dapat dipanggil untuk mengembalikan field deskriptor yang didefinisikan driver.
Demi alasan kinerja, sebuah aplikasi sebaiknya tidak memanggil SQLGetDescField untuk IRD sebelum menjalankan pernyataan.
Pengaturan beberapa bidang yang menjelaskan nama, tipe data, dan penyimpanan data kolom atau parameter juga dapat diambil dalam satu panggilan ke SQLGetDescRec. SQLGetStmtAttr dapat dipanggil untuk mengembalikan pengaturan satu bidang dalam header deskriptor yang juga merupakan atribut pernyataan. SQLColAttribute, SQLDescribeCol, dan SQLDescribeParam mengembalikan bidang catatan atau bookmark.
Ketika sebuah aplikasi memanggil SQLGetDescField untuk mengambil nilai field yang tidak didefinisikan untuk tipe deskriptor tertentu, fungsi tersebut mengembalikan SQL_SUCCESS tetapi nilai yang dikembalikan untuk field tersebut tidak terdefinisi. Misalnya, memanggil SQLGetDescField untuk bidang SQL_DESC_NAME atau SQL_DESC_NULLABLE dari APD atau ARD akan mengembalikan nilai SQL_SUCCESS tetapi tidak terdefinisi untuk bidang tersebut.
Ketika sebuah aplikasi memanggil SQLGetDescField untuk mengambil nilai field yang didefinisikan untuk tipe deskriptor tertentu tetapi tidak memiliki nilai default dan belum ditetapkan, fungsi tersebut mengembalikan SQL_SUCCESS tetapi nilai yang dikembalikan untuk field tersebut tidak terdefinisi. Untuk informasi lebih lanjut tentang inisialisasi bidang deskriptor dan deskripsi bidang, lihat "Inisialisasi Bidang Deskriptor" di SQLSetDescField. Untuk informasi selengkapnya tentang deskriptor, lihat Deskriptor.
Fungsi Terkait
| Untuk informasi mengenai | Lihat |
|---|---|
| Mendapatkan beberapa bidang deskriptor | Fungsi SQLGetDescRec |
| Mengatur bidang deskriptor tunggal | Fungsi SQLSetDescField |
| Mengatur beberapa bidang deskriptor | Fungsi SQLSetDescRec |