Wiki source for KeyPgGetfileio


Show raw source

{{fbdoc item="title" value="GET (File I/O)"}}----
Reads data from a file to a buffer

{{fbdoc item="syntax"}}##
**Get** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|Long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], [[KeyPgByref|ByRef]] //data// [[KeyPgAs|As]] [[KeyPgAny|Any]] [, [//amount// [[KeyPgAs|As]] [[KeyPgUinteger|Uinteger]]] [, [[KeyPgByref|ByRef]] //bytesread// [[KeyPgAs|As]] [[KeyPgUinteger|Uinteger]]] ]
**Get** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|Long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], //data// [[KeyPgAs|As]] [[KeyPgString|String]] [, , [[KeyPgByref|ByRef]] //bytesread// [[KeyPgAs|As]] [[KeyPgUinteger|Uinteger]] ]
**Get** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|Long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], //data()// [[KeyPgAs|As]] [[KeyPgAny|Any]] [, , [[KeyPgByref|ByRef]] //bytesread// [[KeyPgAs|As]] [[KeyPgUinteger|Uinteger]] ]
##
{{fbdoc item="usage"}}##
**Get** #//filenum//, //position//, //data// [, [//amount//] [, //bytesread// ] ]
varres = **Get** (#//filenum//, //position//, //data// [, [//amount//] [, //bytesread// ] ] )
##
{{fbdoc item="param"}}
##//filenum//##
The value passed to ##[[KeyPgOpen|Open]]## when the file was opened.
##//position//##
The position where the read must start. If the file was opened ##[[KeyPgRandom|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 or a dereferenced pointer. The read operation will try to fill completely the variable, unless the ##[[KeyPgEof|EOF]]## is reached.
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 ##[[KeyPgString|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 ##[[KeyPgOpValueOf|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// * [[KeyPgSizeof|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.

{{fbdoc item="ret"}}
##**Get()**## returns a 32 bit ##[[KeyPgLong|Long]]##: a zero (##0##) on success; non-zero on error.
Note: if ##[[KeyPgEof|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.

{{fbdoc item="desc"}}
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 ##[[KeyPgRandom|Random]]## mode, the size in bytes of the data to read must match the specified record size.

//Note: If a dereferenced [w/z]string pointer is passed to ##**Get**##, the ##//amount//## parameter is not taken into account as it is by passing a dereferenced numeric pointer. But instead, the pointed buffer must begin with at least as many non-zero elements as the number of elements to read.//

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/get.bas"}}%%(freebasic)
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
%%

{{fbdoc item="filename" value="examples/manual/fileio/get-file.bas"}}%%(freebasic)
' 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
%%

{{fbdoc item="diff"}}
- ##**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.

{{fbdoc item="see"}}
- ##[[KeyPgGetgraphics|Get (Graphics)]]## different usage of same keyword
- ##[[KeyPgPutfileio|Put (File I/O)]]##
- ##[[KeyPgOpen|Open]]##
- ##[[KeyPgClose|Close]]##
- ##[[KeyPgBinary|Binary]]##
- ##[[KeyPgRandom|Random]]##
- ##[[KeyPgFreefile|Freefile]]##
- ##[[ProPgFileIO|File I/O methods comparison]]##

{{fbdoc item="back" value="CatPgFile|File I/O Functions"}}
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode