SQLTables-Funktion

Artikel
05/23/2023

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: Open Group

Zusammenfassung
SQLTables gibt die Liste der Tabellen-, Katalog- oder Schemanamen und Tabellentypen zurück, die in einer bestimmten Datenquelle gespeichert sind. Der Treiber gibt die Informationen als Resultset zurück.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle für abgerufene Ergebnisse.

Catalogname
[Eingabe] Katalogname. Das CatalogName-Argument akzeptiert Suchmuster, wenn das SQL_ODBC_VERSION-Umgebungsattribut SQL_OV_ODBC3 ist. Es akzeptiert keine Suchmuster, wenn SQL_OV_ODBC2 festgelegt ist. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn ein Treiber Daten aus verschiedenen Datenbankdatenbanken abruft, gibt eine leere Zeichenfolge ("") die Tabellen an, die keine Kataloge enthalten.

Wenn das Attribut der SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird CatalogName als Bezeichner behandelt, und die Groß- und Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist CatalogName ein Musterwertargument. es wird wörtlich behandelt, und sein Fall ist von Bedeutung. Weitere Informationen finden Sie unter Argumente in Katalogfunktionen.

NameLength1
[Eingabe] Länge in Zeichen von *CatalogName.

Schemaname
[Eingabe] Zeichenfolgensuchmuster für Schemanamen. Wenn ein Treiber Schemas für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen Datenbankdatenbanken abruft, gibt eine leere Zeichenfolge ("") die Tabellen ohne Schemas an.

Wenn das Attribut SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird SchemaName als Bezeichner behandelt, und die Groß- und Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist SchemaName ein Musterwertargument. es wird wörtlich behandelt, und sein Fall ist von Bedeutung.

NameLength2
[Eingabe] Länge in Zeichen von *SchemaName.

TableName
[Eingabe] Zeichenfolgensuchmuster für Tabellennamen.

Wenn das Attribut SQL_ATTR_METADATA_ID-Anweisung auf SQL_TRUE festgelegt ist, wird TableName als Bezeichner behandelt, und die Groß- und Kleinschreibung ist nicht signifikant. Wenn es SQL_FALSE ist, ist TableName ein Musterwertargument. es wird wörtlich behandelt, und sein Fall ist von Bedeutung.

NameLength3
[Eingabe] Länge in Zeichen von *TableName.

TableType
[Eingabe] Liste der zu übereinstimmenden Tabellentypen.

Beachten Sie, dass das Attribut SQL_ATTR_METADATA_ID-Anweisung keine Auswirkungen auf das TableType-Argument hat. TableType ist ein Wertlistenargument, unabhängig von der Einstellung von SQL_ATTR_METADATA_ID.

NameLength4
[Eingabe] Länge in Zeichen von *TableType.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLTables SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLTables zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE	Fehler	BESCHREIBUNG
01000	Allgemeine Warnung	Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08S01	Kommunikationslinkfehler	Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden war, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde.
24.000	Ungültiger Cursorstatus	Im StatementHandle war ein Cursor geöffnet, und SQLFetch oder SQLFetchScroll wurde aufgerufen. Dieser Fehler wird vom Treiber-Manager zurückgegeben, wenn SQLFetch oder SQLFetchScroll nicht SQL_NO_DATA zurückgegeben hat und vom Treiber zurückgegeben wird, wenn SQLFetch oder SQLFetchScroll SQL_NO_DATA zurückgegeben hat. Im StatementHandle war ein Cursor geöffnet, aber SQLFetch oder SQLFetchScroll wurden nicht aufgerufen.
40001	Serialisierungsfehler	Die Transaktion wurde aufgrund eines Ressourcen-Deadlocks mit einer anderen Transaktion zurückgesetzt.
40003	Anweisungsabschluss unbekannt	Bei der zugehörigen Verbindung ist während der Ausführung dieser Funktion ein Fehler aufgetreten, und der Status der Transaktion kann nicht bestimmt werden.
HY000	Allgemeiner Fehler	Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001	Fehler bei der Speicherbelegung	Der Treiber konnte arbeitsspeicher nicht zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist.
HY008	Vorgang abgebrochen	Für statementHandle wurde die asynchrone Verarbeitung aktiviert. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die AnweisungHandle aufgerufen. Dann wurde die Funktion erneut auf der StatementHandle aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle auf der StatementHandle von einem anderen Thread in einer Multithreadanwendung aufgerufen.
HY009	Ungültige Verwendung von NULL-Zeiger	Das SQL_ATTR_METADATA_ID-Anweisungsattribut wurde auf SQL_TRUE festgelegt, das CatalogName-Argument war ein NULL-Zeiger, und die SQL_CATALOG_NAME InfoType gibt zurück, dass Katalognamen unterstützt werden. (DM) Das Attribut SQL_ATTR_METADATA_ID-Anweisung wurde auf SQL_TRUE festgelegt, und das SchemaName - oder TableName-Argument war ein NULL-Zeiger.
HY010	Funktionssequenzfehler	(DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als SQLTables aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese Funktion) wurde für das StatementHandle aufgerufen und wurde weiterhin ausgeführt, als diese Funktion aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden.
HY013	Fehler bei der Speicherverwaltung	Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen.
HY090	Ungültige Zeichenfolgen- oder Pufferlänge	(DM) Der Wert eines der Längenargumente war kleiner als 0, aber nicht gleich SQL_NTS. Der Wert eines der Namenslängenargumente überschreitet den maximalen Längenwert für den entsprechenden Namen.
HY117	Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- und schreibgeschützte Funktionen sind zulässig.	(DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYC00	Optionales Feature nicht implementiert	Ein Katalog wurde angegeben, und der Treiber oder die Datenquelle unterstützt keine Kataloge. Es wurde ein Schema angegeben, und der Treiber oder die Datenquelle unterstützt keine Schemas. Für den Katalognamen, das Tabellenschema oder den Tabellennamen wurde ein Zeichenfolgensuchmuster angegeben, und die Datenquelle unterstützt keine Suchmuster für eines oder mehrere dieser Argumente. Die Kombination aus den aktuellen Einstellungen des SQL_ATTR_CONCURRENCY- und SQL_ATTR_CURSOR_TYPE-Anweisungsattributes wurde vom Treiber oder der Datenquelle nicht unterstützt. Das SQL_ATTR_USE_BOOKMARKS-Anweisungsattribut wurde auf SQL_UB_VARIABLE festgelegt, und das Attribut der SQL_ATTR_CURSOR_TYPE-Anweisung wurde auf einen Cursortyp festgelegt, für den der Treiber keine Lesezeichen unterstützt.
HYT00	Timeout abgelaufen	Der Abfragetimeoutzeitraum ist abgelaufen, bevor die Datenquelle das angeforderte Resultset zurückgegeben hat. Der Timeoutzeitraum wird über SQLSetStmtAttr festgelegt, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Verbindungstimeout abgelaufen	Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Treiber unterstützt diese Funktion nicht.	(DM) Der Der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht.
IM017	Abruf ist im asynchronen Benachrichtigungsmodus deaktiviert.	Wenn das Benachrichtigungsmodell verwendet wird, wird die Abfrage deaktiviert.
IM018	SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen.	Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen.

Kommentare

SQLTables listet alle Tabellen im angeforderten Bereich auf. Ein Benutzer kann über SELECT-Berechtigungen für eine dieser Tabellen verfügen oder nicht. Um die Barrierefreiheit zu überprüfen, kann eine Anwendung:

Rufen Sie SQLGetInfo auf , und überprüfen Sie den SQL_ACCESSIBLE_TABLES Informationstyp.
Rufen Sie SQLTablePrivileges auf , um die Berechtigungen für jede Tabelle zu überprüfen.

Andernfalls muss die Anwendung in der Lage sein, eine Situation zu behandeln, in der der Benutzer eine Tabelle auswählt, für die KEINE SELECT-Berechtigungen gewährt werden.

Die Argumente SchemaName und TableName akzeptieren Suchmuster. Das Argument CatalogName akzeptiert Suchmuster, wenn das SQL_ODBC_VERSION-Umgebungsattribut SQL_OV_ODBC3 ist. Es akzeptiert keine Suchmuster, wenn SQL_OV_ODBC2 festgelegt ist. Wenn SQL_OV_ODBC3 festgelegt ist, erfordert ein ODBC 3*.x*-Treiber, dass Wildcardzeichen im CatalogName-Argument mit Escapezeichen versehen werden, damit sie wörtlich behandelt werden. Weitere Informationen zu gültigen Suchmustern finden Sie unter Musterwertargumente.

Hinweis

Weitere Informationen zur allgemeinen Verwendung, zu Argumenten und zurückgegebenen Daten von ODBC-Katalogfunktionen finden Sie unter Katalogfunktionen.

Um die Enumeration von Katalogen, Schemas und Tabellentypen zu unterstützen, werden die folgenden speziellen Semantiken für die Argumente CatalogName, SchemaName, TableName und TableType von SQLTables definiert:

Wenn CatalogName SQL_ALL_CATALOGS und SchemaName und TableName leere Zeichenfolgen sind, enthält das Resultset eine Liste gültiger Kataloge für die Datenquelle. (Alle Spalten mit Ausnahme der spalte TABLE_CAT enthalten NULLs.)
Wenn SchemaName SQL_ALL_SCHEMAS und CatalogName und TableName leere Zeichenfolgen sind, enthält das Resultset eine Liste gültiger Schemas für die Datenquelle. (Alle Spalten mit Ausnahme der spalte TABLE_SCHEM enthalten NULLs.)
Wenn TableType SQL_ALL_TABLE_TYPES und CatalogName, SchemaName und TableName leere Zeichenfolgen sind, enthält das Resultset eine Liste gültiger Tabellentypen für die Datenquelle. (Alle Spalten mit Ausnahme der spalte TABLE_TYPE enthalten NULLs.)

Wenn TableType keine leere Zeichenfolge ist, muss es eine Liste mit durch Trennzeichen getrennten Werten für die relevanten Typen enthalten. Jeder Wert kann in einfache Anführungszeichen (') oder ohne Anführungszeichen eingeschlossen werden, z. B. "TABLE", "VIEW" oder "TABLE, VIEW". Eine Anwendung sollte den Tabellentyp immer in Großbuchstaben angeben. Der Treiber sollte den Tabellentyp in jeden Fall konvertieren, der von der Datenquelle benötigt wird. Wenn die Datenquelle einen angegebenen Tabellentyp nicht unterstützt, gibt SQLTables keine Ergebnisse für diesen Typ zurück.

SQLTables gibt die Ergebnisse als Standardresultset zurück, geordnet nach TABLE_TYPE, TABLE_CAT, TABLE_SCHEM und TABLE_NAME. Informationen dazu, wie diese Informationen verwendet werden können, finden Sie unter Verwendung von Katalogdaten.

Um die tatsächliche Länge der spalten TABLE_CAT, TABLE_SCHEM und TABLE_NAME zu bestimmen, kann eine Anwendung SQLGetInfo mit den Informationstypen SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN und SQL_MAX_TABLE_NAME_LEN aufrufen.

Die folgenden Spalten wurden für ODBC 3*.x* umbenannt. Die Änderungen des Spaltennamens wirken sich nicht auf die Abwärtskompatibilität aus, da Anwendungen anhand der Spaltennummer gebunden werden.

ODBC 2.0-Spalte	ODBC 3.x-Spalte
TABLE_QUALIFIER	TABLE_CAT
TABLE_OWNER	TABLE_SCHEM

In der folgenden Tabelle sind die Spalten im Resultset aufgeführt. Zusätzliche Spalten über Spalte 5 (ANMERKUNGEN) hinaus können vom Treiber definiert werden. Eine Anwendung sollte Zugriff auf treiberspezifische Spalten erhalten, indem sie vom Ende des Resultsets heruntergezählt wird, anstatt eine explizite Ordnungsposition anzugeben. Weitere Informationen finden Sie unter Von Katalogfunktionen zurückgegebene Daten.

Spaltenname	Spaltennummer	Datentyp	Kommentare
TABLE_CAT (ODBC 1.0)	1	Varchar	Katalogname; NULL, wenn nicht auf die Datenquelle anwendbar. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen DBMS abruft, gibt er eine leere Zeichenfolge ("") für die Tabellen zurück, die keine Kataloge enthalten.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Schemaname; NULL, wenn nicht auf die Datenquelle anwendbar. Wenn ein Treiber Schemas für einige Tabellen unterstützt, aber nicht für andere, z. B. wenn der Treiber Daten aus verschiedenen DBMS abruft, gibt er eine leere Zeichenfolge ("") für die Tabellen zurück, die keine Schemas haben.
TABLE_NAME (ODBC 1.0)	3	Varchar	Tabellenname.
TABLE_TYPE (ODBC 1.0)	4	Varchar	Name des Tabellentyps; eine der folgenden: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" oder ein datenquellenspezifischer Typname. Die Bedeutungen von "ALIAS" und "SYNONYM" sind treiberspezifisch.
HINWEISE (ODBC 1.0)	5	Varchar	Eine Beschreibung der Tabelle.

Beispiel

Der folgende Beispielcode gibt keine Handles und Verbindungen frei. Codebeispiele zum Freigeben von Handles und Anweisungen finden Sie unter SQLFreeHandle-Funktion und SQLFreeStmt-Funktion .

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

Informationen über	Finden Sie unter
Binden eines Puffers an eine Spalte in einem Resultset	SQLBindCol-Funktion
Abbrechen der Anweisungsverarbeitung	SQLCancel-Funktion
Zurückgeben von Berechtigungen für eine Spalte oder Spalten	SQLColumnPrivileges-Funktion
Zurückgeben der Spalten in einer Tabelle oder Tabellen	SQLColumns-Funktion
Abrufen einer einzelnen Zeile oder eines Datenblocks in vorwärtsgerichteter Richtung	SQLFetch-Funktion
Abrufen eines Datenblocks oder Scrollen durch ein Resultset	SQLFetchScroll-Funktion
Zurückgeben von Tabellenstatistiken und Indizes	SQLStatistics-Funktion
Zurückgeben von Berechtigungen für eine Tabelle oder Tabellen	SQLTablePrivileges-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien

Teilen über

SQLTables-Funktion

Syntax

Argumente

Gibt zurück

Diagnose

Kommentare

Beispiel

Weitere Informationen

Feedback

Zusätzliche Ressourcen

Teilen über

SQLTables-Funktion

Syntax

Argumente

Gibt zurück

Diagnose

Kommentare

Beispiel

Verwandte Funktionen

Weitere Informationen

Feedback

Zusätzliche Ressourcen