Função SQLColAttribute

Artigo
05/23/2023

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92

Resumo
SQLColAttribute retorna informações de descritor para uma coluna em um conjunto de resultados. As informações do descritor são retornadas como uma cadeia de caracteres, um valor dependente do descritor ou um valor inteiro.

Observação

Para obter mais informações sobre como o Gerenciador de Driver mapeia essa função para quando um ODBC 3. O aplicativo x está trabalhando com um ODBC 2. x driver, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.

Sintaxe

  
SQLRETURN SQLColAttribute (  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ColumnNumber,  
      SQLUSMALLINT    FieldIdentifier,  
      SQLPOINTER      CharacterAttributePtr,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLLEN *        NumericAttributePtr);

Argumentos

StatementHandle
[Entrada] Identificador de instrução.

ColumnNumber
[Entrada] O número do registro no IRD do qual o valor do campo deve ser recuperado. Esse argumento corresponde ao número de colunas de dados de resultado, ordenados sequencialmente em ordem de coluna crescente, começando em 1. As colunas podem ser descritas em qualquer ordem.

A coluna 0 pode ser especificada nesse argumento, mas todos os valores, exceto SQL_DESC_TYPE e SQL_DESC_OCTET_LENGTH retornarão valores indefinidos.

FieldIdentifier
[Entrada] O identificador do descritor. Esse identificador define qual campo no IRD deve ser consultado (por exemplo, SQL_COLUMN_TABLE_NAME).

CharacterAttributePtr
[Saída] Ponteiro para um buffer no qual retornar o valor no campo FieldIdentifier da linha ColumnNumber do IRD, se o campo for uma cadeia de caracteres. Caso contrário, o campo não será usado.

Se CharacterAttributePtr for NULL, StringLengthPtr ainda retornará o número total de bytes (excluindo o caractere de terminação nula para dados de caractere) disponíveis para retornar no buffer apontado por CharacterAttributePtr.

BufferLength
[Entrada] Se FieldIdentifier for um campo definido por ODBC e CharacterAttributePtr apontar para uma cadeia de caracteres ou buffer binário, esse argumento deverá ser o comprimento de *CharacterAttributePtr. Se FieldIdentifier for um campo definido por ODBC e *CharacterAttributePtr for um inteiro, esse campo será ignorado. Se *CharacterAttributePtr for uma cadeia de caracteres Unicode (ao chamar SQLColAttributeW), o argumento BufferLength deverá ser um número par. Se FieldIdentifier for um campo definido pelo driver, o aplicativo indicará a natureza do campo para o Gerenciador de Driver definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:

Se CharacterAttributePtr for um ponteiro para um ponteiro, BufferLength deverá ter o valor SQL_IS_POINTER.
Se CharacterAttributePtr for um ponteiro para uma cadeia de caracteres, BufferLength será o comprimento do buffer.
Se CharacterAttributePtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em BufferLength. Isso coloca um valor negativo em BufferLength.
Se CharacterAttributePtr for um ponteiro para um tipo de dados de comprimento fixo, BufferLength deverá ser um dos seguintes: SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT.

StringLengthPtr
[Saída] Ponteiro para um buffer no qual retornar o número total de bytes (excluindo o byte de terminação nula para dados de caractere) disponível para retornar em *CharacterAttributePtr.

Para dados de caracteres, se o número de bytes disponíveis para retornar for maior ou igual a BufferLength, as informações do descritor em *CharacterAttributePtr serão truncadas para BufferLength menos o comprimento de um caractere de terminação nula e serão terminadas em nulo pelo driver.

Para todos os outros tipos de dados, o valor de BufferLength é ignorado e o driver pressupõe que o tamanho de *CharacterAttributePtr seja de 32 bits.

