共用方式為

FilePut 函式

  • 發行項

更新：2007 年 11 月

將變數資料寫入磁碟檔案。

My 功能在檔案 I/O 作業中的產能和效能勝過 FilePut。如需詳細資訊，請參閱 My.Computer.FileSystem 物件。

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

參數

  • FileNumber
    必要項。任何有效的檔案號碼。

  • Value
    必要項。有效的變數名稱，該名稱包含已寫入磁碟的資料。

  • RecordNumber
    選擇項。寫入開始的資料錄號碼 (Random 模式檔案) 或位元組號碼 (Binary 模式檔案)。

  • ArrayIsDynamic
    選擇項。只有在編寫陣列時才適用。指定是否將陣列視為動態 (Dynamic)，及是否寫入字串的陣列描述項來描述長度。

  • StringIsFixedLength
    選擇項。只有在編寫字串時才適用。指定是否要針對檔案的字串編寫二位元組字串長度的描述項。預設值為 False。

例外狀況

例外狀況類型

錯誤代碼

條件

ArgumentException

63

RecordNumber < 1，且不等於 -1。

IOExceptio

52

FileNumber 不存在。

IOException

54

檔案模式無效。

如果將使用非結構化錯誤處理的 Visual Basic 6.0 應用程式升級，請參閱「錯誤代碼」資料行 (您可以將錯誤代碼與 Number 屬性 (Err 物件) 比對)。但是，請盡可能考慮以 Visual Basic 的結構化例外處理概觀 取代這類錯誤控制項。

備註

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

以 FilePut 寫入的資料，通常是會使用 FileGet 自檔案中讀取。

檔案中的第一個資料錄或位元組位於位置 1，第二個資料錄或位元組則在位置 2，以此類推。如果您省略 RecordNumber，則會寫入前一個 FileGet 或 FilePut 函式後的下一筆資料錄或位元組，或是由前一個 Seek 函式所指向的下一筆資料錄或位元組。

StringIsFixedLength 引數會控制函式是否要將字串解譯為變數或固定長度。FilePut 在引數為 True 時不會寫入長度描述項。如果您將 StringIsFixedLength = True 和 FilePut 搭配使用，則您需要對 FileGet 執行相同動作，而且還必須確定字串會初始化為預期的長度。

