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 dari berikut ini:

SQL_SCOPE_CURROW: Rowid dijamin hanya valid saat diposisikan pada baris tersebut. Pemilihan ulang nanti 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 dari berikut ini:

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.

Mengembalikan

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 Driver Manager 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 dalam 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 penunjuk 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 penunjuk 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 Panjang string atau 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 Jenis kolom di luar rentang (DM) Nilai IdentifierType tidak valid ditentukan.
HY098 Jenis cakupan di luar rentang (DM) Nilai Cakupan yang tidak valid ditentukan.
HY099 Jenis nullable di luar rentang (DM) Nilai Nullable yang tidak valid ditentukan.
HY117 Koneksi ditangguhkan karena status transaksi 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 Batas waktu kedaluwarsa Periode batas waktu kueri kedaluwarsa sebelum sumber data mengembalikan tataan 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 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.

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 pada kolom tabel, tidak selalu mengembalikan kolom yang secara unik mengidentifikasi setiap baris, atau kolom yang diperbarui secara otomatis 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 tataan hasil standar, yang diurutkan berdasarkan CAKUPAN.

Kolom berikut telah diganti namanya untuk ODBC 3.x. Perubahan nama kolom tidak memengaruhi kompatibilitas mundur karena aplikasi mengikat menurut nomor kolom.

Kolom ODBC 2.0 Kolom ODBC 3.x
PRESISI COLUMN_SIZE
LENGTH BUFFER_LENGTH
SKALA DECIMAL_DIGITS

Untuk menentukan panjang sebenarnya dari kolom COLUMN_NAME, aplikasi dapat memanggil SQLGetInfo dengan opsi SQL_MAX_COLUMN_NAME_LEN.

Tabel berikut ini 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 saat 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 SQL jenis data. Ini bisa berupa tipe data SQL ODBC atau jenis data SQL khusus driver. Untuk daftar tipe data SQL ODBC 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 sama dengan kolom COLUMN_SIZE untuk data karakter atau biner. 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 tersebut adalah kolom semu, seperti Oracle ROWID:

SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Catatan: Untuk interoperabilitas maksimum, kolom semu 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 meskipun 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 membutuhkan kemampuan untuk memeriksa apakah ada kolom dalam baris tertentu yang telah diperbarui saat baris dipilih kembali menggunakan rowid. Misalnya, setelah memilih kembali baris menggunakan rowid, aplikasi dapat membandingkan nilai sebelumnya di 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.

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 maju-saja Fungsi SQLFetch
Mengambil blok data atau menggulir melalui kumpulan hasil Fungsi SQLFetchScroll
Mengembalikan kolom kunci primer Fungsi SQLPrimaryKeys

Lihat juga

Referensi API ODBC
File Header ODBC