Função SQLTables

Artigo
05/23/2023

Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: Open Group

Resumo
SQLTables retorna a lista de nomes de tabela, catálogo ou esquema e tipos de tabela, armazenados em uma fonte de dados específica. O driver retorna as informações como um conjunto de resultados.

Sintaxe

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

Argumentos

StatementHandle
[Entrada] Identificador de instrução para resultados recuperados.

Catalogname
[Entrada] Nome do catálogo. O argumento CatalogName aceitará padrões de pesquisa se o atributo de ambiente SQL_ODBC_VERSION for SQL_OV_ODBC3; ele não aceitará padrões de pesquisa se SQL_OV_ODBC2 estiver definido. Se um driver der suporte a catálogos para algumas tabelas, mas não para outras, como quando um driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica as tabelas que não têm catálogos.

Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, CatalogName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, CatalogName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo. Para obter mais informações, consulte Argumentos em funções de catálogo.

NameLength1
[Entrada] Comprimento em caracteres de *CatalogName.

Schemaname
[Entrada] Padrão de pesquisa de cadeia de caracteres para nomes de esquema. Se um driver der suporte a esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, uma cadeia de caracteres vazia ("") indica as tabelas que não têm esquemas.

Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, SchemaName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, SchemaName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo.

NameLength2
[Entrada] Comprimento em caracteres de *SchemaName.

TableName
[Entrada] Padrão de pesquisa de cadeia de caracteres para nomes de tabela.

Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, TableName será tratado como um identificador e seu caso não será significativo. Se for SQL_FALSE, TableName será um argumento de valor padrão; é tratado literalmente, e seu caso é significativo.

NameLength3
[Entrada] Comprimento em caracteres de *TableName.

TableType
[Entrada] Lista de tipos de tabela a serem correspondidos.

Observe que o atributo de instrução SQL_ATTR_METADATA_ID não tem efeito sobre o argumento TableType . TableType é um argumento de lista de valores, independentemente da configuração de SQL_ATTR_METADATA_ID.

NameLength4
[Entrada] Comprimento em caracteres de *TableType.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLTables retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Identificador de StatementHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLTables e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

SQLSTATE	Erro	Descrição
01000	Aviso geral	Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
08S01	Falha no link de comunicação	O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes da conclusão do processamento da função.
24.000	Estado de cursor inválido	Um cursor foi aberto no StatementHandle e SQLFetch ou SQLFetchScroll foram chamados. Esse erro será retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e for retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA. Um cursor foi aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não foram chamados.
40001	Falha na serialização	A transação foi revertida devido a um deadlock de recursos com outra transação.
40003	Conclusão da instrução desconhecida	Falha na conexão associada durante a execução dessa função e o estado da transação não pode ser determinado.
HY000	Erro geral	Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer MessageText* descreve o erro e sua causa.
HY001	Erro de alocação de memória	O driver não pôde alocar memória necessária para dar suporte à execução ou à conclusão da função.
HY008	Operação cancelada	O processamento assíncrono foi habilitado para o StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle. Em seguida, a função foi chamada novamente no StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle de um thread diferente em um aplicativo multithread.
HY009	Uso inválido de ponteiro nulo	O atributo de instrução SQL_ATTR_METADATA_ID foi definido como SQL_TRUE, o argumento CatalogName era um ponteiro nulo e o SQL_CATALOG_NAME InfoType retorna que há suporte para nomes de catálogo. (DM) O atributo de instrução SQL_ATTR_METADATA_ID foi definido como SQL_TRUE e o argumento SchemaName ou TableName era um ponteiro nulo.
HY010	Erro de sequência de funções	(DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função assíncrona ainda estava em execução quando SQLTables foi chamado. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. (DM) Uma função de execução assíncrona (não esta) foi chamada para o StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para o StatementHandle e retornaram SQL_NEED_DATA. Essa função foi chamada antes de os dados serem enviados para todos os parâmetros ou colunas de dados em execução.
HY013	Erro de gerenciamento de memória	A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa.
HY090	Comprimento de buffer ou cadeia de caracteres inválida	(DM) O valor de um dos argumentos de comprimento era menor que 0, mas não igual a SQL_NTS. O valor de um dos argumentos de comprimento do nome excedeu o valor de comprimento máximo para o nome correspondente.
HY117	A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas.	(DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran.
HYC00	Recurso opcional não implementado	Um catálogo foi especificado e o driver ou fonte de dados não dá suporte a catálogos. Um esquema foi especificado e o driver ou fonte de dados não dá suporte a esquemas. Um padrão de pesquisa de cadeia de caracteres foi especificado para o nome do catálogo, esquema de tabela ou nome da tabela e a fonte de dados não dá suporte a padrões de pesquisa para um ou mais desses argumentos. A combinação das configurações atuais dos atributos de instrução SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE não era compatível com o driver ou a fonte de dados. O atributo de instrução SQL_ATTR_USE_BOOKMARKS foi definido como SQL_UB_VARIABLE e o atributo de instrução SQL_ATTR_CURSOR_TYPE foi definido como um tipo de cursor para o qual o driver não dá suporte a indicadores.
HYT00	Tempo limite esgotado	O período de tempo limite da consulta expirou antes da fonte de dados retornar o conjunto de resultados solicitado. O período de tempo limite é definido por meio de SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01	O tempo limite da conexão expirou	O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	O driver não dá suporte a essa função	(DM) O driver associado ao StatementHandle não dá suporte à função .
IM017	A sondagem está desabilitada no modo de notificação assíncrona	Sempre que o modelo de notificação é usado, a sondagem é desabilitada.
IM018	SQLCompleteAsync não foi chamado para concluir a operação assíncrona anterior nesse identificador.	Se a chamada de função anterior no identificador retornar SQL_STILL_EXECUTING e se o modo de notificação estiver habilitado, SQLCompleteAsync deverá ser chamado no identificador para fazer o pós-processamento e concluir a operação.

Comentários

SQLTables lista todas as tabelas no intervalo solicitado. Um usuário pode ou não ter privilégios SELECT para qualquer uma dessas tabelas. Para verificar a acessibilidade, um aplicativo pode:

Chame SQLGetInfo e verifique o tipo de informações SQL_ACCESSIBLE_TABLES.
Chame SQLTablePrivileges para verificar os privilégios de cada tabela.

Caso contrário, o aplicativo deve ser capaz de lidar com uma situação em que o usuário seleciona uma tabela para a qual os privilégios SELECT não são concedidos.

Os argumentos SchemaName e TableName aceitam padrões de pesquisa. O argumento CatalogName aceitará padrões de pesquisa se o atributo de ambiente SQL_ODBC_VERSION for SQL_OV_ODBC3; ele não aceitará padrões de pesquisa se SQL_OV_ODBC2 estiver definido. Se SQL_OV_ODBC3 estiver definido, um driver ODBC 3*.x* exigirá que caracteres curinga no argumento CatalogName sejam escapados para serem tratados literalmente. Para obter mais informações sobre padrões de pesquisa válidos, consulte Argumentos de valor padrão.

Observação

Para obter mais informações sobre o uso geral, argumentos e dados retornados de funções de catálogo ODBC, consulte Funções de catálogo.

Para dar suporte à enumeração de catálogos, esquemas e tipos de tabela, a seguinte semântica especial é definida para os argumentos CatalogName, SchemaName, TableName e TableType de SQLTables:

Se CatalogName for SQL_ALL_CATALOGS e SchemaName e TableName forem cadeias de caracteres vazias, o conjunto de resultados conterá uma lista de catálogos válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_CAT, contêm NULLs.)
Se SchemaName for SQL_ALL_SCHEMAS e CatalogName e TableName forem cadeias de caracteres vazias, o conjunto de resultados conterá uma lista de esquemas válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_SCHEM, contêm NULLs.)
Se TableType for SQL_ALL_TABLE_TYPES e CatalogName, SchemaName e TableName forem cadeias de caracteres vazias, o conjunto de resultados conterá uma lista de tipos de tabela válidos para a fonte de dados. (Todas as colunas, exceto a coluna TABLE_TYPE, contêm NULLs.)

Se TableType não for uma cadeia de caracteres vazia, ela deverá conter uma lista de valores separados por vírgulas para os tipos de interesse; cada valor pode ser colocado entre aspas simples (') ou sem aspas, por exemplo, 'TABLE', 'VIEW' ou TABLE, VIEW. Um aplicativo sempre deve especificar o tipo de tabela em maiúsculas; o driver deve converter o tipo de tabela em qualquer caso necessário para a fonte de dados. Se a fonte de dados não der suporte a um tipo de tabela especificado, o SQLTables não retornará nenhum resultado para esse tipo.

SQLTables retorna os resultados como um conjunto de resultados padrão, ordenado por TABLE_TYPE, TABLE_CAT, TABLE_SCHEM e TABLE_NAME. Para obter informações sobre como essas informações podem ser usadas, consulte Usos de dados de catálogo.

Para determinar os comprimentos reais das colunas TABLE_CAT, TABLE_SCHEM e TABLE_NAME, um aplicativo pode chamar SQLGetInfo com os tipos de informações SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN e SQL_MAX_TABLE_NAME_LEN.

As colunas a seguir foram renomeada para ODBC 3*.x*. As alterações de nome de coluna não afetam a compatibilidade com versões anteriores porque os aplicativos são associados por número de coluna.

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

A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 5 (REMARKS) podem ser definidas pelo driver. Um aplicativo deve obter acesso a colunas específicas do driver contando a partir do final do conjunto de resultados em vez de especificar uma posição ordinal explícita. Para obter mais informações, consulte Dados retornados por funções de catálogo.

Nome da coluna	Número da coluna	Tipo de dados	Comentários
TABLE_CAT (ODBC 1.0)	1	Varchar	Nome do catálogo; NULL se não for aplicável à fonte de dados. Se um driver der suporte a catálogos para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para as tabelas que não têm catálogos.
TABLE_SCHEM (ODBC 1.0)	2	Varchar	Nome do esquema; NULL se não for aplicável à fonte de dados. Se um driver der suporte a esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de DBMSs diferentes, ele retorna uma cadeia de caracteres vazia ("") para as tabelas que não têm esquemas.
TABLE_NAME (ODBC 1.0)	3	Varchar	Nome da tabela.
TABLE_TYPE (ODBC 1.0)	4	Varchar	Nome do tipo de tabela; um dos seguintes: "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM" ou um nome de tipo específico da fonte de dados. Os significados de "ALIAS" e "SYNONYM" são específicos do driver.
COMENTÁRIOS (ODBC 1.0)	5	Varchar	Uma descrição da tabela.

Exemplo

O código de exemplo a seguir não libera identificadores e conexões. Consulte Função SQLFreeHandle e Função SQLFreeStmt para obter exemplos de código para liberar identificadores e instruções.

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

Para obter informações sobre	Consulte
Associar um buffer a uma coluna em um conjunto de resultados	Função SQLBindCol
Cancelando o processamento de instruções	Função SQLCancel
Retornando privilégios para uma coluna ou colunas	Função SQLColumnPrivileges
Retornando as colunas em uma tabela ou tabelas	Função SQLColumns
Buscar uma única linha ou um bloco de dados em uma direção somente para frente	Função SQLFetch
Buscar um bloco de dados ou rolar por um conjunto de resultados	Função SQLFetchScroll
Retornando estatísticas e índices de tabela	Função SQLStatistics
Retornando privilégios para uma tabela ou tabela	Função SQLTablePrivileges

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC

Compartilhar via

Função SQLTables

Sintaxe

Argumentos

Retornos

Diagnósticos

Comentários

Exemplo

Consulte Também

Comentários

Recursos adicionais

Compartilhar via

Função SQLTables

Sintaxe

Argumentos

Retornos

Diagnósticos

Comentários

Exemplo

Funções relacionadas

Consulte Também

Comentários

Recursos adicionais