Funzione SQLColAttribute

Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92

Riepilogo
SQLColAttribute restituisce informazioni sul descrittore per una colonna in un set di risultati. Le informazioni sul descrittore vengono restituite come stringa di caratteri, un valore dipendente dal descrittore o un valore intero.

Sintassi

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

Argomenti

StatementHandle
[Input] Handle di istruzione.

ColumnNumber
[Input] Numero del record nell'IRD da cui recuperare il valore del campo. Questo argomento corrisponde al numero di colonne dei dati dei risultati, ordinato in sequenza in ordine di colonna crescente, a partire da 1. Le colonne possono essere descritte in qualsiasi ordine.

La colonna 0 può essere specificata in questo argomento, ma tutti i valori tranne SQL_DESC_TYPE e SQL_DESC_OCTET_LENGTH restituiranno valori non definiti.

FieldIdentifier
[Input] Handle del descrittore. Questo handle definisce il campo in cui deve essere eseguita una query in IRD, ad esempio SQL_COLUMN_TABLE_NAME.

CharacterAttributePtr
[Output] Puntatore a un buffer in cui restituire il valore nel campo FieldIdentifier della riga ColumnNumber dell'IRD, se il campo è una stringa di caratteri. In caso contrario, il campo non è usato.

Se CharacterAttributePtr è NULL, StringLengthPtr restituirà comunque il numero totale di byte (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta CharacterAttributePtr.

BufferLength
[Input] Se FieldIdentifier è un campo definito da ODBC e CharacterAttributePtr punta a una stringa di caratteri o a un buffer binario, questo argomento deve essere la lunghezza di *CharacterAttributePtr. Se FieldIdentifier è un campo definito da ODBC e *CharacterAttributePtr è un numero intero, questo campo viene ignorato. Se * CharacterAttributePtr è una stringa Unicode (quando si chiama SQLColAttributeW), l'argomento BufferLength deve essere un numero pari. Se FieldIdentifier è un campo definito dal driver, l'applicazione indica la natura del campo in Gestione driver impostando l'argomento BufferLength . BufferLength può avere i valori seguenti:

• Se CharacterAttributePtr è un puntatore a un puntatore, BufferLength deve avere il valore SQL_IS_POINTER.

• Se CharacterAttributePtr è un puntatore a una stringa di caratteri, BufferLength è la lunghezza del buffer.

• Se CharacterAttributePtr è un puntatore a un buffer binario, l'applicazione inserisce il risultato della macro SQL_LEN_BINARY_ATTR(length) in BufferLength. In questo modo viene impostato un valore negativo in BufferLength.

• Se CharacterAttributePtr è un puntatore a un tipo di dati a lunghezza fissa, BufferLength deve essere uno dei seguenti: SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT o SQL_IS_USMALLINT.

StringLengthPtr
[Output] Puntatore a un buffer in cui restituire il numero totale di byte (escluso il byte di terminazione Null per i dati di tipo carattere) da restituire in *CharacterAttributePtr.

Per i dati di tipo carattere, se il numero di byte disponibili per la restituzione è maggiore o uguale a BufferLength, le informazioni del descrittore in *CharacterAttributePtr vengono troncate a BufferLength meno la lunghezza di un carattere di terminazione Null e terminano con null dal driver.

Per tutti gli altri tipi di dati, il valore di BufferLength viene ignorato e il driver presuppone che le dimensioni di *CharacterAttributePtr siano di 32 bit.

NumericAttributePtr
[Output] Puntatore a un buffer intero in cui restituire il valore nel campo FieldIdentifier della riga ColumnNumber dell'IRD, se il campo è un tipo di descrittore numerico, ad esempio SQL_DESC_COLUMN_LENGTH. In caso contrario, il campo non è usato. Si noti che alcuni driver possono scrivere solo il bit inferiore a 32 bit o 16 bit di un buffer e lasciare invariato il bit di ordine superiore. Pertanto, le applicazioni devono inizializzare il valore su 0 prima di chiamare questa funzione.

Valori restituiti

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLColAttribute restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLColAttribute e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Quando viene chiamato dopo SQLPrepare e prima di SQLExecute, SQLColAttribute può restituire qualsiasi SQLSTATE che può essere restituito da SQLPrepare o SQLExecute, a seconda di quando l'origine dati valuta l'istruzione SQL associata a StatementHandle.

Per motivi di prestazioni, un'applicazione non deve chiamare SQLColAttribute prima di eseguire un'istruzione.

Commenti

Per informazioni su come le applicazioni usano le informazioni restituite da SQLColAttribute, vedere Metadati del set di risultati.

SQLColAttribute restituisce informazioni in *NumericAttributePtr o in *CharacterAttributePtr. Le informazioni sui numeri interi vengono restituite in *NumericAttributePtr come valore SQLLEN. Tutti gli altri formati di informazioni vengono restituiti in *CharacterAttributePtr. Quando vengono restituite informazioni in *NumericAttributePtr, il driver ignora CharacterAttributePtr, BufferLength e StringLengthPtr. Quando vengono restituite informazioni in *CharacterAttributePtr, il driver ignora NumericAttributePtr.

SQLColAttribute restituisce valori dai campi descrittore dell'IRD. La funzione viene chiamata con un handle di istruzione anziché con un handle descrittore. I valori restituiti da SQLColAttribute per i valori FieldIdentifier elencati più avanti in questa sezione possono anche essere recuperati chiamando SQLGetDescField con l'handle IRD appropriato.

I campi descrittori attualmente definiti, la versione di ODBC in cui sono stati introdotti e gli argomenti in cui vengono restituite le informazioni vengono visualizzati più avanti in questa sezione; più tipi di descrittore possono essere definiti dai driver per sfruttare i vantaggi di origini dati diverse.

ODBC 3.x driver deve restituire un valore per ogni campo descrittore. Se un campo descrittore non si applica a un driver o a un'origine dati e, se non diversamente specificato, il driver restituisce 0 in *StringLengthPtr o una stringa vuota in *CharacterAttributePtr.

Compatibilità con le versioni precedenti

ODBC 3.La funzione x SQLColAttribute sostituisce odbc 2 deprecato.Funzione x SQLColAttributes. Quando si esegue il mapping di SQLColAttributes a SQLColAttribute (quando odbc 2.L'applicazione x funziona con odbc 3.x driver) o mapping di SQLColAttribute a SQLColAttributes (quando odbc 3.L'applicazione x funziona con odbc 2.x driver), Gestione driver passa il valore di FieldIdentifier attraverso, lo esegue il mapping a un nuovo valore o restituisce un errore, come indicato di seguito:

• Se il valore #define di ODBC 2.xFieldIdentifier corrisponde al valore #define di ODBC 3.xFieldIdentifier, il valore nella chiamata di funzione viene appena passato.

• Valori #define di ODBC 2.XFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION e SQL_COLUMN_SCALE sono diversi dai valori #define di ODBC 3.xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE e SQL_DESC_LENGTH. ODBC 2.X Driver deve supportare solo ODBC 2.x valori. ODBC 3.X Driver deve supportare sia i valori "SQL_COLUMN" che "SQL_DESC" per questi tre FieldIdentifiers. Questi valori sono diversi perché precisione, scala e lunghezza sono definiti in modo diverso in ODBC 3.x che erano in ODBC 2.x. Per altre informazioni, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione.

• Se il valore #define di ODBC 2.xFieldIdentifier è diverso dal valore #define di ODBC 3.xFieldIdentifier, come avviene con i valori COUNT, NAME e NULLABLE, il valore nella chiamata di funzione viene mappato al valore corrispondente. Ad esempio, SQL_COLUMN_COUNT viene mappato a SQL_DESC_COUNT e SQL_DESC_COUNT viene mappato a SQL_COLUMN_COUNT, a seconda della direzione del mapping.

• Se FieldIdentifier è un nuovo valore in ODBC 3.x, per cui non esiste alcun valore corrispondente in ODBC 2.x, non verrà mappato quando un ODBC 3.L'applicazione x la usa in una chiamata a SQLColAttribute in un'applicazione ODBC 2.x driver e la chiamata restituirà SQLSTATE HY091 (identificatore di campo del descrittore non valido).

Nella tabella seguente sono elencati i tipi di descrittore restituiti da SQLColAttribute. Il tipo per i valori NumericAttributePtr è SQLLEN *.

SQLColAttribute è un'alternativa estendibile a SQLDescribeCol. SQLDescribeCol restituisce un set fisso di informazioni sul descrittore basato su SQL ANSI-89. SQLColAttribute consente l'accesso al set più esteso di informazioni sui descrittori disponibili nelle estensioni del fornitore ANSI SQL-92 e DBMS.

Funzioni correlate

Esempio

Il codice di esempio seguente non libera handle e connessioni. Vedere Funzione SQLFreeHandle, Programma ODBC di esempio e Funzione SQLFreeStmt per esempi di codice per gestire e istruzioni gratuite.

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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC
Programma di esempio ODBC