Fungsi SQLDescribeCol

Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92

Summary
SQLDescribeCol mengembalikan deskriptor hasil - nama kolom, tipe, ukuran kolom, digit desimal, dan nullability - untuk satu kolom dalam set hasil. Informasi ini juga tersedia di bidang IRD.

Syntax

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);

Arguments

StatementHandle
[Input] Handel pernyataan.

Nomor Kolom
[Input] Nomor kolom data hasil, diurutkan secara berurutan dalam urutan kolom yang meningkat, dimulai dari 1. Argumen ColumnNumber juga dapat diatur ke 0 untuk mendeskripsikan kolom bookmark.

ColumnName
[Output] Penunjuk ke buffer tanpa henti untuk mengembalikan nama kolom. Nilai ini dibaca dari bidang SQL_DESC_NAME pada IRD. Jika kolom tidak bernama atau nama kolom tidak dapat ditentukan, driver mengembalikan string kosong.

Jika ColumnName bernilai NULL, NameLengthPtr tetap akan mengembalikan total jumlah karakter (tidak termasuk karakter null-terminasi untuk data karakter) yang tersedia untuk dikembalikan di buffer yang diarahkan oleh ColumnName.

BufferLength
[Input] Panjang buffer *ColumnName , dalam karakter.

NameLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan total karakter (tidak termasuk terminasi null) yang tersedia untuk dikembalikan di *ColumnName. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar atau sama dengan BufferLength, nama kolom dalam *ColumnName dipotong menjadi BufferLength dikurangi panjang karakter null-terminasi.

DataTypePtr
[Output] Penunjuk ke buffer untuk mengembalikan tipe data SQL dari kolom. Nilai ini dibaca dari bidang SQL_DESC_CONCISE_TYPE IRD. Ini akan menjadi salah satu nilai dalam SQL Data Types, atau tipe data SQL khusus driver. Jika tipe data tidak dapat ditentukan, driver mengembalikan SQL_UNKNOWN_TYPE.

Di ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME, atau SQL_TYPE_TIMESTAMP dikembalikan dalam *DataTypePtr untuk data tanggal, waktu, atau timestamp, masing-masing; di ODBC 2. x, SQL_DATE, SQL_TIME, atau SQL_TIMESTAMP dikembalikan. Driver Manager melakukan pemetaan yang diperlukan saat ODBC 2.aplikasi x bekerja dengan ODBC 3.x driver atau ketika ODBC 3.aplikasi x bekerja dengan ODBC 2.x driver.

Ketika ColumnNumber sama dengan 0 (untuk kolom bookmark), SQL_BINARY dikembalikan dalam *DataTypePtr untuk bookmark panjang variabel. (SQL_INTEGER dikembalikan jika marka buku digunakan oleh ODBC 3.aplikasi x bekerja dengan ODBC 2.x driver atau oleh ODBC 2.aplikasi x bekerja dengan ODBC 3.x driver.)

Untuk informasi lebih lanjut tentang tipe data ini, lihat Tipe Data SQL di Lampiran D: Tipe Data. Untuk informasi tentang jenis data SQL khusus driver, lihat dokumentasi driver.

ColumnSizePtr
[Output] Penunjuk ke buffer untuk mengembalikan ukuran (dalam karakter) kolom pada sumber data. Jika ukuran kolom tidak dapat ditentukan, driver mengembalikan 0. Untuk informasi selengkapnya tentang ukuran kolom, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan dalam Lampiran D: Jenis Data.

DecimalDigitsPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah digit desimal kolom pada sumber data. Jika jumlah digit desimal tidak dapat ditentukan atau tidak berlaku, pengemudi mengembalikan 0. Untuk informasi lebih lanjut tentang digit desimal, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan di Lampiran D: Tipe Data.

NullablePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai yang menunjukkan apakah kolom mengizinkan nilai NULL. Nilai ini dibaca dari bidang SQL_DESC_NULLABLE pada IRD. Nilainya adalah salah satu dari yang berikut ini:

SQL_NO_NULLS: Kolom tidak mengizinkan nilai NULL.

SQL_NULLABLE: Kolom mengizinkan nilai NULL.

SQL_NULLABLE_UNKNOWN: Driver tidak dapat menentukan apakah kolom mengizinkan nilai NULL.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostics

Ketika SQLDescribeCol mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE yang terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan HandleStatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umum dikembalikan oleh SQLDescribeCol 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 *ColumnName tidak cukup besar untuk mengembalikan seluruh nama kolom, sehingga nama kolom dipotong. Panjang nama kolom yang tidak terpotong dikembalikan dalam *NameLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
07005	Pernyataan yang disiapkan bukan spesifikasi kursor	Pernyataan yang terkait dengan StatementHandle tidak mengembalikan set hasil. Tidak ada kolom yang bisa dijelaskan.
07009	Indeks deskriptor tidak valid	(DM) Nilai yang ditentukan untuk argumen ColumnNumber sama dengan 0, dan opsi pernyataan SQL_ATTR_USE_BOOKMARKS adalah SQL_UB_OFF. Nilai yang ditentukan untuk argumen ColumnNumber lebih besar dari jumlah kolom dalam set hasil.
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	Kegagalan alokasi memori	Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi.
HY008	Operasi dibatalkan	Pemrosesan asinkron diaktifkan untuk StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle. Kemudian fungsi dipanggil lagi pada StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle dari utas yang berbeda dalam aplikasi multithread.
HY010	Kesalahan urutan fungsi	(DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih berjalan saat SQLDescribeCol dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. (DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. (DM) Fungsi dipanggil sebelum memanggil SQLPrepare, SQLExecute, atau fungsi katalog pada handle pernyataan. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution.
HY013	Kesalahan manajemen memori	Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
HY090	String atau panjang buffer tidak valid	(DM) Nilai yang ditentukan untuk argumen BufferLength kurang dari 0.
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	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 StatementHandle tidak mendukung fungsi.
IM017	Polling dinonaktifkan dalam mode pemberitahuan asinkron	Setiap kali model pemberitahuan digunakan, polling dinonaktifkan.
IM018	SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini.	Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi.

SQLDescribeCol dapat mengembalikan SQLSTATE apa pun yang dapat dikembalikan oleh SQLPrepare atau SQLExecute saat dipanggil setelah SQLPrepare dan sebelum SQLExecute, tergantung pada kapan sumber data mengevaluasi pernyataan SQL yang terkait dengan handle pernyataan.

Untuk alasan kinerja, sebuah aplikasi sebaiknya tidak memanggil SQLDescribeCol sebelum menjalankan pernyataan.

Komentar

Sebuah aplikasi biasanya memanggil SQLDescribeCol setelah panggilan ke SQLPrepare dan sebelum atau sesudah panggilan terkait ke SQLExecute. Sebuah aplikasi juga dapat memanggil SQLDescribeCol setelah panggilan ke SQLExecDirect. Untuk informasi selengkapnya, lihat Metadata Tataan Hasil.

SQLDescribeCol mengambil nama kolom, tipe, dan panjang yang dihasilkan oleh pernyataan SELECT . Jika kolom adalah sebuah ekspresi, *ColumnName adalah string kosong atau nama yang didefinisikan oleh driver.

Note

ODBC mendukung SQL_NULLABLE_UNKNOWN sebagai ekstensi, meskipun spesifikasi Open Group dan SQL Access Group Call Level Interface tidak menentukan opsi untuk SQLDescribeCol.

Untuk informasi mengenai	Lihat
Mengikat buffer ke kolom dalam tataan hasil	SQLBindCol
Membatalkan pemrosesan pernyataan	SQLCancel
Mengembalikan informasi tentang kolom dalam tataan hasil	SQLColAttribute
Mengambil beberapa baris data	SQLFetch
Mengembalikan jumlah kolom set hasil	SQLNumResultCols
Menyiapkan pernyataan untuk eksekusi	SQLPrepare

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-24