Шаг 122 - Метод GetRows

Описание
Загружает строки объекта Recordset в массив.

Set имяМассива = наборЗаписей.GetRows (числоСтрок)

Параметры
имяМассива
Имя переменной типа Variant, в которой сохраняются возвращаемые данные.
наборЗаписей
Объектная переменная, представляющая объект Recordset.
числоСтрок
Выражение или переменная типа Variant, задающая число возвращаемых строк.

Замечания
Метод GetRows используется для копирования записей из объекта Recordset в двумерный массив. Первый индекс массива определяет поле, а второй номер строки, как в следующей примере, где intField представляет поле, а intRecord задает номер строки:

avarRecords(intField, intRecord)

Для того чтобы возвратить значение первого поля во второй записи, следует использовать такие значения индексов:

field1 = avarRecords(0,1)

Значение второго поля в первой записи возвращается с помощью следующей инструкции:

field2 = avarRecords(1,0)

При возвращении данных методом GetRows переменная avarRecords автоматически превращается в двумерный массив.
Если число затребованных строк превышает действительное число строк, возвращаются только имеющиеся строки. Для определения реально возвращенного методом GetRows числа строк следует вызвать функцию языка Visual Basic для приложений UBound, поскольку массив переменного размера позволяет уместить столько строк, сколько было возвращено. Например, если результаты возвращаются в переменную тип Variant с именем varA, определить число возвращенных строк позволяет следующая инструкция:

numReturned = UBound(varA,2) + 1

Единицу следует добавить, поскольку нумерация элементов массива начинается с нуля. Число возвращаемых строк ограничивается только доступной памятью и должно выбираться в соответствии с реальными потребностями. Не рекомендуется копировать всю таблицу в массив с помощью метода GetRows, особенно, если это большая таблица.
Поскольку в массив записывается содержимое всех полей объекта Recordset, в том числе содержимое полей типа Memo и Long Binary, полезно сначала выполнить запрос, ограничивающий число возвращаемых полей.
После вызова метода GetRows указатель текущей записи переводится на следующую несчитанную строку. Это означает, что в смысле размещения записи вызов GetRows эквивалентен выполнению метода Move на указанное числоСтрок.
Если делается попытка загрузить все строки с помощью многократных вызовов метода GetRows, следует с помощью свойства EOF убедиться, что достигнут конец объекта Recordset. Метод GetRows возвращает меньше строк, чем запрашивалось, либо в конце набора записей, либо при невозможности загрузить какую-либо строку из запрашиваемого диапазона. Например, если не удалось загрузить пятую запись из запрашиваемых десяти записей, GetRows возвратит четыре записи и оставит текущей запись, с которой возникли проблемы. Ошибка выполнения при этом не генерируется. Такая ситуация может возникнуть, если запись удалена другим пользователем из объекта Recordset типа динамического набора записей. Такая ситуация иллюстрируется в примере.

Пример
Следующая программа использует метод GetRows для загрузки указанного числа строк из объекта Recordset и заполнения массива полученными данными. Метод GetRows возвращает менее указанного числа строк в двух случаях: при обнаружения метки конца файла EOF или при попытке загрузки записи, удаленной другим пользователем. Функция возвращает False только в последнем случае. Для выполнения этой процедуры требуется функция GetRowsOK.

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("Борей.mdb")

	Set rstEmployees = dbsNorthwind.OpenRecordset( 	"SELECT Имя, Фамилия, Должность " & 	"FROM Сотрудники ORDER BY Фамилия", dbOpenSnapshot)

	With rstEmployees

		Do While True

			' Принимает от пользователя число строк.

			strMessage = "Введите число загружаемых строк."

			intRows = Val(InputBox(strMessage))

			If intRows <= 0 Then Exit Do

			' При успешном выполнении GetRowsOK печатает результаты;

			' при обнаружении конца файла ничего не делается.

			If GetRowsOK(rstEmployees, intRows, avarRecords) Then

				If intRows > UBound(avarRecords, 2) + 1 Then

					Debug.Print "(Недостаточно записей в объекте " & "Recordset для загрузки " & intRows & " строк.)"

				End If

				Debug.Print UBound(avarRecords, 2) + 1 & " записей обнаружено."

				' Печатает загруженные данные.

				For intRecord = 0 To UBound(avarRecords, 2)

					Debug.Print "    " & 	avarRecords(0, intRecord) & " " & _

						avarRecords(1, intRecord) & ", " & avarRecords(2, intRecord)

				Next intRecord

			Else

				' В предположении, что GetRows возвращает ошибку 

				' из-за изменения данных другим пользователем, 

				' вызывает метод Requery для обновления 

				' объекта Recordset и возобновления операции.

				If .Restartable Then

					If MsgBox("Ошибка в методе GetRows. Повторить?", vbYesNo) = vbYes Then

						.Requery

					Else

						Debug.Print "Ошибка в методе GetRows!"

						Exit Do

					End If

				Else

					Debug.Print "Ошибка в методе GetRows! " & "Неверное значение свойства Restartable!"

					Exit Do

				End If

			End If

			' Так как после вызова GetRows указатель текущей записи

			' остается на последней проверенной записи, переводит

			' указатель в начало объекта Recordset перед

			' выполнением нового цикла поиска.

			.MoveFirst

		Loop

	End With

	rstEmployees.Close

	dbsNorthwind.Close

End Sub

Function GetRowsOK(rstTemp As Recordset, intNumber As Integer, avarData As Variant) As Boolean

	' Сохраняет результаты вызова GetRows в массиве.

	avarData = rstTemp.GetRows(intNumber)

	' Возвращает False, только если возвращено менее указанного

	' количества строк, но не при достижении конца объекта 

	' Recordset.

	If intNumber > UBound(avarData, 2) + 1 And 	Not rstTemp.EOF Then

		GetRowsOK = False

	Else

		GetRowsOK = True

	End If

End Function