SQLColAttribute-funktion

Efterlevnad
Version introducerad: ODBC 3.0 Standardefterlevnad: ISO 92

Sammanfattning
SQLColAttribute returnerar beskrivningsinformation för en kolumn i en resultatuppsättning. Beskrivningsinformation returneras som en teckensträng, ett deskriptorberoende värde eller ett heltalsvärde.

Syntax

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

Argument

StatementHandle
[Indata] Instruktionshandtag.

ColumnNumber
[Indata] Numret på posten i IRD som fältvärdet ska hämtas från. Det här argumentet motsvarar kolumnantalet resultatdata, ordnade sekventiellt i ökande kolumnordning, med början 1. Kolumner kan beskrivas i valfri ordning.

Kolumn 0 kan anges i det här argumentet, men alla värden utom SQL_DESC_TYPE och SQL_DESC_OCTET_LENGTH returnerar odefinierade värden.

FieldIdentifier
[Indata] Beskrivningshandtaget. Den här referensen definierar vilket fält i IRD som ska frågas (till exempel SQL_COLUMN_TABLE_NAME).

CharacterAttributePtr
[Utdata] Pekare till en buffert där värdet ska returneras i fältet FieldIdentifier i ColumnNumber rad i IRD, om fältet är en teckensträng. Annars används inte fältet.

Om CharacterAttributePtr är NULL returnerar StringLengthPtr fortfarande det totala antalet byte (exklusive null-avslutningstecknet för teckendata) som är tillgängligt för att returnera i bufferten som pekas på av CharacterAttributePtr.

BufferLength
[Indata] Om FieldIdentifier är ett ODBC-definierat fält och CharacterAttributePtr pekar på en teckensträng eller binär buffert, bör det här argumentet vara längden på *CharacterAttributePtr. Om FieldIdentifier är ett ODBC-definierat fält och *CharacterAttributePtr är ett heltal ignoreras det här fältet. Om *CharacterAttributePtr är en Unicode-sträng (när du anropar SQLColAttributeW) måste argumentet BufferLength vara ett jämnt tal. Om FieldIdentifier är ett drivrutinsdefinierat fält anger programmet fältets natur till Driver Manager genom att ange argumentet BufferLength. BufferLength kan ha följande värden:

• Om CharacterAttributePtr är en pekare till en pekare bör BufferLength ha värdet SQL_IS_POINTER.

• Om CharacterAttributePtr är en pekare till en teckensträng är BufferLength längden på bufferten.

• Om CharacterAttributePtr är en pekare till en binär buffert placerar programmet resultatet av makrot SQL_LEN_BINARY_ATTR(längd) i BufferLength. Detta placerar ett negativt värde i BufferLength.

• Om CharacterAttributePtr är en pekare till en datatyp med fast längd måste BufferLength vara något av följande: SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT eller SQL_IS_USMALLINT.

StringLengthPtr
[Utdata] Pekare till en buffert där det totala antalet byte (exklusive null-avslutningsbyte för teckendata) ska returneras i *CharacterAttributePtr.

Om antalet tillgängliga byte för teckendata är större än eller lika med BufferLengthtrunkeras beskrivningsinformationen i *CharacterAttributePtr till BufferLength- minus längden på ett null-avslutningstecken och är null-avslutad av drivrutinen.

För alla andra typer av data ignoreras värdet för BufferLength och drivrutinen antar att storleken på *CharacterAttributePtr är 32 bitar.

NumericAttributePtr
[Utdata] Pekare till en heltalsbuffert där värdet returneras i fältet FieldIdentifier i ColumnNumber rad i IRD, om fältet är en numerisk beskrivningstyp, till exempel SQL_DESC_COLUMN_LENGTH. Annars används inte fältet. Observera att vissa drivrutiner bara kan skriva den nedre 32-bitars eller 16-bitars bufferten och lämna biten i högre ordning oförändrad. Därför bör program initiera värdet till 0 innan den här funktionen anropas.

Returnerar

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostik

När SQLColAttribute returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde hämtas genom att anropa SQLGetDiagRec med en HandleType- av SQL_HANDLE_STMT och en Hantera av StatementHandle. I följande tabell visas de SQLSTATE-värden som ofta returneras av SQLColAttribute och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

När det anropas efter SQLPrepare och före SQLExecutekan SQLColAttribute returnera valfri SQLSTATE som kan returneras av SQLPrepare eller SQLExecute, beroende på när datakällan utvärderar SQL-instruktionen som är associerad med StatementHandle.

Av prestandaskäl bör ett program inte anropa SQLColAttribute- innan en instruktion körs.

Kommentarer

Information om hur program använder informationen som returneras av SQLColAttributefinns i Metadata för resultatuppsättningar.

SQLColAttribute returnerar information antingen i *NumericAttributePtr eller i *CharacterAttributePtr. Heltalsinformation returneras i *NumericAttributePtr som ett SQLLEN-värde. alla andra informationsformat returneras i *CharacterAttributePtr. När information returneras i *NumericAttributePtrignorerar drivrutinen CharacterAttributePtr, BufferLengthoch StringLengthPtr. När information returneras i *CharacterAttributePtrignorerar drivrutinen NumericAttributePtr.

SQLColAttribute returnerar värden från deskriptorfälten i IRD. Funktionen anropas med ett instruktionshandtag i stället för ett beskrivande handtag. Värdena som returneras av SQLColAttribute för FieldIdentifier värden som anges senare i det här avsnittet kan också hämtas genom att anropa SQLGetDescField med lämplig IRD-referens.

De för närvarande definierade deskriptorfälten, den version av ODBC som de introducerades i och argumenten där information returneras för dem visas senare i det här avsnittet. fler deskriptortyper kan definieras av drivrutiner för att dra nytta av olika datakällor.

En ODBC 3.x drivrutin måste returnera ett värde för vart och ett av deskriptorfälten. Om ett deskriptorfält inte gäller för en drivrutin eller datakälla och om inget annat anges returnerar drivrutinen 0 i *StringLengthPtr eller en tom sträng i *CharacterAttributePtr.

Bakåtkompatibilitet

ODBC 3.x-funktionen SQLColAttribute ersätter den inaktuella ODBC 2.x funktion SQLColAttributes. När du mappar SQLColAttributes till SQLColAttribute (när ett ODBC 2.x-program fungerar med en ODBC 3.x drivrutin) eller mappning SQLColAttribute till SQLColAttributes (när ett ODBC 3.x-program fungerar med en ODBC 2.x drivrutin) skickar Driver Manager antingen värdet för FieldIdentifier igenom, mappar det till ett nytt värde eller returnerar ett fel enligt följande:

• Om #define värdet för ODBC 2.xFieldIdentifier är samma som #define värdet för ODBC 3.xFieldIdentifierskickas värdet i funktionsanropet.

• De #define värdena för ODBC 2.xFieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION och SQL_COLUMN_SCALE skiljer sig från de #define värdena för ODBC 3.xFieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE och SQL_DESC_LENGTH. En ODBC 2.x drivrutin behöver endast stöd för ODBC 2.x värden. En ODBC 3.x-drivrutin måste ha stöd för både "SQL_COLUMN" och "SQL_DESC"-värden för dessa tre FieldIdentifiers. Dessa värden skiljer sig eftersom precision, skala och längd definieras på olika sätt i ODBC 3.x än i ODBC 2.x. Mer information finns i Kolumnstorlek, Decimalsiffror, Överför oktettlängd och Visningsstorlek.

• Om #define värdet för ODBC 2.xFieldIdentifier skiljer sig från #define värdet för ODBC 3.xFieldIdentifier, som inträffar med värdena COUNT, NAME och NULLABLE mappas värdet i funktionsanropet till motsvarande värde. Till exempel mappas SQL_COLUMN_COUNT till SQL_DESC_COUNT och SQL_DESC_COUNT mappas till SQL_COLUMN_COUNT, beroende på mappningens riktning.

• Om FieldIdentifier är ett nytt värde i ODBC 3.x, där det inte fanns något motsvarande värde i ODBC 2.xmappas den inte när en ODBC 3.x-programmet använder det i ett anrop till SQLColAttribute i en ODBC 2.x drivrutin och anropet returnerar SQLSTATE HY091 (ogiltig deskriptorfältidentifierare).

I följande tabell visas de beskrivningstyper som returneras av SQLColAttribute. Typen för NumericAttributePtr värden är SQLLEN *.

SQLColAttribute är ett utökningsbart alternativ till SQLDescribeCol. SQLDescribeCol returnerar en fast uppsättning beskrivande information baserat på ANSI-89 SQL. SQLColAttribute ger åtkomst till den mer omfattande uppsättningen beskrivande information som finns i ANSI SQL-92- och DBMS-leverantörstillägg.

Relaterade funktioner

Exempel

Följande exempelkod frigör inte referenser och anslutningar. Se SQLFreeHandle Function, Sample ODBC Programoch SQLFreeStmt Function för kodexempel för kostnadsfria referenser och instruktioner.

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

Se även

ODBC API-referens
ODBC-huvudfiler
ODBC-exempelprogram