Funkce SQLTables

Soulad
Představená verze: ODBC 1.0 Soulad standardů: Open Group

Shrnutí
SQLTables vrací seznam názvů tabulek, katalogů nebo schémat a typů tabulek, uložených v konkrétním datovém zdroji. Ovladač vrátí informace jako sadu výsledků.

Syntax

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

Arguments

StatementHandle
[Vstup] Handle příkazu pro získané výsledky.

CatalogName
[Vstup] Název katalogu. Argument CatalogName přijímá vyhledávací vzory, pokud je atribut SQL_ODBC_VERSION environment SQL_OV_ODBC3; nepřijímá vyhledávací vzory, pokud je SQL_OV_ODBC2 nastaveno. Pokud ovladač podporuje katalogy pro některé tabulky, ale ne pro jiné, například když ovladač získává data z různých DBMS, prázdný řetězec ("") označuje ty tabulky, které katalogy nemají.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, CatalogName je považován za identifikátor a jeho případ není významný. Pokud je to SQL_FALSE, CatalogName je argument vzorové hodnoty; Je brána doslovně a její případ je významný. Další informace naleznete v tématu Argumenty funkce katalogu.

NameLength1
[Vstup] Délka znaků *CatalogName.

Název schématu
[Vstup] Vzor vyhledávání řetězců pro názvy schémat. Pokud ovladač podporuje schémata pro některé tabulky, ale ne pro jiné, například když ovladač získává data z různých DBMS, prázdný řetězec ("") označuje ty tabulky, které schémata nemají.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, SchemaName je považován za identifikátor a jeho případ není významný. Pokud je to SQL_FALSE, SchemaName je argument hodnoty vzoru; Je brána doslovně a její případ je významný.

NameLength2
[Vstup] Délka znaků *SchemaName.

TableName
[Vstup] Vzor vyhledávání řetězců pro názvy tabulek.

Pokud je atribut SQL_ATTR_METADATA_ID příkazu nastaven na SQL_TRUE, TableName je považován za identifikátor a jeho případ není významný. Pokud je SQL_FALSE, TableName je argument vzorové hodnoty; Je brána doslovně a její případ je významný.

NameLength3
[Vstup] Délka znaků *TableName.

Typ tabulky
[Vstup] Seznam typů tabulek, které je třeba shodovat.

Všimněte si, že atribut SQL_ATTR_METADATA_ID příkazu nemá žádný vliv na argument TableType . TableType je argument se seznamem hodnot, bez ohledu na nastavení SQL_ATTR_METADATA_ID.

NameLength4
[Vstup] Délka ve znacích *TableType.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR nebo SQL_INVALID_HANDLE.

Diagnostics

Když SQLTables vrátí SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, kterou lze získat voláním SQLGetDiagRec pomocí HandleType SQL_HANDLE_STMT a HandleStatementHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLTables obvykle vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

Comments

SQLTables uvádí všechny tabulky v požadovaném rozsahu. Uživatel může, ale nemusí mít SELECT práva k kterémukoli z těchto tabulek. Pro kontrolu přístupnosti může aplikace:

• Zavolejte na SQLGetInfo a zkontrolujte typ SQL_ACCESSIBLE_TABLES informací.

• Zavolejte SQLTablePrivileges a zkontrolujte oprávnění pro každou tabulku.

Jinak musí aplikace zvládnout situaci, kdy uživatel vybere tabulku, pro kterou nejsou uděleny oprávnění SELECT .

Argumenty SchemaName a TableName přijímají vyhledávací vzory. Argument CatalogName přijímá vyhledávací vzory, pokud je atribut SQL_ODBC_VERSION environment SQL_OV_ODBC3; nepřijímá vyhledávací vzory, pokud je SQL_OV_ODBC2 nastaveno. Pokud je SQL_OV_ODBC3 nastaveno, ovladač ODBC 3*.x* bude vyžadovat, aby byly v argumentu CatalogName uniknuty žolíkové znaky, aby byly brány doslovně. Pro více informací o platných vyhledávacích vzorcích viz Argumenty hodnoty vzoru.

Pro podporu enumerace katalogů, schémat a typů tabulek jsou definovány následující speciální sémantiky pro argumenty CatalogName, SchemaName, TableName a TableType v SQLTables:

• Pokud je CatalogName SQL_ALL_CATALOGS a SchemaName a TableName prázdné řetězce, výsledná sada obsahuje seznam platných katalogů pro datový zdroj. (Všechny sloupce kromě sloupce TABLE_CAT obsahují NULLs.)

• Pokud je SchemaName SQL_ALL_SCHEMAS a CatalogName a TableName prázdné řetězce, výsledná sada obsahuje seznam platných schémat pro datový zdroj. (Všechny sloupce kromě sloupce TABLE_SCHEM obsahují NULLy.)

• Pokud je TableType SQL_ALL_TABLE_TYPES a CatalogName, SchemaName a TableName prázdné řetězce, výsledná sada obsahuje seznam platných typů tabulek pro datový zdroj. (Všechny sloupce kromě sloupce TABLE_TYPE obsahují NULLs.)

Pokud TableType není prázdný řetězec, musí obsahovat seznam hodnot oddělených čárkami pro typy zájmu; Každá hodnota může být uzavřena v jedné uvozovkách (') nebo bez uvozovek, například 'TABLE', 'VIEW' nebo TABLE, VIEW. Aplikace by měla vždy uvádět typ tabulky velkými písmeny; Ovladač by měl převést typ tabulky na případ, který potřebuje datový zdroj. Pokud datový zdroj nepodporuje specifikovaný typ tabulky, SQLTables nevrací žádné výsledky pro tento typ.

SQLTables vrací výsledky jako standardní množinu výsledků, seřazenou podle TABLE_TYPE, TABLE_CAT, TABLE_SCHEM a TABLE_NAME. Informace o použití těchto informací naleznete v tématu Použití dat katalogu.

Pro určení skutečných délek sloupců TABLE_CAT, TABLE_SCHEM a TABLE_NAME může aplikace volat SQLGetInfo s typy informací SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN a SQL_MAX_TABLE_NAME_LEN.

Následující sloupce byly přejmenovány pro ODBC 3*.x*. Změny názvů sloupců neovlivňují zpětnou kompatibilitu, protože aplikace se vážou podle čísla sloupce.

Následující tabulka uvádí sloupce v sadě výsledků. Další sloupce za sloupcem 5 (POZNÁMKY) může řidič definovat. Aplikace by měla získat přístup ke sloupcům specifickým pro ovladače tím, že odpočítává od konce sady výsledků místo určení explicitní řadové pozice. Další informace naleznete v tématu Data vrácená funkcemi katalogu.

Example

Následující ukázkový kód nenabízí volné rukojeti a spojení. Viz SQLFreeHandle Function a SQLFreeStmt Function pro ukázky kódu pro volné rukojeti a příkazy.

// 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 );  
}  

Související funkce

Viz také

Referenční rozhraní ODBC API
Soubory hlaviček ODBC