NumericAttributePtr
[Saída] Ponteiro para um buffer inteiro no qual retornar o valor no campo FieldIdentifier da linha ColumnNumber do IRD, se o campo for um tipo de descritor numérico, como SQL_DESC_COLUMN_LENGTH. Caso contrário, o campo não será usado. Observe que alguns drivers só podem gravar os 32 bits inferiores ou 16 bits de um buffer e deixar o bit de ordem superior inalterado. Portanto, os aplicativos devem inicializar o valor como 0 antes de chamar essa função.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLColAttribute 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 SQLColAttribute 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.)
01004	Dados de cadeia de caracteres, truncados à direita	O buffer *CharacterAttributePtr não era grande o suficiente para retornar o valor inteiro da cadeia de caracteres, portanto, o valor da cadeia de caracteres foi truncado. O comprimento do valor da cadeia de caracteres não confiável é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)
07005	Instrução preparada não é uma especificação de cursor	A instrução associada ao StatementHandle não retornou um conjunto de resultados e FieldIdentifier não foi SQL_DESC_COUNT. Não havia colunas para descrever.
07009	Índice de descritor inválido	(DM) O valor especificado para ColumnNumber era igual a 0 e o atributo de instrução SQL_ATTR_USE_BOOKMARKS foi SQL_UB_OFF. O valor especificado para o argumento ColumnNumber foi maior que o número de colunas no conjunto de resultados.
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 SQLGetDiagField da estrutura de dados de diagnóstico 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 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. 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.
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 asíncrona ainda estava em execução quando SQLColAttribute foi chamado. (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) A função foi chamada antes de chamar SQLPrepare, SQLExecDirect ou uma função de catálogo para StatementHandle. (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) CharacterAttributePtr é uma cadeia de caracteres e BufferLength* era menor que 0, mas não igual a SQL_NTS.
HY091	Identificador de campo de descritor inválido	O valor especificado para o argumento FieldIdentifier não era um dos valores definidos e não era um valor definido pela implementação.
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	Driver sem capacidade	O valor especificado para o argumento FieldIdentifier não era compatível com o driver.
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.

Quando chamado após SQLPrepare e antes de SQLExecute, SQLColAttribute pode retornar qualquer SQLSTATE que possa ser retornado por SQLPrepare ou SQLExecute, dependendo de quando a fonte de dados avalia a instrução SQL associada ao StatementHandle.

Por motivos de desempenho, um aplicativo não deve chamar SQLColAttribute antes de executar uma instrução .

Comentários

Para obter informações sobre como os aplicativos usam as informações retornadas por SQLColAttribute, consulte Metadados do conjunto de resultados.

SQLColAttribute retorna informações em *NumericAttributePtr ou em *CharacterAttributePtr. As informações de inteiro são retornadas em *NumericAttributePtr como um valor SQLLEN; todos os outros formatos de informações são retornados em *CharacterAttributePtr. Quando as informações são retornadas em *NumericAttributePtr, o driver ignora CharacterAttributePtr, BufferLength e StringLengthPtr. Quando as informações são retornadas em *CharacterAttributePtr, o driver ignora NumericAttributePtr.

SQLColAttribute retorna valores dos campos do descritor do IRD. A função é chamada com um identificador de instrução em vez de um identificador de descritor. Os valores retornados por SQLColAttribute para os valores fieldIdentifier listados posteriormente nesta seção também podem ser recuperados chamando SQLGetDescField com o identificador IRD apropriado.

Os campos de descritor definidos no momento, a versão do ODBC em que foram introduzidos e os argumentos nos quais as informações são retornadas para eles são mostrados posteriormente nesta seção; mais tipos de descritor podem ser definidos por drivers para aproveitar diferentes fontes de dados.

Um ODBC 3. x driver deve retornar um valor para cada um dos campos do descritor. Se um campo descritor não se aplicar a um driver ou fonte de dados e, a menos que indicado de outra forma, o driver retornará 0 em *StringLengthPtr ou uma cadeia de caracteres vazia em *CharacterAttributePtr.

Backward Compatibility

O ODBC 3. X function SQLColAttribute substitui o ODBC 2 preterido. x função SQLColAttributes. Ao mapear SQLColAttributes para SQLColAttribute (quando um ODBC 2. O aplicativo x está trabalhando com um ODBC 3. x driver) ou mapeamento de SQLColAttribute para SQLColAttributes (quando um ODBC 3. O aplicativo x está trabalhando com um ODBC 2. x driver), o Gerenciador de Driver passa o valor de FieldIdentifier, mapeia-o para um novo valor ou retorna um erro, da seguinte maneira:

Observação

O prefixo usado em valores FieldIdentifier no ODBC 3. x foi alterado do usado no ODBC 2. x. O novo prefixo é "SQL_DESC"; o prefixo antigo era "SQL_COLUMN".

