FilePut 関数

[アーティクル]
09/30/2008

更新 : 2007 年 11 月

変数の内容をディスク上のファイルに書き込みます。

My 機能により、FilePut よりも、ファイルの I/O 操作の生産性とパフォーマンスが向上します。詳細については、「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
省略可能です。配列を書き込む場合にだけ適用されます。配列を動的に処理するかどうか、および配列の長さを表す文字列に配列記述子を書き込むかどうかを指定します。
StringIsFixedLength
省略可能です。文字列を書き込む場合にだけ適用されます。文字列に関する 2 バイトの記述子をファイルに書き込むかどうかを指定します。既定のクラスは 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 番目のレコード番号またはバイト位置は 2 になります。引数 RecordNumber を省略すると、最後に呼び出した FileGet 関数または FilePut 関数、あるいは最後に呼び出した Seek 関数が示す位置の次のレコードまたはバイトが書き込まれます。

StringIsFixedLength 引数は、関数が文字列を可変長と固定長どちらで解釈するかを制御します。引数が True のとき、FilePut は長さ記述子を書き込みません。FilePut で StringIsFixedLength = True を指定した場合は、FileGet でも同じように指定する必要があります。また、文字列が正しい長さに初期化されているかどうかを確認する必要もあります。

ランダムモード

Random モードで開いたファイルの場合は、次の規則が適用されます。

書き込むデータの長さが FileOpen 関数の RecordLength 句で指定した長さを超えない限り、FilePut 関数は次のレコードを直前のレコードの終端から書き込みます。レコードの終わりと次のレコードの先頭の間には、ファイルバッファの内容が埋め込まれます。埋め込まれるデータの量は指定できないため、通常はレコード長を書き込むデータ長に合わせます。書き込むデータの長さが FileOpen 関数の RecordLength 句で指定した長さを超えると、例外が発生します。
可変長文字列変数を使う場合、FilePut 関数は文字列の長さを示す 2 バイトの記述子を書き込んでから、変数にデータを書き込みます。FileOpen 関数の RecordLength 句では、文字列の実際の長さより 2 バイト以上大きい値を指定する必要があります。
書き込む変数が数値型を格納するオブジェクトである場合、FilePut 関数は、オブジェクトの VarType を表す 2 バイトのデータを書き込み、次に変数のデータを書き込みます。たとえば、整数型を格納するオブジェクトを書き込む場合、FilePut 関数は 6 バイトを書き込みます。内訳は、VarType(3) (Integer) を示す 2 バイトと、データを格納する 4 バイトです。FileOpen 関数のパラメータ RecordLengthには、実際にデータを格納するために必要なバイト数より 2 バイト以上大きい値を指定する必要があります。
文字列を格納するオブジェクト型の変数を使う場合、FilePut 関数は、オブジェクトの VarType(8) を示す 2 バイトの記述子を書き込んでから、文字列の長さを示す 2 バイトの記述子を書き込み、その後、文字列データを書き込みます。FileOpen 関数のパラメータ RecordLength で指定するレコード長には、文字列の実際の長さより 4 バイト以上大きい値を指定する必要があります。記述子なしで文字列を書き込む場合は、パラメータ StringIsFixedLength に True を渡します。この場合は、正しい長さの文字列を読み込む必要があります。
配列型の変数を使う場合は、配列のサイズと次元を表す記述子を書き込むかどうかを選択できます。Visual Basic 6.0 以前のバージョンでは、動的配列にファイル記述子を書き込みます。固定サイズの配列には書き込みません。Visual Basic 2005 の既定設定では、記述子を書き込みません。記述子を書き込むには、パラメータ ArrayIsDynamic を True に設定します。配列を書き込むときは、配列の読み取り方法に合わせる必要があります。記述子を使って読み取る場合は、記述子を書き込む必要があります。記述子は、配列のランク、サイズ、および各ランクの最小値を指定します。長さが 2 + 次元の数 X 8 に等しい場合は (2 + 8 * NumberOfDimensions) です。FileOpen 関数の RecordLength 句で指定するレコード長は、データと配列の記述子を書き込むために必要なバイト数の合計、またはそれ以上である必要があります。たとえば、次の配列を定義すると、配列がディスクに書き込まれる場合に 118 バイトが必要です。
```
Dim MyArray(4,9) As Integer
```
その他の型の変数 (可変長文字列変数とオブジェクト型変数以外) を使う場合、FilePut 関数は、変数のデータだけを書き込みます。FileOpen 関数の RecordLength 句では、書き込むデータの長さ以上の値を指定する必要があります。

構造体の要素を FilePut 関数を使って書き込む場合、各要素は独立しているかのように書き込まれますが、各要素の間には何も埋め込まれません。VBFixedString 属性を構造体内の文字列フィールドに適用すると、ディスクに書き込むときに文字列のサイズを示すことができます。

メモ :
文字列フィールドのバイト数が、VBFixedString 属性に指定した値よりも大きい場合は、ディスクに書き込むときに文字列が切り取られます。

バイナリモード

Binary モードで開かれているファイルでは、Random モードの規則のほとんどが適用されますが、いくつか例外があります。Binary モードで開かれたファイルの次の規則は、Random モードの規則と異なります。

FileOpen 関数の RecordLength 句は無効です。FilePut はすべての変数を連続して (レコードの間にパディングを入れずに) ディスクに書き込みます。
構造体配列以外の配列の場合、FilePut 関数は、データだけを書き込みます。記述子は書き込みません。
構造体の要素でない可変長文字列を使用する場合、FilePut 関数は、2 バイトの記述子を書き込みません。書き込まれるバイト数は、文字列内の文字数と同じです。たとえば、次のステートメントは、ファイル番号 1 のファイルに 11 バイトのデータを書き込みます。
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
FilePut 関数を使用してファイルにデータを書き込むには、FileIOPermissionAccess 列挙体からの Write アクセスが必要です。

使用例

FilePut 関数を使って、データをファイルに書き込む例を次に示します。この例では、構造体 Person の 5 つのレコードをファイルに書き込みます。

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