Função SQLSpecialColumns
Compatibilidade
Versão introduzida: ODBC 1.0 Standards Compliance: Open Group
Resumo
SQLSpecialColumns recupera as seguintes informações sobre colunas em uma tabela especificada:
O conjunto ideal de colunas que identifica exclusivamente 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
StatementHandle
[Entrada] Identificador de instrução.
IdentifierType
[Entrada] Tipo de coluna a ser retornada. Deve ser um dos seguintes valores:
SQL_BEST_ROWID: retorna a coluna ou o conjunto ideal de colunas que, ao recuperar valores da coluna ou colunas, permite que qualquer linha na tabela especificada seja identificada exclusivamente. Uma coluna pode ser uma pseudocoluna projetada especificamente para essa finalidade (como no Oracle ROWID ou Ingres TID) ou a coluna ou colunas de qualquer índice exclusivo para a tabela.
SQL_ROWVER: Retorna a coluna ou colunas na tabela especificada, se houver, que são atualizadas automaticamente pela fonte de dados quando qualquer valor na linha é atualizado por qualquer transação (como em SQLBase ROWID ou Sybase TIMESTAMP).
Nome do Catálogo
[Entrada] Nome do catálogo da tabela. Se um driver oferecer 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 é um argumento comum, é tratado literalmente e seu caso é significativo. Para obter mais informações, confira Argumentos em funções de catálogo.
NomeLength1
[Entrada] Comprimento em caracteres de *CatalogName.
Nome do esquema
[Entrada] Nome do esquema para a tabela. Se um driver oferecer 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 é um argumento comum, é tratado literalmente e seu caso é significativo.
NomeLength2
[Entrada] Comprimento em caracteres de *SchemaName.
TableName
[Entrada] Nome da tabela. Esse argumento não pode ser um ponteiro nulo. TableName 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 é um argumento comum, é tratado literalmente e seu caso é significativo.
NomeLength3
[Entrada] Comprimento em caracteres de *TableName.
Escopo
[Entrada] Escopo mínimo necessário do rowid. O rowid retornado pode ser de maior escopo. Deve ser uma destas opções:
SQL_SCOPE_CURROW: O rowid é garantido para ser válido apenas enquanto posicionado nessa linha. Uma nova seleçã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 para ser válido durante a transação atual.
SQL_SCOPE_SESSION: O rowid é garantido para ser válido durante a sessão (através dos limites de transação).
Permite valor nulo
[Entrada] Determina se as colunas especiais que podem ter um valor NULL devem ser retornadas. Deve ser uma destas opções:
SQL_NO_NULLS: Excluir colunas especiais que podem ter valores NULL. Alguns drivers não podem oferecer suporte a SQL_NO_NULLS e esses drivers retornarão um conjunto de resultados vazio se SQL_NO_NULLS foi especificado. As candidaturas devem ser preparadas para este caso e solicitar SQL_NO_NULLS apenas se for absolutamente necessário.
SQL_NULLABLE: Retornar colunas especiais mesmo que elas possam ter valores NULL.
Retornos
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, 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 por SQLSpecialColumns 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 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 que o processamento da função fosse concluído. |
| 24000 | Estado de cursor inválido | Um cursor foi aberto no StatementHandle, e SQLFetch ou SQLFetchScroll foram chamados. Esse erro é retornado pelo Gerenciador de Driver se SQLFetch ou SQLFetchScroll não tiver retornado SQL_NO_DATA e será retornado pelo driver se SQLFetch ou SQLFetchScroll tiver retornado SQL_NO_DATA. Um cursor estava aberto no StatementHandle, mas SQLFetch ou SQLFetchScroll não havia sido chamado. |
| 40001 | Falha de serialização | A transação foi revertida devido a um impasse 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 SQLSTATE específico e para o qual nenhum SQLSTATE específico de 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 a memória necessária para suportar a 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 argumento TableName era um ponteiro nulo. O atributo SQL_ATTR_METADATA_ID instrução foi definido como SQL_TRUE, o argumento CatalogName era um ponteiro nulo e o SQL_CATALOG_NAME InfoType retorna que os nomes de catálogo são suportados. (DM) O atributo SQL_ATTR_METADATA_ID instrução foi definido como SQL_TRUE e o argumento SchemaName era um ponteiro nulo. |
| HY010 | Erro de sequência de função | (DM) Uma função de execução assíncrona foi chamada para o identificador de conexão associado ao StatementHandle. Essa função ainda estava em execução quando SQLSpecialColumns foi chamado. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem 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 foi chamado para o StatementHandle e retornou SQL_NEED_DATA. Essa função foi chamada antes que os dados fossem 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 pouca memória. |
| HY090 | Cadeia de caracteres inválida ou comprimento do buffer | (DM) O valor de um dos argumentos de comprimento foi menor que 0, mas não igual a SQL_NTS. O valor de um dos argumentos length excedeu o valor de comprimento máximo para o nome correspondente. O comprimento máximo de cada nome pode ser obtido chamando SQLGetInfo com os valores InfoType: SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN ou SQL_MAX_TABLE_NAME_LEN. |
| HY097 | Tipo de coluna fora do intervalo | (DM) Um valor IdentifierType inválido foi especificado. |
| HY098 | Tipo de escopo fora do intervalo | (DM) Um valor de escopo inválido foi especificado. |
| HY099 | Tipo anulável fora do intervalo | (DM) Um valor anulável inválido foi especificado. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão 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 a fonte de dados não oferece suporte a catálogos. Um esquema foi especificado e o driver ou a fonte de dados não oferece 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 suportada pelo driver ou pela 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 oferece suporte a marcadores. |
| HYT00 | Timeout expired | O período de tempo limite da consulta expirou antes que a fonte de dados retornasse 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 de conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite de conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver não suporta esta função | (DM) O driver associado ao StatementHandle não oferece suporte à função. |
| IM017 | A sondagem está desativada 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 neste 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
Quando o argumento IdentifierType é SQL_BEST_ROWID, SQLSpecialColumns retorna a coluna ou colunas que identificam exclusivamente cada linha na tabela. Essas colunas sempre podem ser usadas em uma cláusula select-list ou WHERE . SQLColumns, que é usado para retornar uma variedade de informações nas colunas de uma tabela, não necessariamente retorna as colunas que identificam exclusivamente cada linha ou colunas que são atualizadas automaticamente quando qualquer valor na linha é atualizado por uma transação. Por exemplo, SQLColumns pode não retornar o Oracle pseudo-coluna ROWID. É por isso que SQLSpecialColumns é usado para retornar essas colunas. Para obter mais informações, consulte Usos de dados de catálogo.
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.
Se não houver colunas que identifiquem exclusivamente cada linha na tabela, SQLSpecialColumns retornará um conjunto de linhas sem linhas, uma chamada subsequente para SQLFetch ou SQLFetchScroll na instrução retornará SQL_NO_DATA.
Se os argumentos IdentifierType, Scope ou Nullable especificarem características que não são suportadas pela fonte de dados, SQLSpecialColumns retornará um conjunto de resultados vazio.
Se o atributo de instrução SQL_ATTR_METADATA_ID estiver definido como SQL_TRUE, os argumentos CatalogName, SchemaName e TableName serão tratados como identificadores, portanto, não poderão ser definidos como um ponteiro nulo em determinadas situações. (Para obter mais informações, consulte Argumentos em funções de catálogo.)
SQLSpecialColumns retorna os resultados como um conjunto de resultados padrão, ordenado por SCOPE.
As colunas a seguir foram renomeadas para ODBC 3.x. As alterações de nome de coluna não afetam a compatibilidade com versões anteriores porque os aplicativos se associam por número de coluna.
| Coluna ODBC 2.0 | Coluna ODBC 3.x |
|---|---|
| PRECISION | COLUMN_SIZE |
| COMPRIMENTO | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
Para determinar o comprimento real da coluna COLUMN_NAME, um aplicativo 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. Um aplicativo deve obter acesso a colunas específicas do driver fazendo contagem regressiva 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 | Column number | Tipo de dados | Comentários |
|---|---|---|---|
| ESCOPO (ODBC 1.0) | 1 | Smallint | Escopo real do rowid. Contém um dos seguintes valores: SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL é retornado quando IdentifierType é SQL_ROWVER. Para obter uma descrição de cada valor, consulte a descrição de Escopo em "Sintaxe", anteriormente nesta seção. |
| COLUMN_NAME (ODBC 1.0) | 2 | Varchar não NULL | Nome da coluna. O driver retorna uma cadeia de caracteres vazia para uma coluna que não tem um nome. |
| DATA_TYPE (ODBC 1.0) | 3 | Smallint não NULL | Tipo de dados SQL. Pode ser um tipo de dados SQL ODBC ou um tipo de dados SQL específico do driver. Para obter uma lista de tipos de dados ODBC SQL válidos, consulte Tipos de dados SQL. Para informações sobre tipos de dados SQL específicos do driver, confira a documentação do driver. |
| TYPE_NAME (ODBC 1.0) | 4 | Varchar não NULL | Nome do tipo de dados dependente da fonte de dados; por exemplo, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" ou "CHAR ( ) PARA DADOS DE BITS". |
| COLUMN_SIZE (ODBC 1.0) | 5 | Inteiro | O tamanho da coluna na fonte de dados. Para obter mais informações sobre o tamanho da coluna, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho da exibição. |
| BUFFER_LENGTH (ODBC 1.0) | 6 | Inteiro | O comprimento em bytes de dados transferidos em uma operação SQLGetData ou SQLFetch se SQL_C_DEFAULT for especificado. Para dados numéricos, esse tamanho pode ser diferente do tamanho dos dados armazenados na fonte de dados. Esse valor pode ser diferente de COLUMN_SIZE coluna para dados de caracteres. Para obter mais informações, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho da exibição. |
| DECIMAL_DIGITS (ODBC 1.0) | 7 | Smallint | Os dígitos decimais da coluna na fonte de dados. NULL é retornado para tipos de dados em que dígitos decimais não são aplicáveis. Para obter mais informações sobre dígitos decimais, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho da exibição. |
| PSEUDO_COLUMN (ODBC 2.0) | 8 | Smallint | Indica se a coluna é uma pseudocoluna, como Oracle ROWID: SQL_PC_UNKNOWN SQL_PC_NOT_PSEUDO SQL_PC_PSEUDO Nota: Para máxima interoperabilidade, pseudocolunas não devem ser citadas com o caractere de aspas de identificador retornado por SQLGetInfo. |
Depois que o aplicativo recupera valores para SQL_BEST_ROWID, o aplicativo pode usar esses valores para selecionar novamente essa linha dentro do escopo definido. A instrução SELECT tem a garantia de retornar nenhuma linha ou uma linha.
Se um aplicativo selecionar novamente uma linha com base na coluna rowid ou colunas e a linha não for encontrada, o aplicativo poderá assumir que a linha foi excluída ou que as colunas rowid foram modificadas. O contrário não é verdadeiro: mesmo que o rowid não tenha sido alterado, as outras colunas na linha podem ter sido alteradas.
As colunas retornadas para SQL_BEST_ROWID do tipo de coluna são úteis para aplicativos 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 são garantidas para não mudar enquanto posicionado nessa linha.
A coluna ou colunas do rowid podem permanecer válidas mesmo quando o cursor não está posicionado na linha; o aplicativo pode determinar isso verificando a coluna SCOPE no conjunto de resultados.
As colunas retornadas para o tipo de coluna SQL_ROWVER são úteis para aplicativos 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, depois de selecionar novamente uma linha usando rowid, o aplicativo pode comparar os valores anteriores nas colunas SQL_ROWVER com os que acabaram de ser buscados. Se o valor em uma coluna SQL_ROWVER for diferente do valor anterior, o aplicativo poderá alertar o usuário de que os dados na exibição foram alterados.
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 |
|---|---|
| Vinculando um buffer a uma coluna em um conjunto de resultados | Função SQLBindCol |
| Cancelando o processamento de instruções | Função SQLCancel |
| Retornando as colunas em uma tabela ou tabelas | Função SQLColumns |
| Buscando 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 as colunas de uma chave primária | Função SQLPrimaryKeys |