SQLGetData-Funktion

Artikel
05/23/2023

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

Zusammenfassung
SQLGetData ruft Daten für eine einzelne Spalte im Resultset oder für einen einzelnen Parameter ab, nachdem SQLParamData SQL_PARAM_DATA_AVAILABLE zurückgegeben hat. Es kann mehrmals aufgerufen werden, um Daten mit variabler Länge in Teilen abzurufen.

Syntax

  
SQLRETURN SQLGetData(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   Col_or_Param_Num,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);

Argumente

StatementHandle
[Eingabe] Anweisungshandle.

Col_or_Param_Num
[Eingabe] Zum Abrufen von Spaltendaten ist es die Nummer der Spalte, für die Daten zurückgegeben werden sollen. Resultsetspalten werden in erhöhter Spaltenreihenfolge beginnend bei 1 nummeriert. Die Textmarkenspalte ist Die Spaltennummer 0; Dies kann nur angegeben werden, wenn Lesezeichen aktiviert sind.

Zum Abrufen von Parameterdaten handelt es sich um das Ordinal des Parameters, der bei 1 beginnt.

TargetType
[Eingabe] Der Typbezeichner des C-Datentyps des *TargetValuePtr-Puffers . Eine Liste der gültigen C-Datentypen und Typbezeichner finden Sie im Abschnitt "C-Datentypen " in Anhang D: Datentypen.

Wenn TargetType SQL_ARD_TYPE ist, verwendet der Treiber den typbezeichner, der im feld SQL_DESC_CONCISE_TYPE der ARD angegeben ist. Wenn TargetType SQL_APD_TYPE ist, verwendet SQLGetData denselben C-Datentyp, der in SQLBindParameter angegeben wurde. Andernfalls überschreibt der in SQLGetData angegebene C-Datentyp den in SQLBindParameter angegebenen C-Datentyp. Wenn es SQL_C_DEFAULT ist, wählt der Treiber den standardmäßigen C-Datentyp basierend auf dem SQL-Datentyp der Quelle aus.

Sie können auch einen erweiterten C-Datentyp angeben. Weitere Informationen finden Sie unter C-Datentypen in ODBC.

TargetValuePtr
[Ausgabe] Zeigen Sie auf den Puffer, in dem die Daten zurückgegeben werden sollen.

TargetValuePtr darf nicht NULL sein.

BufferLength
[Eingabe] Länge des *TargetValuePtr-Puffers in Bytes.

Der Treiber verwendet BufferLength , um das Schreiben über das Ende des *TargetValuePtr-Puffers zu vermeiden, wenn Daten mit variabler Länge zurückgegeben werden, z. B. Zeichen- oder Binärdaten. Beachten Sie, dass der Treiber das Nullendpunktzeichen zählt, wenn Zeichendaten an *TargetValuePtr zurückgegeben werden. *TargetValuePtr muss daher Leerzeichen für das Nullendzeichen enthalten, oder der Treiber schneidet die Daten ab.

Wenn der Treiber Daten mit fester Länge zurückgibt, z. B. eine ganze Zahl oder eine Datumsstruktur , ignoriert der Treiber BufferLength und geht davon aus, dass der Puffer groß genug ist, um die Daten aufzunehmen. Daher ist es wichtig, dass die Anwendung einen großen Puffer für Daten mit fester Länge zuweist, oder der Treiber über das Ende des Puffers schreibt.

SQLGetData gibt SQLSTATE HY090 (Ungültige Zeichenfolge oder Pufferlänge) zurück, wenn BufferLength kleiner als 0 ist, aber nicht, wenn BufferLength 0 ist.

StrLen_or_IndPtr
[Ausgabe] Zeigen Sie auf den Puffer, in dem die Länge oder der Indikatorwert zurückgegeben werden soll. Wenn es sich um einen Nullzeiger handelt, wird kein Längen- oder Indikatorwert zurückgegeben. Dadurch wird ein Fehler zurückgegeben, wenn die abgerufenen Daten NULL sind.

SQLGetData kann die folgenden Werte im Längen-/Indikatorpuffer zurückgeben:

Die Länge der verfügbaren Daten, die zurückgegeben werden sollen
SQL_NO_TOTAL
SQL_NULL_DATA

Weitere Informationen finden Sie unter Verwenden von Längen-/Indikatorwerten und "Kommentaren" in diesem Thema.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostik

Wenn SQLGetData entweder SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert durch Aufrufen von SQLGetDiagRec mit einem HandleType von SQL_HANDLE_STMT und einem Handle of StatementHandle abgerufen werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLGetData zurückgegeben werden, und jede wird 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	Error	Beschreibung
01000	Allgemeiner Warnhinweis	Treiberspezifische Informationsmeldung. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
01004	Zeichenfolgendaten, rechts abgeschnitten	Nicht alle Daten für die angegebene Spalte, Col_or_Param_Num, konnten in einem einzigen Aufruf der Funktion abgerufen werden. SQL_NO_TOTAL oder die Länge der daten, die in der angegebenen Spalte vor dem aktuellen Aufruf von SQLGetData verbleiben, wird in *StrLen_or_IndPtr zurückgegeben. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) Weitere Informationen zur Verwendung mehrerer Aufrufe von SQLGetData für eine einzelne Spalte finden Sie unter "Kommentare".
01S07	Bruchabkürzung	Die für mindestens eine Spalte zurückgegebenen Daten wurden abgeschnitten. Bei numerischen Datentypen wurde der Bruchteil der Zahl abgeschnitten. Für Zeit-, Zeitstempel- und Intervalldatentypen, die eine Zeitkomponente enthalten, wurde der Bruchteil der Zeit abgeschnitten. (Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
07006	Verletzung des Eingeschränkten Datentyp-Attributs	Der Datenwert einer Spalte im Resultset kann nicht in den vom Argument TargetType angegebenen C-Datentyp konvertiert werden.
07009	Ungültiger Deskriptorindex	Der für das Argument Col_or_Param_Num angegebene Wert war 0, und das attribut der SQL_ATTR_USE_BOOKMARKS-Anweisung wurde auf SQL_UB_OFF festgelegt. Der für das Argument angegebene Wert Col_or_Param_Num war größer als die Anzahl der Spalten im Resultset. Der Col_or_Param_Num Wert war nicht gleich dem Ordinal des verfügbaren Parameters. (DM) Die angegebene Spalte wurde gebunden. Diese Beschreibung gilt nicht für Treiber, die die SQL_GD_BOUND Bitmaske für die Option SQL_GETDATA_EXTENSIONS in SQLGetInfo zurückgeben. (DM) Die Anzahl der angegebenen Spalte war kleiner oder gleich der Anzahl der höchsten gebundenen Spalte. Diese Beschreibung gilt nicht für Treiber, die die SQL_GD_ANY_COLUMN Bitmaske für die Option SQL_GETDATA_EXTENSIONS in SQLGetInfo zurückgeben. (DM) Die Anwendung hat bereits SQLGetData für die aktuelle Zeile aufgerufen. Die Nummer der spalte, die im aktuellen Aufruf angegeben wurde, war kleiner als die Nummer der spalte, die im vorherigen Aufruf angegeben wurde; und der Treiber gibt die SQL_GD_ANY_ORDER Bitmaske für die option SQL_GETDATA_EXTENSIONS in SQLGetInfo nicht zurück. (DM) Das Argument TargetType wurde SQL_ARD_TYPE, und der Col_or_Param_Num Deskriptordatensatz in der ARD hat die Konsistenzüberprüfung nicht bestanden. (DM) Das Argument TargetType wurde SQL_ARD_TYPE, und der Wert im feld SQL_DESC_COUNT der ARD war kleiner als das argument Col_or_Param_Num .
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.
22002	Indikatorvariable erforderlich, aber nicht angegeben	StrLen_or_IndPtr war ein Nullzeiger und NULL-Daten wurden abgerufen.
22003	Numerischer Wert außerhalb des Bereichs	Das Zurückgeben des numerischen Werts (als numerische oder Zeichenfolge) für die Spalte hätte dazu geführt, dass der gesamte Teil (im Gegensatz zu Bruchzahlen) der Zahl abgeschnitten wird. Weitere Informationen finden Sie in Anhang D: Datentypen.
22007	Ungültiges Datetime-Format	Die Zeichenspalte im Resultset wurde an ein C-Datum, eine Uhrzeit oder eine Zeitstempelstruktur gebunden, und der Wert in der Spalte war ein ungültiges Datum, eine Uhrzeit oder ein Zeitstempel. Weitere Informationen finden Sie in Anhang D: Datentypen.
22012	Division durch Null	Ein Wert aus einem arithmetischen Ausdruck, der zu Einer Division durch Null führte, wurde zurückgegeben.
22015	Intervallfeldüberlauf	Das Zuweisen eines genauen numerischen oder Intervall-SQL-Typs zu einem Intervall-C-Typ hat zu einem Verlust signifikanter Ziffern im führenden Feld geführt. Beim Zurückgeben von Daten an einen Intervall-C-Typ gab es keine Darstellung des Werts des SQL-Typs im Intervall C-Typ.
22018	Ungültiger Zeichenwert für die Umwandlungsspezifikation	Eine Zeichenspalte im Resultset wurde an einen Zeichen C-Puffer zurückgegeben, und die Spalte enthielt ein Zeichen, für das keine Darstellung im Zeichensatz des Puffers vorhanden war. Der Typ C war eine genaue oder ungefähre Zahl, ein Datum/Uhrzeit oder ein Intervall-Datentyp; Der SQL-Typ der Spalte war ein Zeichendatentyp; und der Wert in der Spalte war kein gültiges Literal des gebundenen C-Typs.
24.000	Ungültiger Cursorstatus	(DM) Die Funktion wurde aufgerufen, ohne zuerst SQLFetch oder SQLFetchScroll aufzurufen, um den Cursor in der erforderlichen Datenzeile zu positionieren. (DM) Die StatementHandle war in einem ausgeführten Zustand, aber dem StatementHandle wurde kein Resultset zugeordnet. Ein Cursor wurde für " StatementHandle " geöffnet, und SQLFetch Oder SQLFetchScroll wurde aufgerufen, der Cursor wurde jedoch vor dem Start des Resultsets oder nach dem Ende des Resultsets positioniert.
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	Speicherzuweisungsfehler	Der Treiber konnte speicher nicht zuordnen, der erforderlich ist, um die Ausführung oder den Abschluss der Funktion zu unterstützen.
HY003	Programmtyp außerhalb des Bereichs	(DM) Das Argument TargetType war kein gültiger Datentyp, SQL_C_DEFAULT, SQL_ARD_TYPE (beim Abrufen von Spaltendaten) oder SQL_APD_TYPE (im Falle des Abrufens von Parameterdaten). (DM) Das Argument Col_or_Param_Num war 0, und das Argument TargetType wurde nicht für eine Textmarke mit fester Länge oder SQL_C_VARBOOKMARK für eine Textmarke mit variabler Länge SQL_C_BOOKMARK.
HY008	Vorgang abgebrochen	Die asynchrone Verarbeitung wurde für " StatementHandle" aktiviert. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für das StatementHandle aufgerufen, und dann wurde die Funktion erneut für "StatementHandle" aufgerufen. Die Funktion wurde aufgerufen, und bevor sie die Ausführung abgeschlossen hat, wurde SQLCancel oder SQLCancelHandle für die Anweisungshandle von einem anderen Thread in einer Multithreadanwendung aufgerufen, und dann wurde die Funktion erneut für das StatementHandle aufgerufen.
HY009	Ungültige Verwendung des Nullzeigers	(DM) Das Argument TargetValuePtr war ein Nullzeiger.
HY010	Funktionssequenzfehler	(DM) Das angegebene StatementHandle war nicht in einem ausgeführten Zustand. Die Funktion wurde aufgerufen, ohne zuerst SQLExecDirect, SQLExecute oder eine Katalogfunktion aufzurufen. (DM) Eine asynchron ausgeführte Funktion wurde für den Verbindungshandle aufgerufen, der dem StatementHandle zugeordnet ist. Diese asynchrone Funktion wurde noch ausgeführt, als die SQLGetData-Funktion aufgerufen wurde. (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) SQLExecute, SQLExecDirect, SQLBulkOperations oder SQLSetPos wurde für " StatementHandle " aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle Daten bei ausführungsparametern oder -spalten gesendet wurden. (DM) Die StatementHandle war in einem ausgeführten Zustand, aber dem StatementHandle wurde kein Resultset zugeordnet. Ein Aufruf von SQLExeceute, SQLExecDirect oder SQLMoreResults hat SQL_PARAM_DATA_AVAILABLE zurückgegeben, aber SQLGetData wurde anstelle von SQLParamData aufgerufen.
HY013	Speicherverwaltungsfehler	Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund geringer Arbeitsspeicherbedingungen.
HY090	Ungültige Zeichenfolgen- oder Pufferlänge	(DM) Der für argument "BufferLength " angegebene Wert war kleiner als 0. Der für argument "BufferLength " angegebene Wert war kleiner als 4, das argument Col_or_Param_Num wurde auf 0 festgelegt, und der Treiber war ein ODBC 2.x-Treiber.
HY109	Ungültige Cursorposition	Der Cursor wurde (von SQLSetPos, SQLFetch, SQLFetchScroll oder SQLBulkOperations) in einer Zeile positioniert, die gelöscht oder nicht abgerufen werden konnte. Der Cursor war ein Vorwärtscursor, und die Zeilensatzgröße war größer als eins.
HY117	Die Verbindung wird aufgrund des unbekannten Transaktionsstatus angehalten. Es sind nur Trenn- und schreibgeschützte Funktionen zulässig.	(DM) Weitere Informationen zum angehaltenen Zustand finden Sie unter SQLEndTran Function.
HYC00	Optionales Feature wurde nicht implementiert	Der Treiber oder die Datenquelle unterstützt die Verwendung von SQLGetData mit mehreren Zeilen in SQLFetchScroll nicht. Diese Beschreibung gilt nicht für Treiber, die die SQL_GD_BLOCK Bitmaske für die Option SQL_GETDATA_EXTENSIONS in SQLGetInfo zurückgeben. Der Treiber oder die Datenquelle unterstützt die durch die Kombination des TargetType-Arguments und den SQL-Datentyp der entsprechenden Spalte angegebene Konvertierung nicht. Dieser Fehler gilt nur, wenn der SQL-Datentyp der Spalte einem treiberspezifischen SQL-Datentyp zugeordnet wurde. Der Treiber unterstützt nur ODBC 2.x, und das Argument TargetType war eine der folgenden: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT und eines der Intervall-C-Datentypen, die in C-Datentypen in Anhang D: Datentypen aufgeführt sind. Der Treiber unterstützt nur ODBC-Versionen vor 3.50, und das Argument TargetType wurde SQL_C_GUID.
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 dem StatementHandle entsprechende Treiber unterstützt die Funktion nicht.
IM017	Die Abrufung ist im asynchronen Benachrichtigungsmodus deaktiviert.	Immer wenn das Benachrichtigungsmodell verwendet wird, ist die Abrufung 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 Nachbearbeitung durchzuführen und den Vorgang abzuschließen.

Kommentare

SQLGetData gibt die Daten in einer angegebenen Spalte zurück. SQLGetData kann nur aufgerufen werden, nachdem mindestens eine Zeile vom Resultset von SQLFetch, SQLFetchScroll oder SQLExtendedFetch abgerufen wurde. Wenn Daten mit variabler Länge zu groß sind, um in einem einzelnen Aufruf von SQLGetData (aufgrund einer Einschränkung in der Anwendung) zurückgegeben zu werden, kann SQLGetData sie in Teilen abrufen. Es ist möglich, einige Spalten in einer Zeile zu binden und SQLGetData für andere aufzurufen, obwohl dies einigen Einschränkungen unterliegt. Weitere Informationen finden Sie unter Abrufen langer Daten.

Informationen zur Verwendung von SQLGetData mit gestreamten Ausgabeparametern finden Sie unter Abrufen von Ausgabeparametern mit SQLGetData.

Verwenden von SQLGetData

Wenn der Treiber keine Erweiterungen für SQLGetData unterstützt, kann die Funktion Daten nur für ungebundene Spalten mit einer Zahl zurückgeben, die größer als die der letzten gebundenen Spalte ist. Darüber hinaus muss innerhalb einer Datenzeile der Wert des arguments Col_or_Param_Num in jedem Aufruf von SQLGetData größer oder gleich dem Wert von Col_or_Param_Num im vorherigen Aufruf sein; d. h. Daten müssen in zunehmender Spaltennummernreihenfolge abgerufen werden. Wenn keine Erweiterungen unterstützt werden, kann SQLGetData nicht aufgerufen werden, wenn die Rowsetgröße größer als 1 ist.

Fahrer können jede dieser Einschränkungen entspannen. Um zu bestimmen, welche Einschränkungen ein Treiber entspannt, ruft eine Anwendung SQLGetInfo mit einer der folgenden SQL_GETDATA_EXTENSIONS Optionen auf:

SQL_GD_OUTPUT_PARAMS = SQLGetData kann aufgerufen werden, um Ausgabeparameterwerte zurückzugeben. Weitere Informationen finden Sie unter Abrufen von Ausgabeparametern mit SQLGetData.
SQL_GD_ANY_COLUMN. Wenn diese Option zurückgegeben wird, kann SQLGetData für jede ungebundene Spalte aufgerufen werden, einschließlich derer vor der letzten gebundenen Spalte.
SQL_GD_ANY_ORDER. Wenn diese Option zurückgegeben wird, kann SQLGetData für ungebundene Spalten in beliebiger Reihenfolge aufgerufen werden.
SQL_GD_BLOCK. Wenn diese Option von SQLGetInfo für den SQL_GETDATA_EXTENSIONS InfoType zurückgegeben wird, unterstützt der Treiber Aufrufe von SQLGetData, wenn die Rowsetgröße größer als 1 ist und die Anwendung SQLSetPos mit der option SQL_POSITION aufrufen kann, um den Cursor vor dem Aufrufen von SQLGetData auf der richtigen Zeile zu positionieren.
SQL_GD_BOUND. Wenn diese Option zurückgegeben wird, kann SQLGetData für gebundene Spalten sowie ungebundene Spalten aufgerufen werden.

Es gibt zwei Ausnahmen von diesen Einschränkungen und die Fähigkeit eines Fahrers, sie zu entspannen. Zunächst sollte SQLGetData niemals für einen Vorwärtscursor aufgerufen werden, wenn die Rowsetgröße größer als 1 ist. Wenn ein Treiber Lesezeichen unterstützt, muss er immer die Möglichkeit zum Aufrufen von SQLGetData für Spalte 0 unterstützen, auch wenn anwendungen sqlGetData für andere Spalten vor der letzten gebundenen Spalte nicht aufrufen können. (Wenn eine Anwendung mit einem ODBC 2*.x*-Treiber arbeitet, SQLGetData gibt erfolgreich eine Textmarke zurück, wenn sie mit Col_or_Param_Num gleich 0 nach einem Aufruf von SQLFetch aufgerufen wird, da SQLFetch vom ODBC 3*.x*-Treiber-Manager mit einer FetchOrientation von SQL_FETCH_NEXT und SQLGetData mit einem Col_or_Param_Num von 0 vom ODBC 3*.x*-Treiber-Manager mit einer FOption von SQL_GET_BOOKMARK zugeordnet wird.)

SQLGetData kann nicht verwendet werden, um die Textmarke für eine Zeile abzurufen, die gerade durch Aufrufen von SQLBulkOperations mit der Option SQL_ADD eingefügt wurde, da der Cursor nicht in der Zeile positioniert ist. Eine Anwendung kann die Textmarke für eine solche Zeile abrufen, indem Sie Spalte 0 binden, bevor SQLBulkOperations mit SQL_ADD aufgerufen wird. In diesem Fall gibt SQLBulkOperations die Textmarke im gebundenen Puffer zurück. SQLFetchScroll kann dann mit SQL_FETCH_BOOKMARK aufgerufen werden, um den Cursor in dieser Zeile neu zu positionieren.

Wenn das Argument TargetType ein Intervalldatentyp ist, werden die standardintervallführende Genauigkeit (2) und die Standardintervallsekundengenauigkeit (6) wie in den Feldern SQL_DESC_DATETIME_INTERVAL_PRECISION und SQL_DESC_PRECISION der ARD für die Daten verwendet. Wenn das TargetType-Argument ein SQL_C_NUMERIC Datentyp ist, werden die Standardgenauigkeit (treiberdefiniert) und die Standardskala (0) wie in den Feldern SQL_DESC_PRECISION und SQL_DESC_SCALE der ARD für die Daten verwendet. Wenn eine Standardgenauigkeit oder -skalierung nicht geeignet ist, sollte die Anwendung das entsprechende Deskriptorfeld explizit durch einen Aufruf von SQLSetDescField oder SQLSetDescRec festlegen. Sie kann das feld SQL_DESC_CONCISE_TYPE auf SQL_C_NUMERIC festlegen und SQLGetData mit einem TargetType-Argument von SQL_ARD_TYPE aufrufen, wodurch die Genauigkeits- und Skalierungswerte in den Deskriptorfeldern verwendet werden.

Hinweis

In ODBC 2*.x* legen Anwendungen TargetType auf SQL_C_DATE, SQL_C_TIME oder SQL_C_TIMESTAMP fest, um anzugeben, dass *TargetValuePtr eine Datums-, Uhrzeit- oder Zeitstempelstruktur ist. In ODBC 3*.x* legen Anwendungen TargetType auf SQL_C_TYPE_DATE, SQL_C_TYPE_TIME oder SQL_C_TYPE_TIMESTAMP fest. Der Treiber-Manager macht bei Bedarf basierend auf der Anwendungs- und Treiberversion geeignete Zuordnungen.

Abrufen von Daten mit variabler Länge in Teilen

SQLGetData kann verwendet werden, um Daten aus einer Spalte abzurufen, die Daten mit variabler Länge in Teilen enthält, d. h., wenn der Bezeichner des SQL-Datentyps der Spalte SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY oder ein treiberspezifischer Bezeichner für einen Variablenlängentyp ist.

Um Daten aus einer Spalte in Teilen abzurufen, ruft die Anwendung SQLGetData mehrmals nacheinander für dieselbe Spalte auf. Bei jedem Aufruf gibt SQLGetData den nächsten Teil der Daten zurück. Es liegt an der Anwendung, die Teile neu zusammenzusammeln, wobei das Nullendpunktzeichen aus Zwischenteilen von Zeichendaten entfernt wird. Wenn mehr Daten zurückgegeben werden sollen oder nicht genügend Puffer für das Endzeichen zugeordnet wurde, gibt SQLGetData SQL_SUCCESS_WITH_INFO und SQLSTATE 01004 zurück (Daten abgeschnitten). Wenn der letzte Teil der Daten zurückgegeben wird, gibt SQLGetData SQL_SUCCESS zurück. Weder SQL_NO_TOTAL noch Null können beim letzten gültigen Aufruf zurückgegeben werden, um Daten aus einer Spalte abzurufen, da die Anwendung dann keine Möglichkeit hätte zu wissen, wie viel der Daten im Anwendungspuffer gültig ist. Wenn SQLGetData danach aufgerufen wird, wird SQL_NO_DATA zurückgegeben. Weitere Informationen finden Sie im nächsten Abschnitt "Abrufen von Daten mit SQLGetData".

Textmarken mit variabler Länge können in Teilen von SQLGetData zurückgegeben werden. Wie bei anderen Daten gibt ein Aufruf von SQLGetData zum Zurückgeben von Textmarken mit variabler Länge in Teilen SQLSTATE 01004 (Zeichenfolgendaten, rechts abgeschnitten) und SQL_SUCCESS_WITH_INFO zurück, wenn mehr Daten zurückgegeben werden sollen. Dies unterscheidet sich von dem Fall, wenn eine Textmarke mit variabler Länge durch einen Aufruf von SQLFetch oder SQLFetchScroll abgeschnitten wird, der SQL_ERROR und SQLSTATE 22001 zurückgibt (Zeichenfolgendaten, rechts abgeschnitten).

SQLGetData kann nicht verwendet werden, um Daten mit fester Länge in Teilen zurückzugeben. Wenn SQLGetData mehrere Mal in einer Zeile für eine Spalte mit Daten mit fester Länge aufgerufen wird, wird SQL_NO_DATA für alle Aufrufe nach dem ersten Zurückgegeben.

Abrufen von streamten Ausgabeparametern

Wenn ein Treiber gestreamte Ausgabeparameter unterstützt, kann eine Anwendung SQLGetData mit einem kleinen Puffer mehrmals aufrufen, um einen großen Parameterwert abzurufen. Weitere Informationen zum streamten Ausgabeparameter finden Sie unter Abrufen von Ausgabeparametern mithilfe von SQLGetData.

Abrufen von Daten mit SQLGetData

Um Daten für die angegebene Spalte zurückzugeben, führt SQLGetData die folgende Abfolge von Schritten aus:

Gibt SQL_NO_DATA zurück, wenn sie bereits alle Daten für die Spalte zurückgegeben hat.
Legt *StrLen_or_IndPtr auf SQL_NULL_DATA fest, wenn die Daten NULL sind. Wenn die Daten NULL sind und StrLen_or_IndPtr ein Nullzeiger war, gibt SQLGetData SQLSTATE 22002 zurück (Indikatorvariable erforderlich, aber nicht angegeben).

Wenn die Daten für die Spalte nicht NULL sind, fährt SQLGetData mit Schritt 3 fort.
Wenn das attribut der SQL_ATTR_MAX_LENGTH-Anweisung auf einen Wert ungleich Null festgelegt ist, wenn die Spalte Zeichen- oder Binärdaten enthält und SQLGetData zuvor nicht für die Spalte aufgerufen wurde, werden die Daten auf SQL_ATTR_MAX_LENGTH Bytes abgeschnitten.

Hinweis

Das Attribut der SQL_ATTR_MAX_LENGTH-Anweisung soll den Netzwerkdatenverkehr reduzieren. Sie wird in der Regel von der Datenquelle implementiert, wodurch die Daten abgeschnitten werden, bevor sie über das Netzwerk zurückgegeben werden. Treiber und Datenquellen sind nicht erforderlich, um sie zu unterstützen. Um sicherzustellen, dass Daten auf eine bestimmte Größe abgeschnitten werden, sollte eine Anwendung einen Puffer dieser Größe zuweisen und die Größe im Argument BufferLength angeben.
Konvertiert die Daten in den in TargetType angegebenen Typ. Die Daten erhalten die Standardgenauigkeit und skalierung für diesen Datentyp. Wenn TargetType SQL_ARD_TYPE ist, wird der Datentyp im feld SQL_DESC_CONCISE_TYPE der ARD verwendet. Wenn TargetType SQL_ARD_TYPE ist, erhalten die Daten die Genauigkeit und Skalierung in den Feldern SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION und SQL_DESC_SCALE der ARD, je nach Datentyp im feld SQL_DESC_CONCISE_TYPE. Wenn eine Standardgenauigkeit oder -skalierung nicht geeignet ist, sollte die Anwendung das entsprechende Deskriptorfeld explizit durch einen Aufruf von SQLSetDescField oder SQLSetDescRec festlegen.
Wenn die Daten in einen Datentyp variabler Länge konvertiert wurden, z. B. Zeichen oder binär, überprüft SQLGetData, ob die Länge der Daten BufferLength überschreitet. Wenn die Länge von Zeichendaten (einschließlich des Null-Beendigungszeichens ) PufferLength überschreitet, schneidet SQLGetData die Daten in BufferLength ab, weniger die Länge eines Null-Beendigungszeichens. Anschließend wird die Daten null beendet. Wenn die Länge der Binärdaten die Länge des Datenpuffers überschreitet, schneidet SQLGetData sie in BufferLength Bytes ab.

Wenn der bereitgestellte Datenpuffer zu klein ist, um das Nullendpunktzeichen zu speichern, gibt SQLGetData SQL_SUCCESS_WITH_INFO und SQLSTATE 01004 zurück.

SQLGetData schneidet daten, die in Datentypen mit fester Länge konvertiert wurden, nie ab. Es wird immer davon ausgegangen, dass die Länge von *TargetValuePtr die Größe des Datentyps ist.
Platziert die konvertierten (und möglicherweise abgeschnittenen) Daten in *TargetValuePtr. Beachten Sie, dass SQLGetData keine Daten aus der Zeile zurückgeben kann.
Platziert die Länge der Daten in *StrLen_or_IndPtr. Wenn StrLen_or_IndPtr ein Nullzeiger war, gibt SQLGetData die Länge nicht zurück.
- Bei Zeichen- oder Binärdaten ist dies die Länge der Daten nach der Konvertierung und vor dem Abschneiden aufgrund von BufferLength. Wenn der Treiber die Länge der Daten nach der Konvertierung nicht ermitteln kann, wie es bei langen Daten der Fall ist, wird SQL_SUCCESS_WITH_INFO zurückgegeben und die Länge auf SQL_NO_TOTAL festgelegt. (Der letzte Aufruf an SQLGetData muss immer die Länge der Daten zurückgeben, nicht null oder SQL_NO_TOTAL.) Wenn Daten aufgrund des attributs SQL_ATTR_MAX_LENGTH Anweisung abgeschnitten wurden, wird der Wert dieses Attributs - im Gegensatz zur tatsächlichen Länge - in *StrLen_or_IndPtr platziert. Dies liegt daran, dass dieses Attribut zum Abschneiden von Daten auf dem Server vor der Konvertierung konzipiert ist, sodass der Treiber keine Möglichkeit hat, herauszufinden, was die tatsächliche Länge ist. Wenn SQLGetData mehrmals nacheinander für dieselbe Spalte aufgerufen wird, ist dies die Länge der Daten, die zu Beginn des aktuellen Aufrufs verfügbar sind. Das heißt, die Länge nimmt bei jedem nachfolgenden Aufruf ab.
- Bei allen anderen Datentypen ist dies die Länge der Daten nach der Konvertierung; d. h. die Größe des Typs, in den die Daten konvertiert wurden.
Wenn die Daten während der Konvertierung ohne Bedeutungsverlust abgeschnitten werden (z. B. wird die reelle Zahl 1,234 beim Konvertieren in die ganze Zahl 1 abgeschnitten) oder weil BufferLength zu klein ist (z. B. wird die Zeichenfolge "abcdef" in einem 4-Byte-Puffer platziert), sqlGetData gibt SQLSTATE 01004 (Daten abgeschnitten) und SQL_SUCCESS_WITH_INFO zurück. Wenn Daten aufgrund des attributs SQL_ATTR_MAX_LENGTH Anweisung ohne Bedeutung abgeschnitten werden, gibt SQLGetData SQL_SUCCESS zurück und gibt SQLSTATE 01004 nicht zurück (Daten abgeschnitten).

Der Inhalt des gebundenen Datenpuffers (wenn SQLGetData in einer gebundenen Spalte aufgerufen wird) und der Längen-/Indikatorpuffer nicht definiert sind, wenn SQLGetData SQL_SUCCESS oder SQL_SUCCESS_WITH_INFO nicht zurückgibt.

Aufeinanderfolgende Aufrufe von SQLGetData rufen Daten aus der letzten angeforderten Spalte ab. Vorherige Offsets werden ungültig. Beispiel: Wenn die folgende Sequenz ausgeführt wird:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

Der zweite Aufruf von SQLGetData(icol=n) ruft Daten vom Anfang der n-Spalte ab. Ein Offset in den Daten aufgrund früherer Aufrufe von SQLGetData für die Spalte ist nicht mehr gültig.

Deskriptoren und SQLGetData

SQLGetData interagiert nicht direkt mit Deskriptorfeldern.

Wenn TargetType SQL_ARD_TYPE ist, wird der Datentyp im feld SQL_DESC_CONCISE_TYPE der ARD verwendet. Wenn TargetType entweder SQL_ARD_TYPE oder SQL_C_DEFAULT ist, erhalten die Daten die Genauigkeit und Skalierung in den Feldern SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION und SQL_DESC_SCALE der ARD, je nach Datentyp im feld SQL_DESC_CONCISE_TYPE.

Codebeispiel

Im folgenden Beispiel führt eine Anwendung eine SELECT-Anweisung aus, um ein Resultset der Kunden-IDs, Namen und Telefonnummern zurückzugeben, die nach Name, ID und Telefonnummer sortiert sind. Für jede Datenzeile ruft sie SQLFetch auf, um den Cursor an die nächste Zeile zu positionieren. Es ruft SQLGetData auf, um die abgerufenen Daten abzurufen. Die Puffer für die Daten und die zurückgegebene Anzahl von Bytes werden im Aufruf von SQLGetData angegeben. Schließlich werden der Name, die ID und die Telefonnummer der einzelnen Mitarbeiter ausgegeben.

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}