Random 模式

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

  • 如果寫入資料的長度小於 FileOpen 函式之 RecordLength 子句所指定的長度，則 FilePut 會以資料錄長度界限寫入後續的資料錄。資料錄結尾與下一筆資料錄開始間的空白將以目前檔案緩衝區的內容填補。因為無法以任何確實方式來判斷填補的數量，所以通常最好讓資料錄長度與寫入資料相符。如果資料長度大於 FileOpen 函式之 RecordLength 子句所指定的長度，將發生例外狀況。

  • 如果寫入的變數是個字串，則 FilePut 會寫入包含字串長度的兩個位元組的描述項，再寫入變數的資料。因此，由 FileOpen 函式之 RecordLength 子句所指定的長度至少必須比字串的實際長度還長 2 個位元組。

  • 如果寫入的變數是個包含數字型別 (Numeric Type) 的物件，則 FilePut 會寫入用於辨識物件 VarType 的兩個位元組，再寫入變數。例如，當寫入包含整數的物件時，FilePut 會寫入六個位元組：兩個位元組用於將此物件識別為 VarType(3) (Integer)，而其他四個位元組用於包含資料。FileOpen 函式之 RecordLength 參數所指定的資料錄長度，至少要大於儲存變數所需之實際位元組數的兩個位元組。

  • 如果寫入的變數是一個包含字串的物件，則 FilePut 會寫入一個雙位元組的描述項來識別物件的 VarType(8)，以及一個雙位元組的描述項來表示字串的長度，然後再寫入字串資料。在 FileOpen 函式中，由 RecordLength 參數所指定的資料錄長度，必須至少比字串的實際長度還大四個位元組。如果想要置入不含描述項的字串，則您應該傳遞 True 給 StringIsFixedLength 參數，而且所讀入的字串應有正確的長度。

  • 如果寫入的變數是個陣列，您可以選擇是否要寫入陣列大小和維度的描述項。Visual Basic 6.0 及較舊的版本會為動態陣列寫入檔案描述項，但是不會為固定大小的陣列寫入描述項。Visual Basic 2005 預設為不寫入描述項。若要寫入描述項，請將 ArrayIsDynamic 參數設定為 True。寫入陣列時，您必須配合讀取陣列的方式；如果陣列將和描述項一起讀取，您就必須寫入描述項。描述項會指定陣列的陣序規範，每個陣序規範的大小和下限。其長度等於 2 加 8 乘以維度的數目：(2 + 8 * NumberOfDimensions)。FileOpen 函式之 RecordLength 子句所指定的資料錄長度，必須大於或等於寫入陣列資料和陣列描述項所需的所有位元組總和。例如，將陣列寫入磁碟時，下列陣列宣告需要 118 個位元組。

    Dim MyArray(4,9) As Integer

  • 如果寫入的變數是任何其他型別的變數 (非變動長度字串或物件)，則 FilePut 只會寫入變數資料。FileOpen 函式之 RecordLength 子句所指定的資料錄長度必須大於或等於被寫入資料的長度。

  • FilePut 寫入結構元素的方式，就像是每個元素是個別寫入的一樣 (除了元素間沒有任何填補外)。VBFixedString 屬性 (Attribute) 可套用於結構中的字串欄位，用來表示字串寫入磁碟時的大小。

    注意事項：

    寫入磁碟時，位元組超過 VBFixedString 屬性所指定的字串欄位會被截斷。

二進位模式

對於在 Binary 模式下開啟的檔案而言，大多數的 Random 模式規則都適用，不過有少數的例外情形。在 Binary 模模式中開啟的檔案所適用的下列規則與 Random 模式的規則不同：

  • FileOpen 函式中的 RecordLength 子句沒有作用。FilePut 會將所有變數連續寫入磁碟中，也就是說資料錄間沒有填補。

  • 對於非結構中陣列的其他陣列，FilePut 只會寫入資料。不會寫入描述項。

  • FilePut 寫入非結構元素的變動長度字串時，不會寫入兩個位元組長的描述項。寫入的位元組數等於字串的字元數。例如，下列陳述式會將 11 個位元組寫入檔案號碼 1：

    Dim hellow As String = "Hello World"
FilePut(1,hellow)

  • 使用 FilePut 函式寫入檔案，需要有 FileIOPermissionAccess 列舉型別的 Write 存取權。

範例

這個範例使用 FilePut 函式將資料寫入檔案中。這裡在檔案中寫入五筆 Person 結構的資料錄。

Structure Person 
   Public ID As Integer
   Public Name As String
End Structure

Sub WriteData()
   Dim PatientRecord As Person
   Dim recordNumber As Integer    
'    Open file for random access.
   FileOpen(1, "C:\TESTFILE.txt", OpenMode.Binary)
   ' Loop 5 times.
   For recordNumber = 1 To 5 
      ' Define ID.
      PatientRecord.ID = recordNumber   
      ' Create a string.
      PatientRecord.Name = "Name " & recordNumber
      ' Write record to file.
      FilePut(1, PatientRecord)
   Next recordNumber
   FileClose(1)
End Sub

智慧型裝置開發人員注意事項

不支援這個函式。

需求

命名空間 (Namespace)︰Microsoft.VisualBasic

**模組︰**FileSystem

組件：Visual Basic Runtime Library (在 Microsoft.VisualBasic.dll 中)

請參閱

參考

FileGet 函式

FileOpen 函式

Seek 函式

FileGetObject 函式

VBFixedStringAttribute 類別

Len 函式 (Visual Basic)

ArgumentException

IOException

其他資源

在 Visual Basic 中寫入檔案