Fungsi SQLTables

Artikel
05/23/2023

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: Grup Terbuka

Ringkasan
SQLTables mengembalikan daftar nama tabel, katalog, atau skema, dan tipe tabel, yang disimpan dalam sumber data tertentu. Driver mengembalikan informasi sebagai kumpulan hasil.

Sintaks

  
SQLRETURN SQLTables(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      TableType,  
     SQLSMALLINT    NameLength4);

Argumen

StatementHandle
[Input] Handel pernyataan untuk hasil yang diambil.

CatalogName
[Input] Nama katalog. Argumen CatalogName menerima pola pencarian jika atribut lingkungan SQL_ODBC_VERSION SQL_OV_ODBC3; argumen tidak menerima pola pencarian jika SQL_OV_ODBC2 diatur. 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.

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 nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan. Untuk informasi selengkapnya, lihat Argumen di Fungsi Katalog.

NameLength1
[Input] Panjang karakter *CatalogName.

SchemaName
[Input] Pola pencarian string untuk 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.

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 nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan.

NameLength2
[Input] Panjang karakter *SchemaName.

TableName
[Input] Pola pencarian string untuk nama tabel.

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 nilai pola; itu diperlakukan secara harfiah, dan kasusnya signifikan.

NameLength3
[Input] Panjang karakter *TableName.

TableType
[Input] Daftar jenis tabel yang cocok.

Perhatikan bahwa atribut pernyataan SQL_ATTR_METADATA_ID tidak berpengaruh pada argumen TableType . TableType adalah argumen daftar nilai, terlepas dari pengaturan SQL_ATTR_METADATA_ID.

NameLength4
[Input] Panjang karakter *TableType.

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Saat SQLTables 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 SQLTables 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	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 atau TableName 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 SQLTables 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 nama melebihi nilai panjang maksimum untuk nama yang sesuai.
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. Pola pencarian string ditentukan untuk nama katalog, skema tabel, atau nama tabel, dan sumber data tidak mendukung pola pencarian untuk satu atau beberapa argumen tersebut. 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

SQLTables mencantumkan semua tabel dalam rentang yang diminta. Pengguna mungkin atau mungkin tidak memiliki hak istimewa SELECT ke salah satu tabel ini. Untuk memeriksa aksesibilitas, aplikasi dapat:

Hubungi SQLGetInfo dan periksa jenis informasi SQL_ACCESSIBLE_TABLES.
Panggil SQLTablePrivileges untuk memeriksa hak istimewa untuk setiap tabel.

Jika tidak, aplikasi harus dapat menangani situasi di mana pengguna memilih tabel tempat hak istimewa SELECT tidak diberikan.

Argumen SchemaName dan TableName menerima pola pencarian. Argumen CatalogName menerima pola pencarian jika atribut lingkungan SQL_ODBC_VERSION SQL_OV_ODBC3; argumen tidak menerima pola pencarian jika SQL_OV_ODBC2 diatur. Jika SQL_OV_ODBC3 diatur, driver ODBC 3*.x* akan mengharuskan karakter wildcard dalam argumen CatalogName diloloskan untuk diperlakukan secara harfiah. Untuk informasi selengkapnya tentang pola pencarian yang valid, lihat Argumen Nilai Pola.

Catatan

Untuk informasi selengkapnya tentang penggunaan umum, argumen, dan data fungsi katalog ODBC yang dikembalikan, lihat Fungsi Katalog.

Untuk mendukung enumerasi katalog, skema, dan jenis tabel, semantik khusus berikut didefinisikan untuk argumen CatalogName, SchemaName, TableName, dan TableType dari SQLTables:

Jika CatalogName SQL_ALL_CATALOGS dan SchemaName dan TableName adalah string kosong, kumpulan hasil berisi daftar katalog yang valid untuk sumber data. (Semua kolom kecuali kolom TABLE_CAT berisi NULL.)
Jika SchemaName SQL_ALL_SCHEMAS dan CatalogName dan TableName adalah string kosong, kumpulan hasil berisi daftar skema yang valid untuk sumber data. (Semua kolom kecuali kolom TABLE_SCHEM berisi NULL.)
Jika TableType SQL_ALL_TABLE_TYPES dan CatalogName, SchemaName, dan TableName adalah string kosong, kumpulan hasil berisi daftar jenis tabel yang valid untuk sumber data. (Semua kolom kecuali kolom TABLE_TYPE berisi NULL.)

Jika TableType bukan string kosong, tableType harus berisi daftar nilai yang dipisahkan koma untuk jenis yang diminati; setiap nilai dapat diapit dalam tanda kutip tunggal (') atau tidak dikutip, misalnya, 'TABLE', 'VIEW' atau TABLE, VIEW. Aplikasi harus selalu menentukan jenis tabel dalam huruf besar; driver harus mengonversi jenis tabel ke kasus apa pun yang diperlukan oleh sumber data. Jika sumber data tidak mendukung tipe tabel tertentu, SQLTables tidak mengembalikan hasil apa pun untuk jenis tersebut.

SQLTables mengembalikan hasil sebagai kumpulan hasil standar, diurutkan berdasarkan TABLE_TYPE, TABLE_CAT, TABLE_SCHEM, dan TABLE_NAME. Untuk informasi tentang bagaimana informasi ini dapat digunakan, lihat Penggunaan Data Katalog.

Untuk menentukan panjang aktual kolom TABLE_CAT, TABLE_SCHEM, dan TABLE_NAME, aplikasi dapat memanggil SQLGetInfo dengan jenis informasi SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, dan SQL_MAX_TABLE_NAME_LEN.

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

Tabel berikut mencantumkan kolom dalam tataan hasil. Kolom tambahan di luar kolom 5 (REMARKS) 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; 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; 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	Nama tabel.
TABLE_TYPE (ODBC 1.0)	4	Varchar	Nama jenis tabel; salah satu hal berikut: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM", atau nama jenis khusus sumber data. Arti "ALIAS" dan "SINONIM" khusus driver.
KOMENTAR (ODBC 1.0)	5	Varchar	Deskripsi tabel.

Contoh

Kode sampel berikut tidak membebaskan handel dan koneksi. Lihat Fungsi SQLFreeHandle dan Fungsi SQLFreeStmt untuk sampel kode guna mengosongkan handel dan pernyataan.

// SQLTables.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
// simple helper functions  
int MySQLSuccess(SQLRETURN rc) {  
   return (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO);  
}  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printCatalog(const struct DataBinding* catalogResult) {  
   if (catalogResult[0].StrLen_or_Ind != SQL_NULL_DATA)   
      printf("Catalog Name = %s\n", (char *)catalogResult[0].TargetValuePtr);  
}  
  
// remember to disconnect and free memory, and free statements and handles  
int main() {  
   int bufferSize = 1024, i, numCols = 5;  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   wchar_t* dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   wchar_t* userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR*)"Driver={SQL Server}", SQL_NTS, (SQLCHAR*)connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferSize);  
  
   bufferSize = 1024;  
  
   // allocate memory for the binding  
   // free this memory when done  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // setup the binding (can be used even if the statement is closed by closeStatementHandle)  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   // all catalogs query  
   printf( "A list of names of all catalogs\n" );  
   retCode = SQLTables( hstmt, (SQLCHAR*)SQL_ALL_CATALOGS, SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS, (SQLCHAR*)"", SQL_NTS );  
   for ( retCode = SQLFetch(hstmt) ;  MySQLSuccess(retCode) ; retCode = SQLFetch(hstmt) )  
      printCatalog( catalogResult );  
}

Untuk informasi tentang	Lihat
Mengikat buffer ke kolom dalam tataan hasil	Fungsi SQLBindCol
Membatalkan pemrosesan pernyataan	Fungsi SQLCancel
Mengembalikan hak istimewa untuk kolom atau kolom	Fungsi SQLColumnPrivileges
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 statistik dan indeks tabel	Fungsi SQLStatistics
Mengembalikan hak istimewa untuk tabel atau tabel	Fungsi SQLTablePrivileges

Lihat Juga

Referensi API ODBC
File Header ODBC

Bagikan melalui

Fungsi SQLTables

Sintaks

Argumen

Kembali

Diagnostik

Komentar

Contoh

Lihat Juga

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Fungsi SQLTables

Sintaks

Argumen

Kembali

Diagnostik

Komentar

Contoh

Fungsi Terkait

Lihat Juga

Saran dan Komentar

Sumber Daya Tambahan: