SQLGetData, functie

Artikel
01/02/2025

conformance
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ISO 92

Samenvattings-
SQLGetData gegevens ophaalt voor één kolom in de resultatenset of voor één parameter nadat SQLParamData- SQL_PARAM_DATA_AVAILABLE retourneert. Het kan meerdere keren worden aangeroepen om gegevens over de lengte van variabelen op te halen in delen.

Syntaxis

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

Argumenten

StatementHandle-
[Invoer] Instructiehandgreep.

Col_or_Param_Num
[Invoer] Voor het ophalen van kolomgegevens is dit het nummer van de kolom waarvoor gegevens moeten worden geretourneerd. Kolommen met resultatensets worden genummerd in toenemende kolomvolgorde vanaf 1. De kolom bladwijzer is kolomnummer 0; dit kan alleen worden opgegeven als bladwijzers zijn ingeschakeld.

Voor het ophalen van parametergegevens is dit het rangtelwoord van de parameter, die begint bij 1.

TargetType-
[Invoer] De type-id van het C-gegevenstype van de *TargetValuePtr buffer. Zie de sectie C-gegevenstypen in bijlage D: Gegevenstypen voor een lijst met geldige C-gegevenstypen en type-id's.

Als TargetType- is SQL_ARD_TYPE, gebruikt het stuurprogramma de type-id die is opgegeven in het SQL_DESC_CONCISE_TYPE veld van de ARD. Als TargetType- is SQL_APD_TYPE, gebruikt SQLGetData- hetzelfde C-gegevenstype dat is opgegeven in SQLBindParameter-. Anders overschrijft het C-gegevenstype dat is opgegeven in SQLGetData het C-gegevenstype dat is opgegeven in SQLBindParameter-. Als het SQL_C_DEFAULT is, selecteert het stuurprogramma het standaardgegevenstype C op basis van het SQL-gegevenstype van de bron.

U kunt ook een uitgebreid C-gegevenstype opgeven. Zie C-gegevenstypen in ODBC-voor meer informatie.

TargetValuePtr-
[Uitvoer] Wijs de buffer aan waarin de gegevens moeten worden geretourneerd.

TargetValuePtr- kan niet NULL zijn.

BufferLength-
[Invoer] Lengte van de *TargetValuePtr buffer in bytes.

Het stuurprogramma gebruikt BufferLength- om te voorkomen dat u langs het einde van de *TargetValuePtr buffer schrijft bij het retourneren van gegevens van variabele lengte, zoals teken of binaire gegevens. Houd er rekening mee dat het stuurprogramma het teken null-beëindiging telt bij het retourneren van tekengegevens naar *TargetValuePtr. * TargetValuePtr- moet daarom ruimte bevatten voor het teken null-beëindiging, anders worden de gegevens afgekapt door het stuurprogramma.

Wanneer het stuurprogramma gegevens met een vaste lengte retourneert, zoals een geheel getal of een datumstructuur, negeert het stuurprogramma BufferLength en wordt ervan uitgegaan dat de buffer groot genoeg is om de gegevens op te slaan. Het is daarom belangrijk dat de toepassing een grote buffer toewijst voor gegevens met een vaste lengte of dat het stuurprogramma voorbij het einde van de buffer schrijft.

SQLGetData- retourneert SQLSTATE HY090 (ongeldige tekenreeks- of bufferlengte) wanneer BufferLength- kleiner is dan 0, maar niet wanneer BufferLength- 0 is.

StrLen_or_IndPtr
[Uitvoer] Wijs de buffer aan waarin de lengte of indicatorwaarde moet worden geretourneerd. Als dit een null-aanwijzer is, wordt er geen lengte of indicatorwaarde geretourneerd. Hiermee wordt een fout geretourneerd wanneer de opgehaalde gegevens NULL zijn.

SQLGetData- kan de volgende waarden retourneren in de lengte/indicatorbuffer:

De lengte van de gegevens die beschikbaar zijn om te retourneren
SQL_NO_TOTAL
SQL_NULL_DATA

Zie Lengte-/indicatorwaarden gebruiken en Opmerkingen in dit onderwerp voor meer informatie.

Retourneert

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

Diagnostiek

Wanneer SQLGetData- SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec- aan te roepen met een HandleType- van SQL_HANDLE_STMT en een Handle van StatementHandle. De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLGetData- en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

