Fonction SQLColAttribute

Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92

Résumé
SQLColAttribute retourne des informations de descripteur pour une colonne dans un jeu de résultats. Les informations de descripteur sont retournées sous la forme d’une chaîne de caractères, d’une valeur dépendante du descripteur ou d’une valeur entière.

Syntaxe

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

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ColumnNumber
[Entrée] Numéro de l’enregistrement dans l’IRD à partir duquel la valeur du champ doit être récupérée. Cet argument correspond au nombre de colonnes de données de résultat, ordonné séquentiellement dans l’ordre croissant des colonnes, en commençant à 1. Les colonnes peuvent être décrites dans n’importe quel ordre.

La colonne 0 peut être spécifiée dans cet argument, mais toutes les valeurs, sauf SQL_DESC_TYPE et SQL_DESC_OCTET_LENGTH retournent des valeurs non définies.

FieldIdentifier
[Entrée] Handle de descripteur. Ce handle définit le champ dans l’IRD à interroger (par exemple, SQL_COLUMN_TABLE_NAME).

CharacterAttributePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur dans le champ FieldIdentifier de la ligne ColumnNumber de l’IRD, si le champ est une chaîne de caractères. Sinon, le champ n’est pas utilisé.

Si CharacterAttributePtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exception du caractère d’arrêt null pour les données de caractères) disponible dans la mémoire tampon pointée par CharacterAttributePtr.

BufferLength
[Entrée] Si FieldIdentifier est un champ défini par ODBC et CharacterAttributePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *CharacterAttributePtr. Si FieldIdentifier est un champ défini par ODBC et *CharacterAttributePtr est un entier, ce champ est ignoré. Si le *CharacterAttributePtr est une chaîne Unicode (lors de l’appel de SQLColAttributeW), l’argument BufferLength doit être un nombre pair. Si FieldIdentifier est un champ défini par le pilote, l’application indique la nature du champ sur le Gestionnaire de pilotes en définissant l’argument BufferLength . BufferLength peut avoir les valeurs suivantes :

• Si CharacterAttributePtr est un pointeur vers un pointeur, BufferLength doit avoir la valeur SQL_IS_POINTER.

• Si CharacterAttributePtr est un pointeur vers une chaîne de caractères, bufferLength est la longueur de la mémoire tampon.

• Si CharacterAttributePtr est un pointeur vers une mémoire tampon binaire, l’application place le résultat de la macro SQL_LEN_BINARY_ATTR(length) dans BufferLength. Cela place une valeur négative dans BufferLength.

• Si CharacterAttributePtr est un pointeur vers un type de données de longueur fixe, BufferLength doit être l’un des éléments suivants : SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT ou SQL_IS_USMALLINT.

StringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exception de l’octet de terminaison Null pour les données de caractères) disponible dans *CharacterAttributePtr.

Pour les données de caractères, si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les informations de descripteur dans *CharacterAttributePtr sont tronquées à BufferLength moins la longueur d’un caractère d’arrêt null et sont terminées par null par le pilote.

Pour tous les autres types de données, la valeur de BufferLength est ignorée et le pilote suppose que la taille de *CharacterAttributePtr est de 32 bits.

NumericAttributePtr
[Sortie] Pointeur vers une mémoire tampon entière dans laquelle retourner la valeur dans le champ FieldIdentifier de la ligne ColumnNumber de l’IRD, si le champ est un type de descripteur numérique, tel que SQL_DESC_COLUMN_LENGTH. Sinon, le champ n’est pas utilisé. Notez que certains pilotes peuvent écrire uniquement les bits 32 bits inférieurs ou 16 bits d’une mémoire tampon et laisser le bit de l’ordre supérieur inchangé. Par conséquent, les applications doivent initialiser la valeur sur 0 avant d’appeler cette fonction.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLColAttribute retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_STMT et un handle d’instructionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLColAttribute et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Lorsqu’il est appelé après SQLPrepare et avant SQLExecute, SQLColAttribute peut retourner n’importe quel SQLSTATE qui peut être retourné par SQLPrepare ou SQLExecute, selon le moment où la source de données évalue l’instruction SQL associée à StatementHandle.

Pour des raisons de performances, une application ne doit pas appeler SQLColAttribute avant d’exécuter une instruction.

Commentaires

Pour plus d’informations sur la façon dont les applications utilisent les informations retournées par SQLColAttribute, consultez Métadonnées du jeu de résultats.

SQLColAttribute retourne des informations dans *NumericAttributePtr ou dans *CharacterAttributePtr. Les informations entières sont retournées dans *NumericAttributePtr en tant que valeur SQLLEN ; tous les autres formats d’informations sont retournés dans *CharacterAttributePtr. Lorsque des informations sont retournées dans *NumericAttributePtr, le pilote ignore CharacterAttributePtr, BufferLength et StringLengthPtr. Lorsque des informations sont retournées dans *CharacterAttributePtr, le pilote ignore NumericAttributePtr.

SQLColAttribute retourne des valeurs des champs de descripteur de l’IRD. La fonction est appelée avec un handle d’instruction plutôt qu’un descripteur. Les valeurs retournées par SQLColAttribute pour les valeurs FieldIdentifier répertoriées plus loin dans cette section peuvent également être récupérées en appelant SQLGetDescField avec le handle IRD approprié.

Les champs de descripteur actuellement définis, la version d’ODBC dans laquelle ils ont été introduits et les arguments dans lesquels les informations sont retournées sont affichés plus loin dans cette section ; D’autres types de descripteur peuvent être définis par les pilotes pour tirer parti de différentes sources de données.

ODBC 3.x driver doit retourner une valeur pour chacun des champs de descripteur. Si un champ descripteur ne s’applique pas à un pilote ou à une source de données et, sauf indication contraire, le pilote retourne 0 dans *StringLengthPtr ou une chaîne vide dans *CharacterAttributePtr.

Compatibilité descendante

ODBC 3.x function SQLColAttribute remplace l’ODBC 2 déconseillé.x function SQLColAttributes. Lors du mappage de SQLColAttributes à SQLColAttribute (lorsqu’un ODBC 2.x application fonctionne avec ODBC 3.x driver) ou mapper SQLColAttribute à SQLColAttributes (lorsqu’un ODBC 3.x application fonctionne avec ODBC 2.x driver), le Gestionnaire de pilotes transmet la valeur de FieldIdentifier par le biais de FieldIdentifier , le mappe à une nouvelle valeur ou retourne une erreur, comme suit :

• Si la valeur #define du odbc 2.x FieldIdentifier est identique à la valeur #define du odbc 3.x FieldIdentifier, la valeur de l’appel de fonction vient d’être transmise.

• Valeurs #define du ODBC 2.x FieldIdentifiers SQL_COLUMN_LENGTH, SQL_COLUMN_PRECISION et SQL_COLUMN_SCALE sont différents des valeurs #define du odbc 3.x FieldIdentifiers SQL_DESC_PRECISION, SQL_DESC_SCALE et SQL_DESC_LENGTH. ODBC 2.Le pilote x n’a besoin que de prendre en charge ODBC 2.valeurs x . ODBC 3.Le pilote x doit prendre en charge les valeurs « SQL_COLUMN » et « SQL_DESC » pour ces trois FieldIdentifiers. Ces valeurs sont différentes, car la précision, l’échelle et la longueur sont définies différemment dans ODBC 3.x qu’ils étaient dans ODBC 2.x. Pour plus d’informations, consultez La taille des colonnes, les chiffres décimaux, la longueur des octets de transfert et la taille d’affichage.

• Si la valeur #define du odbc 2.x FieldIdentifier est différent de la valeur #define du odbc 3.x FieldIdentifier, tel qu’il se produit avec les valeurs COUNT, NAME et NULLABLE, la valeur de l’appel de fonction est mappée à la valeur correspondante. Par exemple, SQL_COLUMN_COUNT est mappé à SQL_DESC_COUNT et SQL_DESC_COUNT est mappé à SQL_COLUMN_COUNT, selon la direction du mappage.

• Si FieldIdentifier est une nouvelle valeur dans ODBC 3.x, pour lequel il n’y avait aucune valeur correspondante dans ODBC 2.x, il ne sera pas mappé lorsqu’un ODBC 3.x application l’utilise dans un appel à SQLColAttribute dans un ODBC 2.x driver, et l’appel retourne SQLSTATE HY091 (identificateur de champ de descripteur non valide).

Le tableau suivant répertorie les types de descripteur retournés par SQLColAttribute. Le type des valeurs NumericAttributePtr est SQLLEN *.

SQLColAttribute est une alternative extensible à SQLDescribeCol. SQLDescribeCol retourne un ensemble fixe d’informations de descripteur basées sur ANSI-89 SQL. SQLColAttribute permet d’accéder à l’ensemble plus complet d’informations de descripteur disponibles dans les extensions de fournisseur ANSI SQL-92 et SGBD.

Fonctions connexes

Exemple

L’exemple de code suivant ne libère pas de handles et de connexions. Consultez la fonction SQLFreeHandle, l’exemple de programme ODBC et la fonction SQLFreeStmt pour obtenir des exemples de code pour libérer des handles et des instructions.

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

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Exemple de programme ODBC