Função SQLStatistics

SQLStatistics Recupera uma lista de estatísticas sobre uma única tabela e os índices associados a essa tabela. O condutor devolve a informação como conjunto de resultados.

Conformidade

Versão introduzida: Conformidade com as Normas ODBC 1.0: ISO 92

Sintaxe

SQLRETURN SQLStatistics(
     SQLHSTMT        StatementHandle ,
     SQLCHAR *       CatalogName ,
     SQLSMALLINT     NameLength1 ,
     SQLCHAR *       SchemaName ,
     SQLSMALLINT     NameLength2 ,
     SQLCHAR *       TableName ,
     SQLSMALLINT     NameLength3 ,
     SQLUSMALLINT    Unique ,
     SQLUSMALLINT    Reserved);

Arguments

HandleStatement

[Entrada] Identificador do extrato.

Nome do Catálogo

[Entrada] Nome do catálogo. Se um driver suporta catálogos para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma string vazia ("") indica aquelas tabelas que não têm catálogos. O CatalogName não pode conter um padrão de pesquisa em cadeia de caracteres.

Se o SQL_ATTR_METADATA_ID atributo da instrução estiver definido como SQL_TRUE, CatalogName é tratado como identificador e o seu caso não é significativo. Se for SQL_FALSE, Nome do Catálogo é um argumento comum; é tratado literalmente, e o seu caso é significativo. Para mais informações, consulte Argumentos em Funções de Catálogo.

NomeComprimento1

[Entrada] Comprimento em caracteres do CatalogName.

Nome do esquema

[Entrada] Nome do esquema. Se um driver suporta esquemas para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma string vazia ("") indica as tabelas que não têm esquemas. O SchemaName não pode conter um padrão de pesquisa de cadeias.

Se o SQL_ATTR_METADATA_ID atributo da instrução for definido como SQL_TRUE, SchemaName é tratado como um identificador e o seu caso não é significativo. Se for SQL_FALSE, o Nome do Esquema é um argumento comum; é tratado literalmente, e o seu caso é significativo.

NomeComprimento2

[Entrada] Comprimento em caracteres do NomeEsquema.

Nome da tabela

[Entrada] Nome da mesa. Este argumento não pode ser um ponto nulo. O TableName não consegue conter um padrão de pesquisa de cadeias.

Se o SQL_ATTR_METADATA_ID atributo da instrução for definido como SQL_TRUE, TableName é tratado como identificador e o seu caso não é significativo. Se for SQL_FALSE, TableName é um argumento comum; é tratado literalmente, e o seu caso é significativo.

NomeComprimento3

[Entrada] Comprimento em caracteres do TableName.

Único

[Entrada] Tipo de índice: SQL_INDEX_UNIQUE ou SQL_INDEX_ALL.

Reservado

[Entrada] Indica a importância das CARDINALITY colunas e PAGES no conjunto de resultados. As seguintes opções afetam apenas o retorno das CARDINALITY colunas e PAGES ; a informação do índice é devolvida mesmo que CARDINALITY e PAGES não forem devolvidas.

SQL_ENSURE solicita que o controlador recupere incondicionalmente as estatísticas. (Drivers que cumprem apenas o padrão Open Group e não suportam extensões ODBC não poderão suportar SQL_ENSURE.)

SQL_QUICK solicita que o driver recupere os CARDINALITY e PAGES só se estiverem facilmente disponíveis no servidor. Neste caso, o driver não garante que os valores estão atuais. (As aplicações escritas para o padrão Open Group receberão sempre SQL_QUICK comportamento de drivers compatíveis com ODBC 3.x.)

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, ou SQL_INVALID_HANDLE.

Diagnóstico

Quando SQLStatistics retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor associado SQLSTATE pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_STMT e um Handle de StatementHandle. A tabela seguinte lista os SQLSTATE valores normalmente devolvidos por SQLStatistics e explica cada um no contexto desta função; a notação (DM) precede as descrições de cada SQLSTATE um devolvidas pelo Gestor de Drivers. O código de retorno associado a cada SQLSTATE valor é SQL_ERROR, salvo indicação em contrário.

Comments

SQLStatistics retorna informação sobre uma única tabela como conjunto padrão de resultados, ordenado por NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME, e ORDINAL_POSITION. O conjunto de resultados combina informação estatística (nas CARDINALITY colunas e PAGES do conjunto de resultados) para a tabela com informações sobre cada índice. Para informações sobre como esta informação pode ser utilizada, consulte Utilizações dos Dados de Catálogo.

Para determinar os comprimentos reais dos , , , e COLUMN_NAME das colunas, uma aplicação pode chamar SQLGetInfo com as SQL_MAX_CATALOG_NAME_LENopções, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN, e SQL_MAX_COLUMN_NAME_LEN . TABLE_NAMETABLE_SCHEMTABLE_CAT

As colunas seguintes foram renomeadas para ODBC 3.x. As alterações no nome das colunas não afetam a compatibilidade retroativa porque as aplicações associam por número de coluna.

A tabela seguinte lista as colunas do conjunto de resultados. Colunas adicionais para além da coluna 13 (FILTER_CONDITION) podem ser definidas pelo driver. Uma aplicação deve aceder a colunas específicas do driver contando decrescentemente a partir do final do conjunto de resultados em vez de especificar uma posição ordinal explícita. Para mais informações, consulte Dados Devolvidos por Funções de Catálogo.

Se a linha do conjunto de resultados corresponder a uma tabela, o driver define TYPE para SQL_TABLE_STAT e define NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME, e ASC_OR_DESC para NULL. Se CARDINALITY ou PAGES não estiverem disponíveis na fonte de dados, o driver define-as para NULL.

Exemplo de código

Para um exemplo de código de uma função semelhante, veja Função SQLColumns.

Funções relacionadas

Conteúdo relacionado

• Referência API ODBC
• Ficheiros de Cabeçalho ODBC