SQLColumns-Funktion

Konformität
Eingeführte Version: ODBC 1.0 Standards Compliance: Open Group

Summary
SQLColumns liefert die Liste der Spaltennamen in den angegebenen Tabellen. Der Treiber gibt diese Information als Ergebnis zurück, das auf dem angegebenen StatementHandle gesetzt ist.

Syntax

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

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Catalogname
[Eingabe] Katalogname. Wenn ein Treiber Kataloge für einige Tabellen, aber nicht für andere unterstützt, etwa wenn der Treiber Daten aus verschiedenen DBMS abruft, zeigt eine leere Zeichenkette ("") jene Tabellen an, die keine Kataloge besitzen. CatalogName kann kein String-Suchmuster enthalten.

NameLength1
[Eingabe] Länge in den Zeichen von *CatalogName.

SchemaName
[Eingabe] Zeichenkettensuchmuster für Schemanamen. Wenn ein Treiber Schemata für einige Tabellen, aber für andere nicht unterstützt, etwa wenn der Treiber Daten aus verschiedenen DBMS abruft, zeigt eine leere Zeichenkette ("") jene Tabellen an, die keine Schemata enthalten.

NameLength2
[Eingabe] Länge in den Zeichen von *SchemaName.

Tabellenname
[Eingabe] String-Suchmuster für Tabellennamen.

NameLength3
[Eingabe] Länge in den Zeichen von *TableName.

ColumnName
[Eingabe] String-Suchmuster für Spaltennamen.

NameLength4
[Eingabe] Länge in den Zeichen von *ColumnName.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLColumns SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle von StatementHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die typischerweise von SQLColumns zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Diese Funktion wird typischerweise vor der Ausführung von Anweisungen verwendet, um Informationen über Spalten für eine Tabelle oder Tabellen aus dem Katalog der Datenquelle abzurufen. SQLColumns können verwendet werden, um Daten für alle Arten von von SQLTables zurückgegebenen Einträgen abzurufen. Neben Basistabellen kann dies (aber nicht beschränkt auf) Ansichten, Synonyme, Systemtabellen und Ähnliches umfassen. Im Gegensatz dazu beschreiben die Funktionen SQLColAttribute und SQLDescribeCol die Spalten in einer Ergebnismenge, und die Funktion SQLNumResultCols liefert die Anzahl der Spalten in einer Ergebnismenge zurück. Weitere Informationen finden Sie unter Verwendung von Katalogdaten.

SQLColumns liefert die Ergebnisse als Standardergebnismenge zurück, geordnet nach TABLE_CAT, TABLE_SCHEM, TABLE_NAME und ORDINAL_POSITION.

Die Längen der VARCHAR-Säulen sind in der Tabelle nicht angegeben; Die tatsächlichen Längen hängen von der Datenquelle ab. Um die tatsächlichen Längen der Spalten TABLE_CAT, TABLE_SCHEM, TABLE_NAME und COLUMN_NAME zu bestimmen, kann eine Anwendung SQLGetInfo mit den Optionen SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_TABLE_NAME_LEN und SQL_MAX_COLUMN_NAME_LEN aufrufen.

Die folgenden Spalten wurden für ODBC 3 umbenannt. x. Die Änderungen des Spaltennamens beeinflussen die Abwärtskompatibilität nicht, da Anwendungen nach Spaltennummer binden.

Die folgenden Spalten wurden dem von SQLColumns für ODBC 3 zurückgegebenen Ergebnisset hinzugefügt. x:

In der folgenden Tabelle sind die Spalten im Resultset aufgeführt. Zusätzliche Spalten über Spalte 18 (IS_NULLABLE) hinaus können vom Treiber definiert werden. Eine Anwendung sollte Zugriff auf treiberspezifische Spalten erhalten, indem sie vom Ende des Resultsets heruntergezählt werden, anstatt eine explizite Ordnungsposition anzugeben. Weitere Informationen finden Sie unter "Von Katalogfunktionen zurückgegebene Daten".

Codebeispiel

Im folgenden Beispiel deklariert eine Anwendung Puffer für die von SQLColumns zurückgegebene Ergebnismenge. Es ruft SQLColumns auf, um eine Ergebnismenge zurückzugeben, die jede Spalte in der EMPLOYEE-Tabelle beschreibt. Anschließend ruft es SQLBindCol auf, um die Spalten im Ergebnisset an die Puffer zu binden. Schließlich ruft die Anwendung jede Datenzeile mit SQLFetch ab und verarbeitet sie.

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

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien