Bagikan melalui

Fungsi SQLSetDescRec

Kesuaian
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 data kolom atau parameter.

Sintaksis

  
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.

Tipe
[Input] Nilai untuk mengatur bidang SQL_DESC_TYPE untuk catatan deskriptor.

SubJenis
[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 DescriptorHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLSetDescRec dan menjelaskan masing-masing nilai 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 yang dirujuk 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 yang 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 yang fungsinya dijalankan secara asinkron (bukan yang ini) dipanggil dan masih dijalankan ketika fungsi ini dipanggil.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk 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 asinkron ini masih dijalankan ketika fungsi SQLSetDescRec dipanggil.

(DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk salah satu handel pernyataan yang terkait dengan DescriptorHandle dan SQL_PARAM_DATA_AVAILABLE yang dikembalikan. 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 di 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 Batas waktu 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

Nota

Jika panggilan ke SQLSetDescRec gagal, konten catatan 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 mengatur lebih banyak bidang daripada SQLSetDescRec, dapat mengatur bidang pada APD dan IPD dalam satu panggilan, dan tidak memerlukan handel deskriptor.

Nota

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 diatur ke bidang SQL_DESC_DATA_PTR IPD tidak benar-benar disimpan dan tidak dapat diambil dengan panggilan ke SQLGetDescField atau SQLGetDescRec; pengaturan dibuat hanya untuk memaksa pemeriksaan konsistensi.

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

Lihat Juga

Referensi API ODBC
File Header ODBC

  • Last updated on