SQLMoreResults functie

conformance
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ODBC

Samenvatting
SQLMoreResults bepaalt of er meer resultaten beschikbaar zijn in een instructie met SELECT-, UPDATE-, INSERT- of DELETE-instructies en initialiseert in dat geval de verwerking voor deze resultaten.

Syntaxis

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);  

Argumenten

StatementHandle-
[Invoer] Instructiehandgreep.

Retouren

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

Diagnostiek

Wanneer SQLMoreResults SQL_ERROR of SQL_SUCCESS_WITH_INFO retourneert, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_STMT en een Handle of StatementHandle. De volgende tabel bevat de SQLSTATE-waarden die vaak worden geretourneerd door SQLMoreResults en legt elke waarden uit in de context van deze functie; de notatie (DM)' voorafgaat aan de beschrijvingen van SQLSTATEs die worden geretourneerd door Driver Manager. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Opmerkingen

SELECT-instructies retourneren resultaatsets. Met de instructies UPDATE, INSERT en DELETE wordt het aantal betrokken rijen geretourneerd. Als een van deze instructies in batches wordt verzonden, ingediend met matrices van parameters (genummerd in toenemende parametervolgorde, in de volgorde waarin ze in de batch worden weergegeven) of in procedures, kunnen ze meerdere resultatensets of rijaantallen retourneren. Zie Batches van SQL-instructies en matrices van parameterwaarden voor meer informatie over batches met instructies en matrices van parameters.

Nadat de batch is uitgevoerd, wordt de toepassing op de eerste resultatenset geplaatst. De toepassing kan SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos en alle metagegevensfuncties aanroepen, op de eerste of eventuele volgende resultatensets, net zoals bij één resultatenset. Zodra deze is voltooid met de eerste resultatenset, roept de toepassing SQLMoreResults aan om naar de volgende resultatenset te gaan. Als er een andere resultatenset of telling beschikbaar is, retourneert SQLMoreResults SQL_SUCCESS en initialiseert u de resultatenset of het aantal voor extra verwerking. Als er rijtellingsinstructies worden weergegeven tussen instructies voor het genereren van resultatensets, kunnen ze worden overgestapt door SQLMoreResults aan te roepen. Nadat u SQLMoreResults hebt aangeroepen voor UPDATE-, INSERT- of DELETE-instructies , kan een toepassing SQLRowCount aanroepen.

Als er een huidige resultatenset is met niet-gekoppelde rijen, wordt die resultatenset verwijderd en wordt de volgende resultatenset of het volgende aantal beschikbaar. Als alle resultaten zijn verwerkt, retourneert SQLMoreResults SQL_NO_DATA. Voor sommige stuurprogramma's zijn uitvoerparameters en retourwaarden pas beschikbaar als alle resultatensets en het aantal rijen zijn verwerkt. Voor dergelijke stuurprogramma's worden uitvoerparameters en retourwaarden beschikbaar wanneer SQLMoreResults SQL_NO_DATA retourneert.

Alle bindingen die zijn vastgesteld voor de vorige resultatenset blijven geldig. Als de kolomstructuren verschillen voor deze resultatenset, kan het aanroepen van SQLFetch of SQLFetchScroll leiden tot een fout of afkapping. Om dit te voorkomen, moet de toepassing SQLBindCol aanroepen om expliciet opnieuw te koppelen (of doe dit door descriptorvelden in te stellen). De toepassing kan ook SQLFreeStmt aanroepen met een optie van SQL_UNBIND om alle kolombuffers los te koppelen.

De waarden van instructiekenmerken, zoals cursortype, cursor gelijktijdigheid, sleutelsetgrootte of maximale lengte, kunnen veranderen wanneer de toepassing door de batch navigeert door aanroepen naar SQLMoreResults. Als dit gebeurt, retourneert SQLMoreResults SQL_SUCCESS_WITH_INFO en SQLSTATE 01S02 (optiewaarde is gewijzigd).

Als u SQLCloseCursor of SQLFreeStmt aanroept met een optie van SQL_CLOSE, worden alle resultatensets en rijaantallen verwijderd die beschikbaar waren als gevolg van de uitvoering van de batch. De instructiegreep keert terug naar de toegewezen of voorbereide status. SqlCancel aanroepen om een asynchroon uitgevoerde functie te annuleren wanneer een batch is uitgevoerd en de instructiegreep zich in de uitgevoerde, cursorpositie of asynchrone status bevindt, resulteert in alle resultatensets en het aantal rijen dat door de batch wordt gegenereerd als de aanroep annuleren is geslaagd. De instructie keert vervolgens terug naar de voorbereide of toegewezen status.

Als een batch met instructies of een procedure andere SQL-instructies combineert met SELECT-, UPDATE-, INSERT- en DELETE-instructies , hebben deze andere instructies geen invloed op SQLMoreResults.

Zie Meerdere resultaten voor meer informatie.

Als een doorzochte update-, invoeg- of verwijderinstructie in een batch met instructies geen invloed heeft op rijen in de gegevensbron, retourneert SQLMoreResults SQL_SUCCESS. Dit verschilt van het geval bij een doorzochte update, invoeg- of verwijderinstructie die wordt uitgevoerd via SQLExecDirect, SQLExecute of SQLParamData, die SQL_NO_DATA retourneert als deze geen invloed heeft op rijen in de gegevensbron. Als een toepassing SQLRowCount aanroept om het aantal rijen op te halen nadat een aanroep naar SQLMoreResults geen rijen heeft beïnvloed, retourneert SQLRowCount SQL_NO_DATA.

Zie bijlage B: ODBC-statusovergangstabellen voor aanvullende informatie over de geldige volgorde van resultaatverwerkingsfuncties.

Zie Uitvoerparameters ophalen met SQLGetData voor meer informatie over SQL_PARAM_DATA_AVAILABLE en gestreamde uitvoerparameters.

Beschikbaarheid van aantal rijen

Wanneer een batch meerdere opeenvolgende instructies voor het genereren van rijen bevat, is het mogelijk dat deze rijaantallen worden samengevouwen tot slechts één rijaantal. Als een batch bijvoorbeeld vijf invoeginstructies heeft, kunnen bepaalde gegevensbronnen vijf afzonderlijke rijen retourneren. Bepaalde andere gegevensbronnen retourneren slechts één rijaantal dat de som van de vijf afzonderlijke rijen vertegenwoordigt.

Wanneer een batch een combinatie bevat van resultatensetgener- en rijaantal-genererende instructies, zijn rijaantallen mogelijk of helemaal niet beschikbaar. Het gedrag van het stuurprogramma met betrekking tot de beschikbaarheid van het aantal rijen wordt opgesomd in het SQL_BATCH_ROW_COUNT informatietype dat beschikbaar is via een aanroep naar SQLGetInfo. Stel dat de batch een SELECT bevat, gevolgd door twee INSERT-instructies en een andere SELECT. Vervolgens zijn de volgende gevallen mogelijk:

• De rijaantallen die overeenkomen met de twee INSERT-instructies zijn helemaal niet beschikbaar. De eerste aanroep van SQLMoreResults plaatst u in de resultatenset van de tweede SELECT-instructie .

• De rijaantallen die overeenkomen met de twee INSERT-instructies zijn afzonderlijk beschikbaar. (Een aanroep naar SQLGetInfo retourneert niet de SQL_BRC_ROLLED_UP bit voor het SQL_BATCH_ROW_COUNT informatietype.) De eerste aanroep van SQLMoreResults plaatst u op het aantal rijen van de eerste INSERT en de tweede aanroep plaatst u op het aantal rijen van de tweede INSERT. De derde aanroep van SQLMoreResults plaatst u in de resultatenset van de tweede SELECT-instructie .

• De rijaantallen die overeenkomen met de twee INSERT's , worden samengevouwen tot één rijaantal dat beschikbaar is. (Een aanroep naar SQLGetInfo retourneert de SQL_BRC_ROLLED_UP bit voor het SQL_BATCH_ROW_COUNT informatietype.) De eerste aanroep naar SQLMoreResults plaatst u op het aantal samengevouwen rijen en de tweede aanroep naar SQLMoreResults plaatst u in de resultatenset van de tweede SELECT.

Bepaalde stuurprogramma's maken het aantal rijen alleen beschikbaar voor expliciete batches en niet voor opgeslagen procedures.

Verwante functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden
uitvoerparameters ophalen met behulp van SQLGetData