Fungsi SQLTables

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: Grup Terbuka

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

Syntax

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

Arguments

StatementHandle
[Masukan] Pegangan pernyataan untuk hasil yang diambil.

CatalogName
[Input] Nama katalog. Argumen CatalogName menerima pola pencarian jika atribut lingkungan SQL_ODBC_VERSION SQL_OV_ODBC3; Itu tidak menerima pola pencarian jika SQL_OV_ODBC2 ditetapkan. Jika driver mendukung katalog untuk beberapa tabel tetapi tidak untuk yang lain, seperti saat 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
[Masukan] Panjang dalam karakter *CatalogName.

SchemaName
[Masukan] Pola pencarian string untuk nama skema. Jika driver mendukung skema untuk beberapa tabel tetapi tidak untuk yang lain, seperti saat 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
[Masukan] Panjang dalam karakter *SchemaName.

Nama Tabel
[Masukan] 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
[Masukan] Panjang dalam karakter *TableName.

Jenis Tabel
[Masukan] Daftar jenis tabel yang akan dicocokkan.

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.

NamaPanjang4
[Masukan] Panjang dalam karakter *TableType.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostics

Saat SQLTables mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan HandleStatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLTables dan menjelaskan masing-masing nilai dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATE yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.

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:

• Panggil 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 yang hak istimewanya SELECT tidak diberikan.

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

Untuk mendukung pencacahan katalog, skema, dan jenis tabel, semantik khusus berikut ditentukan untuk argumen CatalogName, SchemaName, TableName, dan TableTypeSQLTables:

• Jika CatalogName adalah 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 adalah 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 adalah 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, itu harus berisi daftar nilai yang dipisahkan koma untuk jenis minat; 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 dibutuhkan oleh sumber data. Jika sumber data tidak mendukung jenis tabel yang ditentukan, 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.

Tabel berikut mencantumkan kolom dalam tataan hasil. Kolom tambahan di luar kolom 5 (KETERANGAN) dapat ditentukan oleh pengemudi. 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.

Example

Contoh kode berikut tidak membebaskan pegangan dan koneksi. Lihat Fungsi SQLFreeHandle dan Fungsi SQLFreeStmt untuk sampel kode untuk membebaskan pegangan 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 );  
}  

Fungsi Terkait

Lihat Juga

Referensi API ODBC
File Header ODBC