Função SQLColAttribute

Compatibilidade
Versão introduzida: ODBC 3.0 Conformidade com os padrões: 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.

Sintaxe

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

Argumentos

Identificador de declaração
[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 dados de resultado, ordenados sequencialmente em ordem crescente de coluna, 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
[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á ter 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
[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íveis para retornar em *CharacterAttributePtr.

Para dados de caracteres, se o número de bytes disponíveis para retorno 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 podem gravar apenas os 32 bits ou 16 bits inferiores 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.

Devoluções

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 Handle de StatementHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados por SQLColAttribute e explica cada um 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.

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 pelo 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 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 na qual eles 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 pelos drivers para aproveitar diferentes fontes de dados.

Um ODBC 3.O driver X 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.

Compatibilidade com versões anteriores

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

• 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 só precisa suportar o ODBC 2.Valores de x . Um ODBC 3.x deve dar suporte a 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 for 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 o usa em uma chamada para SQLColAttribute em um ODBC 2.x 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 de valores NumericAttributePtr é SQLLEN *.

SQLColAttribute é uma alternativa extensível ao 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 em extensões de fornecedor ANSI SQL-92 e DBMS.

Funções relacionadas

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 identificadores e instruções livres.

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

Confira também

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