Função SQLColAttribute

Artigo
12/19/2024

Conformidade
Versão introduzida: Conformidade com as normas ODBC 3.0: ISO 92

Resumo
SQLColAttribute retorna informações do 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 o que o Gerenciador de Driver mapeia essa função para quando um ODBC 3.x aplicativo está funcionando 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. Este argumento corresponde ao número da coluna dos dados de resultados, 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 neste 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
[Realização] 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á utilizado.

Se CharacterAttributePtr for NULL, StringLengthPtr ainda retornará o número total de bytes (excluindo o caractere de terminação nula para dados de caracteres) 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 o *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, o 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
[Realização] Ponteiro para um buffer no qual retornar o número total de bytes (excluindo o byte de terminação nula para dados de caracteres) disponíveis 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 nulas pelo driver.

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

NumericAttributePtr
[Realização] 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á utilizado. Observe que alguns drivers podem gravar apenas o buffer inferior de 32 bits ou 16 bits e deixar o bit de ordem superior inalterado. Portanto, os aplicativos devem inicializar o valor para 0 antes de chamar essa função.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnóstico

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 Handle 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 retornados pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

SQLSTATE	Erro	Descrição
01000	Advertência geral	Mensagem informativa específica do motorista. (A função retorna SQL_SUCCESS_WITH_INFO.)
01004	Dados da cadeia de caracteres, truncados à direita	O buffer * CharacterAttributePtr não era grande o suficiente para retornar o valor da cadeia de caracteres inteira, portanto, o valor da cadeia de caracteres foi truncado. O comprimento do valor da cadeia de caracteres não truncada é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)
07005	Declaração preparada que não é um de especificação do 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 foi igual a 0 e o atributo SQL_ATTR_USE_BOOKMARKS statement foi SQL_UB_OFF. O valor especificado para o argumento ColumnNumber era maior do que o número de colunas no conjunto de resultados.
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 pelo 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 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 chamada 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 chamada no StatementHandle de um thread diferente em um aplicativo multithread.
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 assíncrona ainda estava em execução quando SQLColAttribute foi chamado. (DM) SQLExecute, SQLExecDirectou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Esta função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. (DM) A função foi chamada antes de chamar SQLPrepare, SQLExecDirectou uma função de catálogo para o StatementHandle. (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, SQLBulkOperationsou SQLSetPos foi chamado para o StatementHandle e retornou SQL_NEED_DATA. Esta 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 pouca memória.
HY090	String inválida ou comprimento do buffer	(DM) *CharacterAttributePtr é uma cadeia de caracteres e BufferLength foi menor que 0, mas não igual a SQL_NTS.
HY091	Identificador de campo 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 é suspensa devido ao estado desconhecido da transação. Apenas as 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	Motorista não capaz	O valor especificado para o argumento FieldIdentifier não foi suportado pelo driver.
HYT01	O tempo limite de 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 da conexão é definido por meio SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver não suporta esta função	(DM) O driver associado ao StatementHandle não suporta a função.
IM017	A sondagem está desativada no modo de notificação assíncrona	Sempre que o modelo de notificação é usado, a sondagem é desativada.
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.

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.

Observações

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. Informações inteiras são retornadas em *NumericAttributePtr como um valor SQLLEN; todos os outros formatos de informação são retornados em *CharacterAttributePtr. Quando as informações são retornadas em *NumericAttributePtr, o driver ignora CharacterAttributePtr , BufferLengthe StringLengthPtr. Quando as informações são retornadas em *CharacterAttributePtr, o driver ignora NumericAttributePtr.

SQLColAttribute retorna valores dos campos descritores 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 de FieldIdentifier listados posteriormente nesta seção também podem ser recuperados chamando SQLGetDescField com o identificador IRD apropriado.

Os campos descritores atualmente definidos, a versão do ODBC na qual eles foram introduzidos e os argumentos nos quais as informações são retornadas para eles são mostrados mais adiante nesta seção; Mais tipos de descritores podem ser definidos pelos drivers para aproveitar diferentes fontes de dados.

Um ODBC 3.x driver deve retornar um valor para cada um dos campos descritores. Se um campo descritor não se aplicar a um driver ou fonte de dados e salvo indicação em contrário, o driver retornará 0 em *StringLengthPtr ou uma cadeia de caracteres vazia em *CharacterAttributePtr.

Compatibilidade com versões anteriores

O ODBC 3.função xSQLColAttribute substitui o ODBC 2 preterido.função xSQLColAttributes. Ao mapear SQLColAttributes para SQLColAttribute (quando um ODBC 2.x aplicativo está trabalhando com um ODBC 3.x driver), ou mapeando SQLColAttribute para SQLColAttributes (quando um ODBC 3.x aplicativo está trabalhando com um ODBC 2.x driver), o Gerenciador de Driver passa o valor de FieldIdentifier através, Mapeia-o para um novo valor ou retorna um erro, da seguinte maneira:

Observação

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

Se o valor #define do ODBC 2.xFieldIdentifier é o mesmo que o valor #define do ODBC 3.xFieldIdentifier, o valor na chamada de função é apenas passado.
Os valores #define do ODBC 2.xFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION e SQL_COLUMN_SCALE são diferentes dos valores #define do ODBC 3.xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE e SQL_DESC_LENGTH. Um ODBC 2.x driver só precisa suportar o ODBC 2.x valores. Um ODBC 3.x driver deve suportar os valores "SQL_COLUMN" e "SQL_DESC" para esses três FieldIdentifiers. Esses valores são diferentes porque a precisão, a escala e o comprimento são definidos de forma diferente no ODBC 3.x do que no ODBC 2.x. Para obter mais informações, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho de exibição.
Se o valor #define 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 é um novo valor no ODBC 3.x, para o qual não havia valor correspondente no ODBC 2.x, ele não será mapeado quando um ODBC 3.x aplicativo o usa em uma chamada para SQLColAttribute em um ODBC 2.x driver e a chamada retornará SQLSTATE HY091 (identificador de campo descritor inválido).

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

FieldIdentifier	Informação retornou em	Descrição
SQL_DESC_AUTO_UNIQUE_VALUE (ODBC 1.0)	NumericAttributePtr	SQL_TRUE se a coluna for uma coluna de incremento automático. SQL_FALSE se a coluna não for uma coluna de incremento automático ou não for numérica. Este 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 de autoincremento, mas normalmente não pode atualizar valores na coluna. Quando uma inserção é feita em uma coluna de incremento automático, 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 incremento automático começa em qualquer 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 sensível a maiúsculas e minúsculas para agrupamentos e comparações. SQL_FALSE se a coluna não diferenciar maiúsculas de minúsculas para agrupamentos e comparações ou não tiver caracteres.
SQL_DESC_CATALOG_NAME (ODBC 2.0)	CharacterAttributePtr	O catálogo da tabela que contém a coluna. O valor retornado é definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de um modo de exibição. Se a fonte de dados não oferecer suporte a catálogos ou o nome do catálogo não puder ser determinado, uma cadeia de caracteres vazia será retornada. Este campo de registo 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, este campo retorna o tipo de dados conciso; por exemplo, SQL_TYPE_TIME ou SQL_INTERVAL_YEAR. (Para obter mais informações, consulte de identificadores e descritores de tipo de dados no Apêndice D: Tipos de dados.) Esta informação é devolvida a partir do campo de registo 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 tela, consulte Tamanho da coluna, Dígitos decimais, Comprimento do octeto de transferência e Tamanho da tela 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 que sejam específicas da fonte de dados. SQL_FALSE se a coluna não tiver uma precisão fixa e uma escala diferente de zero que sejam 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 não estiver rotulada 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ários. É o comprimento máximo de caracteres para um tipo de dados de comprimento fixo ou o comprimento real de caracteres para um tipo de dados de comprimento variável. Seu valor sempre exclui o byte de terminação nula que termina 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, Comprimento do octeto de transferência e Tamanho da exibição no Apêndice D: Tipos de dados.
SQL_DESC_LITERAL_PREFIX (ODBC 3.0)	CharacterAttributePtr	Este campo de registo VARCHAR(128) contém o caractere ou caracteres que o driver reconhece como um prefixo para um literal desse tipo de dados. Este 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 e sufixos literais.
SQL_DESC_LITERAL_SUFFIX (ODBC 3.0)	CharacterAttributePtr	Este campo de registro VARCHAR(128) contém o caractere ou caracteres que o driver reconhece como um sufixo para um literal desse tipo de dados. Este 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 e sufixos literais.
SQL_DESC_LOCAL_TYPE_NAME (ODBC 3.0)	CharacterAttributePtr	Este campo de registo VARCHAR(128) contém qualquer nome localizado (idioma nativo) para o tipo de dados que possa ser diferente do nome normal do tipo de dados. Se não houver um nome localizado, uma cadeia de caracteres vazia será retornada. Este 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 da coluna, se aplicável. 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 de 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 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. Este 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ários. Para caracteres de comprimento fixo ou tipos binários, este é o comprimento real em bytes. Para caracteres de comprimento variável ou tipos binários, este é 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, Comprimento do octeto de transferência e Tamanho da 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éricos, denota a precisão aplicável. Para os 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éricos. Para os tipos de dados DECIMAL e NUMÉRICO, esta é a escala definida. É 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 é definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de um modo de exibição. Se a fonte de dados não oferecer suporte a esquemas ou o nome do esquema não puder ser determinado, uma cadeia de caracteres vazia será retornada. Este campo de registo 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 utilizada numa cláusula WHERE. (Este é o mesmo que o valor SQL_UNSEARCHABLE no ODBC 2.x.) SQL_PRED_CHAR se a coluna pode ser usada em uma cláusula WHERE, mas apenas com o predicado LIKE. (Este é o mesmo que o valor SQL_LIKE_ONLY no ODBC 2.x.) SQL_PRED_BASIC se a coluna pode ser usada em uma cláusula WHERE com todos os operadores de comparação, exceto LIKE. (Este é o mesmo que o valor de SQL_EXCEPT_LIKE no ODBC 2.x.) SQL_PRED_SEARCHABLE se a coluna pode 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 é definido pela implementação se a coluna for uma expressão ou se a coluna fizer parte de um modo de 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 marcadores de comprimento variável e SQL_INTEGER é retornado para marcadores de comprimento fixo. Para os tipos de dados datetime e interval, este campo retorna o tipo de dados detalhado: SQL_DATETIME ou SQL_INTERVAL. (Para obter mais informações, consulte Identificadores e Descritores de Tipo de Dados 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 contra 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 um nome de coluna ou alias de coluna, SQL_UNNAMED será retornado. Essas informações são retornadas do campo de registro de SQL_DESC_UNNAMED 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 das constantes definidas: SQL_ATTR_READONLY SQL_ATTR_WRITE SQL_ATTR_READWRITE_UNKNOWN SQL_DESC_UPDATABLE descreve a updatability da coluna no conjunto de resultados, não a coluna na tabela base. A capacidade de atualização da coluna base na qual a coluna do conjunto de resultados se baseia 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 própria definição do conjunto de resultados. Se não estiver claro se uma coluna é atualizável, SQL_ATTR_READWRITE_UNKNOWN deve ser retornada.

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

Para obter informações sobre	Ver
Vinculando um buffer a uma coluna em um conjunto de resultados	da função SQLBindCol
Cancelamento do processamento de instruções	da 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
Obtenção de várias linhas de dados	Função SQLFetch

Exemplo

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

// 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);  
}

Ver também

de referência da API ODBC
Arquivos de cabeçalho ODBC
de programa ODBC de exemplo

Partilhar via

Função SQLColAttribute

Sintaxe

Argumentos

Devoluções

Diagnóstico

Observações

Compatibilidade com versões anteriores

Exemplo

Ver também

Comentários

Recursos adicionais

Partilhar via

Função SQLColAttribute

Sintaxe

Argumentos

Devoluções

Diagnóstico

Observações

Compatibilidade com versões anteriores

Funções relacionadas

Exemplo

Ver também

Comentários

Recursos adicionais