Lange gegevens ophalen

DBMSs definiëren lange gegevens als elk teken of binaire gegevens over een bepaalde grootte, zoals 255 tekens. Deze gegevens kunnen klein genoeg zijn om in één buffer op te slaan, zoals een deelbeschrijving van enkele duizenden tekens. Het kan echter te lang zijn om in het geheugen op te slaan, zoals lange tekstdocumenten of bitmaps. Omdat dergelijke gegevens niet in één buffer kunnen worden opgeslagen, worden deze opgehaald uit het stuurprogramma in delen met SQLGetData nadat de andere gegevens in de rij zijn opgehaald.

Als u lange gegevens uit een kolom wilt ophalen, roept een toepassing eerst SQLFetchScroll of SQLFetch aan om naar een rij te gaan en de gegevens voor afhankelijke kolommen op te halen. De toepassing roept vervolgens SQLGetData aan. SQLGetData heeft dezelfde argumenten als SQLBindCol: een instructiehandgreep; een kolomnummer; het gegevenstype C, het adres en de bytelengte van een toepassingsvariabele; en het adres van een lengte/indicatorbuffer. Beide functies hebben dezelfde argumenten omdat ze in feite dezelfde taak uitvoeren: ze beschrijven beide een toepassingsvariabele voor het stuurprogramma en geven aan dat de gegevens voor een bepaalde kolom in die variabele moeten worden geretourneerd. De belangrijkste verschillen zijn dat SQLGetData wordt aangeroepen nadat een rij is opgehaald (en ook wel late binding om deze reden wordt genoemd) en dat de binding die is opgegeven door SQLGetData alleen voor de duur van de aanroep duurt.

Met betrekking tot één kolom gedraagt SQLGetData zich als SQLFetch: hiermee worden de gegevens voor de kolom opgehaald, geconverteerd naar het type toepassingsvariabele en wordt deze in die variabele geretourneerd. Het retourneert ook de bytelengte van de gegevens in de lengte/indicatorbuffer. Zie Een rij gegevens ophalen voor meer informatie over hoe SQLFetch gegevens retourneert.

SQLGetData verschilt van SQLFetch in één belangrijk opzicht. Als deze meer dan één keer achter elkaar wordt aangeroepen voor dezelfde kolom, retourneert elke aanroep een opeenvolgend deel van de gegevens. Elke aanroep behalve de laatste aanroep retourneert SQL_SUCCESS_WITH_INFO en SQLSTATE 01004 (tekenreeksgegevens, rechts afgekapt); de laatste aanroep retourneert SQL_SUCCESS. Dit is hoe SQLGetData wordt gebruikt om lange gegevens op te halen in delen. Wanneer er geen gegevens meer moeten worden geretourneerd, retourneert SQLGetData SQL_NO_DATA. De toepassing is verantwoordelijk voor het samenvoegen van de lange gegevens, wat kan betekenen dat de delen van de gegevens worden samengevoegd. Elk onderdeel is null-beëindigd; de toepassing moet het teken null-beëindiging verwijderen als de onderdelen worden samengevoegd. Het ophalen van gegevens in delen kan worden uitgevoerd voor bladwijzers met een variabele lengte en voor andere lange gegevens. De waarde die wordt geretourneerd in de lengte/indicatorbuffer neemt af in elke aanroep door het aantal bytes dat in de vorige aanroep is geretourneerd, hoewel het gebruikelijk is dat het stuurprogramma de hoeveelheid beschikbare gegevens niet kan detecteren en een bytelengte van SQL_NO_TOTAL retourneert. Voorbeeld:

// Declare a binary buffer to retrieve 5000 bytes of data at a time.  
SQLCHAR       BinaryPtr[5000];  
SQLUINTEGER   PartID;  
SQLINTEGER    PartIDInd, BinaryLenOrInd, NumBytes;  
SQLRETURN     rc;   
SQLHSTMT      hstmt;  
  
// Create a result set containing the ID and picture of each part.  
SQLExecDirect(hstmt, "SELECT PartID, Picture FROM Pictures", SQL_NTS);  
  
// Bind PartID to the PartID column.  
SQLBindCol(hstmt, 1, SQL_C_ULONG, &PartID, 0, &PartIDInd);  
  
// Retrieve and display each row of data.  
while ((rc = SQLFetch(hstmt)) != SQL_NO_DATA) {  
   // Display the part ID and initialize the picture.  
   DisplayID(PartID, PartIDInd);  
   InitPicture();  
  
   // Retrieve the picture data in parts. Send each part and the number   
   // of bytes in each part to a function that displays it. The number   
   // of bytes is always 5000 if there were more than 5000 bytes   
   // available to return (cbBinaryBuffer > 5000). Code to check if   
   // rc equals SQL_ERROR or SQL_SUCCESS_WITH_INFO not shown.  
   while ((rc = SQLGetData(hstmt, 2, SQL_C_BINARY, BinaryPtr, sizeof(BinaryPtr),  
                           &BinaryLenOrInd)) != SQL_NO_DATA) {  
      NumBytes = (BinaryLenOrInd > 5000) || (BinaryLenOrInd == SQL_NO_TOTAL) ?  
                  5000 : BinaryLenOrInd;  
      DisplayNextPictPart(BinaryPtr, NumBytes);  
   }  
}  
  
// Close the cursor.  
SQLCloseCursor(hstmt);  

Er zijn verschillende beperkingen voor het gebruik van SQLGetData. Over het algemeen worden kolommen geopend met SQLGetData:

• Moet worden geopend in volgorde van toenemend kolomnummer (vanwege de manier waarop de kolommen van een resultatenset worden gelezen uit de gegevensbron). Het is bijvoorbeeld een fout om SQLGetData aan te roepen voor kolom 5 en deze vervolgens aan te roepen voor kolom 4.

• Kan niet worden gebonden.

• Moet een hoger kolomnummer hebben dan de laatste afhankelijke kolom. Als de laatste afhankelijke kolom bijvoorbeeld kolom 3 is, is het een fout om SQLGetData aan te roepen voor kolom 2. Daarom moeten toepassingen ervoor zorgen dat lange gegevenskolommen aan het einde van de selectielijst worden geplaatst.

• Kan niet worden gebruikt als SQLFetch of SQLFetchScroll is aangeroepen om meer dan één rij op te halen. Zie Blokcursors gebruiken voor meer informatie.

Sommige stuurprogramma's leggen deze beperkingen niet op. Interoperabele toepassingen moeten ervan uitgaan dat ze bestaan of bepalen welke beperkingen niet worden afgedwongen door SQLGetInfo aan te roepen met de optie SQL_GETDATA_EXTENSIONS.

Als de toepassing niet alle gegevens in een kolom met tekens of binaire gegevens nodig heeft, kan het netwerkverkeer in DBMS-stuurprogramma's worden beperkt door het kenmerk SQL_ATTR_MAX_LENGTH instructie in te stellen voordat de instructie wordt uitgevoerd. Dit beperkt het aantal bytes aan gegevens dat wordt geretourneerd voor een willekeurige teken- of binaire kolom. Stel dat een kolom lange tekstdocumenten bevat. Een toepassing die door de tabel met deze kolom bladert, moet mogelijk alleen de eerste pagina van elk document weergeven. Hoewel dit instructiekenmerk kan worden gesimuleerd in het stuurprogramma, is er geen reden om dit te doen. Met name als een toepassing teken- of binaire gegevens wil afkappen, moet deze een kleine buffer binden aan de kolom met SQLBindCol en het stuurprogramma de gegevens laten afkappen.