Get (File I/O)
Reads data from a file to a buffer
Syntax
`
Get #filenum As Long, [position As LongInt], ByRef data As Any [, [amount As UInteger] [, ByRef bytesread As UInteger] ]
Get #filenum As Long, [position As LongInt], data As String [, , ByRef bytesread As UInteger ]
Get #filenum As Long, [position As LongInt], data() As Any [, , ByRef bytesread As UInteger ]
`
Usage
`
Get #filenum, position, data [, [amount] [, bytesread ] ]
varres = Get (#filenum, position, data [, [amount] [, bytesread ] ] )
`
Parameters
`filenum`
The value passed to `Open` when the file was opened.
`position`
The position where the read must start. If the file was opened `For Random`, the position is in records; otherwise, it is in bytes. If omitted, reading starts at the present file pointer position. The position is 1-based: i.e. first record or byte of a file is at position `1`.
If `position` is omitted or zero (`0`), file reading will start from the current file position.
`data`
The buffer where data is written. It can be a numeric variable, a string, an array, a user defined type (including referenced by `This`), or a dereferenced pointer. The read operation will try to fill completely the variable, unless the `EOF` is reached. For a user-defined type instance, the data impacted is only the non-static data members.
When getting arrays, `data` should be followed by an empty pair of brackets: "`()`". `Get` will read data for all of the values in the array. `amount` is not allowed.
When getting `String`s, the number of bytes read is the same as the number of bytes in the string data. `amount` is not allowed.
Note: If you want to read values into 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 `Get` will overwrite the pointer variable, not the memory it points to.
`amount`
Makes `Get` read `amount` consecutive variables from file to memory, i.e. it reads `(amount * SizeOf(data) )` bytes of data from file into the memory starting at `data`'s memory location. If `amount` is omitted it defaults to `1`, meaning that `Get` just reads a single variable.
`bytesread`
An unsigned integer variable to accept the result of the number of bytes read successfully from the file.
Return Value
`Get()` returns a 32 bit `Long`: a zero (`0`) on success; non-zero on error.
Note: if `EOF` (end of file) is reached while reading, `Get` will return success. The amount of bytes actually read can be checked by passing a `bytesread` variable.
Description
Reads binary data from a file to a buffer variable
`Get` 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 read must match the specified record size.
Note:
- If a real [w/z]string variable is passed to `Get`, the `amount` parameter should be forbidden as it is when passing a string. Do not use. Otherwise, it is ignored (except for the '0' value).
- If a dereferenced [w/z]string pointer is passed to `Get`, 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 must begin with at least as many non-zero elements as the number of elements to read.
- For finer granularity, any [w/z]string variable can be safely passed to `Get` as a 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 `Get #` is naturally dedicated to Binary/Random Access file mode.
- It is also allowed in Input Access file mode, but this was never well tested and results may vary.
Example
`
Dim Shared f As Integer
Sub get_long()
Dim buffer As Long ' Long variable
' Read a Long (4 bytes) from the file into buffer, using file number "f".
Get #f, , buffer
' print out result
Print buffer
Print
End Sub
Sub get_array()
Dim an_array(0 To 10-1) As Long ' array of Longs
' Read 10 Longs (10 * 4 = 40 bytes) from the file into an_array, using file number "f".
Get #f, , an_array()
' print out result
For i As Integer = 0 To 10-1
Print an_array(i)
Next
Print
End Sub
Sub get_mem
Dim pmem As Long Ptr
' allocate memory for 5 Longs
pmem = Allocate(5 * SizeOf(Long))
' Read 5 Longs (5 * 4 = 20 bytes) from the file into allocated memory
Get #f, , *pmem, 5 ' Note pmem must be dereferenced (*pmem, or pmem[0])
' print out result using [] Pointer Indexing
For i As Integer = 0 To 5-1
Print pmem[i]
Next
Print
' free pointer memory to prevent memory leak
Deallocate pmem
End Sub
' Find the first free file file number.
f = FreeFile
' Open the file "file.ext" for binary usage, using the file number "f".
Open "file.ext" For Binary As #f
get_long()
get_array()
get_mem()
' Close the file.
Close #f
`
`
' Load a small text file to a string
Function LoadFile(ByRef filename As String) As String
Dim h As Integer
Dim txt As String
h = FreeFile
If Open( filename For Binary Access Read As #h ) <> 0 Then Return ""
If LOF(h) > 0 Then
txt = String(LOF(h), 0)
If Get( #h, ,txt ) <> 0 Then txt = ""
End If
Close #h
Return txt
End Function
Dim ExampleStr As String
ExampleStr = LoadFile("smallfile.txt")
Print ExampleStr
`
`
' '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

- `Get` in FB can read full arrays as in VB or, alternatively, read a multiple of the data size into the memory.
- `Get` can be used as a function in FB, to find the success/error code returned without having to use error handling procedures.
- FB allows the `bytesread` parameter, to check how many bytes have been successfully read in.

See also

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