Função SQLSpecialColumns

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 1.0: Open Group

Summary
SQLSpecialColumns recupera a seguinte informação 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 automaticamente atualizadas quando qualquer valor na linha é atualizado por uma transação.

Syntax

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

Arguments

HandleStatement
[Entrada] Identificador do extrato.

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

SQL_BEST_ROWID: Devolve a coluna ou conjunto ótimo de colunas que, ao recuperar valores da ou das colunas, permite identificar de forma única qualquer linha na tabela especificada. Uma coluna pode ser uma pseudo-coluna especificamente concebida para este fim (como no Oracle ROWID ou Ingres TID) ou a coluna ou colunas de qualquer índice único para a tabela.

SQL_ROWVER: Devolve a coluna ou colunas na tabela especificada, se existirem, 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).

Nome do Catálogo
[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 SGBD, uma string vazia ("") indica as 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 atributo da instrução SQL_ATTR_METADATA_ID 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 de *NomeDeCatálogo.

Nome do esquema
[Entrada] Nome do esquema para a tabela. Se um driver suportar esquemas para algumas tabelas mas não para outras, como quando o driver recupera dados de diferentes SGBD, uma cadeia vazia ("") denota as tabelas que não têm esquemas. O Nome do Esquema não pode conter um padrão de pesquisa de cadeias de caracteres.

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

NomeComprimento2
[Entrada] Comprimento em caracteres de *NomeEsquema.

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

Se o atributo da instrução SQL_ATTR_METADATA_ID 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 de *NomeTabela.

Scope
[Entrada] Âmbito mínimo exigido do rowid. O rowid regressado pode ser de maior dimensão. Deve ser uma das seguintes opções:

SQL_SCOPE_CURROW: O rowid é garantido válido apenas enquanto estiver posicionado nessa fila. Uma reseleção posterior usando rowid pode não devolver uma linha se a linha foi atualizada ou eliminada por outra transação.

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

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

Anulável
[Entrada] Determina se deve devolver colunas especiais que podem ter um valor NULL. Deve ser uma das seguintes opções:

SQL_NO_NULLS: Excluir colunas especiais que possam ter valores NULL. Alguns drivers não conseguem suportar SQL_NO_NULLS, e estes drivers devolverão um conjunto de resultados vazio se SQL_NO_NULLS for especificado. As candidaturas devem ser preparadas para este caso e pedir SQL_NO_NULLS apenas se for absolutamente necessário.

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

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

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

Comments

Quando o argumento IdentifierType está SQL_BEST_ROWID, SQLSpecialColumns devolve a coluna ou colunas que identificam de forma única cada linha da tabela. Estas colunas podem sempre ser usadas numa cláusula select-list ou WHERE . O SQLColumns, que é usado para devolver uma variedade de informação nas colunas de uma tabela, não retorna necessariamente as colunas que identificam unicamente cada linha, nem as colunas que são automaticamente atualizadas quando qualquer valor na linha é atualizado por uma transação. Por exemplo, o SQLColumns pode não devolver a pseudo-coluna Oracle ROWID. É por isso que o SQLSpecialColumns é usado para devolver estas colunas. Para mais informações, consulte Utilizações dos Dados de Catálogo.

Se não existirem colunas que identifiquem unicamente cada linha da tabela, o SQLSpecialColumns devolve 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 devolve um conjunto de resultados vazio.

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

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

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.

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 seguinte lista as colunas do conjunto de resultados. Colunas adicionais para além da coluna 8 (PSEUDO_COLUMN) podem ser definidas pelo driver. Uma aplicação deve aceder 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 mais informações, consulte Dados Devolvidos por Funções de Catálogo.

Depois de a aplicação recuperar valores para SQL_BEST_ROWID, pode usar esses valores para voltar a selecionar essa linha dentro do âmbito definido. A instrução SELECT garante que não devolve nenhuma linha ou uma linha.

Se uma aplicação reselecionar uma linha com base na coluna rowid ou colunas e a linha não for encontrada, a aplicação pode assumir que a linha foi eliminada 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.

As colunas retornadas para o tipo de coluna SQL_BEST_ROWID são úteis para aplicações que precisam de avançar e voltar dentro de um conjunto de resultados para obter os dados mais recentes de um conjunto de linhas. A coluna ou colunas do rowid garantem que não mudam enquanto estão posicionadas nessa 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 isto verificando a coluna SCOPE no conjunto de resultados.

As colunas retornadas para o tipo de coluna SQL_ROWVER são úteis para aplicações que necessitam da capacidade de verificar se alguma coluna numa dada linha foi atualizada enquanto a linha foi reselecionada usando o rowid. Por exemplo, após selecionar novamente uma linha usando rowid, a aplicação pode comparar os valores anteriores nas colunas SQL_ROWVER com os que acabaram de ser obtidos. Se o valor numa coluna de SQL_ROWVER diferir do valor anterior, a aplicação pode alertar o utilizador de que os dados no ecrã 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
• Ficheiros de Cabeçalho ODBC