SQLDescribeCol-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Summary
SQLDescribeCol liefert für eine Spalte im Ergebnisset den Ergebnisbeschreiber – Spaltenname, Typ, Spaltengröße, Dezimalziffern und Nullfähigkeit – zurück. Diese Informationen sind auch in den Bereichen des IRD verfügbar.

Syntax

  
SQLRETURN SQLDescribeCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLCHAR *      ColumnName,  
      SQLSMALLINT    BufferLength,  
      SQLSMALLINT *  NameLengthPtr,  
      SQLSMALLINT *  DataTypePtr,  
      SQLULEN *      ColumnSizePtr,  
      SQLSMALLINT *  DecimalDigitsPtr,  
      SQLSMALLINT *  NullablePtr);  

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Spaltennummer
[Eingabe] Spaltenzahl der Ergebnisdaten, sequentiell in steigender Spaltenreihenfolge geordnet, beginnend bei 1. Das Kolumnennummer-Argument kann ebenfalls auf 0 gesetzt werden, um die Lesezeichenspalte zu beschreiben.

ColumnName
[Ausgabe] Zeiger auf einen null-terminierten Puffer, um den Spaltennamen zurückzugeben. Dieser Wert wird aus dem SQL_DESC_NAME Feld der IRD abgelesen. Wenn die Spalte unbenannt ist oder der Spaltenname nicht bestimmt werden kann, gibt der Treiber eine leere Zeichenkette zurück.

Wenn ColumnName NULL ist, gibt NameLengthPtr weiterhin die Gesamtzahl der Zeichen zurück (ohne das Null-Terminationszeichen für Zeichendaten), die im von ColumnName gezeigten Puffer zurückgegeben werden können.

BufferLength
[Eingabe] Länge des *ColumnName-Puffers , in Zeichen.

NameLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (ohne die Nullbeendigung) zurückgegeben werden kann, die in *ColumnName. Wenn die Anzahl der zurückgegebenen Zeichen größer als oder gleich BufferLength ist, wird der Spaltenname in *ColumnName auf BufferLength minus die Länge eines Null-Endzeichens gekürzt.

DataTypePtr
[Ausgabe] Zeiger auf einen Puffer, in dem der SQL-Datentyp der Spalte zurückgegeben werden kann. Dieser Wert wird aus dem SQL_DESC_CONCISE_TYPE Feld der IRD abgelesen. Dies wird einer der Werte in SQL Data Types sein oder ein treiberspezifischer SQL-Datentyp. Wenn der Datentyp nicht bestimmt werden kann, gibt der Treiber SQL_UNKNOWN_TYPE zurück.

In ODBC 3. x, SQL_TYPE_DATE, SQL_TYPE_TIME oder SQL_TYPE_TIMESTAMP werden in *DataTypePtr für Datum-, Uhrzeit- oder Zeitstempeldaten zurückgegeben; in ODBC 2. x, SQL_DATE, SQL_TIME oder SQL_TIMESTAMP zurückgegeben wird. Der Treiber-Manager führt die erforderlichen Zuordnungen aus, wenn ein ODBC 2 verwendet wird.x-Anwendung arbeitet mit einem ODBC 3.x-Treiber oder ein ODBC 3-Treiber.x-Anwendung arbeitet mit einem ODBC 2.x-Treiber .

Wenn ColumnNumber gleich 0 (für eine Textmarkespalte) ist, wird SQL_BINARY in *DataTypePtr für Textmarken mit variabler Länge zurückgegeben. (SQL_INTEGER wird zurückgegeben, wenn Lesezeichen von einem ODBC 3 verwendet werden.x-Anwendung , die mit einem ODBC 2 arbeitet.x-Treiber oder odbc 2.x-Anwendung , die mit einem ODBC 3 arbeitet.x-Treiber .)

Weitere Informationen zu diesen Datentypen finden Sie unter SQL Data Types im Anhang D: Data Types. Informationen zu treiberspezifischen SQL-Datentypen finden Sie in der Dokumentation des Treibers.

ColumnSizePtr
[Ausgabe] Zeiger auf einen Puffer, um die Größe (in Zeichen) der Spalte in der Datenquelle zurückzugeben. Wenn die Spaltengröße nicht bestimmt werden kann, gibt der Treiber 0 zurück. Weitere Informationen zur Spaltengröße finden Sie unter Spaltengröße, Dezimalziffern, Übertragen der Oktettlänge und Anzeigegröße in Anhang D: Datentypen.

DecimalDigitsPtr
[Ausgabe] Zeiger auf einen Puffer, um die Anzahl der Dezimalziffern der Spalte in der Datenquelle zurückzugeben. Wenn die Anzahl der Dezimalziffern nicht bestimmt werden kann oder nicht anwendbar ist, gibt der Fahrer 0 zurück. Weitere Informationen zu Dezimalziffern finden Sie unter Spaltengröße, Dezimalziffern, Übertragungslänge des Oktetts und Anzeigegröße in Anhang D: Datentypen.

NullablePtr
[Ausgabe] Zeiger auf einen Puffer, in dem ein Wert zurückgegeben wird, der angibt, ob die Spalte NULL-Werte zulässt. Dieser Wert wird aus dem SQL_DESC_NULLABLE Feld des IRD abgelesen. Mögliche Werte:

SQL_NO_NULLS: Die Spalte erlaubt keine NULL-Werte.

SQL_NULLABLE: Die Spalte erlaubt NULL-Werte.

SQL_NULLABLE_UNKNOWN: Der Treiber kann nicht bestimmen, ob die Spalte NULL-Werte zulässt.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLDescribeCol entweder 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 häufig von SQLDescribeCol 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.

SQLDescribeCol kann jeden SQLSTATE zurückgeben, der von SQLPrepare oder SQLExecute zurückgegeben werden kann, wenn er nach SQLPrepare und vor SQLExecute aufgerufen wird, abhängig davon, wann die Datenquelle die mit der Anweisung zugeordnete SQL-Anweisung auswertet.

Aus Leistungsgründen sollte eine Anwendung SQLDescribeCol nicht aufrufen, bevor eine Anweisung ausgeführt wird.

Kommentare

Eine Anwendung ruft SQLDescribeCol typischerweise nach einem Aufruf zu SQLPrepare und vor oder nach dem zugehörigen Aufruf zu SQLExecute auf. Eine Anwendung kann nach einem Aufruf von SQLExecDirect auch SQLDescribeCol aufrufen. Weitere Informationen finden Sie unter "Resultset Metadata".

SQLDescribeCol ruft den Spaltennamen, den Typ und die Länge ab, die durch eine SELECT-Anweisung erzeugt werden. Ist die Spalte ein Ausdruck, ist *ColumnName entweder eine leere Zeichenkette oder ein treiberdefinierter Name.

Verwandte Funktionen

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien