Put (statement)

Syntax

Put [#]filenumber, [recordnumber], variable

Description

Writes data from the specified variable to a Random or Binary file.

Comments

The Put statement accepts the following parameters:

 

Parameter

Description

 

filenumber

Integer representing the file to be written to. This is the same value as returned by the Open statement.

 

recordnumber

Long specifying which record is to be written to the file.

For Binary files, this number represents the first byte to be written starting with the beginning of the file (the first byte is 1). For Random files, this number represents the record number starting with the beginning of the file (the first record is 1). This value ranges from 1 to 2147483647.

If the recordnumber parameter is omitted, the next record is written to the file (if no records have been written yet, then the first record in the file is written). When recordnumber is omitted, the commas must still appear, as in the following example:

 Put #1,,recvar

If recordlength is specified, it overrides any previous change in file position specified with the Seek statement.

 

The variable parameter is the name of any variable of any of the following types:

 

Variable Type

File Storage Description

 

Integer

2 bytes are written to the file.

 

Long

4 bytes are written to the file.

 

String
(variable-length

In Binary files, variable-length strings are written by first determining the specified string variable's length, then writing that many bytes to the file.

In Random files, variable-length strings are written by first writing a 2-byte length, then writing that many characters to the file.

 

String
(fixed-length)

Fixed-length strings are written to Random and Binary files in the same way: the number of characters equal to the string's declared length are written.

 

Double

8 bytes are written to the file (IEEE format).

 

Single

4 bytes are written to the file (IEEE format).

 

Date

8 bytes are written to the file (IEEE double format).

 

Boolean

2 bytes are written to the file (either –1 for TRUE or 0 for FALSE).

 

Variant

A 2-byte VarType is written to the file followed by the data as described above. With variants of type 10 (user-defined errors), the 2-byte VarType is followed by a 2-byte unsigned integer (the error value), which is then followed by 2 additional bytes of information.

The exception is with strings, which are always preceded by a 2-byte string length.

 

User-defined types

Each member of a user-defined data type is written individually.

In Binary files, variable-length strings within user-defined types are written by first writing a 2-byte length followed by the string's content. This storage is different than variable-length strings outside of user-defined types.

When writing user-defined types, the record length must be greater than or equal to the combined size of each element within the data type.

 

Arrays

Arrays cannot be written to a file using the Put statement.

 

Objects

Object variables cannot be written to a file using the Put statement.

 

With Random files, a runtime error will occur if the length of the data being written exceeds the record length (specified as the reclen parameter with the Open statement). If the length of the data being written is less than the record length, the entire record is written along with padding (whatever data happens to be in the I/O buffer at that time). With Binary files, the data elements are written contiguously: they are never separated with padding.

Example

This example opens a file for random write, then writes ten records into the file with the values 10-50. Then the file is closed and reopened in random mode for read, and the records are read with the Get statement. The result is displayed in a dialog box.

Sub Main()
  Open "test.dat" For Random Access Write As #1
  For x = 1 To 10
    r% = x * 10
    Put #1,x,r%
  Next x
  Close

  Open "test.dat" For Random Access Read As #1
  For x = 1 To 10
    Get #1,x,r%
    msg1 = "Record " & x & " is: " & r% & Basic.Eoln$
  Next x

  MsgBox msg1
  Close
  Kill "test.dat"
End Sub

See Also

Open (statement); Put (statement); Write# (statement); Print# (statement).

More information

P