Função SQLStatistics
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLStatistics recupera uma lista de estatísticas sobre uma única tabela e os índices associados à tabela. O driver retorna as informações como um conjunto de resultados.
Sintaxe
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
Argumentos
StatementHandle
[Entrada] Identificador de instrução.
Catalogname
[Entrada] Nome do catálogo. 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, uma cadeia de caracteres vazia ("") indica as tabelas que não têm catálogos. CatalogName não pode conter um padrão de pesquisa de cadeia de caracteres.
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 comum; é 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] Nome do 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. SchemaName não pode conter um padrão de pesquisa de cadeia de caracteres.
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 comum; é tratado literalmente, e seu caso é significativo.
NameLength2
[Entrada] Comprimento em caracteres de *SchemaName.
TableName
[Entrada] Nome da tabela. Esse argumento não pode ser um ponteiro nulo. SchemaName não pode conter um padrão de pesquisa de cadeia de caracteres.
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 comum; é tratado literalmente, e seu caso é significativo.
NameLength3
[Entrada] Comprimento em caracteres de *TableName.
Exclusivo
[Entrada] Tipo de índice: SQL_INDEX_UNIQUE ou SQL_INDEX_ALL.
Reserved
[Entrada] Indica a importância das colunas CARDINALITY e PAGES no conjunto de resultados. As opções a seguir afetam apenas o retorno das colunas CARDINALITY e PAGES; as informações de índice serão retornadas mesmo se CARDINALITY e PAGES não forem retornados.
SQL_ENSURE solicita que o driver recupere incondicionalmente as estatísticas. (Os drivers que estão em conformidade apenas com o padrão Open Group e não dão suporte a extensões ODBC não poderão dar suporte a SQL_ENSURE.)
SQL_QUICK solicita que o driver recupere CARDINALITY e PAGES somente se eles estiverem prontamente disponíveis no servidor. Nesse caso, o driver não assegura que os valores são atuais. (Os aplicativos gravados no padrão Open Group sempre receberão SQL_QUICK comportamento de drivers compatíveis com ODBC 3.x.)
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLStatistics 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 SQLStatistics e explica cada um deles 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 o contrário.
| 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 função concluir o processamento. |
| 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 | A conexão associada falhou 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 StatementHandle. A função foi chamada e, antes de concluir a execução, SQLCancel ou SQLCancelHandle foi chamado no StatementHandle e, 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 argumento TableName era um 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 era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) Uma função em 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 a função SQLStatistics foi chamada. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para StatementHandle e retornado 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 StatementHandle e ainda estava em execução quando essa função foi chamada. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos foram chamados para StatementHandle e retornados 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álido | (DM) O valor de um dos argumentos de comprimento de nome era menor que 0, mas não igual a SQL_NTS. O valor de um dos argumentos de comprimento de nome excedeu o valor de comprimento máximo para o nome correspondente. |
| HY100 | Tipo de opção de exclusividade fora do intervalo | (DM) Um valor Exclusivo inválido foi especificado. |
| HY101 | Tipo de opção de precisão fora do intervalo | (DM) Foi especificado um valor reservado inválido. |
| 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. 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
SQLStatistics retorna informações sobre uma única tabela como um conjunto de resultados padrão, ordenado por NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME e ORDINAL_POSITION. O conjunto de resultados combina informações de estatísticas (nas colunas CARDINALITY e PAGES do conjunto de resultados) para a tabela com informações sobre cada índice. 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, TABLE_NAME e COLUMN_NAME, um aplicativo pode chamar SQLGetInfo com as opções SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.
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.
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 |
| SEQ_IN_INDEX | ORDINAL_POSITION |
| COLLATION | ASC_OR_DESC |
A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 13 (FILTER_CONDITION) 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 da tabela à qual a estatística ou o índice se aplica; 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 da tabela à qual a estatística ou índice se aplica; 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 não NULL | Nome da tabela à qual a estatística ou índice se aplica. |
| NON_UNIQUE (ODBC 1.0) | 4 | Smallint | Indica se o índice não permite valores duplicados: SQL_TRUE se os valores de índice podem ser não exclusivos. SQL_FALSE se os valores de índice precisarem ser exclusivos. NULL será retornado se TYPE for SQL_TABLE_STAT. |
| INDEX_QUALIFIER (ODBC 1.0) | 5 | Varchar | O identificador usado para qualificar o nome do índice fazendo um DROP INDEX; NULL será retornado se um qualificador de índice não tiver suporte da fonte de dados ou se TYPE for SQL_TABLE_STAT. Se um valor não nulo for retornado nesta coluna, ele deverá ser usado para qualificar o nome do índice em uma instrução DROP INDEX ; caso contrário, o TABLE_SCHEM deve ser usado para qualificar o nome do índice. |
| INDEX_NAME (ODBC 1.0) | 6 | Varchar | Nome do índice; NULL será retornado se TYPE for SQL_TABLE_STAT. |
| TYPE (ODBC 1.0) | 7 | Smallint não NULL | Tipo de informação que está sendo retornada: SQL_TABLE_STAT indica uma estatística para a tabela (na coluna CARDINALITY ou PAGES). SQL_INDEX_BTREE indica um índice de Árvore B. SQL_INDEX_CLUSTERED indica um índice clusterizado. SQL_INDEX_CONTENT indica um índice de conteúdo. SQL_INDEX_HASHED indica um índice com hash. SQL_INDEX_OTHER indica outro tipo de índice. |
| ORDINAL_POSITION (ODBC 1.0) | 8 | Smallint | Número de sequência de colunas no índice (começando com 1); NULL será retornado se TYPE for SQL_TABLE_STAT. |
| COLUMN_NAME (ODBC 1.0) | 9 | Varchar | Nome da coluna. Se a coluna for baseada em uma expressão, como SALARY + BENEFITS, a expressão será retornada; se a expressão não puder ser determinada, uma cadeia de caracteres vazia será retornada. NULL será retornado se TYPE for SQL_TABLE_STAT. |
| ASC_OR_DESC (ODBC 1.0) | 10 | Char(1) | Sequência de classificação para a coluna: "A" para crescente; "D" para decrescente; NULL será retornado se a sequência de classificação de coluna não tiver suporte da fonte de dados ou se TYPE for SQL_TABLE_STAT. |
| CARDINALIDADE (ODBC 1.0) | 11 | Inteiro | Cardinalidade da tabela ou índice; número de linhas na tabela se TYPE for SQL_TABLE_STAT; número de valores exclusivos no índice se TYPE não for SQL_TABLE_STAT; NULL será retornado se o valor não estiver disponível na fonte de dados. |
| PAGES (ODBC 1.0) | 12 | Inteiro | Número de páginas usadas para armazenar o índice ou a tabela; número de páginas para a tabela se TYPE for SQL_TABLE_STAT; número de páginas para o índice se TYPE não for SQL_TABLE_STAT; NULL será retornado se o valor não estiver disponível na fonte de dados ou se não for aplicável à fonte de dados. |
| FILTER_CONDITION (ODBC 2.0) | 13 | Varchar | Se o índice for um índice filtrado, essa será a condição de filtro, como SALARY > 30000; se a condição de filtro não puder ser determinada, essa será uma cadeia de caracteres vazia. NULL se o índice não for um índice filtrado, não será possível determinar se o índice é um índice filtrado ou SE TYPE está SQL_TABLE_STAT. |
Se a linha no conjunto de resultados corresponder a uma tabela, o driver definirá TYPE como SQL_TABLE_STAT e definirá NON_UNIQUE, INDEX_QUALIFIER, INDEX_NAME, ORDINAL_POSITION, COLUMN_NAME e ASC_OR_DESC como NULL. Se CARDINALITY ou PAGES não estiverem disponíveis na fonte de dados, o driver os definirá como NULL.
Exemplo de código
Para obter um exemplo de código de uma função semelhante, consulte SQLColumns.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Associar um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento da instrução | Função SQLCancel |
| Buscar uma única linha ou um bloco de dados em uma direção somente de avanço. | Função SQLFetch |
| Buscando um bloco de dados ou rolando por um conjunto de resultados | Função SQLFetchScroll |
| Retornando as colunas de chaves estrangeiras | Função SQLForeignKeys |
| Retornando as colunas de uma chave primária | Função SQLPrimaryKeys |