Een rij met gegevens ophalen

Een toepassing roept SQLFetch aan om een rij met gegevens op te halen. SQLFetch kan worden aangeroepen met elk type cursor, maar de cursor van de rijenset wordt alleen verplaatst in een voorwaartse richting. SQLFetch gaat door naar de volgende rij en retourneert de gegevens voor kolommen die zijn gebonden aan aanroepen naar SQLBindCol. Wanneer de cursor het einde van de resultatenset bereikt, retourneert SQLFetch SQL_NO_DATA. Zie SqlBindCol gebruiken voor voorbeelden van het aanroepen van SQLFetch.

Precies hoe SQLFetch wordt geïmplementeerd, is stuurprogrammaspecifiek, maar het algemene patroon is dat het stuurprogramma de gegevens voor afhankelijke kolommen uit de gegevensbron ophaalt, converteert op basis van de typen van de afhankelijke variabelen en plaatst de geconverteerde gegevens in deze variabelen. Als het stuurprogramma geen gegevens kan converteren, retourneert SQLFetch een fout. De toepassing kan doorgaan met het ophalen van rijen, maar de gegevens voor de huidige rij gaan verloren. Wat er gebeurt met de gegevens voor niet-afhankelijke kolommen, is afhankelijk van het stuurprogramma, maar de meeste stuurprogramma's halen deze op en negeren of halen ze nooit op.

Het stuurprogramma stelt ook de waarden in van eventuele lengte-/indicatorbuffers die zijn gebonden. Als de gegevenswaarde voor een kolom NULL is, stelt het stuurprogramma de bijbehorende lengte/indicatorbuffer in op SQL_NULL_DATA. Als de gegevenswaarde niet NULL is, stelt het stuurprogramma de lengte/indicatorbuffer in op de bytelengte van de gegevens na conversie. Als deze lengte niet kan worden bepaald, zoals soms het geval is met lange gegevens die door meer dan één functieoproep worden opgehaald, stelt het stuurprogramma de lengte/indicatorbuffer in op SQL_NO_TOTAL. Voor gegevenstypen met een vaste lengte, zoals gehele getallen en datumstructuren, is de bytelengte de grootte van het gegevenstype.

Voor gegevens met variabele lengte, zoals tekengegevens en binaire gegevens, controleert het stuurprogramma de bytelengte van de geconverteerde gegevens tegen de bytelengte van de buffer die aan de kolom is gebonden; de lengte van de buffer wordt opgegeven in het argument BufferLength in SQLBindCol. Als de bytelengte van de geconverteerde gegevens groter is dan de bytelengte van de buffer, kapt het stuurprogramma de gegevens af om in de buffer te passen, retourneert de niet-afgekorte lengte in de lengte/indicatorbuffer, retourneert SQL_SUCCESS_WITH_INFO en plaatst SQLSTATE 01004 (gegevens afgekort) in de diagnose-informatie. De enige uitzondering hierop is als een bladwijzer met variabele lengte wordt afgekapt wanneer deze wordt geretourneerd door SQLFetch, dat SQLSTATE 22001 retourneert (tekenreeksgegevens, rechts afgekapt).

Gegevens met een vaste lengte worden nooit afgekapt, omdat het stuurprogramma ervan uitgaat dat de grootte van de afhankelijke buffer de grootte van het gegevenstype is. Afkapping van gegevens is meestal zeldzaam, omdat de toepassing meestal een buffer bindt die groot genoeg is om de volledige gegevenswaarde op te slaan; het bepaalt de benodigde grootte van de metagegevens. De toepassing kan echter expliciet een buffer binden die te klein is. Het kan bijvoorbeeld de eerste 20 tekens van een deelbeschrijving of de eerste 100 tekens van een lange tekstkolom ophalen en weergeven.

Tekengegevens moeten door het stuurprogramma worden beëindigd voordat ze worden geretourneerd naar de toepassing, zelfs als deze zijn afgekapt. Het teken null-terminatie is niet opgenomen in de geretourneerde bytelengte, maar vereist wel ruimte in de gereserveerde buffer. Stel dat een toepassing tekenreeksen gebruikt die bestaan uit tekengegevens in de ASCII-tekenset, een stuurprogramma 50 tekens aan gegevens bevat die moeten worden geretourneerd en de buffer van de toepassing 25 bytes lang is. In de buffer van de toepassing retourneert het stuurprogramma de eerste 24 tekens gevolgd door een null-terminatiekarakter. In de lengte/indicatorbuffer wordt een bytelengte van 50 geretourneerd.

De toepassing kan het aantal rijen in de resultatenset beperken door het kenmerk SQL_ATTR_MAX_ROWS instructie in te stellen voordat de instructie wordt uitgevoerd waarmee de resultatenset wordt gemaakt. De preview-modus in een toepassing die wordt gebruikt om rapporten op te maken, heeft bijvoorbeeld slechts voldoende gegevens nodig om de eerste pagina van het rapport weer te geven. Door de grootte van de resultatenset te beperken, zou een dergelijke functie sneller worden uitgevoerd. Dit statementattribuut is bedoeld om netwerkverkeer te verminderen en kan niet door alle stuurprogramma's worden ondersteund.