SQLGetDescField-Funktion

  • Artikel

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

Zusammenfassung
SQLGetDescField gibt die aktuelle Einstellung oder den aktuellen Wert eines einzelnen Felds eines Deskriptordatensatzes zurück.

Syntax

  
SQLRETURN SQLGetDescField(  
     SQLHDESC        DescriptorHandle,  
     SQLSMALLINT     RecNumber,  
     SQLSMALLINT     FieldIdentifier,  
     SQLPOINTER      ValuePtr,  
     SQLINTEGER      BufferLength,  
     SQLINTEGER *    StringLengthPtr);

Argumente

DescriptorHandle
[Eingabe] Deskriptorhandle.

RecNumber
[Eingabe] Gibt den Deskriptordatensatz an, aus dem die Anwendung Informationen sucht. Deskriptordatensätze werden von 0 nummeriert, wobei datensatznummer 0 der Lesezeichendatensatz ist. Wenn das Argument FieldIdentifier ein Headerfeld angibt, wird RecNumber ignoriert. Wenn RecNumber kleiner oder gleich SQL_DESC_COUNT die Zeile jedoch keine Daten für eine Spalte oder einen Parameter enthält, gibt ein Aufruf von SQLGetDescField die Standardwerte der Felder zurück. (Weitere Informationen finden Sie unter Initialisierung von Deskriptorfeldern in SQLSetDescField.)

FieldIdentifier
[Eingabe] Gibt das Feld des Deskriptors an, dessen Wert zurückgegeben werden soll. Weitere Informationen finden Sie im Abschnitt "FieldIdentifier Argument" in SQLSetDescField.

ValuePtr
[Ausgabe] Zeiger auf einen Puffer, in dem die Deskriptorinformationen zurückgegeben werden sollen. Der Datentyp hängt vom Wert von FieldIdentifier ab.

Wenn ValuePtr den Ganzzahltyp aufweist, sollten Anwendungen einen Puffer von SQLULEN verwenden und den Wert auf 0 initialisieren, bevor sie diese Funktion aufrufen, da einige Treiber möglicherweise nur die unteren 32-Bit- oder 16-Bit eines Puffers schreiben und das Bit mit höherer Reihenfolge unverändert lassen.

Wenn ValuePtr NULL ist, gibt StringLengthPtr weiterhin die Gesamtanzahl der Bytes (mit Ausnahme des NULL-Terminierungszeichens für Zeichendaten) zurück, die im Puffer zurückgegeben werden können, auf den ValuePtr verweist.

BufferLength
[Eingabe] Wenn FieldIdentifier ein von ODBC definiertes Feld ist und ValuePtr auf eine Zeichenfolge oder einen binären Puffer zeigt, sollte dieses Argument die Länge von *ValuePtr aufweisen. Wenn FieldIdentifier ein von ODBC definiertes Feld und *ValuePtr eine ganze Zahl ist, wird BufferLength ignoriert. Wenn der Wert in *ValuePtr einen Unicode-Datentyp aufweist (beim Aufrufen von SQLGetDescFieldW), muss das BufferLength-Argument eine gerade Zahl sein.

Wenn FieldIdentifier ein vom Treiber definiertes Feld ist, gibt die Anwendung dem Treiber-Manager die Art des Felds an, indem sie das BufferLength-Argument festlegt. BufferLength kann die folgenden Werte aufweisen:

  • Wenn *ValuePtr ein Zeiger auf eine Zeichenfolge ist, ist BufferLength die Länge der Zeichenfolge oder SQL_NTS.

  • Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des makros SQL_LEN_BINARY_ATTR(length) in BufferLength. Dadurch wird ein negativer Wert in BufferLength platziert.

  • Wenn *ValuePtr ein Zeiger auf einen anderen Wert als eine Zeichenfolge oder binäre Zeichenfolge ist, sollte BufferLength den Wert SQL_IS_POINTER haben.

  • Wenn *ValuePtr einen Datentyp mit fester Länge enthält, ist BufferLength entweder SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT oder SQL_IS_USMALLINT.

StringLengthPtr
[Ausgabe] Zeiger auf den Puffer, in dem die Gesamtzahl der Bytes zurückgegeben werden soll (mit Ausnahme der Anzahl der Bytes, die für das NULL-Terminierungszeichen erforderlich sind), die in *ValuePtr zurückgegeben werden können.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_NO_DATA oder SQL_INVALID_HANDLE.

SQL_NO_DATA wird zurückgegeben, wenn RecNumber größer als die aktuelle Anzahl von Deskriptordatensätzen ist.

SQL_NO_DATA wird zurückgegeben, wenn DescriptorHandle ein IRD-Handle ist und sich die Anweisung im Zustand vorbereitet oder ausgeführt befindet, aber kein geöffneter Cursor zugeordnet war.

Diagnose

Wenn SQLGetDescField 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 von StatementHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLGetDescField 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 *ValuePtr war nicht groß genug, um das gesamte Deskriptorfeld zurückzugeben, sodass das Feld abgeschnitten wurde. Die Länge des unwahren Deskriptorfelds wird in *StringLengthPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07009 Ungültiger Deskriptorindex (DM) Das RecNumber-Argument war gleich 0, das Attribut der SQL_ATTR_USE_BOOKMARK-Anweisung wurde SQL_UB_OFF, und das Argument DescriptorHandle war ein IRD-Handle. (Dieser Fehler kann für einen explizit zugeordneten Deskriptor nur zurückgegeben werden, wenn der Deskriptor einem Anweisungshandle zugeordnet ist.)

