Fungsi SQLSetDescRec
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
Fungsi SQLSetDescRec mengatur beberapa bidang deskriptor yang memengaruhi jenis data dan buffer yang terikat ke kolom atau data parameter.
Sintaks
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
Argumen
DescriptorHandle
[Input] Handel deskriptor. Ini tidak boleh menjadi handel IRD.
RecNumber
[Input] Menunjukkan catatan deskriptor yang berisi bidang yang akan diatur. Rekaman deskriptor diberi nomor dari 0, dengan nomor rekaman 0 menjadi catatan bookmark. Argumen ini harus sama dengan atau lebih besar dari 0. Jika RecNumber lebih besar dari nilai SQL_DESC_COUNT, SQL_DESC_COUNTis berubah menjadi nilai RecNumber.
Jenis
[Input] Nilai untuk mengatur bidang SQL_DESC_TYPE untuk catatan deskriptor.
SubType
[Input] Untuk rekaman yang jenisnya SQL_DATETIME atau SQL_INTERVAL, ini adalah nilai untuk mengatur bidang SQL_DESC_DATETIME_INTERVAL_CODE.
Panjang
[Input] Nilai untuk mengatur bidang SQL_DESC_OCTET_LENGTH untuk catatan deskriptor.
Presisi
[Input] Nilai untuk mengatur bidang SQL_DESC_PRECISION untuk catatan deskriptor.
Skala
[Input] Nilai untuk mengatur bidang SQL_DESC_SCALE untuk catatan deskriptor.
DataPtr
[Input atau Output Yang Ditangguhkan] Nilai untuk mengatur bidang SQL_DESC_DATA_PTR untuk catatan deskriptor. DataPtr dapat diatur ke penunjuk null.
Argumen DataPtr dapat diatur ke penunjuk null untuk mengatur bidang SQL_DESC_DATA_PTR ke penunjuk null. Jika handel dalam argumen DescriptorHandle dikaitkan dengan ARD, ini akan membongkar kolom.
StringLengthPtr
[Input atau Output Yang Ditangguhkan] Nilai untuk mengatur bidang SQL_DESC_OCTET_LENGTH_PTR untuk catatan deskriptor. StringLengthPtr dapat diatur ke penunjuk null untuk mengatur bidang SQL_DESC_OCTET_LENGTH_PTR ke penunjuk null.
IndicatorPtr
[Input atau Output Yang Ditangguhkan] Nilai untuk mengatur bidang SQL_DESC_INDICATOR_PTR untuk catatan deskriptor. IndicatorPtr dapat diatur ke penunjuk null untuk mengatur bidang SQL_DESC_INDICATOR_PTR ke penunjuk null.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLSetDescRec 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 umumnya dikembalikan oleh SQLSetDescRec 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.) |
| 07009 | Indeks deskriptor tidak valid | Argumen RecNumber diatur ke 0, dan DescriptorHandle merujuk ke handel IPD. Argumen RecNumber kurang dari 0. Argumen RecNumber lebih besar dari jumlah maksimum kolom atau parameter yang dapat didukung sumber data, dan argumen DescriptorHandle adalah APD, IPD, atau ARD. Argumen RecNumber sama dengan 0, dan argumen DescriptorHandle mengacu pada APD yang dialokasikan secara implisit. (Kesalahan ini tidak terjadi dengan deskriptor aplikasi yang dialokasikan secara eksplisit karena tidak diketahui apakah deskriptor aplikasi yang dialokasikan secara eksplisit adalah APD atau ARD hingga waktu eksekusi.) |
| 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. |
| 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) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle tempat DescriptorHandle dikaitkan 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 ainkron ini masih dijalankan ketika fungsi SQLSetDescRec dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan DescriptorHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY016 | Tidak dapat mengubah deskriptor baris implementasi | Argumen DescriptorHandle dikaitkan dengan IRD. |
| HY021 | Informasi deskriptor yang tidak konsisten | Bidang Tipe , atau bidang lain yang terkait dengan bidang SQL_DESC_TYPE dalam deskriptor, tidak valid atau konsisten. Informasi deskriptor yang diperiksa selama pemeriksaan konsistensi tidak konsisten. (Lihat "Pemeriksaan Konsistensi," nanti di bagian ini.) |
| HY090 | String atau panjang buffer tidak valid | (DM) Driver adalah driver ODBC 2.x , deskriptor adalah ARD, argumen ColumnNumber diatur ke 0, dan nilai yang ditentukan untuk argumen BufferLength tidak sama dengan 4. |
| 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 SQLSetDescRec untuk mengatur bidang berikut untuk satu kolom atau parameter:
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_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
Catatan
Jika panggilan ke SQLSetDescRec gagal, konten rekaman deskriptor yang diidentifikasi oleh argumen RecNumber tidak ditentukan.
Saat mengikat kolom atau parameter, SQLSetDescRec memungkinkan Anda mengubah beberapa bidang yang memengaruhi pengikatan tanpa memanggil SQLBindCol atau SQLBindParameter atau melakukan beberapa panggilan ke SQLSetDescField. SQLSetDescRec dapat mengatur bidang pada deskriptor yang saat ini tidak terkait dengan pernyataan. Perhatikan bahwa SQLBindParameter menetapkan lebih banyak bidang daripada SQLSetDescRec, dapat mengatur bidang pada APD dan IPD dalam satu panggilan, dan tidak memerlukan handel deskriptor.
Catatan
Atribut pernyataan SQL_ATTR_USE_BOOKMARKS harus selalu diatur sebelum memanggil SQLSetDescRec dengan argumen RecNumber 0 untuk mengatur bidang bookmark. Meskipun ini tidak wajib, sangat disarankan.
Pemeriksaan Konsistensi
Pemeriksaan konsistensi dilakukan oleh driver secara otomatis setiap kali aplikasi menetapkan bidang SQL_DESC_DATA_PTR APD, ARD, atau IPD. Jika salah satu bidang tidak konsisten dengan bidang lain, SQLSetDescRec akan mengembalikan SQLSTATE HY021 (Informasi deskriptor yang tidak konsisten).
Setiap kali aplikasi mengatur bidang SQL_DESC_DATA_PTR APD, ARD, atau IPD, driver memeriksa bahwa nilai bidang SQL_DESC_TYPE dan nilai yang berlaku untuk bidang SQL_DESC_TYPE tersebut valid dan konsisten. Pemeriksaan ini selalu dilakukan ketika SQLBindParameter atau SQLBindCol dipanggil atau ketika SQLSetDescRec dipanggil untuk APD, ARD, atau IPD. Pemeriksaan konsistensi ini mencakup pemeriksaan berikut pada bidang deskriptor:
Bidang SQL_DESC_TYPE harus merupakan salah satu jenis ODBC C atau SQL yang valid atau jenis SQL khusus driver. Bidang SQL_DESC_CONCISE_TYPE harus merupakan salah satu jenis ODBC C atau SQL yang valid atau jenis C atau SQL khusus driver, termasuk jenis tanggalwaktu dan interval yang ringkas.
Jika bidang rekaman SQL_DESC_TYPE SQL_DATETIME atau SQL_INTERVAL, bidang SQL_DESC_DATETIME_INTERVAL_CODE harus merupakan salah satu kode tanggalwaktu atau interval yang valid. (Lihat deskripsi bidang SQL_DESC_DATETIME_INTERVAL_CODE di SQLSetDescField.)
Jika bidang SQL_DESC_TYPE menunjukkan jenis numerik, bidang SQL_DESC_PRECISION dan SQL_DESC_SCALE diverifikasi agar valid.
Jika bidang SQL_DESC_CONCISE_TYPE adalah jenis data waktu atau tanda waktu, jenis interval dengan komponen detik, atau salah satu jenis data interval dengan komponen waktu, bidang SQL_DESC_PRECISION diverifikasi menjadi presisi detik yang valid.
Jika SQL_DESC_CONCISE_TYPE adalah jenis data interval, bidang SQL_DESC_DATETIME_INTERVAL_PRECISION diverifikasi menjadi nilai presisi depan interval yang valid.
Bidang SQL_DESC_DATA_PTR IPD biasanya tidak diatur; namun, aplikasi dapat melakukannya untuk memaksa pemeriksaan konsistensi bidang IPD. Pemeriksaan konsistensi tidak dapat dilakukan pada IRD. Nilai yang bidang SQL_DESC_DATA_PTR IPD diatur ke tidak benar-benar disimpan dan tidak dapat diambil oleh panggilan ke SQLGetDescField atau SQLGetDescRec; pengaturan dibuat hanya untuk memaksa pemeriksaan konsistensi.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat kolom | Fungsi SQLBindCol |
| Mengikat parameter | Fungsi SQLBindParameter |
| Mendapatkan bidang deskriptor tunggal | Fungsi SQLGetDescField |
| Mendapatkan beberapa bidang deskriptor | Fungsi SQLGetDescRec |
| Mengatur bidang deskriptor tunggal | Fungsi SQLSetDescField |