SQLFetch-functie

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

Samenvatting
SQLFetch haalt de volgende rijenset met gegevens op uit de resultatenset en retourneert gegevens voor alle afhankelijke kolommen.

Syntaxis

  
SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle);  

Argumenten

StatementHandle-
[Invoer] Instructiehandgreep.

Retouren

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

Diagnostiek

Wanneer SQLFetch SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door de SQLGetDiagRec-functie aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle of StatementHandle. De volgende tabel bevat de SQLSTATE-waarden die doorgaans worden geretourneerd door SQLFetch en legt elk 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. Als er een fout optreedt in één kolom, kan SQLGetDiagField worden aangeroepen met een DiagIdentifier van SQL_DIAG_COLUMN_NUMBER om de kolom te bepalen waarop de fout is opgetreden; en SQLGetDiagField kunnen worden aangeroepen met een DiagIdentifier van SQL_DIAG_ROW_NUMBER om de rij te bepalen die die kolom bevat.

Voor al die SQLSTATEs die SQL_SUCCESS_WITH_INFO of SQL_ERROR (behalve 01xxx SQLSTATEs) kunnen retourneren, wordt SQL_SUCCESS_WITH_INFO geretourneerd als er een fout optreedt in een of meer, maar niet alle rijen van een multirow-bewerking en SQL_ERROR wordt geretourneerd als er een fout optreedt bij een bewerking met één rij.

Opmerkingen

SQLFetch retourneert de volgende rijenset in de resultatenset. Deze kan alleen worden aangeroepen zolang er een resultatenset bestaat: dat wil gezegd, na een aanroep die een resultatenset maakt en voordat de cursor over die resultatenset wordt gesloten. Als er kolommen afhankelijk zijn, worden de gegevens in die kolommen geretourneerd. Als de toepassing een aanwijzer heeft opgegeven voor een rijstatusmatrix of een buffer waarin het aantal opgehaalde rijen moet worden geretourneerd, retourneert SQLFetch ook deze informatie. Aanroepen naar SQLFetch kunnen worden gemengd met aanroepen naar SQLFetchScroll , maar kunnen niet worden gemengd met aanroepen naar SQLExtendedFetch. Zie Een rij met gegevens ophalen voor meer informatie.

Als een ODBC 3*.x*-toepassing werkt met een ODBC 2*.x*-stuurprogramma, wijst Driver Manager SQLFetch-aanroepen toe aan SQLExtendedFetch voor een ODBC 2*.x*-stuurprogramma dat ONDERSTEUNING biedt voor SQLExtendedFetch. Als het ODBC 2*.x*-stuurprogramma SQLExtendedFetch niet ondersteunt, wijst Driver Manager SQLFetch-aanroepen toe aan SQLFetch in het ODBC 2*.x*-stuurprogramma, waardoor slechts één rij kan worden opgehaald.

Zie Voor meer informatie blokcursors, schuifbare cursors en compatibiliteit met eerdere versies in bijlage G: stuurprogrammarichtlijnen voor compatibiliteit met eerdere versies.

De cursor plaatsen

Wanneer de resultatenset wordt gemaakt, wordt de cursor vóór het begin van de resultatenset geplaatst. SQLFetch haalt de volgende rijenset op. Het is gelijk aan het aanroepen van SQLFetchScroll met FetchOrientation ingesteld op SQL_FETCH_NEXT. Zie Cursors en Cursors blokkeren voor meer informatie over cursors.

Het kenmerk SQL_ATTR_ROW_ARRAY_SIZE instructie geeft het aantal rijen in de rijenset op. Als de rijenset die wordt opgehaald door SQLFetch het einde van de resultatenset overlapt, retourneert SQLFetch een gedeeltelijke rijenset. Als S + R - 1 groter is dan L, waarbij S de beginrij is van de rijenset die wordt opgehaald, is R de grootte van de rijenset en L de laatste rij in de resultatenset, zijn alleen de eerste L - S + 1 rijen van de rijenset geldig. De resterende rijen zijn leeg en hebben een status van SQL_ROW_NOROW.

Nadat SQLFetch is geretourneerd, is de huidige rij de eerste rij van de rijenset.

De regels in de volgende tabel beschrijven cursorpositie na een aanroep naar SQLFetch, op basis van de voorwaarden in de tweede tabel in deze sectie.

[1] Als de grootte van de rijenset wordt gewijzigd tussen ophalen, is dit de grootte van de rijenset die is gebruikt bij het vorige ophalen.

[2] Als de grootte van de rijenset wordt gewijzigd tussen ophalen, is dit de grootte van de rijenset die is gebruikt met de nieuwe ophaalbewerking.

Stel dat een resultatenset 100 rijen heeft en dat de grootte van de rijenset 5 is. In de volgende tabel ziet u de rijenset en retourcode die door SQLFetch wordt geretourneerd voor verschillende beginposities.

Gegevens retourneren in afhankelijke kolommen

Omdat SQLFetch elke rij retourneert, worden de gegevens voor elke afhankelijke kolom in de buffer aan die kolom gekoppeld. Als er geen kolommen zijn gebonden, retourneert SQLFetch geen gegevens, maar verplaatst de blokcursor wel vooruit. De gegevens kunnen nog steeds worden opgehaald met behulp van SQLGetData. Als de cursor een multirow cursor is (dat wil gezegd, de SQL_ATTR_ROW_ARRAY_SIZE groter is dan 1), kan SQLGetData alleen worden aangeroepen als SQL_GD_BLOCK wordt geretourneerd wanneer SQLGetInfo wordt aangeroepen met een InfoType van SQL_GETDATA_EXTENSIONS. (Zie SQLGetData voor meer informatie.)

Voor elke afhankelijke kolom in een rij doet SQLFetch het volgende:

1. Hiermee stelt u de lengte/indicatorbuffer in op SQL_NULL_DATA en gaat u naar de volgende kolom als de gegevens NULL zijn. Als de gegevens NULL zijn en er geen lengte/indicatorbuffer is gebonden, retourneert SQLFetch SQLSTATE 22002 (indicatorvariabele vereist maar niet opgegeven) voor de rij en gaat naar de volgende rij. Zie Bufferadressen in SQLBindCol voor informatie over het bepalen van het adres van de lengte/indicatorbuffer.

   Als de gegevens voor de kolom niet NULL zijn, gaat SQLFetch verder met stap 2.

2. Als het kenmerk SQL_ATTR_MAX_LENGTH instructie is ingesteld op een niet-nulwaarde en de kolom teken- of binaire gegevens bevat, worden de gegevens afgekapt tot SQL_ATTR_MAX_LENGTH bytes.

   Opmerking

   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 deze 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 cbValueMax in SQLBindCol.

3. Converteert de gegevens naar het type dat is opgegeven door TargetType in SQLBindCol.

4. Als de gegevens zijn geconverteerd naar een gegevenstype met variabele lengte, zoals teken of binair, controleert SQLFetch of de lengte van de gegevens groter is dan de lengte van de gegevensbuffer. Als de lengte van tekengegevens (inclusief het teken null-beëindiging) groter is dan de lengte van de gegevensbuffer, kapt SQLFetch de gegevens af tot de lengte van de gegevensbuffer, 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, kapt SQLFetch deze af tot de lengte van de gegevensbuffer. De lengte van de gegevensbuffer wordt opgegeven met BufferLength in SQLBindCol.

   SQLFetch kapt nooit gegevens af die zijn geconverteerd naar gegevenstypen met een vaste lengte; er wordt altijd van uitgegaan dat de lengte van de gegevensbuffer de grootte van het gegevenstype is.

5. Hiermee worden de geconverteerde (en mogelijk afgekapte) gegevens in de gegevensbuffer geplaatst. Zie Bufferadressen in SQLBindCol voor informatie over het bepalen van het adres van de gegevensbuffer.

6. Hiermee wordt de lengte van de gegevens in de lengte/indicatorbuffer geplaatst. Als de indicatorpointer en de lengtepointer beide zijn ingesteld op dezelfde buffer (zoals een aanroep naar SQLBindCol wel), wordt de lengte in de buffer geschreven voor geldige gegevens en SQL_NULL_DATA in de buffer voor NULL-gegevens wordt geschreven. Als er geen lengte-/indicatorbuffer is gebonden, retourneert SQLFetch de lengte niet.

   • Voor teken- of binaire gegevens is dit de lengte van de gegevens na conversie en vóór afkapping omdat de gegevensbuffer te klein is. Als het stuurprogramma de lengte van de gegevens na conversie niet kan bepalen, zoals soms het geval is bij lange gegevens, wordt de lengte ingesteld op SQL_NO_TOTAL. Als gegevens zijn afgekapt vanwege het kenmerk SQL_ATTR_MAX_LENGTH instructie, wordt de waarde van dit kenmerk in de lengte/indicatorbuffer geplaatst in plaats van de werkelijke lengte. 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.

   • 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.

   Zie Bufferadressen in SQLBindCol voor informatie over het bepalen van het adres van de lengte/indicatorbuffer.

7. Als de gegevens worden afgekapt tijdens de conversie zonder verlies van significante cijfers (bijvoorbeeld het reële getal 1,234 wordt afgekapt tot het gehele getal 1 wanneer ze worden geconverteerd), retourneert SQLFetch SQLSTATE 01S07 (fractionele afkapping) en SQL_SUCCESS_WITH_INFO. Als de gegevens worden afgekapt omdat de lengte van de gegevensbuffer te klein is (de tekenreeks 'abcdef' wordt bijvoorbeeld in een buffer van 4 bytes geplaatst), retourneert SQLFetch SQLSTATE 01004 (gegevens afgekapt) en SQL_SUCCESS_WITH_INFO. Als gegevens worden afgekapt vanwege het kenmerk van de SQL_ATTR_MAX_LENGTH-instructie, retourneert SQLFetch SQL_SUCCESS en retourneert SQLSTATE 01S07 (fractionele afkapping) of SQLSTATE 01004 (gegevens afgekapt). Als gegevens worden afgekapt tijdens de conversie met een verlies van significante cijfers (bijvoorbeeld als een SQL_INTEGER waarde groter dan 100.000 is geconverteerd naar een SQL_C_TINYINT), retourneert SQLFetch SQLSTATE 22003 (numerieke waarde buiten het bereik) en SQL_ERROR (als de grootte van de rijset 1 is) of SQL_SUCCESS_WITH_INFO (als de rijset groter is dan 1).

De inhoud van de afhankelijke gegevensbuffer en de lengte/indicatorbuffer zijn niet gedefinieerd als SQLFetch of SQLFetchScroll geen SQL_SUCCESS of SQL_SUCCESS_WITH_INFO retourneert.

Rijstatusmatrix

De matrix rijstatus wordt gebruikt om de status van elke rij in de rijenset te retourneren. Het adres van deze matrix wordt opgegeven met het kenmerk SQL_ATTR_ROW_STATUS_PTR instructie. De matrix wordt toegewezen door de toepassing en moet zoveel elementen bevatten als die zijn opgegeven door het kenmerk SQL_ATTR_ROW_ARRAY_SIZE instructie. De waarden worden ingesteld door SQLFetch, SQLFetchScroll en SQLBulkOperations of SQLSetPos (behalve wanneer ze zijn aangeroepen nadat de cursor is geplaatst door SQLExtendedFetch). Als de waarde van het kenmerk SQL_ATTR_ROW_STATUS_PTR instructie een null-aanwijzer is, retourneren deze functies niet de rijstatus.

De inhoud van de matrixbuffer rijstatus is niet gedefinieerd als SQLFetch of SQLFetchScroll geen SQL_SUCCESS of SQL_SUCCESS_WITH_INFO retourneert.

De volgende waarden worden geretourneerd in de rijstatusmatrix.

[1] Voor sleutelsets, gemengde en dynamische cursors, als een sleutelwaarde wordt bijgewerkt, wordt de rij met gegevens als verwijderd beschouwd en wordt er een nieuwe rij toegevoegd.

[2] Sommige stuurprogramma's kunnen geen updates voor gegevens detecteren en kunnen daarom deze waarde niet retourneren. Een toepassing roept SQLGetInfo aan met de optie SQL_ROW_UPDATES om te bepalen of een stuurprogramma updates voor verwende rijen kan detecteren.

[3] SQLFetch kan deze waarde alleen retourneren wanneer deze is gemengd met aanroepen naar SQLFetchScroll. Dit komt doordat SQLFetch vooruitgaat door de resultatenset en wanneer deze uitsluitend wordt gebruikt, geen rijen verklinkt. Omdat er geen rijen worden verwed, detecteert SQLFetch geen wijzigingen die zijn aangebracht in eerder opgehaalde rijen. Als SQLFetchScroll echter de cursor plaatst voordat eerder opgehaalde rijen worden gebruikt en SQLFetch wordt gebruikt om deze rijen op te halen, kan SQLFetch eventuele wijzigingen in deze rijen detecteren.

[4] Alleen geretourneerd door SQLBulkOperations. Niet ingesteld door SQLFetch of SQLFetchScroll.

Opgehaalde rijen buffer

De opgehaalde rijen worden gebruikt om het aantal opgehaalde rijen te retourneren, inclusief rijen waarvoor geen gegevens zijn geretourneerd omdat er een fout is opgetreden tijdens het ophalen. Met andere woorden, het is het aantal rijen waarvoor de waarde in de rijstatusmatrix niet SQL_ROW_NOROW is. Het adres van deze buffer wordt opgegeven met het kenmerk SQL_ATTR_ROWS_FETCHED_PTR instructie. De buffer wordt toegewezen door de toepassing. Het is ingesteld door SQLFetch en SQLFetchScroll. Als de waarde van het kenmerk SQL_ATTR_ROWS_FETCHED_PTR instructie een null-aanwijzer is, retourneren deze functies niet het aantal opgehaalde rijen. Om het nummer van de huidige rij in de resultatenset te bepalen, kan een toepassing SQLGetStmtAttr aanroepen met het kenmerk SQL_ATTR_ROW_NUMBER.

De inhoud van de opgehaalde buffer voor rijen is niet gedefinieerd als SQLFetch of SQLFetchScroll geen SQL_SUCCESS of SQL_SUCCESS_WITH_INFO retourneert, behalve wanneer SQL_NO_DATA wordt geretourneerd. In dat geval is de waarde in de opgehaalde buffer voor rijen ingesteld op 0.

Foutafhandeling

Fouten en waarschuwingen kunnen van toepassing zijn op afzonderlijke rijen of op de hele functie. Zie Diagnostics en SQLGetDiagField voor meer informatie over diagnostische records.

Fouten en waarschuwingen voor de hele functie

Als een fout van toepassing is op de hele functie, zoals SQLSTATE HYT00 (time-out verlopen) of SQLSTATE 24000 (ongeldige cursorstatus), retourneert SQLFetch SQL_ERROR en de toepasselijke SQLSTATE. De inhoud van de rijensetbuffers is niet gedefinieerd en de cursorpositie is ongewijzigd.

Als een waarschuwing van toepassing is op de hele functie, retourneert SQLFetch SQL_SUCCESS_WITH_INFO en de toepasselijke SQLSTATE. De statusrecords voor waarschuwingen die van toepassing zijn op de hele functie, worden geretourneerd vóór de statusrecords die van toepassing zijn op afzonderlijke rijen.

Fouten en waarschuwingen in afzonderlijke rijen

Als een fout (zoals SQLSTATE 22012 (Delen door nul)) of een waarschuwing (zoals SQLSTATE 01004 (gegevens afgekapt)) van toepassing is op één rij, doet SQLFetch het volgende:

• Hiermee stelt u het bijbehorende element van de rijstatusmatrix in op SQL_ROW_ERROR op fouten of SQL_ROW_SUCCESS_WITH_INFO voor waarschuwingen.

• Voegt nul of meer statusrecords toe die SQLSTATEs bevatten voor de fout of waarschuwing.

• Hiermee stelt u de rij- en kolomnummervelden in de statusrecords in. Als SQLFetch een rij- of kolomnummer niet kan bepalen, wordt dat getal respectievelijk ingesteld op SQL_ROW_NUMBER_UNKNOWN of SQL_COLUMN_NUMBER_UNKNOWN. Als de statusrecord niet van toepassing is op een bepaalde kolom, stelt SQLFetch het kolomnummer in op SQL_NO_COLUMN_NUMBER.

SQLFetch blijft rijen ophalen totdat alle rijen in de rijenset zijn opgehaald. Het retourneert SQL_SUCCESS_WITH_INFO, tenzij er een fout optreedt in elke rij van de rijenset (niet inclusief rijen met status SQL_ROW_NOROW), in welk geval het SQL_ERROR retourneert. Met name als de grootte van de rijenset 1 is en er een fout optreedt in die rij, retourneert SQLFetch SQL_ERROR.

SQLFetch retourneert de statusrecords in rijnummervolgorde. Dat wil gezegd, het retourneert alle statusrecords voor onbekende rijen (indien aanwezig); vervolgens worden alle statusrecords voor de eerste rij (indien aanwezig) geretourneerd, waarna alle statusrecords voor de tweede rij (indien van toepassing) worden geretourneerd, enzovoort. De statusrecords voor elke rij worden geordend volgens de normale regels voor het ordenen van statusrecords; Zie 'Reeks statusrecords' in SQLGetDiagField voor meer informatie.

Descriptors en SQLFetch

In de volgende secties wordt beschreven hoe SQLFetch communiceert met descriptors.

Argumenttoewijzingen

Het stuurprogramma stelt geen descriptorvelden in op basis van de argumenten van SQLFetch.

Andere descriptorvelden

De volgende descriptorvelden worden gebruikt door SQLFetch.

Alle descriptorvelden kunnen ook worden ingesteld via SQLSetDescField.

Afzonderlijke lengte- en indicatorbuffers

Toepassingen kunnen één buffer of twee afzonderlijke buffers binden die kunnen worden gebruikt voor het opslaan van lengte- en indicatorwaarden. Wanneer een toepassing SQLBindCol aanroept, stelt het stuurprogramma de velden SQL_DESC_OCTET_LENGTH_PTR en SQL_DESC_INDICATOR_PTR van de ARD in op hetzelfde adres, dat wordt doorgegeven in het argument StrLen_or_IndPtr . Wanneer een toepassing SQLSetDescField of SQLSetDescRec aanroept, kunnen deze twee velden worden ingesteld op verschillende adressen.

SQLFetch bepaalt of de toepassing afzonderlijke lengte- en indicatorbuffers heeft opgegeven. In dit geval stelt SQLFetch , wanneer de gegevens niet NULL zijn, de indicatorbuffer in op 0 en retourneert de lengte in de lengtebuffer. Wanneer de gegevens NULL zijn, stelt SQLFetch de indicatorbuffer in op SQL_NULL_DATA en wordt de lengtebuffer niet gewijzigd.

Codevoorbeeld

Zie SQLBindCol, SQLColumns, SQLGetData en SQLProcedures.

Verwante functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden