NextRecordset Method (ADO)

   Example   Applies To   

Clears the current Recordset object and returns the next Recordset by advancing through a series of commands.

Syntax

Set recordset2 = recordset1.NextRecordset( RecordsAffected )

Return Value

Returns a Recordset object. In the syntax model, recordset1 and recordset2 can be the same Recordset object, or you can use separate objects.

Parameters

RecordsAffected   Optional. A Long variable to which the provider returns the number of records that the current operation affected.

Remarks

Use the NextRecordset method to return the results of the next command in a compound command statement or of a stored procedure that returns multiple results. If you open a Recordset object based on a compound command statement (for example, "SELECT * FROM table1;SELECT * FROM table2") using the Execute method on a Command or the Open method on a Recordset, ADO executes only the first command and returns the results to recordset. To access the results of subsequent commands in the statement, call the NextRecordset method.

As long as there are additional results, the NextRecordset method will continue to return Recordset objects. If a row-returning command returns no records, the returned Recordset object will be empty; test for this case by verifying that the BOF and EOF properties are both True. If a non–row-returning command executes successfully, the returned Recordset object will be closed, which you can verify by testing the State property on the Recordset. When there are no more results, recordset will be set to Nothing.

If an edit is in progress while in immediate update mode, calling the NextRecordset method generates an error; call the Update or CancelUpdate method first.

If you need to pass parameters for more than one command in the compound statement by filling the Parameters collection or by passing an array with the original Open or Execute call, the parameters must be in the same order in the collection or array as their respective commands in the command series. You must finish reading all the results before reading output parameter values.

When you call the NextRecordset method, ADO executes only the next command in the statement. If you explicitly close the Recordset object before stepping through the entire command statement, ADO never executes the remaining commands.

Remote Data Service Usage   The NextRecordset method is not available on a client-side Recordset object.