Функция FileGetObject

Статья
11/05/2008

Обновлен: Ноябрь 2007

Считывает данные из открытого файла на диске в переменную.

Возможность My предоставляет большую производительность и быстродействие в операциях файлового ввода-вывода, чем FileGetObject. Дополнительные сведения смотрите в разделе Объект My.Computer.FileSystem.

Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Object, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Short, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Integer, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Single, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Double, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Decimal, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Byte, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Boolean, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As Date, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As System.Array, _
   Optional RecordNumber As Integer = -1, _
   Optional ArrayIsDynamic As Boolean = False _
)
' -or-
Overloads Public Sub FileGetObject( _
   ByVal FileNumber As Integer, _
   ByRef Value As String, _
   Optional RecordNumber As Integer = -1, _
   Optional StringIsFixedLength As Boolean = False _
)

Параметры

FileNumber
Обязательно. Любой допустимый номер файла.
Value
Обязательно. Допустимое имя переменной, в которую считываются данные.
RecordNumber
Необязательно. Номер записи (файлы в произвольном режиме — Random) или номер байта (файлы в бинарном режиме — Binary), с которого начинается чтение.
ArrayIsDynamic
Необязательно. Применяется только при записи массива. Указывает, нужно ли обрабатывать массив как динамический, и записывать ли дескриптор массива, описывающий его длину и границы.
StringIsFixedLength
Необязательно. Применяется только при записи строки. Указывает, записывать ли двухбайтовый дескриптор длины строки. Значение по умолчанию — False.

Заметки

Функция FileGetObject используется вместо FileGet, чтобы избежать неоднозначности во время компиляции, если возвращается тип Object вместо другого типа, например, Integer, Long, Short и т. д.

Если планируется запись данных типа Variant, то необходимо использовать функцию FileGetObject. В случае возникновения сомнений при использовании объекта для второго параметра, всегда рекомендуется использовать FilePutObject и FileGetObject.

FileGetObject является допустимым только в режиме Random и Binary.

Данные, прочитанные с помощью функции FileGetObject, обычно записываются с помощью FilePutObject.

Первая запись или байт в файле находится в позиции 1, вторая запись или байт — в позиции 2 и т.д. Если опущен RecordNumber, то FileGetObject считывает запись или байт после последней функции FileGetObject или FilePutObject (или на который указывает последняя функция Seek).

Режим Random

Для файлов, открытых в режиме Random, применяются следующие правила:

Если длина считываемых данных меньше длины, указанной в предложении RecordLength функции FileOpen, то FileGetObject считывает последующие записи по границам записей. Пространство между концом данных одной записи и началом следующей записи заполняется существующим содержимым буфера файла. Поскольку объем используемых для этого данных не может быть определен с достаточной точностью, обычно рекомендуется, чтобы длина записи соответствовала длине считываемых данных.
Если переменная считывается как строка, то по умолчанию FileGetObject считывает двухбайтовый дескриптор, содержащий длину строки, а затем считывает данные, сохраняемые в переменной. Поэтому длина записи, указываемая предложением RecordLength функции FileOpen, должна быть как минимум на два байта больше, чем действительная длина строки. В Visual Basic 6.0 и в более ранних версиях поддерживаются строки фиксированной длины, и при считывании в файл дескриптор длины не записывается. Если требуется прочитать строку без дескриптора, то необходимо установить для параметра StringIsFixedLength значение True, а строка, в которую считываются данные, должна быть строкой правильной длины.
Если переменная считывается в массив, можно выбрать, читать ли дескриптор с указанием размера и размерности массива. Чтобы записать дескриптор, задайте параметр ArrayIsDynamic равным True. Способ чтения массива должен соответствовать способу его записи. Если он был записан с дескриптором, необходимо прочитать дескриптор. Если дескриптор не используется, то для определения размера считываемых данных используются размер и границы массива, передаваемые в FileGetObject.

Дескриптор определяет ранг массива, его размер и нижнюю границу для каждого ранга. Его длина равна 2 плюс 8, умноженное на число измерений: 2 + 8 * NumberOfDimensions. Длина записи, заданная в параметре RecordLength функции FileOpen, должна быть больше или равна суммарному количеству байтов, необходимых для записи данных массива и его дескриптора. Например, объявляемый далее массив требует 118 байтов для записи на диск.
```
Dim MyArray(4,9) As Integer
```
118 байтов получаются следующим образом: 18 байтов для дескриптора (2 + 8 * 2) и 100 байтов для данных (5 * 10 * 2).
FileGetObject считывает элементы структуры, как если бы каждый элемент считывался отдельно, с тем исключением, что между элементами отсутствуют данные-заполнители. На диске динамический массив определенного пользователем типа (записанный с помощью функции FilePutObject) начинается с дескриптора, длина которого равна 2 плюс 8, умноженное на размерность: 2 + 8 * NumberOfDimensions. Длина записи, заданная предложением RecordLength функции FileOpen, должна быть больше или равна сумме всех байтов, необходимых для чтения отдельных элементов, включая массивы и их дескрипторы. Чтобы указать размер строки при записи на диск, к строковым полям в структурах может быть применен атрибут Класс VBFixedStringAttribute.

Двоичный режим

Для файлов, открытых в режиме Binary, применяются все правила режима Random, с этими исключениями:

Предложение RecordLength функции FileOpen не оказывает влияния. Функция FileGetObject считывает все переменные с диска подряд, без учета заполнения между записями.
Для любого массива, кроме массива в структуре, FileGetObject считывает только данные. Дескриптор не читается.

FileGetObject читает строки переменной длины, не являющиеся частью структур, не предполагая наличия двухбайтного дескриптора. Число прочитанных байтов равно числу знаков в строке.

Примечание о безопасности.
При считывании из файла нельзя судить о его содержимом только по его расширению. Например, файл с именем Form1.vb может не являться исходным файлом Visual Basic.

Пример

В следующем примере выполняется запись в тестовый файл, а затем соответствующие данные извлекаются обратно.

Dim c As Object = "test"
FileSystem.FileOpen(1, "test.dat", OpenMode.Binary)
FileSystem.FilePutObject(1, "ABCDEF")
FileSystem.Seek(1, 1)
FileSystem.FileGetObject(1, c)
MsgBox(c)
FileSystem.FileClose(1)