SQLFetch-funktion

Efterlevnad
Version introducerad: ODBC 1.0 Standardefterlevnad: ISO 92

Sammanfattning
SQLFetch hämtar nästa raduppsättning med data från resultatuppsättningen och returnerar data för alla bundna kolumner.

Syntax

  
SQLRETURN SQLFetch(  
     SQLHSTMT     StatementHandle);  

Argumentpunkter

StatementHandle
[Indata] Instruktionshandtag.

Retur

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

Diagnostik

När SQLFetch returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde hämtas genom att anropa SQLGetDiagRec-funktionen med en HandleType av SQL_HANDLE_STMT och ett handtag för StatementHandle. I följande tabell visas DE SQLSTATE-värden som vanligtvis returneras av SQLFetch och förklarar var och en i kontexten för den här funktionen. notationen "(DM)" föregår beskrivningarna av SQLSTATEs som returneras av Driver Manager. Returkoden som är associerad med varje SQLSTATE-värde är SQL_ERROR, om inget annat anges. Om ett fel uppstår i en enda kolumn kan SQLGetDiagField anropas med en DiagIdentifier av SQL_DIAG_COLUMN_NUMBER för att fastställa kolumnen som felet inträffade på. och SQLGetDiagField kan anropas med en DiagIdentifier av SQL_DIAG_ROW_NUMBER för att fastställa raden som innehåller kolumnen.

För alla SQLSTATE:er som kan returnera SQL_SUCCESS_WITH_INFO eller SQL_ERROR (utom 01xxx SQLSTATEs) returneras SQL_SUCCESS_WITH_INFO om ett fel inträffar på en eller flera, men inte alla rader i en multirow-åtgärd, och SQL_ERROR returneras om ett fel inträffar på en enskild radåtgärd.

Kommentarer

SQLFetch returnerar nästa raduppsättning i resultatuppsättningen. Det kan bara anropas när det finns en resultatuppsättning: det vill säga efter ett anrop som skapar en resultatuppsättning och innan markören över resultatuppsättningen stängs. Om några kolumner är bundna returneras data i dessa kolumner. Om programmet har angett en pekare till en radstatusmatris eller en buffert där du kan returnera antalet hämtade rader returnerar SQLFetch även den här informationen. Anrop till SQLFetch kan blandas med anrop till SQLFetchScroll men kan inte blandas med anrop till SQLExtendedFetch. Mer information finns i Hämta en rad med data.

Om ett ODBC 3*.x*-program fungerar med en ODBC 2*.x*-drivrutin mappar Driver Manager SQLFetch-anrop till SQLExtendedFetch för en ODBC 2*.x*-drivrutin som stöder SQLExtendedFetch. Om ODBC 2*.x*-drivrutinen inte stöder SQLExtendedFetch mappar Driver Manager SQLFetch-anrop till SQLFetch i ODBC 2*.x*-drivrutinen, som bara kan hämta en enda rad.

Mer information finns i Blockera markörer, rullningsbara markörer och Bakåtkompatibilitet i bilaga G: Drivrutinsriktlinjer för bakåtkompatibilitet.

Placera markören

När resultatuppsättningen skapas placeras markören innan resultatuppsättningen börjar. SQLFetch hämtar nästa raduppsättning. Det motsvarar att anropa SQLFetchScroll med FetchOrientation inställt på SQL_FETCH_NEXT. Mer information om markörer finns i Markörer och Blockmarkörer.

Attributet SQL_ATTR_ROW_ARRAY_SIZE-instruktion anger antalet rader i raduppsättningen. Om raduppsättningen som hämtas av SQLFetch överlappar slutet av resultatuppsättningen returnerar SQLFetch en partiell raduppsättning. Om S + R - 1 är större än L, där S är startraden för raduppsättningen som hämtas, R är raduppsättningens storlek och L är den sista raden i resultatuppsättningen är endast de första L - S + 1 raderna i raduppsättningen giltiga. De återstående raderna är tomma och har statusen SQL_ROW_NOROW.

När SQLFetch har returnerats är den aktuella raden den första raden i raduppsättningen.

Reglerna i följande tabell beskriver markörpositionering efter ett anrop till SQLFetch, baserat på de villkor som anges i den andra tabellen i det här avsnittet.

[1] Om raduppsättningens storlek ändras mellan hämtningar är detta den raduppsättningsstorlek som användes med föregående hämtning.

[2] Om raduppsättningens storlek ändras mellan hämtningar är detta den raduppsättningsstorlek som användes med den nya hämtningen.

Anta till exempel att en resultatuppsättning har 100 rader och raduppsättningens storlek är 5. I följande tabell visas raduppsättningen och returkoden som returneras av SQLFetch för olika startpositioner.

Returnera data i bundna kolumner

När SQLFetch returnerar varje rad placeras data för varje bunden kolumn i bufferten som är bunden till den kolumnen. Om inga kolumner är bundna returnerar SQLFetch inga data, men flyttar blockmarkören framåt. Data kan fortfarande hämtas med hjälp av SQLGetData. Om markören är en markören med flera ändar (dvs. SQL_ATTR_ROW_ARRAY_SIZE är större än 1) kan SQLGetData bara anropas om SQL_GD_BLOCK returneras när SQLGetInfo anropas med en InfoType av SQL_GETDATA_EXTENSIONS. (Mer information finns i SQLGetData.)

För varje bunden kolumn i en rad gör SQLFetch följande:

1. Anger längden/indikatorbufferten till SQL_NULL_DATA och fortsätter till nästa kolumn om data är NULL. Om data är NULL och ingen längd/indikatorbuffert har bundits returnerar SQLFetch SQLSTATE 22002 (indikatorvariabel krävs men tillhandahålls inte) för raden och fortsätter till nästa rad. Information om hur du fastställer adressen för längd-/indikatorbufferten finns i "Buffertadresser" i SQLBindCol.

   Om data för kolumnen inte är NULL fortsätter SQLFetch till steg 2.

2. Om SQL_ATTR_MAX_LENGTH-instruktionsattributet är inställt på ett icke-nollvärde och kolumnen innehåller tecken eller binära data trunkeras data till SQL_ATTR_MAX_LENGTH byte.

   Anmärkning

   Attributet SQL_ATTR_MAX_LENGTH-instruktionen är avsett att minska nätverkstrafiken. Den implementeras vanligtvis av datakällan, som trunkerar data innan de returneras via nätverket. Drivrutiner och datakällor krävs inte för att stödja det. För att garantera att data trunkeras till en viss storlek bör ett program därför allokera en buffert av den storleken och ange storleken i argumentet cbValueMax i SQLBindCol.

3. Konverterar data till den typ som anges av TargetType i SQLBindCol.

4. Om data konverterades till en datatyp med variabel längd, till exempel tecken eller binär, kontrollerar SQLFetch om datalängden överskrider databuffertens längd. Om längden på teckendata (inklusive null-avslutningstecken) överskrider längden på databufferten trunkerar SQLFetch data till längden på databufferten mindre längden på ett null-avslutningstecken. Sedan null-avslutar data. Om längden på binära data överskrider databuffertens längd trunkerar SQLFetch den till längden på databufferten. Längden på databufferten anges med BufferLength i SQLBindCol.

   SQLFetch trunkerar aldrig data som konverterats till datatyper med fast längd. Det förutsätter alltid att längden på databufferten är storleken på datatypen.

5. Placerar konverterade (och eventuellt trunkerade) data i databufferten. Information om hur du fastställer databuffertens adress finns i "Buffertadresser" i SQLBindCol.

6. Placerar längden på data i längden/indikatorbufferten. Om indikatorpekaren och längdpekaren båda var inställda på samma buffert (som ett anrop till SQLBindCol gör), skrivs längden i bufferten för giltiga data och SQL_NULL_DATA skrivs i bufferten för NULL-data. Om ingen längd/indikatorbuffert var bunden returnerar SQLFetch inte längden.

   • För tecken eller binära data är detta längden på data efter konverteringen och före trunkering på grund av att databufferten är för liten. Om drivrutinen inte kan fastställa längden på data efter konverteringen, vilket ibland är fallet med långa data, anger den längden till SQL_NO_TOTAL. Om data trunkerades på grund av SQL_ATTR_MAX_LENGTH-instruktionsattributet placeras värdet för det här attributet i längd-/indikatorbufferten i stället för den faktiska längden . Det beror på att det här attributet är utformat för att trunkera data på servern före konverteringen, så att drivrutinen inte kan ta reda på vad den faktiska längden är.

   • För alla andra datatyper är det här längden på data efter konverteringen. Det är alltså storleken på den typ som data konverterades till.

   Information om hur du fastställer adressen för längd-/indikatorbufferten finns i "Buffertadresser" i SQLBindCol.

7. Om data trunkeras under konverteringen utan förlust av signifikanta siffror (till exempel att det verkliga talet 1.234 trunkeras till heltal 1 när de konverteras) returnerar SQLFetch SQLSTATE 01S07 (bråktals trunkering) och SQL_SUCCESS_WITH_INFO. Om data trunkeras på grund av att längden på databufferten är för liten (till exempel strängen "abcdef" placeras i en 4-bytesbuffert) returnerar SQLFetch SQLSTATE 01004 (data trunkerade) och SQL_SUCCESS_WITH_INFO. Om data trunkeras på grund av SQL_ATTR_MAX_LENGTH-instruktionsattributet returnerar SQLFetch SQL_SUCCESS och returnerar inte SQLSTATE 01S07 (fraktionell trunkering) eller SQLSTATE 01004 (trunkerade data). Om data trunkeras under konverteringen med en förlust av betydande siffror (till exempel om ett SQL_INTEGER värde som är större än 100 000 konverterades till en SQL_C_TINYINT), returnerar SQLFetch SQLSTATE 22003 (numeriskt värde ligger utom intervallet) och SQL_ERROR (om raduppsättningens storlek är 1) eller SQL_SUCCESS_WITH_INFO (om raduppsättningens storlek är större än 1).

Innehållet i den bundna databufferten och längden/indikatorbufferten är odefinierade om SQLFetch eller SQLFetchScroll inte returnerar SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO.

Radstatusmatris

Radstatusmatrisen används för att returnera status för varje rad i raduppsättningen. Adressen till den här matrisen anges med SQL_ATTR_ROW_STATUS_PTR-instruktionsattributet. Matrisen allokeras av programmet och måste ha så många element som anges av SQL_ATTR_ROW_ARRAY_SIZE-instruktionsattributet. Dess värden anges av SQLFetch, SQLFetchScroll och SQLBulkOperations eller SQLSetPos (förutom när de har anropats efter att markören har placerats av SQLExtendedFetch). Om värdet för SQL_ATTR_ROW_STATUS_PTR-instruktionsattributet är en null-pekare returnerar dessa funktioner inte radstatusen.

Innehållet i radstatusmatrisbufferten är odefinierat om SQLFetch eller SQLFetchScroll inte returnerar SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO.

Följande värden returneras i radstatusmatrisen.

[1] För tangentuppsättningar, blandade och dynamiska markörer anses dataraden ha tagits bort och en ny rad har lagts till om ett nyckelvärde uppdateras.

[2] Vissa drivrutiner kan inte identifiera uppdateringar av data och kan därför inte returnera det här värdet. För att avgöra om en drivrutin kan identifiera uppdateringar av nya rader anropar ett program SQLGetInfo med alternativet SQL_ROW_UPDATES.

[3] SQLFetch kan bara returnera det här värdet när det blandas med anrop till SQLFetchScroll. Detta beror på att SQLFetch går framåt genom resultatuppsättningen och när den används exklusivt, inte reetch några rader. Eftersom inga rader har reetched identifieras inte ändringar som gjorts i tidigare hämtade rader i SQLFetch . Men om SQLFetchScroll placerar markören före tidigare hämtade rader och SQLFetch används för att hämta dessa rader, kan SQLFetch identifiera eventuella ändringar i dessa rader.

[4] Returneras endast av SQLBulkOperations. Anges inte av SQLFetch eller SQLFetchScroll.

Hämtad buffert för rader

Den hämtade bufferten för rader används för att returnera antalet rader som hämtats, inklusive de rader för vilka inga data returnerades eftersom ett fel uppstod när de hämtades. Med andra ord är det antalet rader för vilka värdet i radstatusmatrisen inte SQL_ROW_NOROW. Adressen för den här bufferten anges med SQL_ATTR_ROWS_FETCHED_PTR-instruktionsattributet. Bufferten allokeras av programmet. Den anges av SQLFetch och SQLFetchScroll. Om värdet för SQL_ATTR_ROWS_FETCHED_PTR-instruktionsattributet är en null-pekare returnerar dessa funktioner inte antalet hämtade rader. För att fastställa antalet för den aktuella raden i resultatuppsättningen kan ett program anropa SQLGetStmtAttr med attributet SQL_ATTR_ROW_NUMBER.

Innehållet i den hämtade bufferten för rader är odefinierat om SQLFetch eller SQLFetchScroll inte returnerar SQL_SUCCESS eller SQL_SUCCESS_WITH_INFO, förutom när SQL_NO_DATA returneras, i vilket fall värdet i den hämtade bufferten för rader är inställt på 0.

Felhantering

Fel och varningar kan gälla för enskilda rader eller för hela funktionen. Mer information om diagnostikposter finns i Diagnostik och SQLGetDiagField.

Fel och varningar för hela funktionen

Om ett fel gäller för hela funktionen, till exempel SQLSTATE HYT00 (tidsgränsen har upphört att gälla) eller SQLSTATE 24000 (ogiltigt markörtillstånd), returnerar SQLFetch SQL_ERROR och tillämplig SQLSTATE. Innehållet i raduppsättningsbuffertarna är odefinierat och markörens position är oförändrad.

Om en varning gäller för hela funktionen returnerar SQLFetch SQL_SUCCESS_WITH_INFO och tillämplig SQLSTATE. Statusposterna för varningar som gäller för hela funktionen returneras före statusposterna som gäller för enskilda rader.

Fel och varningar i enskilda rader

Om ett fel (till exempel SQLSTATE 22012 (division med noll)) eller en varning (till exempel SQLSTATE 01004 (data trunkerad)) gäller för en enskild rad, gör SQLFetch följande:

• Anger motsvarande element i radstatusmatrisen till SQL_ROW_ERROR för fel eller SQL_ROW_SUCCESS_WITH_INFO för varningar.

• Lägger till noll eller fler statusposter som innehåller SQLSTATEs för felet eller varningen.

• Anger rad- och kolumnnummerfälten i statusposterna. Om SQLFetch inte kan fastställa ett rad- eller kolumnnummer anger det talet till SQL_ROW_NUMBER_UNKNOWN respektive SQL_COLUMN_NUMBER_UNKNOWN. Om statusposten inte gäller för en viss kolumn anger SQLFetch kolumnnumret till SQL_NO_COLUMN_NUMBER.

SQLFetch fortsätter att hämta rader tills alla rader i raduppsättningen har hämtats. Den returnerar SQL_SUCCESS_WITH_INFO om inte ett fel inträffar på varje rad i raduppsättningen (exklusive rader med status SQL_ROW_NOROW), i vilket fall det returnerar SQL_ERROR. I synnerhet om raduppsättningens storlek är 1 och ett fel inträffar på den raden returnerar SQLFetch SQL_ERROR.

SQLFetch returnerar statusposterna i radnummerordning. Den returnerar alltså alla statusposter för okända rader (om det finns några). därefter returneras alla statusposter för den första raden (om någon) och sedan returneras alla statusposter för den andra raden (om någon) och så vidare. Statusposterna för varje rad sorteras enligt de normala reglerna för att sortera statusposter. Mer information finns i "Sekvens av statusposter" i SQLGetDiagField.

Deskriptorer och SQLFetch

I följande avsnitt beskrivs hur SQLFetch interagerar med deskriptorer.

Argumentmappningar

Drivrutinen anger inga beskrivande fält baserat på argumenten i SQLFetch.

Andra beskrivningsfält

Följande deskriptorfält används av SQLFetch.

Alla deskriptorfält kan också anges via SQLSetDescField.

Separata längd- och indikatorbuffertar

Program kan binda en enda buffert eller två separata buffertar som kan användas för att lagra längd- och indikatorvärden. När ett program anropar SQLBindCol anger drivrutinen fälten SQL_DESC_OCTET_LENGTH_PTR och SQL_DESC_INDICATOR_PTR i ARD till samma adress, som skickas i argumentet StrLen_or_IndPtr . När ett program anropar SQLSetDescField eller SQLSetDescRec kan det ange dessa två fält till olika adresser.

SQLFetch avgör om programmet har angett separata längd- och indikatorbuffertar. I det här fallet, när data inte är NULL, anger SQLFetch indikatorbufferten till 0 och returnerar längden i längdbufferten. När data är NULL ställer SQLFetch in indikatorbufferten på SQL_NULL_DATA och ändrar inte längdbufferten.

Kodexempel

Se SQLBindCol, SQLColumns, SQLGetData och SQLProcedures.

Relaterade funktioner

Se även

ODBC API-referens
ODBC-huvudfiler