Funzione SQLTables

Articolo
08/21/2023

Conformità
Versione introdotta: Conformità standard ODBC 1.0: Gruppo aperto

Riepilogo
SQLTables restituisce l'elenco di nomi di tabella, catalogo o schema e tipi di tabella, archiviati in un'origine dati specifica. Il driver restituisce le informazioni come set di risultati.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione per i risultati recuperati.

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

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, CatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, CatalogName è un argomento del valore del modello, che viene trattato letteralmente e il relativo case è significativo. Per altre informazioni, vedere Argomenti in Funzioni del catalogo.

NameLength1
[Input] Lunghezza in caratteri di *CatalogName.

SchemaName
[Input] Modello di ricerca di stringhe per i nomi degli schemi. Se un driver supporta schemi per alcune tabelle, ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le tabelle che non dispongono di schemi.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, SchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, SchemaName è un argomento del valore del modello, che viene trattato letteralmente e il relativo case è significativo.

NameLength2
[Input] Lunghezza in caratteri di *SchemaName.

TableName
[Input] Modello di ricerca di stringhe per i nomi di tabella.

Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, TableName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, TableName è un argomento del valore del criterio; viene trattato letteralmente e il relativo case è significativo.

NameLength3
[Input] Lunghezza in caratteri di *TableName.

TableType
[Input] Elenco dei tipi di tabella da trovare.

Si noti che l'attributo dell'istruzione SQL_ATTR_METADATA_ID non ha alcun effetto sull'argomento TableType . TableType è un argomento dell'elenco di valori, indipendentemente dall'impostazione di SQL_ATTR_METADATA_ID.

NameLength4
[Input] Lunghezza in caratteri *TableType.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLTables restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLTables e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE	Errore	Descrizione
01000	Avviso generale	Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08S01	Errore del collegamento di comunicazione	Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
24000	Stato del cursore non valido	È stato aperto un cursore in StatementHandle e è stato chiamato SQLFetch o SQLFetchScroll. Questo errore viene restituito da Gestione driver se SQLFetch o SQLFetchScroll non ha restituito SQL_NO_DATA e viene restituito dal driver se SQLFetch o SQLFetchScroll ha restituito SQL_NO_DATA. Un cursore è stato aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non è stato chiamato.
40001	Errore di serializzazione	È stato eseguito il rollback della transazione a causa di un deadlock della risorsa con un'altra transazione.
40003	Completamento istruzione sconosciuto	La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione.
HY000	Errore generale:	Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer MessageText* descrive l'errore e la relativa causa.
HY001	Errore di allocazione della memoria	Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY008	Operazione annullata	L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread.
HY009	Uso non valido del puntatore Null	L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE, l'argomento CatalogName è un puntatore Null e l'SQL_CATALOG_NAME InfoType restituisce che i nomi di catalogo sono supportati. (DM) L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE e l'argomento SchemaName o TableName è un puntatore Null.
HY010	Errore della sequenza di funzioni	(DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione asincrona era ancora in esecuzione quando è stata chiamata SQLTables. (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution.
HY013	Errore di gestione della memoria	Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY090	Lunghezza della stringa o del buffer non valida	(DM) Il valore di uno degli argomenti di lunghezza era minore di 0 ma non uguale a SQL_NTS. Il valore di uno degli argomenti lunghezza nome ha superato il valore di lunghezza massima per il nome corrispondente.
HY117	La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura.	(DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYC00	Funzionalità facoltativa non implementata	È stato specificato un catalogo e il driver o l'origine dati non supporta i cataloghi. È stato specificato uno schema e il driver o l'origine dati non supporta gli schemi. È stato specificato un criterio di ricerca di stringhe per il nome del catalogo, lo schema di tabella o il nome della tabella e l'origine dati non supporta i criteri di ricerca per uno o più di questi argomenti. La combinazione delle impostazioni correnti degli attributi delle istruzioni SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE non è supportata dal driver o dall'origine dati. L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per cui il driver non supporta i segnalibri.
HYT00	Timeout scaduto	Periodo di timeout della query scaduto prima che l'origine dati restituisca il set di risultati richiesto. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	Il timeout della connessione è scaduto	Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Il driver non supporta questa funzione	(DM) Il driver associato a StatementHandle non supporta la funzione.
IM017	Il polling è disabilitato in modalità di notifica asincrona	Ogni volta che viene usato il modello di notifica, il polling è disabilitato.
IM018	SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle.	Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione.

Commenti

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

Chiamare SQLGetInfo e controllare il tipo di informazioni SQL_ACCESSIBLE_TABLES.
Chiamare SQLTablePrivileges per controllare i privilegi per ogni tabella.

In caso contrario, l'applicazione deve essere in grado di gestire una situazione in cui l'utente seleziona una tabella per cui non vengono concessi privilegi SELECT .

Gli argomenti SchemaName e TableName accettano criteri di ricerca. L'argomento CatalogName accetta modelli di ricerca se l'attributo dell'ambiente SQL_ODBC_VERSION è SQL_OV_ODBC3; non accetta modelli 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 considerati come carattere di escape letterali. Per altre informazioni sui modelli di ricerca validi, vedere Argomenti dei valori del criterio.

Nota

Per altre informazioni sull'utilizzo generale, gli argomenti e i dati restituiti delle funzioni del catalogo ODBC, vedere Funzioni del catalogo.

Per supportare l'enumerazione di cataloghi, schemi e tipi di tabella, vengono definite le semantiche speciali seguenti 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 un elenco di cataloghi validi per l'origine dati. Tutte le colonne ad eccezione della colonna TABLE_CAT contengono valori NULL.
Se SchemaName è SQL_ALL_SCHEMAS e CatalogName e TableName sono stringhe vuote, il set di risultati contiene un elenco di schemi validi per l'origine dati. Tutte le colonne ad eccezione della colonna TABLE_SCHEM contengono valori NULL.
Se TableType è SQL_ALL_TABLE_TYPES e CatalogName, SchemaName e TableName sono stringhe vuote, il set di risultati contiene un elenco di tipi di tabella validi per l'origine dati. Tutte le colonne ad eccezione della colonna TABLE_TYPE contengono valori NULL.

Se TableType non è una stringa vuota, deve contenere un elenco di valori delimitati da virgole per i tipi di interesse. Ogni valore può essere racchiuso tra virgolette singole (') o senza virgolette, ad esempio 'TABLE', 'VIEW' o TABLE, VIEW. Un'applicazione deve sempre specificare il tipo di tabella in maiuscolo; il driver deve convertire il tipo di tabella in qualsiasi caso sia necessario per l'origine dati. Se l'origine dati non supporta un tipo di tabella specificato, SQLTables non restituisce alcun risultato per tale tipo.

SQLTables restituisce i risultati come set di risultati standard, ordinati in base a 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 le lunghezze effettive 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 per ODBC 3*.x*. Le modifiche apportate al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni si associano per numero di colonna.

Colonna ODBC 2.0	Colonna ODBC 3.x
TABLE_QUALIFIER	TABLE_CAT
TABLE_OWNER	TABLE_SCHEM

Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive successive alla colonna 5 (REMARKS) 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.

Nome colonna	Column number	Tipo di dati	Commenti
TABLE_CAT (ODBC 1.0)	1	Varchar	Nome catalogo; NULL se non applicabile all'origine dati. Se un driver supporta cataloghi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le tabelle che non dispongono di cataloghi.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nome schema; NULL se non applicabile all'origine dati. Se un driver supporta schemi per alcune tabelle ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le tabelle che non dispongono di schemi.
TABLE_NAME (ODBC 1.0)	3	Varchar	Nome tabella.
TABLE_TYPE (ODBC 1.0)	4	Varchar	Nome del tipo di tabella; uno dei seguenti: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" o un nome di tipo specifico dell'origine dati. I significati di "ALIAS" e "SYNONYM" sono specifici del driver.
OSSERVAZIONI (ODBC 1.0)	5	Varchar	Descrizione della tabella.

Esempio

Il codice di esempio seguente non libera handle e connessioni. Vedere Funzione SQLFreeHandle e funzione SQLFreeStmt per esempi di codice per gli handle e le istruzioni liberi.

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

Per informazioni su	Vedere
Associazione di un buffer a una colonna in un set di risultati	Funzione SQLBindCol
Annullamento dell'elaborazione delle istruzioni	Funzione SQLCancel
Restituzione dei privilegi per una colonna o colonne	Funzione SQLColumnPrivileges
Restituzione delle colonne in una tabella o in tabelle	Funzione SQLColumns
Recupero di una singola riga o di un blocco di dati in una direzione forward-only	Funzione SQLFetch
Recupero di un blocco di dati o scorrimento di un set di risultati	Funzione SQLFetchScroll
Restituzione di statistiche e indici di tabella	Funzione SQLStatistics
Restituzione dei privilegi per una tabella o una tabella	Funzione SQLTablePrivileges

Vedi anche

Riferimento API ODBC
File di intestazione ODBC

Condividi tramite

Funzione SQLTables

Sintassi

Argomenti

Resi

Diagnostica

Commenti

Esempio

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Funzione SQLTables

Sintassi

Argomenti

Resi

Diagnostica

Commenti

Esempio

Funzioni correlate

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive