SQLExtendedFetch-funktion

Överensstämmelse
Version introducerad: ODBC 1.0 Standarder Efterlevnad: Föråldrad

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

Syntax

  
SQLRETURN SQLExtendedFetch(  
      SQLHSTMT         StatementHandle,  
      SQLUSMALLINT     FetchOrientation,  
      SQLLEN           FetchOffset,  
      SQLULEN *        RowCountPtr,  
      SQLUSMALLINT *   RowStatusArray);  

Arguments

StatementHandle
[Indata] Instruktionshandtag.

FetchOrientation
[Input] Typ av apport. Detta är samma som FetchOrientation i SQLFetchScroll.

FetchOffset
[Input] Nummer på raden att hämta. Detta är samma som FetchOffset i SQLFetchScroll, med ett undantag. När FetchOrientation är SQL_FETCH_BOOKMARK är FetchOffset ett bokmärke med fast längde, inte en offset från ett bokmärke. Med andra ord hämtar SQLExtendedFetch bokmärket från detta argument, inte attributet SQL_ATTR_FETCH_BOOKMARK_PTR statement. Den stöder inte bokmärken med variabel längd och tillåter inte att hämta en raduppsättning vid en offset (annat än 0) från ett bokmärke.

RowCountPtr
[Utdata] Peka på en buffert där man returnerar antalet rader som faktiskt hämtats. Denna buffert används på samma sätt som bufferten specificerad av attributet SQL_ATTR_ROWS_FETCHED_PTR statement. Denna buffert används endast av SQLExtendedFetch. Den används inte av SQLFetch eller SQLFetchScroll.

RowStatusArray
[Utdata] Pekar på en array där statusen för varje rad ska returneras. Denna array används på samma sätt som arrayen som specificeras av attributet SQL_ATTR_ROW_STATUS_PTR statement.

Dock lagras inte adressen till denna array i fältet SQL_DESC_STATUS_ARRAY_PTR i IRD. Dessutom används denna array endast av SQLExtendedFetch och av SQLBulkOperations med en Operation av SQL_ADD eller SQLSetPos när den anropas efter SQLExtendedFetch. Den används inte av SQLFetch eller SQLFetchScroll, och den används inte av SQLBulkOperations eller SQLSetPos när de anropas efter SQLFetch eller SQLFetchScroll. Den används inte heller när SQLBulkOperations med en Operation av SQL_ADD anropas innan någon hämtningsfunktion anropas. Med andra ord används den endast i satstillstånd S7. Det används inte i påståenden S5 eller S6. För mer information, se Statement Transitions i Appendix B: ODBC State Transition Tables.

Applikationer bör tillhandahålla en giltig pekare i argumentet RowStatusArray ; om inte, är beteendet hos SQLExtendedFetch och beteendet hos anrop till SQLBulkOperations eller SQLSetPos efter att en markör har placerats av SQLExtendedFetch odefinierade.

Returns

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

Diagnostics

När SQLExtendedFetch returnerar antingen SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde erhållas genom att anropa SQLError. Följande tabell listar de SQLSTATE-värden som vanligtvis returneras av SQLExtendedFetch 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 i en enda kolumn kan SQLGetDiagField anropas med 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.

Comments

Beteendet hos SQLExtendedFetch är identiskt med SQLFetchScroll, med följande undantag:

• SQLExtendedFetch och SQLFetchScroll använder olika metoder för att returnera antalet rader som hämtats. SQLExtendedFetch returnerar antalet rader hämtade i *RowCountPtr; SQLFetchScroll returnerar antalet rader som hämtats direkt till bufferten som SQL_ATTR_ROWS_FETCHED_PTR pekar på. För mer information, se argumentet RowCountPtr .

• SQLExtendedFetch och SQLFetchScroll returnerar status för varje rad i olika arrayer. För mer information, se argumentet RowStatusArray .

• SQLExtendedFetch och SQLFetchScroll använder olika metoder för att hämta bokmärket när FetchOrientation är SQL_FETCH_BOOKMARK. SQLExtendedFetch stöder inte bokmärken med variabel längd eller att hämta raduppsättningar vid en annan offset än 0 från ett bokmärke. För mer information, se argumentet FetchOffset.

• SQLExtendedFetch och SQLFetchScroll använder olika raduppsättningsstorlekar. SQLExtendedFetch använder värdet av attributet SQL_ROWSET_SIZE statement, och SQLFetchScroll använder värdet av attributet SQL_ATTR_ROW_ARRAY_SIZE statement.

• SQLExtendedFetch har något annorlunda felhanteringssemantik än SQLFetchScroll. För mer information, se "Felhantering" i avsnittet "Kommentarer" i SQLFetchScroll.

• SQLExtendedFetch stöder inte bindningsoffsets (attributet SQL_ATTR_ROW_BIND_OFFSET_PTR statement).

• Anrop till SQLExtendedFetch kan inte blandas med anrop till SQLFetch eller SQLFetchScroll, och om SQLBulkOperations anropas innan någon fetch-funktion anropas, kan SQLExtendedFetch inte anropas förrän markören stängs och öppnas igen. Det vill säga, SQLExtendedFetch kan endast anropas i satstillstånd S7. För mer information, se Statement Transitions i Appendix B: ODBC State Transition Tables.

När en applikation anropar SQLFetchScroll medan den använder en ODBC 2*.x*-drivrutin, mappar Driver Manager detta anrop till SQLExtendedFetch. För mer information, se "SQLFetchScroll och ODBC 2*.x* Drivrutiner" i SQLFetchScroll.

I ODBC 2*.x* anropades SQLExtendedFetch för att hämta flera rader och SQLFetch för att hämta en rad en. I ODBC 3*.x* kan SQLFetch däremot anropas för att hämta flera rader.

Relaterade funktioner

Relaterat innehåll

• ODBC API-referens
• ODBC-huvudfiler