Fungsi SQLStatistics
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLStatistics mengambil daftar statistik tentang satu tabel dan indeks yang terkait dengan tabel. Driver mengembalikan informasi sebagai kumpulan hasil.
Sintaks
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
Argumen
StatementHandle
[Input] Handel pernyataan.
CatalogName
[Input] Nama katalog. 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. 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. SchemaName 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.
Unik
[Input] Jenis indeks: SQL_INDEX_UNIQUE atau SQL_INDEX_ALL.
Dipesan
[Input] Menunjukkan pentingnya kolom CARDINALITY dan PAGES dalam tataan hasil. Opsi berikut hanya memengaruhi pengembalian kolom CARDINALITY dan PAGES; informasi indeks dikembalikan meskipun CARDINALITY dan PAGES tidak dikembalikan.
SQL_ENSURE meminta agar driver secara tidak bersyarat mengambil statistik. (Driver yang hanya sesuai dengan standar Grup Terbuka dan tidak mendukung ekstensi ODBC tidak akan dapat mendukung SQL_ENSURE.)
SQL_QUICK meminta agar driver mengambil CARDINALITY dan PAGES hanya jika tersedia dari server. Dalam hal ini, driver tidak memastikan bahwa nilai saat ini. (Aplikasi yang ditulis ke standar Grup Terbuka akan selalu mendapatkan perilaku SQL_QUICK dari ODBC 3.x-compliant drivers.)
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLStatistics 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 biasanya dikembalikan oleh SQLStatistics 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, dan 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 asinkron ini masih dijalankan ketika fungsi SQLStatistics 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 nama kurang dari 0 tetapi tidak sama dengan SQL_NTS. Nilai salah satu argumen panjang nama melebihi nilai panjang maksimum untuk nama yang sesuai. |
| HY100 | Jenis opsi keunikan di luar rentang | (DM) Nilai Unik yang tidak valid ditentukan. |
| HY101 | Jenis opsi akurasi di luar rentang | (DM) Nilai Cadangan 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 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
SQLStatistics mengembalikan informasi tentang satu tabel sebagai tataan hasil standar, diurutkan berdasarkan NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, dan ORDINAL_POSITION. Kumpulan hasil menggabungkan informasi statistik (di kolom CARDINALITY dan PAGES dari tataan hasil) untuk tabel dengan informasi tentang setiap indeks. Untuk informasi tentang bagaimana informasi ini dapat digunakan, lihat Penggunaan Data Katalog.
Untuk menentukan panjang aktual kolom TABLE_CAT, TABLE_SCHEM, TABLE_NAME, dan COLUMN_NAME, aplikasi dapat memanggil SQLGetInfo dengan opsi SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, dan SQL_MAX_COLUMN_NAME_LEN.
Catatan
Untuk informasi selengkapnya tentang penggunaan umum, argumen, dan data fungsi katalog ODBC yang dikembalikan, lihat Fungsi Katalog.
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 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
| SEQ_IN_INDEX | ORDINAL_POSITION |
| PEMERIKSAAN | ASC_OR_DESC |
Tabel berikut mencantumkan kolom dalam tataan hasil. Kolom tambahan di luar kolom 13 (FILTER_CONDITION) dapat ditentukan oleh driver. Aplikasi harus mendapatkan akses ke kolom khusus driver dengan menghitung mundur dari akhir tataan hasil alih-alih menentukan posisi ordinal eksplisit. Untuk informasi selengkapnya, lihat Data yang Dikembalikan oleh Fungsi Katalog.
| Nama kolom | Nomor kolom | Jenis Data | Komentar |
|---|---|---|---|
| TABLE_CAT (ODBC 1.0) | 1 | Varchar | Nama katalog tabel tempat statistik atau indeks berlaku; NULL jika tidak berlaku untuk sumber data. Jika driver mendukung katalog untuk beberapa tabel tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, itu mengembalikan string kosong ("") untuk tabel yang tidak memiliki katalog. |
| TABLE_SCHEM (ODBC 1.0) | 2 | Varchar | Nama skema tabel tempat statistik atau indeks berlaku; NULL jika tidak berlaku untuk sumber data. Jika driver mendukung skema untuk beberapa tabel tetapi tidak untuk yang lain, seperti ketika driver mengambil data dari DBMS yang berbeda, itu mengembalikan string kosong ("") untuk tabel yang tidak memiliki skema. |
| TABLE_NAME (ODBC 1.0) | 3 | Varchar bukan NULL | Nama tabel tabel tempat statistik atau indeks diterapkan. |
| NON_UNIQUE (ODBC 1.0) | 4 | Smallint | Menunjukkan apakah indeks tidak mengizinkan nilai duplikat: SQL_TRUE jika nilai indeks bisa tidak menyatu. SQL_FALSE jika nilai indeks harus unik. NULL dikembalikan jika TYPE SQL_TABLE_STAT. |
| INDEX_QUALIFIER (ODBC 1.0) | 5 | Varchar | Pengidentifikasi yang digunakan untuk memenuhi syarat nama indeks yang melakukan DROP INDEX; NULL dikembalikan jika kualifikasi indeks tidak didukung oleh sumber data atau jika TYPE SQL_TABLE_STAT. Jika nilai non-null dikembalikan dalam kolom ini, nilai tersebut harus digunakan untuk memenuhi syarat nama indeks pada pernyataan DROP INDEX ; jika tidak, TABLE_SCHEM harus digunakan untuk memenuhi syarat nama indeks. |
| INDEX_NAME (ODBC 1.0) | 6 | Varchar | Nama indeks; NULL dikembalikan jika TYPE SQL_TABLE_STAT. |
| TYPE (ODBC 1.0) | 7 | Smallint bukan NULL | Jenis informasi yang dikembalikan: SQL_TABLE_STAT menunjukkan statistik untuk tabel (di kolom CARDINALITY atau PAGES). SQL_INDEX_BTREE menunjukkan indeks B-Tree. SQL_INDEX_CLUSTERED menunjukkan indeks berkluster. SQL_INDEX_CONTENT menunjukkan indeks konten. SQL_INDEX_HASHED menunjukkan indeks yang di-hash. SQL_INDEX_OTHER menunjukkan jenis indeks lain. |
| ORDINAL_POSITION (ODBC 1.0) | 8 | Smallint | Nomor urutan kolom dalam indeks (dimulai dengan 1); NULL dikembalikan jika TYPE SQL_TABLE_STAT. |
| COLUMN_NAME (ODBC 1.0) | 9 | Varchar | Nama kolom. Jika kolom didasarkan pada ekspresi, seperti GAJI + KEUNTUNGAN, ekspresi dikembalikan; jika ekspresi tidak dapat ditentukan, string kosong dikembalikan. NULL dikembalikan jika TYPE SQL_TABLE_STAT. |
| ASC_OR_DESC (ODBC 1.0) | 10 | Char(1) | Urutkan urutan untuk kolom: "A" untuk naik; "D" untuk turun; NULL dikembalikan jika urutan pengurutan kolom tidak didukung oleh sumber data atau jika TYPE SQL_TABLE_STAT. |
| KARDINALITAS (ODBC 1.0) | 11 | Bilangan bulat | Kardinalitas tabel atau indeks; jumlah baris dalam tabel jika TYPE SQL_TABLE_STAT; jumlah nilai unik dalam indeks jika TYPE tidak SQL_TABLE_STAT; NULL dikembalikan jika nilai tidak tersedia dari sumber data. |
| PAGES (ODBC 1.0) | 12 | Bilangan bulat | Jumlah halaman yang digunakan untuk menyimpan indeks atau tabel; jumlah halaman untuk tabel jika TYPE SQL_TABLE_STAT; jumlah halaman untuk indeks jika TYPE tidak SQL_TABLE_STAT; NULL dikembalikan jika nilai tidak tersedia dari sumber data atau jika tidak berlaku untuk sumber data. |
| FILTER_CONDITION (ODBC 2.0) | 13 | Varchar | Jika indeks adalah indeks yang difilter, ini adalah kondisi filter, seperti GAJI > 30000; jika kondisi filter tidak dapat ditentukan, ini adalah string kosong. NULL jika indeks bukan indeks yang difilter, indeks tidak dapat ditentukan apakah indeks adalah indeks yang difilter, atau TYPE SQL_TABLE_STAT. |
Jika baris dalam tataan hasil sesuai dengan tabel, driver mengatur TYPE ke SQL_TABLE_STAT dan mengatur NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME, dan ASC_OR_DESC ke NULL. Jika CARDINALITY atau PAGES tidak tersedia dari sumber data, driver mengaturnya ke NULL.
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 |
| 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 asing | Fungsi SQLForeignKeys |
| Mengembalikan kolom kunci primer | Fungsi SQLPrimaryKeys |