Método Recordset.GetRows (DAO)

Aplica-se a: Access 2013, Office 2013

Recupera múltiplas linhas de um objeto Recordset.

Sintaxe

expressão . GetRows(NumRows)

expressão Uma variável que representa um objeto Conjunto de registros.

Parâmetros

Nome	Necessária/opcional	Tipo de dados	Descrição
NumRows	Opcional	Variant	O número de linhas a serem recuperadas.

Valor de retorno

Variant

Comentários

Use o método GetRows para copiar registros de um Recordset. GetRows retorna uma matriz bidimensional. A primeira assinatura identifica o campo e a segunda identifica o número da linha. Por exemplo, intField representa o campo, e intRecord identifica o número da linha:

avarRecords(intField, intRecord)

Para obter o primeiro valor do campo na segunda linha retornada, use o código como se segue:

field1 = avarRecords(0,1)

Para obter o segundo valor do campo na primeira linha, use o código como se segue:

field2 = avarRecords(1,0)

A variável avarRecords se torna automaticamente uma matriz bidimensional quando GetRows retorna dados.

Se você solicitar mais linhas do que aquelas disponíveis, GetRows retornará apenas o número de linhas disponíveis. Você pode usar a função UBound do Visual Basic for Applications para determinar quantas linhas GetRows realmente recuperou, porque a matriz deve ajustar-se ao número de linhas retornadas. Por exemplo, se você tiver retornado os resultados em uma Variant chamada varA, poderia usar o código a seguir para determinar quantas linhas foram realmente retornadas:

numReturned = UBound(varA,2) + 1

Você precisa usar "+ 1" porque a primeira linha retornada está no elemento 0 da matriz. O número de linhas que você pode recuperar está restrito pela quantidade de memória disponível. Você não deve usar GetRows para recuperar uma tabela inteira em uma matriz, se ela for grande.

Como GetRows retorna todos os campos do Recordset na matriz, inclusive os campos Memo e Long Binary, é possível usar uma consulta que restrinja os campos retornados.

Depois de chamar GetRows, o registro atual é posicionado na próxima linha não lida. Ou seja, GetRows tem o mesmo efeito no registro atual do que Move numrows.

Se você estiver tentando recuperar todas as linhas utilizando várias chamadas de GetRows, use a propriedade EOF para ter certeza de que está no final do Recordset. GetRows retorna menos que o número solicitado se ele estiver no final de Recordset ou se ele não puder recuperar uma linha no intervalo solicitado. Por exemplo, se você estiver tentando recuperar 10 registros, mas não conseguir recuperar o quinto registro, GetRows retornará quatro registros e tornará o quinto registro o registro atual. Isso não irá gerar nenhum erro de tempo de execução. Isso pode ocorrer se outro usuário excluir um registro em um Recordset tipo dynaset. Consulte o exemplo para obter uma demonstração de como tratar isso.

Exemplo

Este exemplo usa o método GetRows para recuperar um número específico de linhas de um Recordset e para preencher uma matriz com os dados resultantes. O método GetRows retornará menos do que o número de linhas desejado nos dois casos: se EOF tiver sido alcançado ou se GetRows tentou recuperar um registro excluído por outro usuário. A função retornará False somente se o segundo caso ocorrer. A função GetRowsOK é exigida para que este procedimento seja executado.

    Sub GetRowsX() 
     
     Dim dbsNorthwind As Database 
     Dim rstEmployees As Recordset 
     Dim strMessage As String 
     Dim intRows As Integer 
     Dim avarRecords As Variant 
     Dim intRecord As Integer 
     
     Set dbsNorthwind = OpenDatabase("Northwind.mdb") 
     Set rstEmployees = dbsNorthwind.OpenRecordset( _ 
     "SELECT FirstName, LastName, Title " & _ 
     "FROM Employees ORDER BY LastName", dbOpenSnapshot) 
     
     With rstEmployees 
     Do While True 
     ' Get user input for number of rows. 
     strMessage = "Enter number of rows to retrieve." 
     intRows = Val(InputBox(strMessage)) 
     
     If intRows <= 0 Then Exit Do 
     
     ' If GetRowsOK is successful, print the results, 
     ' noting if the end of the file was reached. 
     If GetRowsOK(rstEmployees, intRows, _ 
     avarRecords) Then 
     If intRows > UBound(avarRecords, 2) + 1 Then 
     Debug.Print "(Not enough records in " & _ 
     "Recordset to retrieve " & intRows & _ 
     " rows.)" 
     End If 
     Debug.Print UBound(avarRecords, 2) + 1 & _ 
     " records found." 
     
     ' Print the retrieved data. 
     For intRecord = 0 To UBound(avarRecords, 2) 
     Debug.Print " " & _ 
     avarRecords(0, intRecord) & " " & _ 
     avarRecords(1, intRecord) & ", " & _ 
     avarRecords(2, intRecord) 
     Next intRecord 
     Else 
     ' Assuming the GetRows error was due to data 
     ' changes by another user, use Requery to 
     ' refresh the Recordset and start over. 
     If .Restartable Then 
     If MsgBox("GetRows failed--retry?", _ 
     vbYesNo) = vbYes Then 
     .Requery 
     Else 
     Debug.Print "GetRows failed!" 
     Exit Do 
     End If 
     Else 
     Debug.Print "GetRows failed! " & _ 
     "Recordset not Restartable!" 
     Exit Do 
     End If 
     End If 
     
     ' Because using GetRows leaves the current record 
     ' pointer at the last record accessed, move the 
     ' pointer back to the beginning of the Recordset 
     ' before looping back for another search. 
     .MoveFirst 
     Loop 
     End With 
     
     rstEmployees.Close 
     dbsNorthwind.Close 
     
    End Sub 
     
    Function GetRowsOK(rstTemp As Recordset, _ 
     intNumber As Integer, avarData As Variant) As Boolean 
     
     ' Store results of GetRows method in array. 
     avarData = rstTemp.GetRows(intNumber) 
     ' Return False only if fewer than the desired number of 
     ' rows were returned, but not because the end of the 
     ' Recordset was reached. 
     If intNumber > UBound(avarData, 2) + 1 And _ 
     Not rstTemp.EOF Then 
     GetRowsOK = False 
     Else 
     GetRowsOK = True 
     End If 
     
    End Function