SQLMoreResults-funktion

Efterlevnad
Version introducerad: ODBC 1.0 Standardefterlevnad: ODBC

Sammanfattning
SQLMoreResults avgör om fler resultat är tillgängliga för en -instruktion som innehåller SELECT-, UPDATE-, INSERT- eller DELETE-instruktioner och i så fall initierar bearbetningen för dessa resultat.

Syntax

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

Argumentpunkter

StatementHandle
[Indata] Instruktionshandtag.

Retur

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

Diagnostik

När SQLMoreResults returnerar SQL_ERROR eller SQL_SUCCESS_WITH_INFO kan ett associerat SQLSTATE-värde hämtas genom att anropa SQLGetDiagRec 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 SQLMoreResults 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.

Kommentarer

SELECT-uttryck returnerar resultatuppsättningar. UPDATE-, INSERT- och DELETE-uttryck returnerar ett antal berörda rader. Om någon av dessa instruktioner batchas, skickas med matriser med parametrar (numrerade i ökande parameterordning, i den ordning som de visas i batchen), eller i procedurer, kan de returnera flera resultatuppsättningar eller radantal. Information om batchar med instruktioner och matriser med parametrar finns i Batchar med SQL-instruktioner och matriser med parametervärden.

När batchen har körts placeras programmet på den första resultatuppsättningen. Programmet kan anropa SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos och alla metadatafunktioner på den första eller eventuella efterföljande resultatuppsättningar, precis som om det bara fanns en enda resultatuppsättning. När det är klart med den första resultatuppsättningen anropar programmet SQLMoreResults för att gå vidare till nästa resultatuppsättning. Om en annan resultatuppsättning eller ett annat antal är tillgängligt returnerar SQLMoreResults SQL_SUCCESS och initierar resultatuppsättningen eller antalet för ytterligare bearbetning. Om några radantalgenererande instruktioner visas mellan resultatuppsättningsgenererande instruktioner kan de stegas över genom att anropa SQLMoreResults. När du har anropat SQLMoreResults för UPDATE-, INSERT- eller DELETE-instruktioner kan ett program anropa SQLRowCount.

Om det fanns en aktuell resultatuppsättning med otillgängliga rader tar SQLMoreResults bort den resultatuppsättningen och gör nästa resultatuppsättning eller antal tillgängligt. Om alla resultat har bearbetats returnerar SQLMoreResults SQL_NO_DATA. För vissa drivrutiner är utdataparametrar och returvärden inte tillgängliga förrän alla resultatuppsättningar och radantal har bearbetats. För sådana drivrutiner blir utdataparametrar och returvärden tillgängliga när SQLMoreResults returnerar SQL_NO_DATA.

Alla bindningar som har upprättats för den tidigare resultatuppsättningen är fortfarande giltiga. Om kolumnstrukturerna skiljer sig åt för den här resultatuppsättningen kan anrop av SQLFetch eller SQLFetchScroll resultera i ett fel eller trunkering. För att förhindra detta måste programmet anropa SQLBindCol för att uttryckligen ombinda efter behov (eller göra det genom att ange deskriptorfält). Alternativt kan programmet anropa SQLFreeStmtmed alternativet SQL_UNBIND för att avbinda alla kolumnbuffertar.

Värdena för instruktionsattribut, till exempel markörtyp, samtidighet för markören, nyckeluppsättningens storlek eller maximal längd, kan ändras när programmet navigerar genom batchen genom anrop till SQLMoreResults. Om detta händer returnerar SQLMoreResults SQL_SUCCESS_WITH_INFO och SQLSTATE 01S02 (alternativvärdet har ändrats).

Anropar SQLCloseCursor eller SQLFreeStmt med alternativet SQL_CLOSE, tar bort alla resultatuppsättningar och radantal som var tillgängliga som ett resultat av körningen av batchen. Instruktionshandtaget återgår till antingen det allokerade eller förberedda tillståndet. Om du anropar SQLCancel för att avbryta en asynkront körningsfunktion när en batch har körts och instruktionshandtaget är i det körda, markörpositionerade eller asynkrona tillståndet resulterar det i alla resultatuppsättningar och radantal som genereras av batchen som ignoreras om det avbrutna anropet lyckades. -instruktionen återgår sedan till det förberedda eller allokerade tillståndet.

Om en sats med instruktioner eller en procedur blandar andra SQL-uttryck med SELECT-, UPDATE-, INSERT- och DELETE-instruktioner påverkar inte dessa andra instruktioner SQLMoreResults.

Mer information finns i Flera resultat.

Om en sök-, infognings- eller borttagningsinstruktion i en batch med instruktioner inte påverkar några rader i datakällan returnerar SQLMoreResults SQL_SUCCESS. Detta skiljer sig från en sökåtgärd för uppdatering, infogning eller borttagning som körs via SQLExecDirect, SQLExecute eller SQLParamData, som returnerar SQL_NO_DATA om det inte påverkar några rader i datakällan. Om ett program anropar SQLRowCount för att hämta radantalet efter att ett anrop till SQLMoreResults inte har påverkat några rader, returnerar SQLRowCount SQL_NO_DATA.

Mer information om den giltiga sekvenseringen av resultatbearbetningsfunktioner finns i Bilaga B: ODBC-tillståndsövergångstabeller.

Mer information om SQL_PARAM_DATA_AVAILABLE och strömmade utdataparametrar finns i Hämta utdataparametrar med SQLGetData.

Tillgänglighet för antal rader

När en batch innehåller flera efterföljande radantalgenererande instruktioner är det möjligt att dessa radantal samlas upp till bara ett radantal. Om en batch till exempel har fem insert-instruktioner kan vissa datakällor returnera fem enskilda radantal. Vissa andra datakällor returnerar bara ett radantal som representerar summan av de fem enskilda radantalen.

När en batch innehåller en kombination av resultatuppsättningsgenererande och radräkningsgenererande instruktioner kan radantal vara tillgängliga eller inte alls. Drivrutinens beteende när det gäller tillgängligheten för radantal räknas upp i den SQL_BATCH_ROW_COUNT informationstyp som är tillgänglig via ett anrop till SQLGetInfo. Anta till exempel att batchen innehåller en SELECT, följt av två INSERT-instruktioner och en annan SELECT. Då är följande fall möjliga:

• Radantalet som motsvarar de två INSERT-uttrycken är inte tillgängliga alls. Det första anropet till SQLMoreResults placerar dig på resultatuppsättningen för den andra SELECT-instruktionen .

• Radantalet som motsvarar de två INSERT-uttrycken är tillgängliga individuellt. (Ett anrop till SQLGetInfo returnerar inte den SQL_BRC_ROLLED_UP biten för den SQL_BATCH_ROW_COUNT informationstypen.) Det första anropet till SQLMoreResults placerar dig på radantalet för den första INSERT och det andra anropet placerar dig på radantalet för den andra INSERT. Det tredje anropet till SQLMoreResults placerar dig på resultatuppsättningen för den andra SELECT-instruktionen .

• Radantalet som motsvarar de två INSERT:erna summeras till ett enda radantal som är tillgängligt. (Ett anrop till SQLGetInfo returnerar den SQL_BRC_ROLLED_UP biten för informationstypen SQL_BATCH_ROW_COUNT.) Det första anropet till SQLMoreResults placerar dig på antalet samlade rader, och det andra anropet till SQLMoreResults placerar dig på resultatuppsättningen för den andra SELECT.

Vissa drivrutiner gör radantal endast tillgängliga för explicita batchar och inte för lagrade procedurer.

Relaterade funktioner

Se även

ODBC API-referens
ODBC-huvudfiler
hämtar utdataparametrar med SQLGetData