SQLColumns-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standardsefterlevnad: Open Group

Summary
SQLColumns returnerar listan över kolumnnamn i angivna tabeller. Drivrutinen returnerar denna information som ett resultat som satts på den angivna StatementHandle.

Syntax

  
SQLRETURN SQLColumns(  
     SQLHSTMT       StatementHandle,  
     SQLCHAR *      CatalogName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      SchemaName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      TableName,  
     SQLSMALLINT    NameLength3,  
     SQLCHAR *      ColumnName,  
     SQLSMALLINT    NameLength4);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

CatalogName
[Indata] Katalognamn. Om en drivrutin stödjer kataloger för vissa tabeller men inte för andra, till exempel när drivrutinen hämtar data från olika databaser, indikerar en tom sträng ("") de tabeller som inte har kataloger. CatalogName kan inte innehålla ett strängsökningsmönster.

NameLength1
[Input] Längd i tecken i *CatalogName.

Schema-namn
[Input] Strängsökningsmönster för schemanamn. Om en drivrutin stöder scheman för vissa tabeller men inte för andra, till exempel när drivrutinen hämtar data från olika databaser, indikerar en tom sträng ("") de tabeller som inte har scheman.

NameLength2
[Input] Längd i tecken i *SchemaName.

TableName
[Input] Strängsökningsmönster för tabellnamn.

NameLength3
[Input] Längd i tecken av *TableName.

KolumnNamn
[Indata] Strängsökningsmönster för kolumnnamn.

NameLength4
[Indata] Längd i tecken i *ColumnName.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR eller SQL_INVALID_HANDLE.

Diagnostics

När SQLColumns returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_STMT och ett Handle av StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLColumns och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges.

Comments

Denna funktion används vanligtvis före satsexekvering för att hämta information om kolumner för en tabell eller tabeller från datakällans katalog. SQLColumns kan användas för att hämta data för alla typer av objekt som returneras av SQLTables. Utöver bastabeller kan detta inkludera (men är inte begränsat till) vyer, synonymer, systemtabeller och så vidare. Till skillnad från detta beskriver funktionerna SQLColAttribute och SQLDescribeCol kolumnerna i en resultatuppsättning och funktionen SQLNumResultCols returnerar antalet kolumner i en resultatuppsättning. Mer information finns i Användning av katalogdata.

SQLColumns returnerar resultaten som en standardmängd resultat, ordnade efter TABLE_CAT, TABLE_SCHEM, TABLE_NAME och ORDINAL_POSITION.

Längderna på VARCHAR-kolonner visas inte i tabellen; de faktiska längderna beror på datakällan. För att bestämma de faktiska längderna på kolumnerna TABLE_CAT, TABLE_SCHEM, TABLE_NAME och COLUMN_NAME kan ett program anropa SQLGetInfo med alternativen SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN och SQL_MAX_COLUMN_NAME_LEN.

Följande kolumner har bytt namn till ODBC 3. x. Kolumnnamnsändringarna påverkar inte bakåtkompatibilitet eftersom applikationer binds efter kolumnnummer.

Följande kolumner har lagts till i resultatmängden som returnerats av SQLColumns för ODBC 3. x:

I följande tabell visas kolumnerna i resultatuppsättningen. Ytterligare kolumner bortom kolumn 18 (IS_NULLABLE) kan definieras av drivrutinen. Ett program bör få åtkomst till drivrutinsspecifika kolumner genom att räkna ned från slutet av resultatuppsättningen i stället för att ange en explicit ordningstalsposition. Mer information finns i Data som returneras av katalogfunktioner.

Kodexempel

I följande exempel deklarerar en applikation buffertar för resultatmängden som returneras av SQLColumns. Den anropar SQLColumns för att returnera en resultatmängd som beskriver varje kolumn i EMPLOYEE-tabellen. Den anropar sedan SQLBindCol för att binda kolumnerna i resultatuppsättningen till buffertarna. Slutligen hämtar applikationen varje datarad med SQLFetch och bearbetar den.

// SQLColumns_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqlext.h>  
#define STR_LEN 128 + 1  
#define REM_LEN 254 + 1  
  
// Declare buffers for result set data  
SQLCHAR szSchema[STR_LEN];  
SQLCHAR szCatalog[STR_LEN];  
SQLCHAR szColumnName[STR_LEN];  
SQLCHAR szTableName[STR_LEN];  
SQLCHAR szTypeName[STR_LEN];  
SQLCHAR szRemarks[REM_LEN];  
SQLCHAR szColumnDefault[STR_LEN];  
SQLCHAR szIsNullable[STR_LEN];  
  
SQLINTEGER ColumnSize;  
SQLINTEGER BufferLength;  
SQLINTEGER CharOctetLength;  
SQLINTEGER OrdinalPosition;  
  
SQLSMALLINT DataType;  
SQLSMALLINT DecimalDigits;  
SQLSMALLINT NumPrecRadix;  
SQLSMALLINT Nullable;  
SQLSMALLINT SQLDataType;  
SQLSMALLINT DatetimeSubtypeCode;  
  
SQLHSTMT hstmt = NULL;  
  
// Declare buffers for bytes available to return  
SQLINTEGER cbCatalog;  
SQLINTEGER cbSchema;  
SQLINTEGER cbTableName;  
SQLINTEGER cbColumnName;  
SQLINTEGER cbDataType;  
SQLINTEGER cbTypeName;  
SQLINTEGER cbColumnSize;  
SQLLEN cbBufferLength;  
SQLINTEGER cbDecimalDigits;  
SQLINTEGER cbNumPrecRadix;  
SQLINTEGER cbNullable;  
SQLINTEGER cbRemarks;  
SQLINTEGER cbColumnDefault;  
SQLINTEGER cbSQLDataType;  
SQLINTEGER cbDatetimeSubtypeCode;  
SQLINTEGER cbCharOctetLength;  
SQLINTEGER cbOrdinalPosition;  
SQLINTEGER cbIsNullable;  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
   retcode = SQLColumns(hstmt, NULL, 0, NULL, 0, (SQLCHAR*)"CUSTOMERS", SQL_NTS, NULL, 0);  
  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      // Bind columns in result set to buffers  
      SQLBindCol(hstmt, 1, SQL_C_CHAR, szCatalog, STR_LEN,&cbCatalog);  
      SQLBindCol(hstmt, 2, SQL_C_CHAR, szSchema, STR_LEN, &cbSchema);  
      SQLBindCol(hstmt, 3, SQL_C_CHAR, szTableName, STR_LEN,&cbTableName);  
      SQLBindCol(hstmt, 4, SQL_C_CHAR, szColumnName, STR_LEN, &cbColumnName);  
      SQLBindCol(hstmt, 5, SQL_C_SSHORT, &DataType, 0, &cbDataType);  
      SQLBindCol(hstmt, 6, SQL_C_CHAR, szTypeName, STR_LEN, &cbTypeName);  
      SQLBindCol(hstmt, 7, SQL_C_SLONG, &ColumnSize, 0, &cbColumnSize);  
      SQLBindCol(hstmt, 8, SQL_C_SLONG, &BufferLength, 0, &cbBufferLength);  
      SQLBindCol(hstmt, 9, SQL_C_SSHORT, &DecimalDigits, 0, &cbDecimalDigits);  
      SQLBindCol(hstmt, 10, SQL_C_SSHORT, &NumPrecRadix, 0, &cbNumPrecRadix);  
      SQLBindCol(hstmt, 11, SQL_C_SSHORT, &Nullable, 0, &cbNullable);  
      SQLBindCol(hstmt, 12, SQL_C_CHAR, szRemarks, REM_LEN, &cbRemarks);  
      SQLBindCol(hstmt, 13, SQL_C_CHAR, szColumnDefault, STR_LEN, &cbColumnDefault);  
      SQLBindCol(hstmt, 14, SQL_C_SSHORT, &SQLDataType, 0, &cbSQLDataType);  
      SQLBindCol(hstmt, 15, SQL_C_SSHORT, &DatetimeSubtypeCode, 0, &cbDatetimeSubtypeCode);  
      SQLBindCol(hstmt, 16, SQL_C_SLONG, &CharOctetLength, 0, &cbCharOctetLength);  
      SQLBindCol(hstmt, 17, SQL_C_SLONG, &OrdinalPosition, 0, &cbOrdinalPosition);  
      SQLBindCol(hstmt, 18, SQL_C_CHAR, szIsNullable, STR_LEN, &cbIsNullable);  
  
      while (SQL_SUCCESS == retcode) {  
         retcode = SQLFetch(hstmt);  
         /*  
         if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
            0;   // show_error();  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
            0;   // Process fetched data  
         else  
            break;  
        */  
      }  
   }  
}  

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler