Funzione SQLTables

Conformità
Versione introdotta: Conformità agli Standard ODBC 1.0: Open Group

Sommario
SQLTables restituisce l'elenco dei nomi di tabelle, cataloghi o schemi, e tipi di tabelle, memorizzati in una specifica fonte dati. Il driver restituisce le informazioni come set di risultati.

Syntax

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

Arguments

StatementHandle
[Input] Handle dell'istruzione per i risultati recuperati.

CatalogName
[Input] Nome catalogo. L'argomento CatalogName accetta schemi di ricerca se l'attributo SQL_ODBC_VERSION ambiente è SQL_OV_ODBC3; Non accetta schemi di ricerca se SQL_OV_ODBC2 è impostato. Se un driver supporta cataloghi per alcune tabelle ma non per altre, ad esempio quando un driver recupera dati da diversi DBMS, una stringa vuota ("") indica quelle tabelle che non hanno cataloghi.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, CatalogName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, CatalogName è un argomento di valore di pattern; Viene trattato letteralmente, e il suo caso è significativo. Per altre informazioni, vedere Argomenti nelle Funzioni catalogo.

NameLength1
[Input] Lunghezza nei caratteri di *NomeCatalogo.

SchemaName
[Input] Pattern di ricerca stringa per i nomi degli schemi. Se un driver supporta gli schemi per alcune tabelle ma non per altre, ad esempio quando il driver recupera dati da diversi DBMS, una stringa vuota ("") indica quelle tabelle che non hanno schema.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, SchemaName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, Nome dello schema è un argomento di valore di pattern; Viene trattato letteralmente, e il suo caso è significativo.

NameLength2
[Input] Lunghezza nei caratteri di *NomeSchema.

TableName
[Input] Pattern di ricerca stringa per i nomi delle tabelle.

Se l'attributo della SQL_ATTR_METADATA_ID istruzione è impostato su SQL_TRUE, TableName viene trattato come un identificatore e il suo caso non è significativo. Se è SQL_FALSE, TableName è un argomento di valore di pattern; Viene trattato letteralmente, e il suo caso è significativo.

NameLength3
[Input] Lunghezza nei caratteri di *NomeTabella.

Tipo di tabella
[Input] Elenco dei tipi di tabelle da abbinare.

Nota che l'attributo SQL_ATTR_METADATA_ID affermazione non ha alcun effetto sull'argomento TableType . TableType è un argomento di lista di valori, indipendentemente dall'impostazione di SQL_ATTR_METADATA_ID.

NameLength4
[Input] Lunghezza nei caratteri di *TypeTable.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostics

Quando SQLTables restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_STMT e un Handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE tipicamente restituiti da SQLTables e spiega ciascuno nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Comments

SQLTables elenca tutte le tabelle nell'intervallo richiesto. Un utente può avere o meno i privilegi SELECT su una di queste tabelle. Per verificare l'accessibilità, un'applicazione può:

• Chiama SQLGetInfo e controlla il tipo di SQL_ACCESSIBLE_TABLES informazioni.

• Chiama SQLTablePrivileges per verificare i privilegi di ogni tabella.

Altrimenti, l'applicazione deve essere in grado di gestire una situazione in cui l'utente seleziona una tabella per la quale non sono concessi i privilegi SELECT .

Gli argomenti SchemaName e TableName accettano i pattern di ricerca. L'argomento CatalogName accetta schemi di ricerca se l'attributo SQL_ODBC_VERSION ambiente è SQL_OV_ODBC3; Non accetta schemi di ricerca se SQL_OV_ODBC2 è impostato. Se SQL_OV_ODBC3 è impostato, un driver ODBC 3*.x* richiederà che i caratteri jolly nell'argomento CatalogName vengano sfuggiti per essere trattati letteralmente. Per maggiori informazioni sui modelli di ricerca validi, vedi Pattern Value Arguments.

Per supportare l'enumerazione di cataloghi, schemi e tipi di tabelle, sono definite le seguenti semantiche speciali per gli argomenti CatalogName, SchemaName, TableName e TableType di SQLTables:

• Se CatalogName è SQL_ALL_CATALOGS e SchemaName e TableName sono stringhe vuote, il set di risultati contiene una lista di cataloghi validi per la sorgente dati. (Tutte le colonne tranne quella TABLE_CAT contengono NULL.)

• Se SchemaName è SQL_ALL_SCHEMAS e CatalogName e TableName sono stringhe vuote, il set di risultati contiene una lista di schemi validi per la sorgente dati. (Tutte le colonne tranne quella TABLE_SCHEM contengono NULL.)

• Se TableType è SQL_ALL_TABLE_TYPES e CatalogName, SchemaName e TableName sono stringhe vuote, il set di risultati contiene una lista di tipi di tabella validi per la sorgente dati. (Tutte le colonne tranne la colonna TABLE_TYPE contengono NULL.)

Se TableType non è una stringa vuota, deve contenere un elenco di valori separati da virgola per i tipi di interesse; ogni valore può essere racchiuso tra virgolette singole (') o non virgolette, ad esempio 'TABLE', 'VIEW' o TABLE, VIEW. Un'applicazione dovrebbe sempre specificare il tipo di tabella in maiuscolo; Il driver dovrebbe convertire il tipo di tabella in qualsiasi caso necessario alla sorgente dati. Se la sorgente dati non supporta un tipo di tabella specificato, SQLTables non restituisce alcun risultato per quel tipo.

SQLTables restituisce i risultati come un insieme standard, ordinato da TABLE_TYPE, TABLE_CAT, TABLE_SCHEM e TABLE_NAME. Per informazioni su come usare queste informazioni, vedere Uses of Catalog Data.For information about how this information might be used, see Uses of Catalog Data.

Per determinare la lunghezza effettiva delle colonne TABLE_CAT, TABLE_SCHEM e TABLE_NAME, un'applicazione può chiamare SQLGetInfo con i tipi di informazioni SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN e SQL_MAX_TABLE_NAME_LEN.

Le colonne seguenti sono state rinominate in ODBC 3*.x*. I cambiamenti nel nome delle colonne non influiscono sulla retrocompatibilità perché le applicazioni si assegnano per numero di colonna.

Nella tabella seguente sono elencate le colonne nel set di risultati. Colonne aggiuntive oltre la colonna 5 (OSSERVAZIONI) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati invece di specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.

Example

Il seguente codice di esempio non libera handle e connessioni. Vedi SQLFreeHandle Function e SQLFreeStmt Function per esempi di codice verso handle liberi e istruzioni.

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

Funzioni correlate

Vedere anche

Riferimento API ODBC
File di intestazione ODBC