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 (including 
      referenced by This). The operation will try to transfer to disk the 
      complete variable, unless amount 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 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
   Put() returns a 32 bit 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. 

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.

   Note:
      - If a real [w/z]string variable is passed to Put, the amount 
      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 
      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 is written to the file up to 
      the zero element (terminal element which 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"
   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 Long
   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

   Dim As Byte Ptr lpBuffer
   Dim As Long hFile
   Dim As Integer Counter
   Dim As UInteger 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

   ' '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
   * 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.

See also
   * Put (Graphics) different usage of same keyword 
   * Get (File I/O)
   * Open
   * Close
   * Random
   * Binary
   * FreeFile

