SQLDescribeCol-Funktion
Konformität
Eingeführte Version: ODBC 1.0-Standards Compliance: ISO 92
Zusammenfassung
SQLDescribeCol gibt den Ergebnisdeskriptor – Spaltenname, Typ, Spaltengröße, Dezimalstellen und NULL-Zulässigkeit – für eine Spalte im Resultset zurück. Diese Informationen sind auch in den Feldern der 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.
ColumnNumber
[Eingabe] Spaltenanzahl der Ergebnisdaten, sequenziell in steigender Spaltenreihenfolge sortiert, beginnend bei 1. Das Argument ColumnNumber kann auch auf 0 festgelegt werden, um die Lesezeichenspalte zu beschreiben.
ColumnName
[Ausgabe] Zeiger auf einen Puffer mit NULL-Beendigung, in dem der Spaltenname zurückgegeben werden soll. Dieser Wert wird aus dem feld SQL_DESC_NAME der IRD gelesen. Wenn die Spalte unbenannt ist oder der Spaltenname nicht bestimmt werden kann, gibt der Treiber eine leere Zeichenfolge zurück.
Wenn ColumnName NULL ist, gibt NameLengthPtr weiterhin die Gesamtanzahl der Zeichen (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den ColumnName verweist.
BufferLength
[Eingabe] Länge des *ColumnName-Puffers in Zeichen.
NameLengthPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Gesamtzahl der Zeichen (mit Ausnahme der NULL-Beendigung) zurückgegeben werden soll, die in *ColumnName zurückgegeben werden können. Wenn die Anzahl der zurückzugebenden Zeichen größer oder gleich BufferLength ist, wird der Spaltenname in *ColumnName in BufferLength abgeschnitten, abzüglich der Länge eines NULL-Terminierungszeichens.
DataTypePtr
[Ausgabe] Zeiger auf einen Puffer, in dem der SQL-Datentyp der Spalte zurückgegeben werden soll. Dieser Wert wird aus dem feld SQL_DESC_CONCISE_TYPE der IRD gelesen. Dies ist einer der Werte in SQL-Datentypen 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 wird in *DataTypePtr für Datums-, Uhrzeit- oder Zeitstempeldaten zurückgegeben; in ODBC 2. x, SQL_DATE, SQL_TIME oder SQL_TIMESTAMP wird zurückgegeben. Der Treiber-Manager führt die erforderlichen Zuordnungen aus, wenn odbc 2. Die x-Anwendung arbeitet mit odbc 3. x-Treiber oder wenn odbc 3. Die x-Anwendung arbeitet mit odbc 2. x-Treiber .
Wenn ColumnNumber gleich 0 ist (für eine Lesezeichenspalte), wird SQL_BINARY in *DataTypePtr für Lesezeichen variabler Länge zurückgegeben. (SQL_INTEGER wird zurückgegeben, wenn Lesezeichen von odbc 3 verwendet werden. x-Anwendung , die mit odbc 2 arbeitet. x-Treiber oder von ODBC 2. x-Anwendung , die mit odbc 3 arbeitet. x-Treiber .)
Weitere Informationen zu diesen Datentypen finden Sie unter SQL-Datentypen in Anhang D: Datentypen. Informationen zu treiberspezifischen SQL-Datentypen finden Sie in der Treiberdokumentation.
ColumnSizePtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Größe (in Zeichen) der Spalte in der Datenquelle zurückgegeben werden soll. Wenn die Spaltengröße nicht bestimmt werden kann, gibt der Treiber 0 zurück. Weitere Informationen zur Spaltengröße finden Sie unter Spaltengröße, Dezimalstellen, Übertragungs oktettlänge und Anzeigegröße in Anhang D: Datentypen.
DecimalDigitsPtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Anzahl der Dezimalstellen der Spalte in der Datenquelle zurückgegeben werden soll. Wenn die Anzahl der Dezimalstellen nicht bestimmt werden kann oder nicht zutreffend ist, gibt der Treiber 0 zurück. Weitere Informationen zu Dezimalstellen finden Sie unter Spaltengröße, Dezimalstellen, Übertragungs oktettlänge und Anzeigegröße in Anhang D: Datentypen.
NullablePtr
[Ausgabe] Zeiger auf einen Puffer, in dem ein Wert zurückgegeben werden soll, der angibt, ob die Spalte NULL-Werte zulässt. Dieser Wert wird aus dem feld SQL_DESC_NULLABLE der IRD gelesen. Der Wert ist einer der folgenden:
SQL_NO_NULLS: Die Spalte lässt keine NULL-Werte zu.
SQL_NULLABLE: Die Spalte lässt NULL-Werte zu.
SQL_NULLABLE_UNKNOWN: Der Treiber kann nicht ermitteln, ob die Spalte NULL-Werte zulässt.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLDescribeCol entweder 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 häufig von SQLDescribeCol zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der Rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 01004 | Zeichenfolgendaten, rechts abgeschnitten | Der Puffer *ColumnName war nicht groß genug, um den gesamten Spaltennamen zurückzugeben, sodass der Spaltenname abgeschnitten wurde. Die Länge des unwahren Spaltennamens wird in *NameLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 07005 | Vorbereitete Anweisung, keine Cursorspezifikation | Die Anweisung, die dem StatementHandle zugeordnet ist, hat kein Resultset zurückgegeben. Es gab keine Spalten zu beschreiben. |
| 07009 | Ungültiger Deskriptorindex | (DM) Der für das Argument ColumnNumber angegebene Wert war gleich 0, und die Option SQL_ATTR_USE_BOOKMARKS-Anweisung wurde SQL_UB_OFF. Der für das Argument ColumnNumber angegebene Wert war größer als die Anzahl der Spalten im Resultset. |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden wurde, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den keine implementierungsspezifische SQLSTATE definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist. |
| HY008 | Vorgang abgebrochen | Die asynchrone Verarbeitung wurde für statementHandle aktiviert. Die Funktion wurde aufgerufen, und vor Abschluss der Ausführung wurde SQLCancel oder SQLCancelHandle für statementHandle aufgerufen. Anschließend wurde die Funktion für die AnweisungHandle erneut aufgerufen. Die Funktion wurde aufgerufen, und bevor die Ausführung abgeschlossen wurde, wurde SQLCancel oder SQLCancelHandle für die StatementHandle aus einem anderen Thread in einer Multithreadanwendung aufgerufen. |
| HY010 | Funktionssequenzfehler | (DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als SQLDescribeCol aufgerufen wurde. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für statementHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. (DM) Eine asynchron ausgeführte Funktion (nicht diese) wurde für das StatementHandle aufgerufen und wurde noch ausgeführt, als diese Funktion aufgerufen wurde. (DM) Die Funktion wurde aufgerufen, bevor SQLPrepare, SQLExecute oder eine Katalogfunktion für das Anweisungshandle aufgerufen wurde. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für die StatementHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführung gesendet wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY090 | Ungültige Zeichenfolgen- oder Pufferlänge | (DM) Der für das Argument BufferLength angegebene Wert war kleiner als 0. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Der Treiber unterstützt diese Funktion nicht. | (DM) Der der StatementHandle zugeordnete Treiber unterstützt die Funktion nicht. |
| IM017 | Die Abfrage ist im asynchronen Benachrichtigungsmodus deaktiviert. | Wenn das Benachrichtigungsmodell verwendet wird, ist die Abfrage deaktiviert. |
| IM018 | SQLCompleteAsync wurde nicht aufgerufen, um den vorherigen asynchronen Vorgang für dieses Handle abzuschließen. | Wenn der vorherige Funktionsaufruf für das Handle SQL_STILL_EXECUTING zurückgibt und der Benachrichtigungsmodus aktiviert ist, muss SQLCompleteAsync für das Handle aufgerufen werden, um die Nachverarbeitung durchzuführen und den Vorgang abzuschließen. |
SQLDescribeCol kann jeden SQLSTATE zurückgeben, der von SQLPrepare oder SQLExecute zurückgegeben werden kann, wenn nach SQLPrepare und vor SQLExecute aufgerufen wird, je nachdem, wann die Datenquelle die SQL-Anweisung auswertet, die dem Anweisungshandle zugeordnet ist.
Aus Leistungsgründen sollte eine Anwendung SQLDescribeCol nicht aufrufen, bevor eine Anweisung ausgeführt wird.
Kommentare
Eine Anwendung ruft SQLDescribeCol in der Regel nach einem Aufruf von SQLPrepare und vor oder nach dem zugeordneten Aufruf von SQLExecute auf. Eine Anwendung kann SQLDescribeCol auch nach einem Aufruf von SQLExecDirect aufrufen. Weitere Informationen finden Sie unter Resultsetmetadaten.
SQLDescribeCol ruft den Von einer SELECT-Anweisung generierten Spaltennamen, -Typ und -Länge ab. Wenn es sich bei der Spalte um einen Ausdruck handelt, ist *ColumnName entweder eine leere Zeichenfolge oder ein vom Treiber definierter Name.
Hinweis
ODBC unterstützt SQL_NULLABLE_UNKNOWN als Erweiterung, auch wenn die Aufrufebenenschnittstellenspezifikation open Group und SQL Access Group die Option für SQLDescribeCol nicht angibt.
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Binden eines Puffers an eine Spalte in einem Resultset | SQLBindCol |
| Abbrechen der Anweisungsverarbeitung | SQLCancel |
| Zurückgeben von Informationen zu einer Spalte in einem Resultset | SQLColAttribute |
| Abrufen mehrerer Datenzeilen | SQLFetch |
| Zurückgeben der Anzahl von Resultsetspalten | SQLNumResultCols |
| Vorbereiten einer Anweisung für die Ausführung | SQLPrepare |