SQLColumns-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: Open Group

Zusammenfassung
SQLColumns gibt die Liste der Spaltennamen in angegebenen Tabellen zurück. Der Treiber gibt diese Informationen als Resultset für das angegebene StatementHandle zurück.

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, z. B. wenn der Treiber Daten aus verschiedenen Datenbankdatenbanken abruft, gibt eine leere Zeichenfolge ("") die Tabellen an, die keine Kataloge enthalten. CatalogName kann kein Zeichenfolgensuchmuster enthalten.

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

Schemaname
[Eingabe] Zeichenfolgensuchmuster für Schemanamen. Wenn ein Treiber Schemas für einige Tabellen, aber nicht für andere unterstützt, z. B. wenn der Treiber Daten aus verschiedenen Datenbankdatenbanken abruft, gibt eine leere Zeichenfolge ("") die Tabellen ohne Schemas an.

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

TableName
[Eingabe] Zeichenfolgensuchmuster für Tabellennamen.

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

ColumnName
[Eingabe] Zeichenfolgensuchmuster für Spaltennamen.

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

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnose

Wenn SQLColumns SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLColumns zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Diese Funktion wird in der Regel vor der Anweisungsausführung verwendet, um Informationen zu Spalten für eine Tabelle oder Tabellen aus dem Katalog der Datenquelle abzurufen. SQLColumns können verwendet werden, um Daten für alle Typen von Elementen abzurufen, die von SQLTables zurückgegeben werden. Zusätzlich zu Basistabellen kann dies Sichten, Synonyme, Systemtabellen usw. enthalten (ist jedoch nicht beschränkt auf). Im Gegensatz dazu beschreiben die Funktionen SQLColAttribute und SQLDescribeCol die Spalten in einem Resultset, und die Funktion SQLNumResultCols gibt die Anzahl der Spalten in einem Resultset zurück. Weitere Informationen finden Sie unter Verwendung von Katalogdaten.

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

Die Längen der VARCHAR-Spalten werden in der Tabelle nicht angezeigt. die tatsächliche Länge hängt von der Datenquelle ab. Um die tatsächliche Länge 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 wirken sich nicht auf die Abwärtskompatibilität aus, da Anwendungen anhand der Spaltennummer gebunden werden.

Die folgenden Spalten wurden dem Resultset hinzugefügt, das von SQLColumns für ODBC 3 zurückgegeben wird. 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 wird, 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 das von SQLColumns zurückgegebene Resultset. Es ruft SQLColumns auf, um ein Resultset zurückzugeben, das jede Spalte in der EMPLOYEE-Tabelle beschreibt. Anschließend wird SQLBindCol aufgerufen, um die Spalten im Resultset 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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien