SQLFetchScroll-funktion

Överensstämmelse
Version introducerad: ODBC 3.0 Standardsefterlevnad: ISO 92

Summary
SQLFetchScroll hämtar den angivna radmängden av data från resultatmängden och returnerar data för alla bundna kolumner. Radmängder kan specificeras på en absolut eller relativ position eller med bokmärke.

När man arbetar med en ODBC 2.x-drivrutin mappar Driver Manager denna funktion till SQLExtendedFetch. För mer information, se Mapping Replacement Functions for Backward Compatibility of Applications.

Syntax

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

FetchOrientation
[Input]

Typ av apport:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

För mer information, se "Positionering av markören" i avsnittet "Kommentarer".

FetchOffset
[Input]

Nummer på raden att hämta. Tolkningen av detta argument beror på värdet av FetchOrientation-argumentet . För mer information, se "Positionering av markören" i avsnittet "Kommentarer".

Returns

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

Diagnostics

När SQLFetchScroll returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLGetDiagRec med en HandleType av SQL_HANDLE_STMT och en Handle of StatementHandle. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLFetchScroll och förklarar var och en i kontexten av denna funktion; notationen "(DM)" föregår beskrivningarna av SQLSTATE 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 på en enda kolumn kan SQLGetDiagField anropas med en DiagIdentifier SQL_DIAG_COLUMN_NUMBER för att bestämma vilken kolumn felet inträffade i; och SQLGetDiagField kan anropas med en DiagIdentifier av SQL_DIAG_ROW_NUMBER för att bestämma raden som innehåller den kolumnen.

För alla SQLSTATES som kan returnera SQL_SUCCESS_WITH_INFO eller SQL_ERROR (förutom 01xxx SQLSTATE) returneras SQL_SUCCESS_WITH_INFO om ett fel uppstår på en eller flera, men inte alla, rader i en flerradsoperation, och SQL_ERROR returneras om ett fel uppstår i en enradsoperation.

Comments

SQLFetchScroll returnerar en specificerad radmängd från resultatmängden. Radmängder kan specificeras med absolut eller relativ position eller med bokmärke. SQLFetchScroll kan endast anropas medan en resultatmängd finns – det vill säga efter ett anrop som skapar en resultatmängd och innan markören över den mängden stängs. Om några kolumner är bundna, returnerar den data i dessa kolumner. Om applikationen har specificerat en pekare till en radstatusarray eller en buffert för att returnera antalet rader som hämtats, returnerar SQLFetchScroll även denna information. Anrop till SQLFetchScroll kan blandas med anrop till SQLFetch men kan inte blandas med anrop till SQLExtendedFetch.

För mer information, se Användning av blockmarkörer och användning av rullbara markörer.

Positionering av markören

När resultatuppsättningen skapas placeras markören före början av resultatuppsättningen. SQLFetchScroll positionerar blockmarkören baserat på värdena i argumenten FetchOrientation och FetchOffset, som visas i följande tabell. De exakta reglerna för att bestämma starten på det nya radsetet visas i nästa avsnitt.

Drivrutiner behöver inte stödja alla hämtningsorienteringar; en applikation anropar SQLGetInfo med informationstypen SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 eller SQL_STATIC_CURSOR_ATTRIBUTES1 (beroende på markörens typ) för att avgöra vilka hämtaorienteringar som stöds av drivrutinen. Applikationen bör titta på SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE och WQL_CA1_BOOKMARK bitmasker i dessa informationstyper. Dessutom, om markören är endast framåtriktad och FetchOrientation inte är SQL_FETCH_NEXT, returnerar SQLFetchScroll SQLSTATE HY106 (Fetch-typ utanför räckvidd).

Attributet SQL_ATTR_ROW_ARRAY_SIZE anger antalet rader i radmängden. Om raduppsättningen som hämtas av SQLFetchScroll överlappar slutet av resultatmängden, returnerar SQLFetchScroll en partiell raduppsättning. Det vill säga, om S + R - 1 är större än L, där S är startraden i radmängden som hämtas, R är radmängdens storlek och L är den sista raden i resultatmängden, så är endast de första raderna L - S + 1 i radmängden gällande. De återstående raderna är tomma och har statusen SQL_ROW_NOROW.

Efter att SQLFetchScroll återvänder är den aktuella raden den första raden i raduppsättningen.

Regler för markörpositionering

Följande avsnitt beskriver de exakta reglerna för varje värde i FetchOrientation. Dessa regler använder följande notation.

SQL_FETCH_NEXT

Följande regler gäller.

[1] Om raduppsättningsstorleken har ändrats sedan föregående anrop för att hämta rader, är detta raduppsättningsstorleken som användes med föregående anrop.

SQL_FETCH_PRIOR

Följande regler gäller.

[1] SQLFetchScroll returnerar SQLSTATE 01S06 (Försök att hämta innan resultatuppsättningen returnerade den första raduppsättningen) och SQL_SUCCESS_WITH_INFO.

[2] Om raduppsättningsstorleken har ändrats sedan föregående anrop för att hämta rader, är detta den nya raduppsättningsstorleken.