SQLSTATE	Fout	Beschrijving
01000	Algemene waarschuwing	Stuurprogrammaspecifiek informatiebericht. (Functie retourneert SQL_SUCCESS_WITH_INFO.)
01004	Tekenreeksgegevens, rechts afgekapt	Niet alle gegevens voor de opgegeven kolom, Col_or_Param_Num, kunnen worden opgehaald in één aanroep naar de functie. SQL_NO_TOTAL of de lengte van de gegevens die in de opgegeven kolom blijven voordat de huidige aanroep naar SQLGetData- wordt geretourneerd in *StrLen_or_IndPtr. (Functie retourneert SQL_SUCCESS_WITH_INFO.) Zie 'Opmerkingen' voor meer informatie over het gebruik van meerdere aanroepen voor SQLGetData voor één kolom.
01S07	Breukafkapping	De geretourneerde gegevens voor een of meer kolommen zijn afgekapt. Voor numerieke gegevenstypen is het breukgedeelte van het getal afgekapt. Voor tijd-, tijdstempel- en intervalgegevenstypen die een tijdonderdeel bevatten, is het breukgedeelte van de tijd afgekapt. (Functie retourneert SQL_SUCCESS_WITH_INFO.)
07006	Schending van kenmerk van beperkt gegevenstype	De gegevenswaarde van een kolom in de resultatenset kan niet worden geconverteerd naar het C-gegevenstype dat is opgegeven door het argument TargetType.
07009	Ongeldige descriptorindex	De waarde die is opgegeven voor het argument Col_or_Param_Num was 0 en het kenmerk SQL_ATTR_USE_BOOKMARKS instructie is ingesteld op SQL_UB_OFF. De waarde die is opgegeven voor het argument Col_or_Param_Num groter was dan het aantal kolommen in de resultatenset. De Col_or_Param_Num-waarde was niet gelijk aan de rangtel van de parameter die beschikbaar is. (DM) De opgegeven kolom is gebonden. Deze beschrijving is niet van toepassing op stuurprogramma's die de SQL_GD_BOUND bitmasker voor de optie SQL_GETDATA_EXTENSIONS in SQLGetInfo-retourneren. (DM) Het aantal van de opgegeven kolom is kleiner dan of gelijk aan het aantal van de hoogste afhankelijke kolom. Deze beschrijving is niet van toepassing op stuurprogramma's die het SQL_GD_ANY_COLUMN bitmasker voor de optie SQL_GETDATA_EXTENSIONS in SQLGetInfo-retourneren. (DM) De toepassing heeft al SQLGetData- voor de huidige rij aangeroepen; het nummer van de kolom die in de huidige oproep is opgegeven, kleiner was dan het nummer van de kolom die in de voorgaande aanroep is opgegeven; en het stuurprogramma retourneert de SQL_GD_ANY_ORDER bitmasker voor de SQL_GETDATA_EXTENSIONS optie niet in SQLGetInfo. (DM) Het argument TargetType is SQL_ARD_TYPE en de Col_or_Param_Num descriptorrecord in de ARD heeft de consistentiecontrole mislukt. (DM) Het argument TargetType is SQL_ARD_TYPE en de waarde in het SQL_DESC_COUNT veld van de ARD is kleiner dan het argument Col_or_Param_Num.
08S01	Communicatiekoppelingsfout	De communicatiekoppeling tussen het stuurprogramma en de gegevensbron waarmee het stuurprogramma is verbonden, is mislukt voordat de verwerking van de functie is voltooid.
22002	Indicatorvariabele vereist, maar niet opgegeven	StrLen_or_IndPtr was een null-aanwijzer en NULL-gegevens zijn opgehaald.
22003	Numerieke waarde buiten het bereik	Als u de numerieke waarde (als numeriek of tekenreeks) voor de kolom retourneert, wordt het gehele (in plaats van fractionele) deel van het getal afgekapt. Zie bijlage D: gegevenstypenvoor meer informatie.
22007	Ongeldige datum/tijd-notatie	De tekenkolom in de resultatenset is gebonden aan een C-datum-, tijd- of tijdstempelstructuur en de waarde in de kolom was respectievelijk een ongeldige datum, tijd of tijdstempel. Zie bijlage D: gegevenstypenvoor meer informatie.
22012	Delen door nul	Een waarde van een rekenkundige expressie die heeft geresulteerd in delen door nul, is geretourneerd.
22015	Intervalveldoverloop	Het toewijzen van een exact numeriek of interval-SQL-type aan een interval C-type heeft een verlies van significante cijfers in het voorloopveld veroorzaakt. Bij het retourneren van gegevens naar een interval C-type was er geen weergave van de waarde van het SQL-type in het interval C-type.
22018	Ongeldige tekenwaarde voor cast-specificatie	Er is een tekenkolom in de resultatenset geretourneerd naar een teken C-buffer en de kolom bevat een teken waarvoor de tekenset van de buffer niet werd weergegeven. Het C-type was een exacte of geschatte numerieke waarde, een datum/tijd of een gegevenstype interval; het SQL-type van de kolom was een gegevenstype voor tekens; en de waarde in de kolom was geen geldige letterlijke waarde van het afhankelijke C-type.
24000	Ongeldige cursorstatus	(DM) De functie is aangeroepen zonder eerst SQLFetch of SQLFetchScroll- aan te roepen om de cursor op de vereiste rij met gegevens te plaatsen. (DM) De StatementHandle- heeft een uitgevoerde status, maar er is geen resultatenset gekoppeld aan de StatementHandle-. Er is een cursor geopend op de StatementHandle- en SQLFetch of SQLFetchScroll is aangeroepen, maar de cursor is vóór het begin van de resultatenset of na het einde van de resultatenset geplaatst.
HY000	Algemene fout	Er is een fout opgetreden waarvoor er geen specifieke SQLSTATE is en waarvoor geen implementatiespecifieke SQLSTATE is gedefinieerd. Het foutbericht dat wordt geretourneerd door SQLGetDiagRec- in de MessageText buffer beschrijft de fout en de oorzaak ervan.
HY001	Fout bij geheugentoewijzing	Het stuurprogramma kan geen geheugen toewijzen dat nodig is om de uitvoering of voltooiing van de functie te ondersteunen.
HY003	Programmatype buiten bereik	(DM) Het argument TargetType is geen geldig gegevenstype, SQL_C_DEFAULT, SQL_ARD_TYPE (in het geval van het ophalen van kolomgegevens) of SQL_APD_TYPE (in geval van het ophalen van parametergegevens). (DM) Het argument Col_or_Param_Num is 0 en het argument TargetType- is niet SQL_C_BOOKMARK voor een bladwijzer met vaste lengte of SQL_C_VARBOOKMARK voor een bladwijzer met een variabele lengte.
HY008	Bewerking geannuleerd	Asynchrone verwerking is ingeschakeld voor de StatementHandle-. De functie is aangeroepen en voordat de uitvoering werd voltooid, SQLCancel of SQLCancelHandle werd aangeroepen op de StatementHandle-en werd de functie opnieuw aangeroepen op de StatementHandle-. De functie is aangeroepen en voordat de uitvoering is voltooid, werd SQLCancel of SQLCancelHandle aangeroepen op de StatementHandle- uit een andere thread in een multithread-toepassing en werd de functie opnieuw aangeroepen op de StatementHandle-.
HY009	Ongeldig gebruik van null-aanwijzer	(DM) Het argument TargetValuePtr was een null-aanwijzer.
HY010	Fout in functiereeks	(DM) De opgegeven StatementHandle- heeft geen uitgevoerde status. De functie is aangeroepen zonder eerst SQLExecDirectaan te roepen, SQLExecute of een catalogusfunctie. (DM) Er is een asynchroon uitgevoerde functie aangeroepen voor de verbindingsgreep die is gekoppeld aan de StatementHandle-. Deze asynchrone functie werd nog steeds uitgevoerd toen de SQLGetData--functie werd aangeroepen. (DM) Een asynchroon uitgevoerde functie (niet deze) is aangeroepen voor de StatementHandle- en werd nog steeds uitgevoerd toen deze functie werd aangeroepen. (DM) SQLExecute, SQLExecDirect, SQLBulkOperationsof SQLSetPos is aangeroepen voor de StatementHandle- en SQL_NEED_DATA geretourneerd. Deze functie is aangeroepen voordat gegevens werden verzonden voor alle parameters of kolommen voor uitvoering van gegevens. (DM) De StatementHandle- heeft een uitgevoerde status, maar er is geen resultatenset gekoppeld aan de StatementHandle-. Een aanroep van SQLExecute-, SQLExecDirectof SQLMoreResults geretourneerd SQL_PARAM_DATA_AVAILABLE, maar SQLGetData- is aangeroepen in plaats van SQLParamData.
HY013	Fout bij geheugenbeheer	De functie-aanroep kan niet worden verwerkt omdat de onderliggende geheugenobjecten niet kunnen worden geopend, mogelijk vanwege weinig geheugen.
HY090	Ongeldige tekenreeks- of bufferlengte	(DM) De waarde die is opgegeven voor argument BufferLength was kleiner dan 0. De waarde die is opgegeven voor argument BufferLength- was kleiner dan 4, het argument Col_or_Param_Num is ingesteld op 0 en het stuurprogramma was een ODBC 2.x-stuurprogramma.
HY109	Ongeldige cursorpositie	De cursor is positioned (by SQLSetPos, SQLFetch, SQLFetchScrollof SQLBulkOperations) op een rij die is verwijderd of niet kan worden opgehaald. De cursor was een cursor met alleen-doorsturen en de grootte van de rijenset was groter dan één.
HY117	De verbinding is onderbroken vanwege een onbekende transactiestatus. Alleen de verbinding verbreken en alleen-lezenfuncties zijn toegestaan.	(DM) Zie SQLEndTran Functionvoor meer informatie over de onderbroken status.
HYC00	Optionele functie niet geïmplementeerd	Het stuurprogramma of de gegevensbron biedt geen ondersteuning voor het gebruik van SQLGetData- met meerdere rijen in SQLFetchScroll-. Deze beschrijving is niet van toepassing op stuurprogramma's die het SQL_GD_BLOCK bitmasker voor de SQL_GETDATA_EXTENSIONS optie retourneren in SQLGetInfo-. Het stuurprogramma of de gegevensbron biedt geen ondersteuning voor de conversie die is opgegeven door de combinatie van het TargetType argument en het SQL-gegevenstype van de bijbehorende kolom. Deze fout is alleen van toepassing wanneer het SQL-gegevenstype van de kolom is toegewezen aan een stuurprogrammaspecifiek SQL-gegevenstype. Het stuurprogramma ondersteunt alleen ODBC 2.x, en het argument TargetType was een van de volgende: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT en een van de interval C-gegevenstypen die worden vermeld in C-gegevenstypen in bijlage D: gegevenstypen. Het stuurprogramma ondersteunt alleen ODBC-versies vóór 3.50 en het argument TargetType is SQL_C_GUID.
HYT01	Time-out voor verbinding verlopen	De time-outperiode voor de verbinding is verlopen voordat de gegevensbron op de aanvraag heeft gereageerd. De time-outperiode voor de verbinding wordt ingesteld via SQLSetConnectAttr-, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Stuurprogramma biedt geen ondersteuning voor deze functie	(DM) Het stuurprogramma dat overeenkomt met de StatementHandle- biedt geen ondersteuning voor de functie.
IM017	Polling is uitgeschakeld in de asynchrone meldingsmodus	Wanneer het meldingsmodel wordt gebruikt, wordt polling uitgeschakeld.
IM018	SQLCompleteAsync- is niet aangeroepen om de vorige asynchrone bewerking op deze ingang te voltooien.	Als de vorige functieaanroep op de ingang SQL_STILL_EXECUTING retourneert en als de meldingsmodus is ingeschakeld, moet SQLCompleteAsync- worden aangeroepen op de ingang om de bewerking na verwerking uit te voeren en de bewerking te voltooien.

Opmerkingen

SQLGetData- retourneert de gegevens in een opgegeven kolom. SQLGetData- kan alleen worden aangeroepen nadat een of meer rijen zijn opgehaald uit de resultatenset door SQLFetch, SQLFetchScrollof SQLExtendedFetch. Als gegevens met een variabele lengte te groot zijn om te worden geretourneerd in één aanroep naar SQLGetData- (vanwege een beperking in de toepassing), kunnen SQLGetData- deze in delen ophalen. Het is mogelijk om sommige kolommen in een rij te binden en SQLGetData- aan te roepen voor anderen, hoewel dit onderhevig is aan enkele beperkingen. Zie Lange gegevens ophalenvoor meer informatie.

Zie Uitvoerparameters ophalen met BEHULP van SQLGetDatavoor informatie over het gebruik van SQLGetData- met gestreamde uitvoerparameters.

SQLGetData gebruiken

Als het stuurprogramma geen extensies voor SQLGetData-ondersteunt, kan de functie alleen gegevens retourneren voor niet-afhankelijke kolommen met een getal dat groter is dan die van de laatste afhankelijke kolom. Bovendien moet binnen een rij met gegevens de waarde van het argument Col_or_Param_Num in elke aanroep naar SQLGetData- groter zijn dan of gelijk zijn aan de waarde van Col_or_Param_Num in de vorige aanroep; Dat wil gezegd, gegevens moeten worden opgehaald in toenemende volgorde van kolomnummers. Als er ten slotte geen extensies worden ondersteund, kan SQLGetData- niet worden aangeroepen als de grootte van de rijenset groter is dan 1.

Stuurprogramma's kunnen deze beperkingen versoepelen. Om te bepalen welke beperkingen een stuurprogramma versoepelen, roept een toepassing SQLGetInfo aan met een van de volgende SQL_GETDATA_EXTENSIONS opties:

SQL_GD_OUTPUT_PARAMS = SQLGetData- kan worden aangeroepen om uitvoerparameterwaarden te retourneren. Zie Uitvoerparameters ophalen met behulp van SQLGetDatavoor meer informatie.
SQL_GD_ANY_COLUMN. Als deze optie wordt geretourneerd, kan SQLGetData- worden aangeroepen voor een niet-afhankelijke kolom, inclusief die vóór de laatste afhankelijke kolom.
SQL_GD_ANY_ORDER. Als deze optie wordt geretourneerd, kan SQLGetData- in elke volgorde worden aangeroepen voor niet-afhankelijke kolommen.
SQL_GD_BLOCK. Als deze optie wordt geretourneerd door SQLGetInfo- voor het SQL_GETDATA_EXTENSIONS InfoType, ondersteunt het stuurprogramma aanroepen naar SQLGetData- wanneer de rijset groter is dan 1 en de toepassing SQLSetPos aanroept met de optie SQL_POSITION om de cursor op de juiste rij te plaatsen voordat SQLGetData wordt aangeroepen.
SQL_GD_BOUND. Als deze optie wordt geretourneerd, kan SQLGetData- worden aangeroepen voor afhankelijke kolommen en niet-afhankelijke kolommen.

Er zijn twee uitzonderingen op deze beperkingen en het vermogen van een bestuurder om ze te ontspannen. Ten eerste moet SQLGetData- nooit worden aangeroepen voor een cursor die alleen-doorsturen is wanneer de rijset groter is dan 1. Ten tweede, als een stuurprogramma bladwijzers ondersteunt, moet het altijd ondersteuning bieden voor het aanroepen van SQLGetData- voor kolom 0, zelfs als het niet toestaat dat toepassingen SQLGetData- aanroepen voor andere kolommen vóór de laatste afhankelijke kolom. (Wanneer een toepassing werkt met een ODBC 2*.x*-stuurprogramma, SQLGetData- retourneert een bladwijzer wanneer deze wordt aangeroepen met Col_or_Param_Num gelijk aan 0 na een aanroep naar SQLFetch, omdat SQLFetch- is toegewezen door ODBC 3*.x* Driver Manager om SQLExtendedFetch te met een FetchOrientation- van SQL_FETCH_NEXT, en SQLGetData- met een Col_or_Param_Num van 0 is toegewezen door de ODBC 3*.x* Driver Manager om SQLGetStmtOption- te met een fOption- van SQL_GET_BOOKMARK.)

SQLGetData- kan niet worden gebruikt om de bladwijzer voor een rij op te halen die zojuist is ingevoegd door SQLBulkOperations aan te roepen met de optie SQL_ADD, omdat de cursor niet in de rij is geplaatst. Een toepassing kan de bladwijzer voor een dergelijke rij ophalen door kolom 0 te binden voordat SQLBulkOperations- met SQL_ADD wordt aangeroepen. In dat geval retourneert SQLBulkOperations de bladwijzer in de afhankelijke buffer. SQLFetchScroll- kan vervolgens worden aangeroepen met SQL_FETCH_BOOKMARK om de cursor op die rij te verplaatsen.

Als het argument TargetType een gegevenstype interval is, worden respectievelijk de standaardintervalprecisie (2) en de standaardprecisie van het interval (6), zoals ingesteld in de velden SQL_DESC_DATETIME_INTERVAL_PRECISION en SQL_DESC_PRECISION van de ARD, gebruikt voor de gegevens. Als het argument TargetType een SQL_C_NUMERIC gegevenstype is, worden de standaardprecisie (door het stuurprogramma gedefinieerd) en de standaardschaal (0), zoals ingesteld in de velden SQL_DESC_PRECISION en SQL_DESC_SCALE van de ARD, gebruikt voor de gegevens. Als een standaardprecisie of schaal niet geschikt is, moet de toepassing expliciet het juiste descriptorveld instellen door een aanroep naar SQLSetDescField- of SQLSetDescRec-. Het veld SQL_DESC_CONCISE_TYPE kan worden ingesteld op SQL_C_NUMERIC en SQLGetData- aanroepen met een TargetType argument van SQL_ARD_TYPE, waardoor de precisie- en schaalwaarden in de descriptorvelden worden gebruikt.

Notitie

In ODBC 2*.x* stellen toepassingen TargetType in op SQL_C_DATE, SQL_C_TIME of SQL_C_TIMESTAMP om aan te geven dat *TargetValuePtr- een datum-, tijd- of tijdstempelstructuur is. In ODBC 3*.x*stellen toepassingen TargetType- in op SQL_C_TYPE_DATE, SQL_C_TYPE_TIME of SQL_C_TYPE_TIMESTAMP. Driver Manager maakt indien nodig de juiste toewijzingen op basis van de toepassing en de versie van het stuurprogramma.

Variable-Length gegevens ophalen in onderdelen

SQLGetData- kunnen worden gebruikt om gegevens op te halen uit een kolom met gegevens met een variabele lengte in onderdelen. Dat wil gezegd, wanneer de id van het SQL-gegevenstype van de kolom wordt SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY of een stuurprogrammaspecifieke id voor een type variabele lengte.

Als u gegevens uit een kolom in delen wilt ophalen, roept de toepassing SQLGetData meerdere keren achter elkaar aan voor dezelfde kolom. Bij elke aanroep retourneert SQLGetData het volgende deel van de gegevens. Het is aan de toepassing om de onderdelen opnieuw samen te stellen, waarbij het null-beëindigingsteken wordt verwijderd uit tussenliggende delen van tekengegevens. Als er meer gegevens zijn om te retourneren of onvoldoende buffer is toegewezen voor het afsluitteken, retourneert SQLGetData- SQL_SUCCESS_WITH_INFO en SQLSTATE 01004 (gegevens afgekapt). Wanneer het laatste deel van de gegevens wordt geretourneerd, retourneert SQLGetData- SQL_SUCCESS. Noch SQL_NO_TOTAL noch nul kunnen worden geretourneerd bij de laatste geldige aanroep om gegevens op te halen uit een kolom, omdat de toepassing dan niet weet hoeveel van de gegevens in de toepassingsbuffer geldig is. Als SQLGetData- hierna wordt aangeroepen, wordt SQL_NO_DATA geretourneerd. Zie de volgende sectie' 'Gegevens ophalen met SQLGetData' voor meer informatie.

Bladwijzers met variabele lengte kunnen worden geretourneerd in delen door SQLGetData-. Net als bij andere gegevens retourneert een aanroep van SQLGetData om bladwijzers met variabele lengte in delen te retourneren SQLSTATE 01004 (tekenreeksgegevens, rechts afgekapt) en SQL_SUCCESS_WITH_INFO wanneer er meer gegevens moeten worden geretourneerd. Dit verschilt van het geval wanneer een bladwijzer met variabele lengte wordt afgekapt door een aanroep naar SQLFetch of SQLFetchScroll, die SQL_ERROR en SQLSTATE 22001 retourneert (tekenreeksgegevens, rechts afgekapt).

SQLGetData- kan niet worden gebruikt om gegevens met een vaste lengte in delen te retourneren. Als SQLGetData- meer dan één keer in een rij wordt aangeroepen voor een kolom met gegevens met een vaste lengte, wordt SQL_NO_DATA geretourneerd voor alle aanroepen na de eerste keer.

Streamed Output Parameters ophalen

Als een stuurprogramma gestreamde uitvoerparameters ondersteunt, kan een toepassing SQLGetData- aanroepen met een kleine buffer om een grote parameterwaarde op te halen. Zie Uitvoerparameters ophalen met behulp van SQLGetDatavoor meer informatie over de gestreamde uitvoerparameter.

Gegevens ophalen met SQLGetData

Als u gegevens voor de opgegeven kolom wilt retourneren, voert SQLGetData- de volgende reeks stappen uit:

Retourneert SQL_NO_DATA als deze al alle gegevens voor de kolom heeft geretourneerd.
Hiermee stelt u *StrLen_or_IndPtr in op SQL_NULL_DATA als de gegevens NULL zijn. Als de gegevens NULL zijn en StrLen_or_IndPtr een null-aanwijzer was, retourneert SQLGetData- SQLSTATE 22002 (indicatorvariabele vereist maar niet opgegeven).

Als de gegevens voor de kolom niet NULL zijn, gaat SQLGetData- verder met stap 3.
Als het kenmerk SQL_ATTR_MAX_LENGTH instructie is ingesteld op een niet-nulwaarde, als de kolom teken- of binaire gegevens bevat en als SQLGetData- niet eerder is aangeroepen voor de kolom, worden de gegevens afgekapt tot SQL_ATTR_MAX_LENGTH bytes.

Notitie

Het kenmerk SQL_ATTR_MAX_LENGTH instructie is bedoeld om het netwerkverkeer te verminderen. Deze wordt over het algemeen geïmplementeerd door de gegevensbron, waarmee de gegevens worden afgekapt voordat ze via het netwerk worden geretourneerd. Stuurprogramma's en gegevensbronnen zijn niet vereist om deze te ondersteunen. Om ervoor te zorgen dat gegevens worden afgekapt tot een bepaalde grootte, moet een toepassing een buffer van die grootte toewijzen en de grootte opgeven in het argument BufferLength.
Converteert de gegevens naar het type dat is opgegeven in TargetType. De gegevens krijgen de standaardprecisie en schaal voor dat gegevenstype. Als TargetType- is SQL_ARD_TYPE, wordt het gegevenstype in het SQL_DESC_CONCISE_TYPE veld van de ARD gebruikt. Als TargetType- is SQL_ARD_TYPE, krijgen de gegevens de precisie en schaal in de velden SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION en SQL_DESC_SCALE van de ARD, afhankelijk van het gegevenstype in het SQL_DESC_CONCISE_TYPE veld. Als een standaardprecisie of schaal niet geschikt is, moet de toepassing expliciet het juiste descriptorveld instellen door een aanroep naar SQLSetDescField- of SQLSetDescRec-.
Als de gegevens zijn geconverteerd naar een gegevenstype met variabele lengte, zoals teken of binair, controleert SQLGetData of de lengte van de gegevens groter is dan BufferLength-. Als de lengte van tekengegevens (inclusief het teken null-beëindiging) groter is dan BufferLength-, worden de gegevens SQLGetData afgekapt tot BufferLength minder lengte van een null-beëindigingsteken. Vervolgens worden de gegevens door null beëindigd. Als de lengte van binaire gegevens de lengte van de gegevensbuffer overschrijdt, SQLGetData deze afkapt tot BufferLength bytes.

Als de opgegeven gegevensbuffer te klein is om het teken null-beëindiging op te slaan, retourneert SQLGetData SQL_SUCCESS_WITH_INFO en SQLSTATE 01004.

SQLGetData nooit gegevens kapt die zijn geconverteerd naar gegevenstypen met een vaste lengte; er wordt altijd van uitgegaan dat de lengte van *TargetValuePtr de grootte van het gegevenstype is.
Hiermee plaatst u de geconverteerde (en mogelijk afgekapte) gegevens in *TargetValuePtr. Houd er rekening mee dat SQLGetData- geen gegevens buiten de regel kan retourneren.
Hiermee wordt de lengte van de gegevens in *StrLen_or_IndPtr. Als StrLen_or_IndPtr een null-aanwijzer was, retourneert SQLGetData- de lengte niet.
- Voor teken- of binaire gegevens is dit de lengte van de gegevens na conversie en vóór afkapping vanwege BufferLength. Als het stuurprogramma de lengte van de gegevens na conversie niet kan bepalen, zoals soms het geval is bij lange gegevens, wordt SQL_SUCCESS_WITH_INFO geretourneerd en wordt de lengte ingesteld op SQL_NO_TOTAL. (De laatste aanroep van SQLGetData- moet altijd de lengte van de gegevens retourneren, niet nul of SQL_NO_TOTAL.) Als de gegevens zijn afgekapt vanwege het kenmerk SQL_ATTR_MAX_LENGTH instructie, wordt de waarde van dit kenmerk ( in plaats van de werkelijke lengte ) geplaatst in *StrLen_or_IndPtr. Dit komt doordat dit kenmerk is ontworpen voor het afkappen van gegevens op de server vóór de conversie, zodat het stuurprogramma geen manier heeft om uit te zoeken wat de werkelijke lengte is. Wanneer SQLGetData meerdere keren achter elkaar wordt aangeroepen voor dezelfde kolom, is dit de lengte van de gegevens die beschikbaar zijn aan het begin van de huidige aanroep; Dat wil gezegd, de lengte neemt af bij elke volgende aanroep.
- Voor alle andere gegevenstypen is dit de lengte van de gegevens na conversie; Dat wil gezegd, het is de grootte van het type waarnaar de gegevens zijn geconverteerd.
Als de gegevens worden afgekapt zonder verlies van significantie tijdens de conversie (bijvoorbeeld het reële getal 1,234 wordt afgekapt wanneer deze wordt geconverteerd naar het gehele getal 1) of omdat BufferLength te klein is (bijvoorbeeld de tekenreeks 'abcdef' wordt geplaatst in een buffer van 4 byte), SQLGetData- SQLSTATE 01004 (gegevens afgekapt) en SQL_SUCCESS_WITH_INFO retourneert. Als gegevens worden afgekapt zonder significantie te verliezen vanwege het kenmerk van de SQL_ATTR_MAX_LENGTH instructie, retourneert SQLGetData- SQL_SUCCESS en wordt SQLSTATE 01004 (gegevens afgekapt) niet geretourneerd.

De inhoud van de afhankelijke gegevensbuffer (als SQLGetData- wordt aangeroepen op een afhankelijke kolom) en de lengte/indicatorbuffer niet is gedefinieerd als SQLGetData- geen SQL_SUCCESS of SQL_SUCCESS_WITH_INFO retourneert.

Opeenvolgende aanroepen naar SQLGetData haalt gegevens op uit de aangevraagde laatste kolom; eerdere verschuivingen worden ongeldig. Wanneer bijvoorbeeld de volgende reeks wordt uitgevoerd:

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

met de tweede aanroep van SQLGetData(icol=n) worden gegevens opgehaald vanaf het begin van de n-kolom. Elke verschuiving in de gegevens vanwege eerdere aanroepen naar SQLGetData- voor de kolom is niet meer geldig.

Descriptors en SQLGetData

SQLGetData- communiceert niet rechtstreeks met descriptorvelden.

Als TargetType- is SQL_ARD_TYPE, wordt het gegevenstype in het SQL_DESC_CONCISE_TYPE veld van de ARD gebruikt. Als TargetType- SQL_ARD_TYPE of SQL_C_DEFAULT is, krijgen de gegevens de precisie en schaal in de velden SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION en SQL_DESC_SCALE velden van de ARD, afhankelijk van het gegevenstype in het SQL_DESC_CONCISE_TYPE veld.

Codevoorbeeld

In het volgende voorbeeld voert een toepassing een INSTRUCTIE SELECT uit om een resultatenset van de klant-id's, namen en telefoonnummers te retourneren, gesorteerd op naam, id en telefoonnummer. Voor elke rij met gegevens wordt SQLFetch- aanroepen om de cursor naar de volgende rij te plaatsen. Het roept SQLGetData- aan om de opgehaalde gegevens op te halen; de buffers voor de gegevens en het geretourneerde aantal bytes worden opgegeven in de aanroep voor SQLGetData-. Ten slotte worden de naam, id en telefoonnummer van elke werknemer afgedrukt.

#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;  
      }  
   }  
}

Voor informatie over	Zien
Opslag toewijzen voor een kolom in een resultatenset	SQLBindCol-
Bulkbewerkingen uitvoeren die niet gerelateerd zijn aan de positie van de blokcursor	SQLBulkOperations-
Verwerking van instructie annuleren	SQLCancel-
Een SQL-instructie uitvoeren	SQLExecDirect-
Een voorbereide SQL-instructie uitvoeren	SQLExecute-
Een gegevensblok ophalen of door een resultatenset schuiven	SQLFetchScroll-
Eén rij met gegevens of een blok gegevens in een doorstuurrichting ophalen	SQLFetch-
Parametergegevens verzenden tijdens uitvoering	SQLPutData-
De cursor plaatsen, gegevens in de rijenset vernieuwen of gegevens in de rijenset bijwerken of verwijderen	SQLSetPos-

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden
uitvoerparameters ophalen met behulp van SQLGetData

Delen via

SQLGetData, functie

Syntaxis

Argumenten

Retourneert

Diagnostiek

Opmerkingen

SQLGetData gebruiken

Variable-Length gegevens ophalen in onderdelen

Streamed Output Parameters ophalen

Gegevens ophalen met SQLGetData

Descriptors en SQLGetData

Codevoorbeeld

Zie ook

Feedback

Aanvullende resources

Delen via

SQLGetData, functie

Syntaxis

Argumenten

Retourneert

Diagnostiek

Opmerkingen

SQLGetData gebruiken

Variable-Length gegevens ophalen in onderdelen

Streamed Output Parameters ophalen

Gegevens ophalen met SQLGetData

Descriptors en SQLGetData

Codevoorbeeld

Verwante functies

Zie ook

Feedback

Aanvullende resources