Fungsi SQLSpecialColumns
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: Grup Terbuka
Ringkasan
SQLSpecialColumns mengambil informasi berikut tentang kolom dalam tabel tertentu:
Kumpulan kolom optimal yang secara unik mengidentifikasi baris dalam tabel.
Kolom yang diperbarui secara otomatis saat nilai apa pun dalam baris diperbarui oleh transaksi.
Sintaks
SQLRETURN SQLSpecialColumns(
SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLSMALLINT Scope,
SQLSMALLINT Nullable);
Argumen
StatementHandle
[Input] Handel pernyataan.
IdentifierType
[Input] Jenis kolom yang akan dikembalikan. Harus salah satu nilai berikut:
SQL_BEST_ROWID: Mengembalikan kolom optimal atau kumpulan kolom yang, dengan mengambil nilai dari kolom atau kolom, memungkinkan baris apa pun dalam tabel yang ditentukan diidentifikasi secara unik. Kolom dapat berupa kolom pseudo yang dirancang khusus untuk tujuan ini (seperti dalam Oracle ROWID atau Ingres TID) atau kolom atau kolom indeks unik apa pun untuk tabel.
SQL_ROWVER: Mengembalikan kolom atau kolom dalam tabel yang ditentukan, jika ada, yang secara otomatis diperbarui oleh sumber data ketika nilai apa pun dalam baris diperbarui oleh transaksi apa pun (seperti dalam SQLBase ROWID atau Sybase TIMESTAMP).
CatalogName
[Input] Nama katalog untuk tabel. Jika driver mendukung katalog untuk beberapa tabel tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, string kosong ("") menunjukkan tabel yang tidak memiliki katalog. CatalogName tidak boleh berisi pola pencarian string.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, CatalogName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, CatalogName adalah argumen biasa; itu diperlakukan secara harfiah, dan kasusnya signifikan. Untuk informasi selengkapnya, lihat Argumen di Fungsi Katalog.
NameLength1
[Input] Panjang karakter *CatalogName.
SchemaName
[Input] Nama skema untuk tabel. Jika driver mendukung skema untuk beberapa tabel tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, string kosong ("") menunjukkan tabel yang tidak memiliki skema. SchemaName tidak boleh berisi pola pencarian string.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, SchemaName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, SchemaName adalah argumen biasa; itu diperlakukan secara harfiah, dan kasusnya signifikan.
NameLength2
[Input] Panjang karakter *SchemaName.
TableName
[Input] Nama tabel. Argumen ini tidak boleh berupa penunjuk null. TableName tidak boleh berisi pola pencarian string.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, TableName diperlakukan sebagai pengidentifikasi dan kasusnya tidak signifikan. Jika SQL_FALSE, TableName adalah argumen biasa; itu diperlakukan secara harfiah, dan kasusnya signifikan.
NameLength3
[Input] Panjang karakter *TableName.
Cakupan
[Input] Cakupan minimum yang diperlukan dari rowid. Rowid yang dikembalikan mungkin memiliki cakupan yang lebih besar. Harus salah satu hal berikut:
SQL_SCOPE_CURROW: Rowid dijamin hanya valid saat diposisikan pada baris tersebut. Pemilihan ulang yang lebih baru menggunakan rowid mungkin tidak mengembalikan baris jika baris diperbarui atau dihapus oleh transaksi lain.
SQL_SCOPE_TRANSACTION: Rowid dijamin berlaku selama durasi transaksi saat ini.
SQL_SCOPE_SESSION: Rowid dijamin valid selama durasi sesi (di seluruh batas transaksi).
Dapat diubah ke null
[Input] Menentukan apakah akan mengembalikan kolom khusus yang dapat memiliki nilai NULL. Harus salah satu hal berikut:
SQL_NO_NULLS: Kecualikan kolom khusus yang bisa memiliki nilai NULL. Beberapa driver tidak dapat mendukung SQL_NO_NULLS, dan driver ini akan mengembalikan tataan hasil kosong jika SQL_NO_NULLS ditentukan. Aplikasi harus disiapkan untuk kasus ini dan meminta SQL_NO_NULLS hanya jika benar-benar diperlukan.
SQL_NULLABLE: Mengembalikan kolom khusus meskipun kolom tersebut dapat memiliki nilai NULL.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Ketika SQLSpecialColumns 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 SQLSpecialColumns 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.) |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 24000 | Status kursor tidak valid | Kursor terbuka pada StatementHandle, dan SQLFetch atau SQLFetchScroll telah dipanggil. Kesalahan ini dikembalikan oleh Manajer Driver jika SQLFetch atau SQLFetchScroll belum mengembalikan SQL_NO_DATA dan dikembalikan oleh driver jika SQLFetch atau SQLFetchScroll telah mengembalikan SQL_NO_DATA. Kursor terbuka pada StatementHandle, tetapi SQLFetch atau SQLFetchScroll belum dipanggil. |
| 40001 | Kegagalan serialisasi | Transaksi digulung balik karena kebuntuan sumber daya dengan transaksi lain. |
| 40003 | Penyelesaian pernyataan tidak diketahui | Koneksi terkait gagal selama eksekusi fungsi ini, dan status transaksi tidak dapat ditentukan. |
| 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. |
| 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. |
| HY009 | Penggunaan pointer null tidak valid | Argumen TableName adalah penunjuk null. Atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, argumen CatalogName adalah pointer null, dan infoType SQL_CATALOG_NAME mengembalikan bahwa nama katalog didukung. (DM) Atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, dan argumen SchemaName adalah pointer null. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi ini masih dijalankan ketika SQLSpecialColumns 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) 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 salah satu argumen panjang kurang dari 0 tetapi tidak sama dengan SQL_NTS. Nilai salah satu argumen panjang melebihi nilai panjang maksimum untuk nama yang sesuai. Panjang maksimum setiap nama dapat diperoleh dengan memanggil SQLGetInfo dengan nilai InfoType : SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, atau SQL_MAX_TABLE_NAME_LEN. |
| HY097 | Tipe kolom di luar rentang | (DM) Nilai IdentifierType yang tidak valid ditentukan. |
| HY098 | Jenis cakupan di luar rentang | (DM) Nilai Cakupan yang tidak valid ditentukan. |
| HY099 | Tipe nullable di luar rentang | (DM) Nilai Nullable yang tidak valid ditentukan. |
| 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. |
| HYC00 | Fitur opsional tidak diimplementasikan | Katalog ditentukan, dan driver atau sumber data tidak mendukung katalog. Skema ditentukan, dan driver atau sumber data tidak mendukung skema. Kombinasi pengaturan saat ini dari atribut pernyataan SQL_ATTR_CONCURRENCY dan SQL_ATTR_CURSOR_TYPE tidak didukung oleh driver atau sumber data. Atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_VARIABLE, dan atribut pernyataan SQL_ATTR_CURSOR_TYPE diatur ke jenis kursor yang drivernya tidak mendukung marka buku. |
| HYT00 | Waktu habis kedaluwarsa | Periode batas waktu kueri kedaluwarsa sebelum sumber data mengembalikan kumpulan hasil yang diminta. Periode batas waktu diatur melalui SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Kesalahan waktu habis koneksi kedaluwarsa | Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSet Koneksi Attr, 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. |
Komentar
Saat argumen IdentifierType SQL_BEST_ROWID, SQLSpecialColumns mengembalikan kolom atau kolom yang secara unik mengidentifikasi setiap baris dalam tabel. Kolom ini selalu dapat digunakan dalam klausa select-list atau WHERE . SQLColumns, yang digunakan untuk mengembalikan berbagai informasi tentang kolom tabel, tidak selalu mengembalikan kolom yang secara unik mengidentifikasi setiap baris, atau kolom yang secara otomatis diperbarui ketika nilai apa pun dalam baris diperbarui oleh transaksi. Misalnya, SQLColumns mungkin tidak mengembalikan ROWID kolom pseudo Oracle. Inilah sebabnya mengapa SQLSpecialColumns digunakan untuk mengembalikan kolom ini. Untuk informasi selengkapnya, lihat Penggunaan Data Katalog.
Catatan
Untuk informasi selengkapnya tentang penggunaan umum, argumen, dan data fungsi katalog ODBC yang dikembalikan, lihat Fungsi Katalog.
Jika tidak ada kolom yang secara unik mengidentifikasi setiap baris dalam tabel, SQLSpecialColumns mengembalikan set baris tanpa baris; panggilan berikutnya ke SQLFetch atau SQLFetchScroll pada pernyataan mengembalikan SQL_NO_DATA.
Jika argumen IdentifierType, Scope, atau Nullable menentukan karakteristik yang tidak didukung oleh sumber data, SQLSpecialColumns mengembalikan tataan hasil kosong.
Jika atribut pernyataan SQL_ATTR_METADATA_ID diatur ke SQL_TRUE, argumen CatalogName, SchemaName, dan TableName diperlakukan sebagai pengidentifikasi, sehingga tidak dapat diatur ke penunjuk null dalam situasi tertentu. (Untuk informasi selengkapnya, lihat Argumen dalam Fungsi Katalog.)
SQLSpecialColumns mengembalikan hasil sebagai hasil standar yang ditetapkan, diurutkan berdasarkan CAKUPAN.
Kolom berikut telah diganti namanya menjadi ODBC 3.x. Perubahan nama kolom tidak memengaruhi kompatibilitas mundur karena aplikasi mengikat dengan nomor kolom.
| Kolom ODBC 2.0 | Kolom ODBC 3.x |
|---|---|
| PRESISI | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SKALA | DECIMAL_DIGITS |
Untuk menentukan panjang aktual kolom COLUMN_NAME, aplikasi dapat memanggil SQLGetInfo dengan opsi SQL_MAX_COLUMN_NAME_LEN.
Tabel berikut mencantumkan kolom dalam tataan hasil. Kolom tambahan di luar kolom 8 (PSEUDO_COLUMN) dapat ditentukan oleh driver. Aplikasi harus mendapatkan akses ke kolom khusus driver dengan menghitung mundur dari akhir tataan hasil daripada menentukan posisi ordinal eksplisit. Untuk informasi selengkapnya, lihat Data yang Dikembalikan oleh Fungsi Katalog.
| Nama kolom | Nomor kolom | Jenis data | Komentar |
|---|---|---|---|
| CAKUPAN (ODBC 1.0) | 1 | Smallint | Cakupan aktual rowid. Berisi salah satu nilai berikut: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL dikembalikan ketika IdentifierType SQL_ROWVER. Untuk deskripsi setiap nilai, lihat deskripsi Cakupan dalam "Sintaks," sebelumnya di bagian ini. |
| COLUMN_NAME (ODBC 1.0) | 2 | Varchar bukan NULL | Nama kolom. Driver mengembalikan string kosong untuk kolom yang tidak memiliki nama. |
| DATA_TYPE (ODBC 1.0) | 3 | Smallint bukan NULL | Jenis data SQL. Ini bisa berupa jenis data ODBC SQL atau jenis data SQL khusus driver. Untuk daftar jenis data ODBC SQL yang valid, lihat Jenis Data SQL. Untuk informasi tentang jenis data SQL khusus driver, lihat dokumentasi driver. |
| TYPE_NAME (ODBC 1.0) | 4 | Varchar bukan NULL | Nama jenis data yang bergantung pada sumber data; misalnya, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY", atau "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 1.0) | 5 | Bilangan bulat | Ukuran kolom pada sumber data. Untuk informasi selengkapnya tentang ukuran kolom, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan. |
| BUFFER_LENGTH (ODBC 1.0) | 6 | Bilangan bulat | Panjang byte data yang ditransfer pada operasi SQLGetData atau SQLFetch jika SQL_C_DEFAULT ditentukan. Untuk data numerik, ukuran ini mungkin berbeda dari ukuran data yang disimpan pada sumber data. Nilai ini mungkin berbeda dari kolom COLUMN_SIZE untuk data karakter. Untuk informasi selengkapnya, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan. |
| DECIMAL_DIGITS (ODBC 1.0) | 7 | Smallint | Digit desimal kolom pada sumber data. NULL dikembalikan untuk jenis data di mana digit desimal tidak berlaku. Untuk informasi selengkapnya tentang digit desimal, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan. |
| PSEUDO_COLUMN (ODBC 2.0) | 8 | Smallint | Menunjukkan apakah kolom adalah kolom pseudo, seperti Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Catatan: Untuk interoperabilitas maksimum, kolom pseudo tidak boleh dikutip dengan karakter kutipan pengidentifikasi yang dikembalikan oleh SQLGetInfo. |
Setelah aplikasi mengambil nilai untuk SQL_BEST_ROWID, aplikasi dapat menggunakan nilai-nilai ini untuk memilih kembali baris tersebut dalam cakupan yang ditentukan. Pernyataan SELECT dijamin tidak mengembalikan baris atau satu baris.
Jika aplikasi memilih kembali baris berdasarkan kolom atau kolom rowid dan baris tidak ditemukan, aplikasi dapat mengasumsikan bahwa baris telah dihapus atau kolom rowid dimodifikasi. Sebaliknya tidak benar: bahkan jika rowid tidak berubah, kolom lain dalam baris mungkin telah berubah.
Kolom yang dikembalikan untuk jenis kolom SQL_BEST_ROWID berguna untuk aplikasi yang perlu menggulir ke depan dan ke belakang dalam tataan hasil untuk mengambil data terbaru dari sekumpulan baris. Kolom atau kolom rowid dijamin tidak berubah saat diposisikan pada baris tersebut.
Kolom atau kolom rowid mungkin tetap valid bahkan ketika kursor tidak diposisikan pada baris; aplikasi dapat menentukan ini dengan memeriksa kolom CAKUPAN dalam tataan hasil.
Kolom yang dikembalikan untuk jenis kolom SQL_ROWVER berguna untuk aplikasi yang memerlukan kemampuan untuk memeriksa apakah ada kolom dalam baris tertentu yang telah diperbarui saat baris dipilih kembali menggunakan rowid. Misalnya, setelah memilih ulang baris menggunakan rowid, aplikasi dapat membandingkan nilai sebelumnya dalam kolom SQL_ROWVER dengan yang baru saja diambil. Jika nilai dalam kolom SQL_ROWVER berbeda dari nilai sebelumnya, aplikasi dapat memberi tahu pengguna bahwa data pada tampilan telah berubah.
Contoh Kode
Untuk contoh kode fungsi serupa, lihat SQLColumns.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke kolom dalam tataan hasil | Fungsi SQLBindCol |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Mengembalikan kolom dalam tabel atau tabel | Fungsi SQLColumns |
| Mengambil satu baris atau blok data dalam arah terusan saja | Fungsi SQLFetch |
| Mengambil blok data atau menggulir melalui kumpulan hasil | Fungsi SQLFetchScroll |
| Mengembalikan kolom kunci primer | Fungsi SQLPrimaryKeys |