Das Argument FieldIdentifier war ein Datensatzfeld, das RecNumber-Argument war 0, und das Argument DescriptorHandle war ein IPD-Handle.

Das RecNumber-Argument war kleiner als 0.
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 den Arbeitsspeicher nicht zuordnen, der für die Unterstützung der Ausführung oder Fertigstellung der Funktion erforderlich ist.
HY007 Zugeordnete Anweisung ist nicht vorbereitet DescriptorHandle wurde einem StatementHandle als IRD zugeordnet, und das zugeordnete Anweisungshandle wurde nicht vorbereitet oder ausgeführt.
HY010 Funktionssequenzfehler (DM) DescriptorHandle wurde einem StatementHandle zugeordnet, für das eine asynchron ausgeführte Funktion (nicht diese) aufgerufen wurde und noch ausgeführt wurde, als diese Funktion aufgerufen wurde.

(DM) DescriptorHandle wurde einem StatementHandle zugeordnet, für den SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos aufgerufen und SQL_NEED_DATA zurückgegeben wurde. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei der Ausführungsparameter oder -spalten gesendet wurden.

(DM) Eine asynchron ausgeführte Funktion wurde für das Verbindungshandle aufgerufen, das dem DescriptorHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die FUNKTION SQLGetDescField aufgerufen wurde.
HY013 Fehler bei der Speicherverwaltung Der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von geringen Arbeitsspeicherbedingungen.
HY021 Inkonsistente Deskriptorinformationen Die Felder SQL_DESC_TYPE und SQL_DESC_DATETIME_INTERVAL_CODE bilden keinen gültigen ODBC SQL-Typ, keinen gültigen treiberspezifischen SQL-Typ (für IPDs) oder einen gültigen ODBC C-Typ (für APDs oder ARDs).
HY090 Ungültige Zeichenfolgen- oder Pufferlänge (DM) *ValuePtr war eine Zeichenfolge, und BufferLength war kleiner als null.
HY091 Ungültiger Deskriptorfeldbezeichner FieldIdentifier war kein von ODBC definiertes Feld und kein durch die Implementierung definierter Wert.

FieldIdentifier war für descriptorHandle undefiniert.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur trenn- 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 geantwortet hat. Der Verbindungstimeoutzeitraum wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Treiber unterstützt diese Funktion nicht. (DM) Der Treiber, der descriptorHandle zugeordnet ist, unterstützt die Funktion nicht.

Kommentare

Eine Anwendung kann SQLGetDescField aufrufen, um den Wert eines einzelnen Felds eines Deskriptordatensatzes zurückzugeben. Ein Aufruf von SQLGetDescField kann die Einstellung eines beliebigen Felds in einem beliebigen Deskriptortyp zurückgeben, einschließlich Headerfeldern, Datensatzfeldern und Lesezeichenfeldern. Eine Anwendung kann die Einstellungen mehrerer Felder in derselben oder unterschiedlicher Deskriptoren in beliebiger Reihenfolge abrufen, indem sie sqlGetDescField wiederholt aufruft. SQLGetDescField kann auch aufgerufen werden, um treiberdefinierte Deskriptorfelder zurückzugeben.

Aus Leistungsgründen sollte eine Anwendung SQLGetDescField nicht für eine IRD aufrufen, bevor eine Anweisung ausgeführt wird.

Die Einstellungen mehrerer Felder, die den Namen, den Datentyp und die Speicherung von Spalten- oder Parameterdaten beschreiben, können auch in einem einzigen Aufruf von SQLGetDescRec abgerufen werden. SQLGetStmtAttr kann aufgerufen werden, um die Einstellung eines einzelnen Felds im Deskriptorheader zurückzugeben, das auch ein Anweisungsattribut ist. SQLColAttribute, SQLDescribeCol und SQLDescribeParam geben Datensatz- oder Lesezeichenfelder zurück.

Wenn eine Anwendung SQLGetDescField aufruft, um den Wert eines Felds abzurufen, das für einen bestimmten Deskriptortyp nicht definiert ist, gibt die Funktion SQL_SUCCESS zurück, aber der für das Feld zurückgegebene Wert ist nicht definiert. Wenn Sie beispielsweise SQLGetDescField für das SQL_DESC_NAME- oder SQL_DESC_NULLABLE-Feld einer APD oder ARD aufrufen, wird SQL_SUCCESS, aber ein nicht definierter Wert für das Feld zurückgegeben.

Wenn eine Anwendung SQLGetDescField aufruft, um den Wert eines Felds abzurufen, das für einen bestimmten Deskriptortyp definiert ist, aber keinen Standardwert aufweist und noch nicht festgelegt wurde, gibt die Funktion SQL_SUCCESS zurück, aber der für das Feld zurückgegebene Wert ist undefiniert. Weitere Informationen zur Initialisierung von Deskriptorfeldern und Beschreibungen der Felder finden Sie unter Initialisierung von Deskriptorfeldern in SQLSetDescField. Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

Informationen über Finden Sie unter
Abrufen mehrerer Deskriptorfelder SQLGetDescRec-Funktion
Festlegen eines einzelnen Deskriptorfelds SQLSetDescField-Funktion
Festlegen mehrerer Deskriptorfelder SQLSetDescRec-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien