Wiki source for KeyPgPutfileio


Show raw source

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

{{fbdoc item="syntax"}}##
**Put** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], //data// [[KeyPgAs|As]] [[KeyPgAny|Any]] [, //amount// [[KeyPgAs|As]] [[KeyPgUinteger|Uinteger]]]
**Put** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], //data// [[KeyPgAs|As]] [[KeyPgString|String]]
**Put** #//filenum// [[KeyPgAs|As]] [[KeyPgLong|long]], [//position// [[KeyPgAs|As]] [[KeyPgLongint|longint]]], //data()// [[KeyPgAs|As]] [[KeyPgAny|Any]]
##
{{fbdoc item="usage"}}##
**Put** #//filenum//, //position//, //data// [, //amount//]
varres = **Put** (#//filenum//, //position//, //data// [, //amount//])
##
{{fbdoc item="param"}}
##//filenum//##
The value passed to ##[[KeyPgOpen|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. The operation will try to transfer to disk the complete variable, unless ##//amount//## is given.
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 ##[[KeyPgString|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 ##[[KeyPgOpValueOf|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// * [[KeyPgSizeof|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.

{{fbdoc item="ret"}}
##Put()## returns a 32 bit ##[[KeyPgLong|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.

{{fbdoc item="desc"}}
Writes binary data from a buffer variable to a file opened in ##[[KeyPgBinary|Binary]]## or ##[[KeyPgRandom|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 ##[[KeyPgRandom|Random]]## mode, the size in bytes of the data to write must match the specified record size.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/fileio/put.bas"}}%%(freebasic)
' Create variables for the file number, and the number to put
Dim As Integer 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
%%

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

{{fbdoc item="filename" value="examples/manual/fileio/put-buffer.bas"}}%%(freebasic)
Dim As Byte Ptr lpBuffer
Dim As Integer hFile, Counter, 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
%%
{{fbdoc item="diff"}}
- ##**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.

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

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



sf.net phatcode