SQL_FETCH_RELATIVE

Följande regler gäller.

[1] SQLFetchScroll returnerar samma radmängd som om den anropades med FetchOrientation satt till SQL_FETCH_ABSOLUTE. För mer information, se avsnittet "SQL_FETCH_ABSOLUTE".

[2] SQLFetchScroll returnerar SQLSTATE 01S06 (Försök att hämta innan resultatuppsättningen returnerade den första raduppsättningen) och SQL_SUCCESS_WITH_INFO.

[3] Om raduppsättningsstorleken har ändrats sedan föregående anrop för att hämta rader, är detta den nya raduppsättningsstorleken.

SQL_FETCH_ABSOLUTE

Följande regler gäller.

[1] SQLFetchScroll returnerar SQLSTATE 01S06 (Försök att hämta innan resultatuppsättningen returnerade den första raduppsättningen) och SQL_SUCCESS_WITH_INFO.

[2] Om raduppsättningsstorleken har ändrats sedan föregående anrop för att hämta rader, är detta den nya raduppsättningsstorleken.

En absolut hämtning utförd mot en dynamisk markör kan inte ge det önskade resultatet eftersom radpositionerna i en dynamisk markör är obestämda. En sådan operation är ekvivalent med en hämta först följt av en hämta-relativ; det är inte en atomär operation, som en absolut hämtning på en statisk markör.

SQL_FETCH_FIRST

Följande regler gäller.

SQL_FETCH_LAST

Följande regler gäller.

[1] Om raduppsättningsstorleken har ändrats sedan föregående anrop för att hämta rader, är detta den nya raduppsättningsstorleken.

SQL_FETCH_BOOKMARK

Följande regler gäller.

För information om bokmärken, se Bokmärken (ODBC).

Effekten av raderade rader som tagits bort, till och felet påverkar markörens rörelse

Statiska och tangentsatsstyrda markörer upptäcker ibland rader som lagts till i resultatuppsättningen och tar bort rader som tagits bort från resultatuppsättningen. Genom att anropa SQLGetInfo med SQL_STATIC_CURSOR_ATTRIBUTES2- och SQL_KEYSET_CURSOR_ATTRIBUTES2-alternativen och titta på SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS och SQL_CA2_SENSITIVITY_UPDATES bitmasker, avgör en applikation om markörerna som implementeras av en viss drivrutin gör detta. För drivrutiner som kan upptäcka raderade rader och ta bort dem, beskriver följande stycken effekterna av detta beteende. För drivrutiner som kan upptäcka raderade rader men inte kan ta bort dem, har raderingar ingen effekt på markörrörelser, och följande stycken gäller inte.

Om markören upptäcker rader som lagts till i resultatuppsättningen eller tar bort rader som tagits bort från resultatuppsättningen, verkar det som om den bara upptäcker dessa ändringar när den hämtar data. Detta inkluderar fallet när SQLFetchScroll anropas med FetchOrientation satt till SQL_FETCH_RELATIVE och FetchOffset satt till 0 för att repetcha samma raduppsättning, men inkluderar inte fallet när SQLSetPos anropas med fOption satt till SQL_REFRESH. I det senare fallet uppdateras datan i raduppsättningsbuffertarna, men inte rehämtas, och raderade rader tas inte bort från resultatuppsättningen. Således, när en rad raderas från eller infogas i den aktuella raduppsättningen, ändrar inte markören raduppsättningens buffertar. Istället känner den av ändringen när den hämtar en raduppsättning som tidigare inkluderade den raderade raden eller nu inkluderar den insatta raden.

Ett exempel:

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);  

När SQLFetchScroll returnerar en ny raduppsättning som har en position relativt den aktuella radmängden – det vill säga FetchOrientation är SQL_FETCH_NEXT, SQL_FETCH_PRIOR eller SQL_FETCH_RELATIVE – inkluderar den inte ändringar i den aktuella radmängden när startpositionen för den nya radmängden beräknas. Den inkluderar dock ändringar utanför den aktuella raduppsättningen om den kan upptäcka dem. Dessutom, när SQLFetchScroll returnerar en ny radmängd som har en position oberoende av den aktuella raduppsättningen – det vill säga FetchOrientation är SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE eller SQL_FETCH_BOOKMARK – inkluderar den alla ändringar den kan upptäcka, även om de finns i den aktuella raduppsättningen.

När man avgör om nyligen tillagda rader ligger inom eller utanför den aktuella radmängden anses en partiell radmängd sluta vid den sista giltiga raden; det vill säga den sista raden för vilken radstatusen inte är SQL_ROW_NOROW. Till exempel, anta att markören kan upptäcka nyligen tillagda rader, den aktuella raduppsättningen är en delvis raduppsättning, applikationen lägger till nya rader och markören lägger till dessa rader i slutet av resultatuppsättningen. Om applikationen anropar SQLFetchScroll med FetchOrientation inställt på SQL_FETCH_NEXT, returnerar SQLFetchScroll raduppsättningen som börjar med den första nyligen tillagda raden.

Till exempel, anta att den aktuella raduppsättningen består av raderna 21 till 30, raduppsättningens storlek är 10, markören tar bort rader som tagits bort från resultatuppsättningen, och markören känner av rader som lagts till i resultatuppsättningen. Följande tabell visar raderna som SQLFetchScroll returnerar i olika situationer.

[1] Denna kolumn använder radnumren innan några rader sattes in eller togs bort.

[2] I detta fall försöker markören returnera rader som börjar med rad 21. Eftersom rad 21 har tagits bort är den första raden den returnerar rad 22.

Felrader (det vill säga rader med status SQL_ROW_ERROR) påverkar inte markörens rörelse. Till exempel, om den aktuella raduppsättningen börjar med rad 11 och status för rad 11 är SQL_ROW_ERROR, returnerar anrop av SQLFetchScroll med FetchOrientation satt till SQL_FETCH_RELATIVE och FetchOffset satt till 5 raduppsättningen som börjar med rad 16, precis som om statusen för rad 11 var SQL_SUCCESS.

Returnera data i bundna kolumner

SQLFetchScroll returnerar data i bundna kolumner på samma sätt som SQLFetch. För mer information, se "Returning Data in Bound Columns" i SQLFetch Function.

Om inga kolumner är begränsade returnerar SQLFetchScroll inte data men flyttar blockmarkören till den angivna positionen. Om data kan hämtas från obundna kolumner i en blockmarkör med SQLGetData beror på drivrutinen. Denna funktion stöds om ett anrop till SQLGetInfo returnerar SQL_GD_BLOCK bit för SQL_GETDATA_EXTENSIONS informationstyp.

Buffertadresser

SQLFetchScroll använder samma formel för att bestämma adressen till data och längd-/indikatorbuffertar som SQLFetch. För mer information, se "Buffer Addresses" i SQLBindCol Function.

Radstatusmatris

SQLFetchScroll sätter värden i radstatusarrayen på samma sätt som SQLFetch. För mer information, se "Row Status Array" i SQLFetch Function.

Buffert för rader hämtade

SQLFetchScroll returnerar antalet rader hämtade i den raderhämtade bufferten på samma sätt som SQLFetch. För mer information, se "Rows Fetched Buffer" i SQLFetch Function.

Felhantering

När en applikation anropar SQLFetchScroll i en ODBC 3.x-drivrutin, anropar Driver Manager SQLFetchScroll i drivrutinen. När en applikation anropar SQLFetchScroll i en ODBC 2.x-drivrutin, anropar Driver Manager SQLExtendedFetch i drivrutinen. Eftersom SQLFetchScroll och SQLExtendedFetch hanterar fel på något olika sätt, ser applikationen något olika felbeteende när den anropar SQLFetchScroll i ODBC 2.x och ODBC 3.x-drivrutiner.

SQLFetchScroll returnerar fel och varningar på samma sätt som SQLFetch; för mer information, se "Error Handling" i SQLFetch. SQLExtendedFetch returnerar fel på samma sätt som SQLFetch, med följande undantag:

När en varning uppstår som gäller en viss rad i raduppsättningen, sätter SQLExtendedFetch motsvarande post i radstatusarrayen till SQL_ROW_SUCCESS, inte SQL_ROW_SUCCESS_WITH_INFO.

Om fel uppstår i varje rad i radmängden returnerar SQLExtendedFetch SQL_SUCCESS_WITH_INFO, inte SQL_ERROR.

I varje grupp av statusposter som gäller för en enskild rad måste den första statusposten som returneras av SQLExtendedFetch innehålla SQLSTATE 01S01 (Fel i rad); SQLFetchScroll returnerar inte detta SQLSTATE. Om SQLExtendedFetch inte kan returnera ytterligare SQLSTATE måste den ändå returnera denna SQLSTATE.

SQLFetchScroll och optimistisk samtidighet

Om en markör använder optimistisk samtidighet – det vill säga att attributet SQL_ATTR_CONCURRENCY statement har värdet SQL_CONCUR_VALUES eller SQL_CONCUR_ROWVER – uppdaterar SQLFetchScroll de optimistiska samtidighetsvärden som används av datakällan för att upptäcka om en rad har ändrats. Detta händer varje gång SQLFetchScroll hämtar en ny raduppsättning, inklusive när den reletar den aktuella raduppsättningen. (Den anropas med FetchOrientation satt till SQL_FETCH_RELATIVE och FetchOffset satt till 0.)

SQLFetchScroll och ODBC 2.x-drivrutiner

När en applikation anropar SQLFetchScroll i en ODBC 2.x-drivrutin, mappar Driver Manager detta anrop till SQLExtendedFetch. Den skickar följande värden för argumenten i SQLExtendedFetch.

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

Beskrivningar och SQLFetchScroll

SQLFetchScroll interagerar med deskriptorer på samma sätt som SQLFetch. För mer information, se avsnittet "Descriptors and SQLFetchScroll" i SQLFetch Function.

Kodexempel

Se Column-Wise Binding, Row-Wise Binding, Positioned Update and Delete-satser samt Uppdatering av rader i raduppsättningen med SQLSetPos.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler