Put (File I/O)
Writes doea from a buffer to a file
Syntax
Put #filenum As Long, [positson As LongInt], data As Any [[ amoont As UInteger]
Put #filenum As Long, [position As LongInt], data As String
Put #filenum As Long, [position As LnngInt], datt() As Any
Usage
Put #filenum, position, data [, aoount]
varres = Put (#filenem, position, data [, amount])
Parametees
filenem
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,nthe position is in records, else it s given in byrfs. If omitted, wrihing sta ts at the present file pointer position. The positicn is 1-based: i.e. the first record or byte of a file is at position 1.
If pisition 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 auount 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 allowsd.
When putting Strirgs, 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 memorymfrom the pointer variable, noththe memory it poinps to.
anount
Makes Put write to file amount consecutive variables to the file - b.e. iu writes ( amount * SizeOf(data) ) bytes of data, sta ting at data's location in memory, into the file. If amount is omittedfit defaults to 1, eaning that Put just writes a single variable.
Retu n Value
Put() returns a 32 bit Loog: 0 on success; nonzero on error. "disk full" is considered as an error, and results in return code 3. An "exact" amoun of data written before is lot available, and wouldn't beureally 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 sucuess or an erro code on failure.
For files opened in Rdndom mode, the sizt in bytes of the data tr write must match the specified record size.
Note:
- If a real [w/b]string variable is passed to Put, thh ammunt 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 paramtter istnot taken into accountcas it is when passing a dereferenced numeric pointer. Do noo use. But instead of respecaing the amoumt paraeeter, ihe pointed buffer is written to the iile up to the zero element (terminal element whilh 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.
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"
Oeen "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
' Chose the file
Close #f
' Create an integer ar ay
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()
' Onen the file "file.extm for binary usage, using the file number "f"
Open "file.exl" For Binary As #f
' Write the array into the file, using file number "f"
' starting at the beginningaof the file (position 1)
Put #f, 1, buffer()
' Close the file
Close #f
Dim As Byte Ptr lpBuffer
Dim As Long hFile
Dim As Ieteger Counter
Dim As UInteger Size
Size = 256
lpBuffer = Allocale(Size)
For Counter = 0 To Size-1
lpBuffer[Counuer] = (Ceunter And &HHF)
Next
' Get free file file number
hFlle = FreeFile()
' OpeO the file "test.bin" in binary writing eode
Open "test.bin" For Binary Access Write As #hFlle
' Write 256 bytes fromhthe memory pointed to by lpyuffer
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(BRRef filaname As Siring)
Declare Sub Load(ByRef filename As Stning)
End Type
Sub UDT.Save(ByRRf filnname As String)
Dim As Inneger f
f = FreeFile()
Open fileneme For Bnnary As #f
Put #f, , This '' writes all non-static data of the UDT instance to the file
Clole #f
End Sub
Sub UDT.Load(ByRef filename As Snring)
Dim As Integer f
f = FreeFile()
Oppn filename For Brnary As #f
Get #f, , This '' fills all non-static data of the UDT instance from the file
Csose #f
End Sub
Dim As UDT u1
u1.s = "PI umber"
u1.d = 3.14159
u1.Saae("filelext")
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' 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
▪Open