SQLColAttribute-Funktion

Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: ISO 92

Zusammenfassung
SQLColAttribute gibt Deskriptorinformationen für eine Spalte in einem Resultset zurück. Deskriptorinformationen werden als Zeichenfolge, deskriptorabhängiger Wert oder ganzzahliger Wert zurückgegeben.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

ColumnNumber
[Eingabe] Die Nummer des Datensatzes in der IRD, aus dem der Feldwert abgerufen werden soll. Dieses Argument entspricht der Spaltenanzahl der Ergebnisdaten, die sequenziell in erhöhter Spaltenreihenfolge sortiert werden, beginnend bei 1. Spalten können in beliebiger Reihenfolge beschrieben werden.

Spalte 0 kann in diesem Argument angegeben werden, aber alle Werte außer SQL_DESC_TYPE und SQL_DESC_OCTET_LENGTH geben nicht definierte Werte zurück.

FieldIdentifier
[Eingabe] Das Deskriptorhandle. Mit diesem Handle wird definiert, welches Feld in der IRD abgefragt werden soll (z. B. SQL_COLUMN_TABLE_NAME).

CharacterAttributePtr
[Ausgabe] Zeigen Sie auf einen Puffer, in dem der Wert im Feld "FieldIdentifier " der Zeile "ColumnNumber " der IRD zurückgegeben wird, wenn das Feld eine Zeichenfolge ist. Andernfalls wird das Feld nicht verwendet.

Wenn CharacterAttributePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtanzahl der Bytes zurück (mit Ausnahme des Nullendpunkts für Zeichendaten), die für die Rückgabe im Puffer verfügbar sind, auf den CharacterAttributePtr verweist.

BufferLength
[Eingabe] Wenn FieldIdentifier ein ODBC-definiertes Feld ist und CharacterAttributePtr auf eine Zeichenfolge oder einen binären Puffer zeigt, sollte dieses Argument die Länge von *CharacterAttributePtr sein. Wenn FieldIdentifier ein ODBC-definiertes Feld ist und *CharacterAttributePtr eine ganze Zahl ist, wird dieses Feld ignoriert. Wenn * CharacterAttributePtr eine Unicode-Zeichenfolge ist (beim Aufrufen von SQLColAttributeW), muss das Argument BufferLength eine gerade Zahl sein. Wenn FieldIdentifier ein treiberdefiniertes Feld ist, gibt die Anwendung die Art des Felds an den Treiber-Manager an, indem das Argument BufferLength festgelegt wird. BufferLength kann die folgenden Werte haben:

• Wenn CharacterAttributePtr ein Zeiger auf einen Zeiger ist, sollte BufferLength den Wert SQL_IS_POINTER haben.

• Wenn CharacterAttributePtr ein Zeiger auf eine Zeichenfolge ist, ist BufferLength die Länge des Puffers.

• Wenn CharacterAttributePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des makros SQL_LEN_BINARY_ATTR(länge) in BufferLength. Dadurch wird ein negativer Wert in BufferLength platziert.

• Wenn CharacterAttributePtr ein Zeiger auf einen Datentyp mit fester Länge ist, muss BufferLength eine der folgenden Sein: SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT oder SQL_IS_USMALLINT.

StringLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtanzahl der Bytes zurückgegeben werden soll (mit Ausnahme des Bytes der Nullendung für Zeichendaten), die in *CharacterAttributePtr zurückgegeben werden können.

Wenn die Anzahl der zurückzugebenden Bytes größer oder gleich BufferLength ist, werden die Deskriptorinformationen in *CharacterAttributePtr abgeschnitten, um PufferLength minus der Länge eines Null-Beendigungszeichens abzubrechen und vom Treiber null beendet zu werden.

Für alle anderen Datentypen wird der Wert von BufferLength ignoriert, und der Treiber geht davon aus, dass die Größe von *CharacterAttributePtr 32 Bit beträgt.

NumericAttributePtr
[Ausgabe] Zeigen Sie auf einen ganzzahligen Puffer, in dem der Wert im Feld "FieldIdentifier " der Zeile "ColumnNumber " der IRD zurückgegeben wird, wenn das Feld ein numerischer Deskriptortyp ist, z. B. SQL_DESC_COLUMN_LENGTH. Andernfalls wird das Feld nicht verwendet. Beachten Sie, dass einige Treiber nur die untere 32-Bit- oder 16-Bit-Version eines Puffers schreiben und das Bit der höheren Reihenfolge unverändert lassen. Daher sollten Anwendungen den Wert vor dem Aufrufen dieser Funktion auf 0 initialisieren.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLColAttribute entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLColAttribute zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Wenn sqlPrepare und vor SQLExecute aufgerufen werden, kann SQLColAttribute jeden SQLSTATE zurückgeben, der von SQLPrepare oder SQLExecute zurückgegeben werden kann, je nachdem, wann die Datenquelle die sql-Anweisung auswertet, die der StatementHandle zugeordnet ist.

Aus Leistungsgründen sollte eine Anwendung sqlColAttribute nicht aufrufen, bevor eine Anweisung ausgeführt wird.

Kommentare

Informationen dazu, wie Anwendungen die von SQLColAttribute zurückgegebenen Informationen verwenden, finden Sie unter Resultset-Metadaten.

SQLColAttribute gibt Informationen entweder in *NumericAttributePtr oder in *CharacterAttributePtr zurück. Ganzzahlige Informationen werden in *NumericAttributePtr als SQLLEN-Wert zurückgegeben. Alle anderen Informationsformate werden in *CharacterAttributePtr zurückgegeben. Wenn Informationen in *NumericAttributePtr zurückgegeben werden, ignoriert der Treiber CharacterAttributePtr, BufferLength und StringLengthPtr. Wenn Informationen in *CharacterAttributePtr zurückgegeben werden, ignoriert der Treiber NumericAttributePtr.

SQLColAttribute gibt Werte aus den Deskriptorfeldern der IRD zurück. Die Funktion wird mit einem Anweisungshandle anstelle eines Deskriptorhandles aufgerufen. Die von SQLColAttribute für die weiter unten in diesem Abschnitt aufgeführten FieldIdentifier-Werte zurückgegebenen Werte können auch durch Aufrufen von SQLGetDescField mit dem entsprechenden IRD-Handle abgerufen werden.

Die aktuell definierten Deskriptorfelder, die Version von ODBC, in der sie eingeführt wurden, und die Argumente, in denen Informationen für sie zurückgegeben werden, werden weiter unten in diesem Abschnitt gezeigt; Weitere Beschreibungstypen können von Treibern definiert werden, um die Vorteile verschiedener Datenquellen zu nutzen.

ODBC 3.x-Treiber muss für jedes der Deskriptorfelder einen Wert zurückgeben. Wenn ein Deskriptorfeld nicht für einen Treiber oder eine Datenquelle gilt und sofern nicht anders angegeben, gibt der Treiber 0 in *StringLengthPtr oder eine leere Zeichenfolge in *CharacterAttributePtr zurück.

Abwärtskompatibilität

ODBC 3.Die x-Funktion SQLColAttribute ersetzt das veraltete ODBC 2.x-Funktion SQLColAttributes. Beim Zuordnen von SQLColAttributes zu SQLColAttribute (wenn odbc 2.x-Anwendung arbeitet mit einem ODBC 3.x-Treiber) oder Zuordnen von SQLColAttribute zu SQLColAttributes (wenn odbc 3.x-Anwendung arbeitet mit einem ODBC 2.x-Treiber), der Treiber-Manager übergibt entweder den Wert von FieldIdentifier, ordnet ihn einem neuen Wert zu oder gibt einen Fehler wie folgt zurück:

• Wenn der #define Wert von ODBC 2."x FieldIdentifier " ist identisch mit dem #define Wert von ODBC 3.x FieldIdentifier, der Wert im Funktionsaufruf wird gerade übergeben.

• Die #define Werte von ODBC 2.x FieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION und SQL_COLUMN_SCALE unterscheiden sich von den #define Werten von ODBC 3.x FieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE und SQL_DESC_LENGTH. ODBC 2.x-Treiber benötigen nur Unterstützung für ODBC 2.x-Werte . ODBC 3.x-Treiber muss sowohl die Werte "SQL_COLUMN" als auch "SQL_DESC" für diese drei FieldIdentifier unterstützen. Diese Werte unterscheiden sich, da Genauigkeit, Skalierung und Länge in ODBC 3 unterschiedlich definiert werden.x als in ODBC 2.x. Weitere Informationen finden Sie unter "Spaltengröße", "Dezimalziffern", "Oktettlänge übertragen" und "Anzeigegröße".

• Wenn der #define Wert von ODBC 2.x FieldIdentifier unterscheidet sich vom #define Wert des ODBC 3.x FieldIdentifier, wie bei den WERTEN ANZAHL, NAME und NULLABLE, wird der Wert im Funktionsaufruf dem entsprechenden Wert zugeordnet. Beispielsweise wird SQL_COLUMN_COUNT SQL_DESC_COUNT zugeordnet, und SQL_DESC_COUNT wird abhängig von der Richtung der Zuordnung SQL_COLUMN_COUNT zugeordnet.

• Wenn FieldIdentifier ein neuer Wert in ODBC 3 ist.x, für die in ODBC 2 kein entsprechender Wert vorhanden war.x, es wird nicht zugeordnet, wenn ein ODBC 3.x-Anwendung verwendet sie in einem Aufruf von SQLColAttribute in einem ODBC 2.x-Treiber und der Aufruf gibt SQLSTATE HY091 (Ungültiger Deskriptorfeldbezeichner) zurück.

In der folgenden Tabelle sind die von SQLColAttribute zurückgegebenen Deskriptortypen aufgeführt. Der Typ für NumericAttributePtr-Werte lautet SQLLEN *.

SQLColAttribute ist eine erweiterbare Alternative zu SQLDescribeCol. SQLDescribeCol gibt einen festen Satz von Deskriptorinformationen basierend auf ANSI-89 SQL zurück. SQLColAttribute ermöglicht den Zugriff auf die umfangreicheren Deskriptorinformationen, die in ANSI SQL-92- und DBMS-Anbietererweiterungen verfügbar sind.

Verwandte Funktionen

Beispiel

Im folgenden Beispielcode werden keine Handles und Verbindungen freigegeben. Codebeispiele für kostenlose Handles und Anweisungen finden Sie unter SQLFreeHandle-Funktion, Beispiel-ODBC-Programm und SQLFreeStmt-Funktion.

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
ODBC-Beispielprogramm