Bagikan melalui

Fungsi SQLDescribeCol

  • Artikel

Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92

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

Sintaks

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

Argumen

StatementHandle
[Input] Handel pernyataan.

Nomor Kolom
[Input] Jumlah kolom data hasil, diurutkan secara berurutan dalam meningkatkan urutan kolom, mulai dari 1. Argumen ColumnNumber juga dapat diatur ke 0 untuk menjelaskan kolom bookmark.

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

Jika ColumnName ADALAH NULL, NameLengthPtr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan oleh ColumnName.

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

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

DataTypePtr
[Output] Penunjuk ke buffer untuk mengembalikan tipe data SQL kolom. Nilai ini dibaca dari bidang SQL_DESC_CONCISE_TYPE IRD. Ini akan menjadi salah satu nilai dalam Jenis Data SQL, atau jenis data SQL khusus driver. Jika jenis data tidak dapat ditentukan, driver akan 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 tanda waktu, 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 selengkapnya tentang jenis data ini, lihat Jenis Data SQL di Lampiran D: Jenis Data. Untuk informasi tentang jenis data SQL khusus driver, lihat dokumentasi driver.

ColumnSizePtr
[Output] Arahkan ke buffer untuk mengembalikan ukuran (dalam karakter) kolom pada sumber data. Jika ukuran kolom tidak dapat ditentukan, driver akan 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, driver mengembalikan 0. Untuk informasi selengkapnya tentang digit desimal, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan dalam Lampiran D: Jenis Data.

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

SQL_NO_NULLS: Kolom tidak mengizinkan nilai NULL.

SQL_NULLABLE: Kolom memungkinkan nilai NULL.

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

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Ketika SQLDescribeCol 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 SQLDescribeCol 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 *ColumnName tidak cukup besar untuk mengembalikan seluruh nama kolom, sehingga nama kolom terpotong. 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 tataan hasil. Tidak ada kolom untuk dijelaskan.
07009 Indeks deskriptor tidak valid (DM) Nilai yang ditentukan untuk argumen ColumnNumber sama dengan 0, dan opsi pernyataan SQL_ATTR_USE_BOOKMARKS SQL_UB_OFF.

Nilai yang ditentukan untuk argumen ColumnNumber lebih besar dari jumlah kolom dalam tataan 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 dijalankan ketika 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 ini dipanggil sebelum memanggil SQLPrepare, SQLExecute, atau fungsi katalog pada handel 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 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 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 ketika dipanggil setelah SQLPrepare dan sebelum SQLExecute, tergantung pada kapan sumber data mengevaluasi pernyataan SQL yang terkait dengan handel pernyataan.

Untuk alasan performa, aplikasi tidak boleh memanggil SQLDescribeCol sebelum menjalankan pernyataan.

Komentar

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

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

Catatan

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 tentang 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 tataan hasil SQLNumResultCols
Menyiapkan pernyataan untuk eksekusi SQLPrepare

Lihat Juga

Referensi API ODBC
File Header ODBC