Função SQLSpecialColumns

Conformidade
Versão Introduzida: Conformidade com os Padrões ODBC 1.0: Open Group

Summary
SQLSpecialColumns recupera as seguintes informações sobre colunas dentro de uma tabela especificada:

• O conjunto ótimo de colunas que identifica de forma única uma linha na tabela.

• Colunas que são atualizadas automaticamente quando qualquer valor na linha é atualizado por uma transação.

Sintaxe

  
SQLRETURN SQLSpecialColumns(  
     SQLHSTMT      StatementHandle,  
     SQLSMALLINT   IdentifierType,  
     SQLCHAR *     CatalogName,  
     SQLSMALLINT   NameLength1,  
     SQLCHAR *     SchemaName,  
     SQLSMALLINT   NameLength2,  
     SQLCHAR *     TableName,  
     SQLSMALLINT   NameLength3,  
     SQLSMALLINT   Scope,  
     SQLSMALLINT   Nullable);  

Argumentos

Identificador de declaração
[Entrada] Identificador de instrução.

IdentifierType
[Entrada] Tipo de coluna para retornar. Deve ser um dos seguintes valores:

SQL_BEST_ROWID: Retorna a coluna ou conjunto ótimo de colunas que, ao recuperar valores da coluna ou colunas, permite que qualquer linha da tabela especificada seja identificada de forma única. Uma coluna pode ser tanto uma pseudo-coluna especificamente projetada para esse propósito (como no Oracle ROWID ou Ingres TID) quanto a coluna ou colunas de qualquer índice único para a tabela.

SQL_ROWVER: Retorna a coluna ou colunas na tabela especificada, se houver, que são automaticamente atualizadas pela fonte de dados quando qualquer valor na linha é atualizado por qualquer transação (como no SQLBase ROWID ou Sybase TIMESTAMP).

Catalogname
[Entrada] Nome do catálogo para a mesa. Se um driver suporta catálogos para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes DBMSs, uma string vazia ("") denota aquelas tabelas que não possuem catálogos. CatalogName não pode conter um padrão de busca em string.

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

NameLength1
[Entrada] Comprimento em caracteres de *NomeDeCatálogo.

Nome do esquema
[Entrada] Nome do esquema para a tabela. Se um driver suporta esquemas para algumas tabelas, mas não para outras, como quando o driver recupera dados de diferentes SGBDs, uma string vazia ("") denota aquelas tabelas que não possuem esquemas. O NomeSchema não pode conter um padrão de busca em string.

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

NameLength2
[Entrada] Comprimento em caracteres de *NomeEsquema.

TableName
[Entrada] Nome da tabela. Esse argumento não pode ser um ponto nulo. TableName não pode conter um padrão de busca em cadeia de caracteres.

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

NameLength3
[Entrada] Comprimento em caracteres de *NomeTaula.

Scope
[Entrada] Escopo mínimo exigido do Rowid. O rowid retornado pode ter maior alcance. Deve ser um dos seguintes:

SQL_SCOPE_CURROW: O rowid é garantido válido apenas enquanto estiver posicionado naquela fileira. Uma reseleção posterior usando rowid pode não retornar uma linha se a linha foi atualizada ou excluída por outra transação.

SQL_SCOPE_TRANSACTION: O rowid é garantido válido durante toda a transação atual.

SQL_SCOPE_SESSION: O rowid é garantido válido durante toda a sessão (além dos limites das transações).

Anulável
[Entrada] Determina se deve retornar colunas especiais que podem ter valor NULL. Deve ser um dos seguintes:

SQL_NO_NULLS: Exclua colunas especiais que possam ter valores NULL. Alguns drivers não suportam SQL_NO_NULLS, e esses drivers retornam um conjunto de resultados vazio se SQL_NO_NULLS for especificado. As inscrições devem ser preparadas para este caso e solicitarem SQL_NO_NULLS apenas se for absolutamente necessário.

SQL_NULLABLE: Devolver colunas especiais mesmo que possam ter valores NULL.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Quando SQLSpecialColumns 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 Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLSpecialColumns e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

Comments

Quando o argumento IdentifierType está SQL_BEST_ROWID, SQLSpecialColumns retorna a(s) coluna ou colunas que identificam unicamente cada linha da tabela. Essas colunas podem sempre ser usadas em uma cláusula select-list ou WHERE . O SQLColumns, que é usado para retornar uma variedade de informações nas colunas de uma tabela, não necessariamente retorna as colunas que identificam unicamente cada linha, ou as colunas que são automaticamente atualizadas quando qualquer valor na linha é atualizado por uma transação. Por exemplo, SQLColumns pode não retornar o pseudo-coluna ROWID da Oracle. É por isso que o SQLSpecialColumns é usado para retornar essas colunas. Para obter mais informações, consulte Usos de dados de catálogo.

Se não houver colunas que identifiquem unicamente cada linha da tabela, SQLSpecialColumns retorna um conjunto de linhas sem linhas; uma chamada subsequente para SQLFetch ou SQLFetchScroll na instrução retorna SQL_NO_DATA.

Se os argumentos IdentifierType, Scope ou Nullable especificarem características que não são suportadas pela fonte de dados, SQLSpecialColumns retorna um conjunto de resultados vazio.

Se o atributo da instrução SQL_ATTR_METADATA_ID for definido como SQL_TRUE, os argumentos CatalogName, SchemaName e TableName são tratados como identificadores, portanto não podem ser definidos como ponteiro nulo em certas situações. (Para mais informações, veja Argumentos em Funções de Catálogo.)

SQLSpecialColumns retorna os resultados como um conjunto padrão de resultados, ordenado por SCOPE.

As colunas a seguir foram renomeada para ODBC 3.x. As mudanças no nome das colunas não afetam a compatibilidade retroativa porque as aplicações são vinculadas por número de coluna.

Para determinar o comprimento real da coluna COLUMN_NAME, uma aplicação pode chamar SQLGetInfo com a opção SQL_MAX_COLUMN_NAME_LEN.

A tabela a seguir lista as colunas no conjunto de resultados. Colunas adicionais além da coluna 8 (PSEUDO_COLUMN) podem ser definidas pelo driver. Uma aplicação deve obter acesso a colunas específicas do driver contando regressivamente 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.

Após a aplicação recuperar os valores para SQL_BEST_ROWID, pode usar esses valores para reselecionar essa linha dentro do escopo definido. A instrução SELECT garante que não retornará nenhuma linha ou uma linha.

Se uma aplicação reselecionar uma linha baseada na coluna ou colunas rowid e a linha não for encontrada, a aplicação pode assumir que a linha foi deletada ou que as colunas rowid foram modificadas. O oposto não é verdade: mesmo que o rowid não tenha mudado, as outras colunas da linha podem ter mudado.

Colunas retornadas para o tipo de coluna SQL_BEST_ROWID são úteis para aplicações que precisam rolar para frente e para trás dentro de um conjunto de resultados para recuperar os dados mais recentes de um conjunto de linhas. A coluna ou colunas do rowid garantem que não mudarão enquanto posicionadas naquela linha.

A coluna ou colunas do rowid podem permanecer válidas mesmo quando o cursor não está posicionado na linha; a aplicação pode determinar isso verificando a coluna SCOPE no conjunto de resultados.

Colunas retornadas para o tipo de coluna SQL_ROWVER são úteis para aplicações que precisam da capacidade de verificar se alguma coluna em uma determinada linha foi atualizada enquanto a linha foi reselecionada usando o rowid. Por exemplo, após reselecionar uma linha usando rowid, o aplicativo pode comparar os valores anteriores nas colunas SQL_ROWVER com os que acabaram de buscar. Se o valor em uma coluna SQL_ROWVER diferir do valor anterior, o aplicativo pode alertar o usuário de que os dados na tela mudaram.

Exemplo de código

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

Funções relacionadas

Conteúdo relacionado

• Referência da API ODBC
• Arquivos de cabeçalho ODBC