Se o #define valor do ODBC 2. xFieldIdentifier é o mesmo que o valor #define do ODBC 3. xFieldIdentifier, o valor na chamada de função é passado.
O #define valores do ODBC 2. xFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION e SQL_COLUMN_SCALE são diferentes dos valores de #define do ODBC 3. xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE e SQL_DESC_LENGTH. Um ODBC 2. O driver x só precisa dar suporte ao ODBC 2. valores x . Um ODBC 3. O driver x deve dar suporte aos valores "SQL_COLUMN" e "SQL_DESC" para esses três FieldIdentifiers. Esses valores são diferentes porque precisão, escala e comprimento são definidos de forma diferente no ODBC 3. x do que estavam no ODBC 2. x. Para obter mais informações, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho da Exibição.
Se o #define valor do ODBC 2. xFieldIdentifier é diferente do valor #define do ODBC 3. xFieldIdentifier, como ocorre com os valores COUNT, NAME e NULLABLE, o valor na chamada de função é mapeado para o valor correspondente. Por exemplo, SQL_COLUMN_COUNT é mapeado para SQL_DESC_COUNT e SQL_DESC_COUNT é mapeado para SQL_COLUMN_COUNT, dependendo da direção do mapeamento.
Se FieldIdentifier for um novo valor no ODBC 3. x, para o qual não havia nenhum valor correspondente no ODBC 2. x, ele não será mapeado quando um ODBC 3. O aplicativo x o usa em uma chamada para SQLColAttribute em um ODBC 2. x driver e a chamada retornará SQLSTATE HY091 (identificador de campo de descritor inválido).

A tabela a seguir lista os tipos de descritor retornados por SQLColAttribute. O tipo para valores NumericAttributePtr é SQLLEN *.

FieldIdentifier	Informações retornado em	Descrição
SQL_DESC_AUTO_UNIQUE_VALUE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE se a coluna for uma coluna de criação automática. SQL_FALSE se a coluna não for uma coluna de criação automática ou não for numérica. Esse campo é válido apenas para colunas de tipo de dados numéricos. Um aplicativo pode inserir valores em uma linha que contém uma coluna decremento automático, mas normalmente não pode atualizar valores na coluna. Quando uma inserção é feita em uma coluna de autoincremento, um valor exclusivo é inserido na coluna no momento da inserção. O incremento não está definido, mas é específico da fonte de dados. Um aplicativo não deve assumir que uma coluna de autoincremento começa em nenhum ponto específico ou incrementa por qualquer valor específico.
SQL_DESC_BASE_COLUMN_NAME (ODBC 3.0)	CharacterAttributePtr	O nome da coluna base para a coluna do conjunto de resultados. Se um nome de coluna base não existir (como no caso de colunas que são expressões), essa variável conterá uma cadeia de caracteres vazia. Essas informações são retornadas do campo de registro SQL_DESC_BASE_COLUMN_NAME do IRD, que é um campo somente leitura.
SQL_DESC_BASE_TABLE_NAME (ODBC 3.0)	CharacterAttributePtr	O nome da tabela base que contém a coluna. Se o nome da tabela base não puder ser definido ou não for aplicável, essa variável conterá uma cadeia de caracteres vazia. Essas informações são retornadas do campo de registro SQL_DESC_BASE_TABLE_NAME do IRD, que é um campo somente leitura.
SQL_DESC_CASE_SENSITIVE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE se a coluna for tratada como diferenciação de maiúsculas e minúsculas para ordenações e comparações. SQL_FALSE se a coluna não for tratada como diferenciar maiúsculas de minúsculas para ordenações e comparações ou não for de caracteres.
SQL_DESC_CATALOG_NAME (ODBC 2.0)	CharacterAttributePtr	O catálogo da tabela que contém a coluna. O valor retornado será definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de uma exibição. Se a fonte de dados não der suporte a catálogos ou o nome do catálogo não puder ser determinado, uma cadeia de caracteres vazia será retornada. Esse campo de registro VARCHAR não está limitado a 128 caracteres.
SQL_DESC_CONCISE_TYPE (ODBC 1.0)	NumericAttributePtr	O tipo de dados conciso. Para os tipos de dados datetime e interval, esse campo retorna o tipo de dados conciso; por exemplo, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR. (Para obter mais informações, consulte Identificadores de tipo de dados e descritores no apêndice D: tipos de dados.) Essas informações são retornadas do campo de registro SQL_DESC_CONCISE_TYPE do IRD.
SQL_DESC_COUNT (ODBC 1.0)	NumericAttributePtr	O número de colunas disponíveis no conjunto de resultados. Isso retornará 0 se não houver colunas no conjunto de resultados. O valor no argumento ColumnNumber é ignorado. Essas informações são retornadas do campo de cabeçalho SQL_DESC_COUNT do IRD.
SQL_DESC_DISPLAY_SIZE (ODBC 1.0)	NumericAttributePtr	Número máximo de caracteres necessários para exibir dados da coluna. Para obter mais informações sobre o tamanho da exibição, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados.
SQL_DESC_FIXED_PREC_SCALE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE se a coluna tiver uma precisão fixa e uma escala diferente de zero específicas da fonte de dados. SQL_FALSE se a coluna não tiver uma precisão fixa e uma escala diferente de zero específicas da fonte de dados.
SQL_DESC_LABEL (ODBC 2.0)	CharacterAttributePtr	O rótulo ou título da coluna. Por exemplo, uma coluna chamada EmpName pode ser rotulada como Nome do Funcionário ou pode ser rotulada com um alias. Se uma coluna não tiver um rótulo, o nome da coluna será retornado. Se a coluna estiver sem rótulo e sem nome, uma cadeia de caracteres vazia será retornada.
SQL_DESC_LENGTH (ODBC 3.0)	NumericAttributePtr	Um valor numérico que é o comprimento máximo ou real de caracteres de uma cadeia de caracteres ou tipo de dados binário. É o comprimento máximo do caractere para um tipo de dados de comprimento fixo ou o comprimento real do caractere para um tipo de dados de comprimento variável. Seu valor sempre exclui o byte de terminação nula que encerra a cadeia de caracteres. Essas informações são retornadas do campo de registro SQL_DESC_LENGTH do IRD. Para obter mais informações sobre comprimento, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados.
SQL_DESC_LITERAL_PREFIX (ODBC 3.0)	CharacterAttributePtr	Esse campo de registro VARCHAR(128) contém o caractere ou os caracteres que o driver reconhece como um prefixo para um literal desse tipo de dados. Esse campo contém uma cadeia de caracteres vazia para um tipo de dados para o qual um prefixo literal não é aplicável. Para obter mais informações, consulte Prefixos literais e sufixos.
SQL_DESC_LITERAL_SUFFIX (ODBC 3.0)	CharacterAttributePtr	Esse campo de registro VARCHAR(128) contém o caractere ou os caracteres que o driver reconhece como um sufixo para um literal desse tipo de dados. Esse campo contém uma cadeia de caracteres vazia para um tipo de dados para o qual um sufixo literal não é aplicável. Para obter mais informações, consulte Prefixos literais e sufixos.
SQL_DESC_LOCAL_TYPE_NAME (ODBC 3.0)	CharacterAttributePtr	Esse campo de registro VARCHAR(128) contém qualquer nome localizado (idioma nativo) para o tipo de dados que pode ser diferente do nome regular do tipo de dados. Se não houver nenhum nome localizado, uma cadeia de caracteres vazia será retornada. Esse campo é apenas para fins de exibição. O conjunto de caracteres da cadeia de caracteres depende da localidade e normalmente é o conjunto de caracteres padrão do servidor.
SQL_DESC_NAME (ODBC 3.0)	CharacterAttributePtr	O alias de coluna, se ele se aplicar. Se o alias da coluna não se aplicar, o nome da coluna será retornado. Em ambos os casos, SQL_DESC_UNNAMED é definido como SQL_NAMED. Se não houver um nome de coluna ou um alias de coluna, uma cadeia de caracteres vazia será retornada e SQL_DESC_UNNAMED será definida como SQL_UNNAMED. Essas informações são retornadas do campo de registro SQL_DESC_NAME do IRD.
SQL_DESC_NULLABLE (ODBC 3.0)	NumericAttributePtr	SQL_ NULLABLE se a coluna puder ter valores NULL; SQL_NO_NULLS se a coluna não tiver valores NULL; ou SQL_NULLABLE_UNKNOWN se não se sabe se a coluna aceita valores NULL. Essas informações são retornadas do campo de registro SQL_DESC_NULLABLE do IRD.
SQL_DESC_NUM_PREC_RADIX (ODBC 3.0)	NumericAttributePtr	Se o tipo de dados no campo SQL_DESC_TYPE for um tipo de dados numérico aproximado, esse campo SQLINTEGER conterá um valor de 2 porque o campo SQL_DESC_PRECISION contém o número de bits. Se o tipo de dados no campo SQL_DESC_TYPE for um tipo de dados numérico exato, esse campo conterá um valor de 10 porque o campo SQL_DESC_PRECISION contém o número de dígitos decimais. Esse campo é definido como 0 para todos os tipos de dados não numéricos.
SQL_DESC_OCTET_LENGTH (ODBC 3.0)	NumericAttributePtr	O comprimento, em bytes, de uma cadeia de caracteres ou tipo de dados binário. Para caracteres de comprimento fixo ou tipos binários, esse é o comprimento real em bytes. Para tipos binários ou caracteres de comprimento variável, esse é o comprimento máximo em bytes. Esse valor não inclui o terminador nulo. Essas informações são retornadas do campo de registro SQL_DESC_OCTET_LENGTH do IRD. Para obter mais informações sobre comprimento, consulte Tamanho da Coluna, Dígitos Decimais, Tamanho do Octeto de Transferência e Tamanho de Exibição no Apêndice D: Tipos de Dados.
SQL_DESC_PRECISION (ODBC 3.0)	NumericAttributePtr	Um valor numérico que para um tipo de dados numérico indica a precisão aplicável. Para tipos de dados SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP e todos os tipos de dados de intervalo que representam um intervalo de tempo, seu valor é a precisão aplicável do componente de segundos fracionários. Essas informações são retornadas do campo de registro SQL_DESC_PRECISION do IRD.
SQL_DESC_SCALE (ODBC 3.0)	NumericAttributePtr	Um valor numérico que é a escala aplicável para um tipo de dados numérico. Para tipos de dados DECIMAL e NUMERIC, essa é a escala definida. Ele é indefinido para todos os outros tipos de dados. Essas informações são retornadas do campo de registro SCALE do IRD.
SQL_DESC_SCHEMA_NAME (ODBC 2.0)	CharacterAttributePtr	O esquema da tabela que contém a coluna. O valor retornado será definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de uma exibição. Se a fonte de dados não der suporte a esquemas ou o nome do esquema não puder ser determinado, uma cadeia de caracteres vazia será retornada. Esse campo de registro VARCHAR não está limitado a 128 caracteres.
SQL_DESC_SEARCHABLE (ODBC 1.0)	NumericAttributePtr	SQL_PRED_NONE se a coluna não puder ser usada em uma cláusula WHERE. (Isso é o mesmo que o valor SQL_UNSEARCHABLE no ODBC 2. x.) SQL_PRED_CHAR se a coluna puder ser usada em uma cláusula WHERE, mas somente com o predicado LIKE. (Isso é o mesmo que o valor SQL_LIKE_ONLY no ODBC 2. x.) SQL_PRED_BASIC se a coluna puder ser usada em uma cláusula WHERE com todos os operadores de comparação, exceto LIKE. (Isso é o mesmo que o valor SQL_EXCEPT_LIKE no ODBC 2. x.) SQL_PRED_SEARCHABLE se a coluna puder ser usada em uma cláusula WHERE com qualquer operador de comparação. Colunas do tipo SQL_LONGVARCHAR e SQL_LONGVARBINARY geralmente retornam SQL_PRED_CHAR.
SQL_DESC_TABLE_NAME (ODBC 2.0)	CharacterAttributePtr	O nome da tabela que contém a coluna. O valor retornado será definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de uma exibição. Se o nome da tabela não puder ser determinado, uma cadeia de caracteres vazia será retornada.
SQL_DESC_TYPE (ODBC 3.0)	NumericAttributePtr	Um valor numérico que especifica o tipo de dados SQL. Quando ColumnNumber é igual a 0, SQL_BINARY é retornado para indicadores de comprimento variável e SQL_INTEGER é retornado para indicadores de comprimento fixo. Para os tipos de dados datetime e interval, esse campo retorna o tipo de dados detalhado: SQL_DATETIME ou SQL_INTERVAL. (Para obter mais informações, consulte Identificadores de tipo de dados e descritores no apêndice D: tipos de dados. Essas informações são retornadas do campo de registro SQL_DESC_TYPE do IRD. Nota: Para trabalhar com o ODBC 2. x drivers, use SQL_DESC_CONCISE_TYPE em vez disso.
SQL_DESC_TYPE_NAME (ODBC 1.0)	CharacterAttributePtr	Nome do tipo de dados dependente da fonte de dados; por exemplo, "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" ou "CHAR ( ) FOR BIT DATA". Se o tipo for desconhecido, uma cadeia de caracteres vazia será retornada.
SQL_DESC_UNNAMED (ODBC 3.0)	NumericAttributePtr	SQL_NAMED ou SQL_UNNAMED. Se o campo SQL_DESC_NAME do IRD contiver um alias de coluna ou um nome de coluna, SQL_NAMED será retornado. Se não houver nenhum nome de coluna ou alias de coluna, SQL_UNNAMED será retornado. Essas informações são retornadas do campo SQL_DESC_UNNAMED registro do IRD.
SQL_DESC_UNSIGNED (ODBC 1.0)	NumericAttributePtr	SQL_TRUE se a coluna não estiver assinada (ou não for numérica). SQL_FALSE se a coluna estiver assinada.
SQL_DESC_UPDATABLE (ODBC 1.0)	NumericAttributePtr	A coluna é descrita pelos valores para as constantes definidas: SQL_ATTR_READONLY SQL_ATTR_WRITE SQL_ATTR_READWRITE_UNKNOWN SQL_DESC_UPDATABLE descreve a atualização da coluna no conjunto de resultados, não a coluna na tabela base. A updatability da coluna base na qual a coluna do conjunto de resultados é baseada pode ser diferente do valor neste campo. Se uma coluna é atualizável pode ser baseada no tipo de dados, nos privilégios do usuário e na definição do próprio conjunto de resultados. Se não estiver claro se uma coluna é atualizável, SQL_ATTR_READWRITE_UNKNOWN deve ser retornado.

SQLColAttribute é uma alternativa extensível para SQLDescribeCol. SQLDescribeCol retorna um conjunto fixo de informações de descritor com base no SQL ANSI-89. SQLColAttribute permite acesso ao conjunto mais extenso de informações de descritor disponíveis nas extensões de fornecedor DO ANSI SQL-92 e DBMS.

Para obter informações sobre	Consulte
Associar um buffer a uma coluna em um conjunto de resultados	Função SQLBindCol
Cancelando o processamento de instruções	Função SQLCancel
Retornando informações sobre uma coluna em um conjunto de resultados	Função SQLDescribeCol
Buscar um bloco de dados ou rolar por um conjunto de resultados	Função SQLFetchScroll
Buscar várias linhas de dados	Função SQLFetch

Exemplo

O código de exemplo a seguir não libera identificadores e conexões. Consulte Função SQLFreeHandle, Programa ODBC de Exemplo e Função SQLFreeStmt para obter exemplos de código para liberar identificadores e instruções.

// SQLColAttibute.cpp  
// compile with: user32.lib odbc32.lib  
  
#define UNICODE  
  
#include <windows.h>  
#include <sqlext.h>  
#include <strsafe.h>  
  
struct DataBinding {  
   SQLSMALLINT TargetType;  
   SQLPOINTER TargetValuePtr;  
   SQLINTEGER BufferLength;  
   SQLLEN StrLen_or_Ind;  
};  
  
void printStatementResult(SQLHSTMT hstmt) {  
   int bufferSize = 1024, i;  
   SQLRETURN retCode;  
   SQLSMALLINT numColumn = 0, bufferLenUsed;
   
   retCode = SQLNumResultCols(hstmt, &numColumn);  
   
   SQLPOINTER* columnLabels = (SQLPOINTER *)malloc( numColumn * sizeof(SQLPOINTER*) );  
   struct DataBinding* columnData = (struct DataBinding*)malloc( numColumn * sizeof(struct DataBinding) );  
  
   printf( "Columns from that table:\n" );  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnLabels[i] = (SQLPOINTER)malloc( bufferSize*sizeof(char) );  
  
      retCode = SQLColAttribute(hstmt, (SQLUSMALLINT)i + 1, SQL_DESC_LABEL, columnLabels[i], (SQLSMALLINT)bufferSize, &bufferLenUsed, NULL);  
      wprintf( L"Column %d: %s\n", i, (wchar_t*)columnLabels[i] );  
   }  
  
   // allocate memory for the binding  
   for ( i = 0 ; i < numColumn ; i++ ) {  
      columnData[i].TargetType = SQL_C_CHAR;  
      columnData[i].BufferLength = (bufferSize+1);  
      columnData[i].TargetValuePtr = malloc( sizeof(unsigned char)*columnData[i].BufferLength );  
   }  
  
   // setup the binding   
   for ( i = 0 ; i < numColumn ; i++ ) {  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, columnData[i].TargetType,   
         columnData[i].TargetValuePtr, columnData[i].BufferLength, &(columnData[i].StrLen_or_Ind));  
   }  
  
   printf( "Data from that table:\n" );  
   // fetch the data and print out the data  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt) ) {  
      int j;  
      for ( j = 0 ; j < numColumn ; j++ )  
         wprintf( L"%s: %hs\n", columnLabels[j], columnData[j].TargetValuePtr );  
      printf( "\n" );  
   }  
   printf( "\n" );   
}  
  
int main() {  
   int bufferSize = 1024, i, count = 1, numCols = 5;  
   wchar_t firstTableName[1024], * dbName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize ), * userName = (wchar_t *)malloc( sizeof(wchar_t)*bufferSize );  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLWCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen, bufferLen;  
   SQLRETURN retCode;  
  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   struct DataBinding* catalogResult = (struct DataBinding*) malloc( numCols * sizeof(struct DataBinding) );  
   SQLWCHAR* selectAllQuery = (SQLWCHAR *)malloc( sizeof(SQLWCHAR) * bufferSize );  
  
   // connect to database  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLCHAR *)(void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, L"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   // display the database information  
   retCode = SQLGetInfo(hdbc, SQL_DATABASE_NAME, dbName, (SQLSMALLINT)bufferSize, (SQLSMALLINT *)&bufferLen);  
   retCode = SQLGetInfo(hdbc, SQL_USER_NAME, userName, (SQLSMALLINT)bufferSize, &bufferLen);  
  
   for ( i = 0 ; i < numCols ; i++ ) {  
      catalogResult[i].TargetType = SQL_C_CHAR;  
      catalogResult[i].BufferLength = (bufferSize + 1);  
      catalogResult[i].TargetValuePtr = malloc( sizeof(unsigned char)*catalogResult[i].BufferLength );  
   }  
  
   // Set up the binding. This can be used even if the statement is closed by closeStatementHandle  
   for ( i = 0 ; i < numCols ; i++ )  
      retCode = SQLBindCol(hstmt, (SQLUSMALLINT)i + 1, catalogResult[i].TargetType, catalogResult[i].TargetValuePtr, catalogResult[i].BufferLength, &(catalogResult[i].StrLen_or_Ind));  
  
   retCode = SQLTables( hstmt, (SQLWCHAR*)SQL_ALL_CATALOGS, SQL_NTS, L"", SQL_NTS, L"", SQL_NTS, L"", SQL_NTS );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   retCode = SQLTables( hstmt, dbName, SQL_NTS, userName, SQL_NTS, L"%", SQL_NTS, L"TABLE", SQL_NTS );  
  
   for ( retCode = SQLFetch(hstmt) ; retCode == SQL_SUCCESS || retCode == SQL_SUCCESS_WITH_INFO ; retCode = SQLFetch(hstmt), ++count )  
      if ( count == 1 )  
         StringCchPrintfW( firstTableName, 1024, L"%hs", catalogResult[2].TargetValuePtr );  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
  
   wprintf( L"Select all data from the first table (%s)\n", firstTableName );  
   StringCchPrintfW( selectAllQuery, bufferSize, L"SELECT * FROM %s", firstTableName );  
  
   retCode = SQLExecDirect(hstmt, selectAllQuery, SQL_NTS);  
   printStatementResult(hstmt);  
}

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Programa ODBC de exemplo

Função SQLColAttribute

Sintaxe

Argumentos

Retornos

Diagnósticos

Comentários

Backward Compatibility

Funções relacionadas

Exemplo

Consulte Também

Comentários

Comentários

Recursos adicionais