SQLTables-functie

Conformiteit
Versie geïntroduceerd: ODBC 1.0 Standaardnaleving: Open Group

Samenvatting
SQLTables geeft de lijst met tabel-, catalogus- of schemanamen en tabeltypen terug, opgeslagen in een specifieke databron. Het stuurprogramma retourneert de informatie als resultaatset.

Syntax

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

Arguments

StatementHandle
[Invoer] Statementhandle voor opgehaalde resultaten.

CatalogName
[Invoer] Catalogusnaam. Het CatalogName-argument accepteert zoekpatronen als het SQL_ODBC_VERSION environment-attribuut SQL_OV_ODBC3 is; het accepteert geen zoekpatronen als SQL_OV_ODBC2 is ingesteld. Als een driver catalogi ondersteunt voor sommige tabellen maar niet voor andere, bijvoorbeeld wanneer een driver gegevens ophaalt uit verschillende DBMS'en, geeft een lege string ("") aan welke tabellen geen catalogi hebben.

Als het SQL_ATTR_METADATA_ID-statementattribuut is ingesteld op SQL_TRUE, wordt CatalogName behandeld als een identificatie en is het geval niet significant. Als het SQL_FALSE is, is CatalogName een patroonwaarde-argument; Het wordt letterlijk behandeld en het geval is belangrijk. Zie Argumenten in Catalogusfuncties voor meer informatie.

NameLength1
[Invoer] Lengte in tekens van *CatalogName.

Schemanaam
[Invoer] Stringzoekpatroon voor schemanamen. Als een driver schema's ondersteunt voor sommige tabellen maar niet voor andere, bijvoorbeeld wanneer de driver gegevens ophaalt uit verschillende DBMS'en, geeft een lege string ("") aan welke tabellen geen schema's bevatten.

Als het SQL_ATTR_METADATA_ID-statement-attribuut is ingesteld op SQL_TRUE, wordt SchemaName behandeld als een identifier en is het geval niet significant. Als het SQL_FALSE is, is SchemaName een patroonwaarde-argument; Het wordt letterlijk behandeld en het geval is belangrijk.

NameLength2
[Invoer] Lengte in tekens van *SchemaName.

TableName
[Invoer] Stringzoekpatroon voor tabelnamen.

Als het SQL_ATTR_METADATA_ID-statement-attribuut is ingesteld op SQL_TRUE, wordt TableName behandeld als een identifier en is het geval niet significant. Als het SQL_FALSE is, is TableName een patroonwaarde-argument; Het wordt letterlijk behandeld en het geval is belangrijk.

NameLength3
[Invoer] Lengte in tekens van *TableName.

TabelType
[Invoer] Lijst van tafeltypes die overeenkomen.

Let op dat het SQL_ATTR_METADATA_ID-statement-attribuut geen effect heeft op het TableType-argument . TableType is een waardelijst-argument, ongeacht de instelling van SQL_ATTR_METADATA_ID.

NameLength4
[Invoer] Lengte in tekens van *TableType.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR of SQL_INVALID_HANDLE.

Diagnostics

Wanneer SQLTables SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die typisch door SQLTables worden geretourneerd en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Comments

SQLTables geeft alle tabellen in het gevraagde bereik weer op. Een gebruiker kan wel of niet SELECT-rechten hebben voor een van deze tabellen. Om de toegankelijkheid te controleren, kan een applicatie:

• Bel SQLGetInfo en controleer het SQL_ACCESSIBLE_TABLES informatietype.

• Roep SQLTablePrivileges aan om de rechten voor elke tabel te controleren.

Anders moet de applicatie in staat zijn om een situatie aan te gaan waarin de gebruiker een tabel selecteert waarvoor SELECT-rechten niet worden toegekend.

De argumenten SchemaName en TableName accepteren zoekpatronen. Het CatalogName-argument accepteert zoekpatronen als het SQL_ODBC_VERSION environment-attribuut SQL_OV_ODBC3 is; het accepteert geen zoekpatronen als SQL_OV_ODBC2 is ingesteld. Als SQL_OV_ODBC3 is ingesteld, vereist een ODBC 3*.x*-driver dat wildcard-tekens in het CatalogName-argument worden geëscaped om letterlijk te worden behandeld. Voor meer informatie over geldige zoekpatronen, zie Patroonwaardeargumenten.

Om de opsomming van catalogi, schema's en tabeltypen te ondersteunen, zijn de volgende speciale semantiek gedefinieerd voor de CatalogName-, SchemaName-, TableName- en TableType-argumenten van SQLTables:

• Als CatalogName SQL_ALL_CATALOGS is en SchemaName en TableName lege strings zijn, bevat de resultaatset een lijst van geldige catalogi voor de databron. (Alle kolommen behalve de kolom TABLE_CAT bevatten NULLs.)

• Als SchemaName SQL_ALL_SCHEMAS is en CatalogName en TableName lege strings zijn, bevat de resultaatset een lijst van geldige schema's voor de databron. (Alle kolommen behalve de TABLE_SCHEM kolom bevatten NULLs.)

• Als TableType SQL_ALL_TABLE_TYPES is en CatalogName, SchemaName en TableName lege strings zijn, bevat de resultaatset een lijst van geldige tabeltypes voor de databron. (Alle kolommen behalve de kolom TABLE_TYPE bevatten NULLs.)

Als TableType geen lege string is, moet het een lijst van komma-gescheiden waarden bevatten voor de typen van interesse; Elke waarde kan worden omsloten in enkele aanhalingstekens (') of zonder aanhalingstekens, bijvoorbeeld 'TABLE', 'VIEW' of TABLE, VIEW. Een applicatie moet altijd het tabeltype in hoofdletters specificeren; De driver moet het tabeltype omzetten naar het geval dat de databron nodig heeft. Als de gegevensbron een gespecificeerd tabeltype niet ondersteunt, levert SQLTables geen resultaten voor dat type op.

SQLTables geeft de resultaten terug als een standaard resultaatset, geordend op TABLE_TYPE, TABLE_CAT, TABLE_SCHEM en TABLE_NAME. Zie Gebruik van catalogusgegevens voor informatie over hoe deze informatie kan worden gebruikt.

Om de werkelijke lengtes van de kolommen TABLE_CAT, TABLE_SCHEM en TABLE_NAME te bepalen, kan een applicatie SQLGetInfo aanroepen met de SQL_MAX_CATALOG_NAME_LEN-, SQL_MAX_SCHEMA_NAME_LEN- en SQL_MAX_TABLE_NAME_LEN informatietypen.

De volgende kolommen zijn hernoemd naar ODBC 3*.x*. De wijzigingen in kolomnamen beïnvloeden de achterwaartse compatibiliteit niet, omdat applicaties binden op kolomnummer.

De volgende tabel bevat de kolommen in de resultatenset. Extra kolommen voorbij kolom 5 (OPMERKINGEN) kunnen door de bestuurder worden gedefinieerd. Een toepassing moet toegang krijgen tot stuurprogrammaspecifieke kolommen door af te tellen vanaf het einde van de resultatenset in plaats van een expliciete rangschikkingspositie op te geven. Zie Gegevens geretourneerd door Catalogusfuncties voor meer informatie.

Example

De volgende voorbeeldcode maakt handles en verbindingen niet vrij. Zie SQLFreeHandle Function en SQLFreeStmt Function voor codevoorbeelden om handles en statements vrij te maken.

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

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden