SQLGetDescField-Funktion

Konformität
Eingeführte Version: ODBC 3.0 Normenkonformität: ISO 92

Summary
SQLGetDescField gibt die aktuelle Einstellung oder den Wert eines einzelnen Feldes eines Deskriptordatensatzes zurück.

Syntax

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

Argumente

DescriptorHandle
[Eingabe] Beschreibungs-Handle.

RecNumber
[Eingabe] Gibt den Beschreibungsdatensatz an, aus dem der Antrag Informationen abholt. Deskriptoreinträge werden ab 0 nummeriert, wobei Datensatz Nummer 0 der Lesezeicheneintrag ist. Wenn das FieldIdentifier-Argument ein Headerfeld anzeigt, wird RecNumber ignoriert. Wenn RecNumber kleiner als oder gleich SQL_DESC_COUNT ist, aber die Zeile 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. Der Datentyp hängt vom Wert von FieldIdentifier ab.

Wenn ValuePtr vom Integer-Typ ist, sollten Anwendungen einen SQLULEN-Puffer verwenden und den Wert auf 0 initialisieren, bevor diese Funktion aufgerufen wird, da einige Treiber nur die unteren 32- oder 16-Bit-Teile eines Puffers schreiben und das höhere Bit unverändert lassen.

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

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

Wenn FieldIdentifier ein treiberdefiniertes Feld ist, teilt die Anwendung dem Treibermanager die Natur des Feldes an, indem sie das BufferLength-Argument setzt. BufferLength kann folgende Werte haben:

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

  • Wenn *ValuePtr ein Zeiger auf einen binären Puffer ist, platziert die Anwendung das Ergebnis des Makros SQL_LEN_BINARY_ATTR(Länge) in BufferLength. Dies setzt einen negativen Wert in BufferLength.

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

  • Wenn *ValuePtr einen Datentyp mit fester Länge enthält, dann ist BufferLength je nach Bedarf 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 (ohne die für das Null-Endzeichen) benötigte Bytes zurückgegeben werden kann, die in *ValuePtr zurückgegeben werden können.

Rücklieferungen

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 ist als die aktuelle Anzahl der Deskriptordatensätze.

SQL_NO_DATA wird zurückgegeben, wenn DescriptorHandle ein IRD-Handle ist und die Aussage sich im vorbereiteten oder ausgeführten Zustand befindet, aber kein offener Cursor damit verbunden war.

Diagnostics

Wenn SQLGetDescField 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 SQLGetDescField 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.

SQLSTATE Fehler Description
01000 Allgemeiner Warnhinweis 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, daher wurde das Feld abgeschnitten. Die Länge des untrunkierten Deskriptorfeldes 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 SQL_ATTR_USE_BOOKMARK-Statement-Attribut war SQL_UB_OFF, und das DescriptorHandle-Argument war ein IRD-Handle. (Dieser Fehler kann für einen explizit zugewiesenen Deskriptor nur zurückgegeben werden, wenn der Deskriptor mit einem Anweisungshandle verknüpft ist.)

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

Das RecNumber-Argument war weniger 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 dessen Ursache.
HY001 Speicherzuweisungsfehler Der Treiber konnte den erforderlichen Arbeitsspeicher nicht zuordnen, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY007 Die zugeordnete Anweisung ist nicht vorbereitet. DescriptorHandle war als IRD mit einem StatementHandle verknüpft, und der zugehörige Statement-Handle war weder vorbereitet noch ausgeführt worden.
HY010 Funktionssequenzfehler (DM) DescriptorHandle war mit einem StatementHandle verknüpft, für den eine asynchron ausführende Funktion (nicht diese) aufgerufen wurde und noch ausgeführt wurde, wenn diese Funktion aufgerufen wurde.

(DM) DescriptorHandle war mit einem StatementHandle verknüpft, für den SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos aufgerufen und SQL_NEED_DATA zurückgegeben wurden. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden.

(DM) Eine asynchron ausführende Funktion wurde für den Verbindungshandle aufgerufen, der mit dem DescriptorHandle verknüpft ist. Diese asynchrone Funktion lief noch, als die SQLGetDescField-Funktion aufgerufen wurde.
HY013 Speicherverwaltungsfehler Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer 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 Zeichenkette, und BufferLength war kleiner als null.
HY091 Feldbekennung für ungültige Deskriptoren FieldIdentifier war kein von ODBC definiertes Feld und kein implementierungsdefinierter Wert.

FieldIdentifier war für DescriptorHandle nicht definiert.
HY117 Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig. (DM) Für weitere Informationen über den suspendierten Zustand siehe 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 SQL_ATTR_CONNECTION_TIMEOUT festgelegt.
IM001 Dieser Treiber unterstützt diese Funktion nicht. (DM) Der mit dem DescriptorHandle verknüpfte Treiber unterstützt die Funktion nicht.

Kommentare

Eine Anwendung kann SQLGetDescField aufrufen, um den Wert eines einzelnen Feldes eines Deskriptordatensatzes zurückzugeben. Ein Aufruf von SQLGetDescField kann die Einstellung eines beliebigen Feldes in jedem Deskriptortyp zurückgeben, einschließlich Kopffelde, Datensatzfelder und Lesezeichenfelder. Eine Anwendung kann die Einstellungen mehrerer Felder in demselben oder unterschiedlichen Deskriptoren in beliebiger Reihenfolge erhalten, indem sie wiederholt SQLGetDescField aufruft. SQLGetDescField kann auch aufgerufen werden, um treiberdefinierte Deskriptorfelder zurückzugeben.

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

Die Einstellungen mehrerer Felder, die den Namen, Datentyp und die Speicherung von Spalten- oder Parameterdaten beschreiben, können ebenfalls in einem einzigen Aufruf zu SQLGetDescRec abgerufen werden. SQLGetStmtAttr kann aufgerufen werden, um die Einstellung eines einzelnen Feldes im Deskriptor-Header zurückzugeben, das auch ein Anweisungsattribut ist. SQLColAttribute, SQLDescribeCol und SQLDescribeParam geben Felder für Einträge oder Lesezeichen zurück.

Wenn eine Anwendung SQLGetDescField aufruft, um den Wert eines Feldes 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 undefiniert. Zum Beispiel gibt das Aufrufen von SQLGetDescField für das SQL_DESC_NAME oder SQL_DESC_NULLABLE Feld eines APD oder ARD SQL_SUCCESS, aber einen undefinierten Wert für das Feld zurück.

Wenn eine Anwendung SQLGetDescField aufruft, um den Wert eines Feldes abzurufen, das für einen bestimmten Deskriptortyp definiert ist, aber keinen Standardwert hat und noch nicht gesetzt 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 deren Beschreibungen finden Sie unter "Initialisierung von Deskriptorfeldern" in SQLSetDescField. Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

Weitere Informationen zu Siehe
Mehrere Deskriptorfelder erhalten SQLGetDescRec-Funktion
Festlegen eines einzelnen Deskriptorfelds SQLSetDescField-Funktion
Setzen mehrerer Deskriptorfelder SQLSetDescRec-Funktion

Verwandte Inhalte

  • Last updated on