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. 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 Strings, 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

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.

Example

' 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

' 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

Example

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

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.