Weitere Informationen zu	Siehe
Zuweisen von Speicher für eine Spalte in einem Resultset	SQLBindCol
Ausführen von Massenvorgängen, die sich nicht auf die Position des Blockcursors beziehen	SQLBulkOperations
Abbrechen der Verarbeitung von Anweisungen	SQLCancel
Ausführen einer SQL-Anweisung	SQLExecDirect
Ausführen einer vorbereiteten SQL-Anweisung	SQLExecute
Abrufen eines Datenblocks oder Scrollen durch ein Resultset	SQLFetchScroll
Abrufen einer einzelnen Datenzeile oder eines Datenblocks in eine Vorwärtsrichtung	SQLFetch
Senden von Parameterdaten zur Ausführungszeit	SQLPutData
Positionieren des Cursors, Aktualisieren von Daten im Rowset oder Aktualisieren oder Löschen von Daten im Rowset	SQLSetPos

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien
Abrufen von Ausgabeparametern mithilfe von SQLGetData

Freigeben über

SQLGetData-Funktion

Syntax

Argumente

Gibt zurück

Diagnostik

Kommentare

Verwenden von SQLGetData

Abrufen von Daten mit variabler Länge in Teilen

Abrufen von streamten Ausgabeparametern

Abrufen von Daten mit SQLGetData

Deskriptoren und SQLGetData

Codebeispiel

Weitere Informationen

Feedback

Zusätzliche Ressourcen

Freigeben über

SQLGetData-Funktion

Syntax

Argumente

Gibt zurück

Diagnostik

Kommentare

Verwenden von SQLGetData

Abrufen von Daten mit variabler Länge in Teilen

Abrufen von streamten Ausgabeparametern

Abrufen von Daten mit SQLGetData

Deskriptoren und SQLGetData

Codebeispiel

Verwandte Funktionen

Weitere Informationen

Feedback

Zusätzliche Ressourcen