FileGetObject 函式

發行項
08/21/2008

更新：2007 年 11 月

自開啟的磁碟檔讀取資料至變數中。

My 功能在檔案 I/O 作業中的產能和效能勝過 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。

備註

如果傳回的是 Object 型別，而非其他型別，例如 Integer、Long、Short 等等，則會使用 FileGetObject 函式來取代 FileGet，以避免在編譯時期產生語意模糊的情況。

如果您想要寫出 Variant 型別，FileGetObject 則為必要項。在不確定時，如果您要使用物件來做為第二個參數，則建議您一律使用 FilePutObject 和 FileGetObject。

FileGetObject 只在 Random 和 Binary 模式中有效。

以 FileGetObject 讀取的資料通常是使用 FilePutObject 寫入。

檔案中的第一個資料錄或位元組位於位置 1，第二個資料錄或位元組則在位置 2，以此類推。如果您省略 RecordNumber，則 FileGetObject 會讀取在最後的 FileGetObject 或 FilePutObject 函式 (或最後的 Seek 函式所指向的資料錄或位元組) 之後的下一筆資料錄或位元組。

Random 模式

下列規則適用於在 Random 模式下開啟的檔案：

如果所讀取資料的長度小於 FileOpen 函式中 RecordLength 子句所指定的長度，則 FileGetObject 會以資料錄長度界限讀取後續的資料錄。資料錄結尾與下一筆資料錄開始間的空白將以目前檔案緩衝區的內容填補。因為無法準確判斷填補資料的數量，所以通常可以將資料錄的長度設為被讀取資料的長度。
如果讀入的變數是一個字串，則依照預設 FileGetObject 會讀取包含字串長度的雙位元組描述項，然後再讀取傳到變數中的資料。因此，由 FileOpen 函式之 RecordLength 子句所指定的資料錄長度，至少必須比字串的實際長度還長 2 個位元組。Visual Basic 6.0 及更早的版本會支援固定長度的字串，而且在讀入檔案時，並不會寫入長度描述項。如果想讀取不含描述項的字串，則您應該傳遞 True 給 StringIsFixedLength 參數，且所讀入的字串應為正確長度。
如果被讀入資料的變數是一個陣列，則您可以選擇讀取陣列的大小及維度的描述項。若要讀取描述項，請將 ArrayIsDynamic 參數設定為 True。讀取陣列時，您必須配合陣列寫入的方式。如果陣列在寫入時包含描述項，您就必須讀取描述項。如果沒有使用描述項，則會用傳送到 FileGetObject 的陣列大小和界限來決定要讀取什麼。

描述項會指定陣列的陣序規範，每個陣序規範的大小和下限。其長度等於 2 加 8 乘以維度的數目：2 + 8 * NumberOfDimensions。FileOpen 函式中 RecordLength 參數所指定的資料錄長度，必須大於或等於寫入陣列資料和陣列描述項所需的所有位元組總和。例如，當以下陣列被寫入磁碟時，其陣列宣告需要 118 個位元組：
```
Dim MyArray(4,9) As Integer
```
118 位元組的分散如下：描述項佔有 18 個位元組 (2 + 8 * 2)，資料則佔有 100 個位元組 (5 * 10 * 2)。
FileGetObject 讀取結構元素的方式，就像是每個元素是個別讀取的一樣 (除了元素間沒有任何填補外)。在磁碟中，使用者定義型別的動態陣列 (以 FilePutObject 寫入) 是以其長度等於 2 加 8 乘以維度數的描述項當做前置字元：2 + 8 * NumberOfDimensions。FileOpen 函式中 RecordLength 子句所指定的資料錄長度必須大於或等於讀取個別項目所需的所有位元組總和，包含任何陣列及其描述項。VBFixedStringAttribute 類別可套用於結構的字串欄位，以表示字串寫入磁碟時的大小。

二進位模式

若為在 Binary 模式中所開啟的檔案，則適用所有 Random 規則，但有下列例外狀況：

FileOpen 函式中的 RecordLength 子句沒有作用。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)