Put (File I/O)
Writes data from a buffer to a file
Syntax
`
Put #filenum As Long, [position As LongInt], data As Any [, amount As UInteger]
Put #filenum As Long, [position As LongInt], data As String
Put #filenum As Long, [position As LongInt], data() As Any
`
Usage
`
Put #filenum, position, data [, amount]
varres = Put (#filenum, position, data [, amount])
`
Parameters
`filenum`
The value passed to `Open` when the file was opened.
`position`
Is the position where `Put` must start in the file. If the file was opened `For Random`, the position is in records, else it is given in bytes. If omitted, writing starts at the present file pointer position. The position is 1-based: i.e. the first record or byte of a file is at position `1`.
If `position` is omitted or zero (`0`), file writing will start from the current file position.
`data`
Is the buffer where data is written from. It can be a numeric variable, a string, an array or a user-defined type (including referenced by `This`). The operation will try to transfer to disk the complete variable, unless `amount` is given. For a user-defined type instance, the data impacted is only the non-static data members.
When putting arrays, `data` should be followed by an empty pair of brackets: '`()`'. `Put` will write all of the data in the array. `amount` is not allowed.
When putting `String`s, the number of bytes written is the same as the number of bytes in the string data. `amount` is not allowed.
Note: If you want to write values from a buffer, you should NOT pass a pointer to the buffer; instead you should pass the first variable in the buffer (this can be done by dereferencing the pointer with `Operator * (Value Of)`). If you pass a pointer directly, then `Put` will put the memory from the pointer variable, not the memory it points to.
`amount`
Makes `Put` write to file `amount` consecutive variables to the file - i.e. it writes `( amount * SizeOf(data) )` bytes of data, starting at `data`'s location in memory, into the file. If `amount` is omitted it defaults to `1`, meaning that `Put` just writes a single variable.
Return Value
`Put()` returns a 32 bit `Long`: `0` on success; nonzero on error. "disk full" is considered as an error, and results in return code `3`. An "exact" amount of data written before is not available, and wouldn't be really useful anyway.
Description
Writes binary data from a buffer variable to a file opened in `Binary` or `Random` mode.
`Put` can be used as a function, and will return `0` on success or an error code on failure.
For files opened in `Random` mode, the size in bytes of the data to write must match the specified record size.
Note:
- If a real [w/z]string variable is passed to `Put`, the `amount` parameter should be forbidden as it is when passing a string. Do not use. Otherwise, it is dangerously used to multiply the string length to be written to the file, but possibly by overflowing outside the provided [w/z]string buffer.
- If a dereferenced [w/z]string pointer is passed to `Put`, the `amount` parameter is not taken into account as it is when passing a dereferenced numeric pointer. Do not use. But instead of respecting the `amount` parameter, the pointed buffer is written to the file up to the zero element (terminal element which is excluded).
- For finer granularity, any [w/z]string variable can be safely passed to `Put` as numeric buffer by providing the first numeric element (an indexed [w/z]string variable, or a dereferenced [w/z]string pointer then indexed) and the number of numeric elements to be processed.
Note:
- Using `Put #` is naturally dedicated to Binary/Random Access file mode.
- It is also allowed in Ouput/Append Access file mode, but this was never well tested and results may vary.
Example
`
' Create variables for the file number, and the number to put
Dim As Long f
Dim As Long value
' Find the first free file number
f = FreeFile()
' Open the file "file.ext" for binary usage, using the file number "f"
Open "file.ext" For Binary As #f
value= 10
' Write the bytes of the integer 'value' into the file, using file number "f"
' starting at the beginning of the file (position 1)
Put #f, 1, value
' Close the file
Close #f
`
`
' Create an integer array
Dim buffer(1 To 10) As Integer
For i As Integer = 1 To 10
buffer(i) = i
Next
' Find the first free file file number
Dim f As Long
f = FreeFile()
' Open the file "file.ext" for binary usage, using the file number "f"
Open "file.ext" For Binary As #f
' Write the array into the file, using file number "f"
' starting at the beginning of the file (position 1)
Put #f, 1, buffer()
' Close the file
Close #f
`
`
Dim As Byte Ptr lpBuffer
Dim As Long hFile
Dim As Integer Counter
Dim As UInteger Size
Size = 256
lpBuffer = Allocate(Size)
For Counter = 0 To Size-1
lpBuffer[Counter] = (Counter And &HFF)
Next
' Get free file file number
hFile = FreeFile()
' Open the file "test.bin" in binary writing mode
Open "test.bin" For Binary Access Write As #hFile
' Write 256 bytes from the memory pointed to by lpBuffer
Put #hFile, , lpBuffer[0], Size
' Close the file
Close #hFile
' Free the allocated memory
Deallocate lpBuffer
`
`
' 'THIS' can be used as argument for writing/filling all non-static data of an UDT instance to/from a file
Type UDT
Dim As String * 32 s
Dim As Double d
Declare Sub Save(ByRef filename As String)
Declare Sub Load(ByRef filename As String)
End Type
Sub UDT.Save(ByRef filename As String)
Dim As Integer f
f = FreeFile()
Open filename For Binary As #f
Put #f, , This '' writes all non-static data of the UDT instance to the file
Close #f
End Sub
Sub UDT.Load(ByRef filename As String)
Dim As Integer f
f = FreeFile()
Open filename For Binary As #f
Get #f, , This '' fills all non-static data of the UDT instance from the file
Close #f
End Sub
Dim As UDT u1
u1.s = "PI number"
u1.d = 3.14159
u1.Save("file.ext")
Dim As UDT u2
u2.Load("file.ext")
Print u2.s
Print u2.d
`
Differences from QB

- `Put` can write full arrays as in VB or, alternatively, write a multiple of the data size from `buffer`'s memory location.
- `Put` can be used as a function in FB, to find the success/error code returned without having to use error handling procedures.

See also

- `Put (Graphics)` different usage of same keyword
- `Get (File I/O)`
- `Open`
- `Close`
- `Random`
- `Binary`
- `FreeFile`