PUT Statement

Syntax

Description

Writes binary data from a variable to the file associated with file number #n. The file must be opened for BINARY or RANDOM access. If the optional position is specified, the file pointer is first set to that position before writing. In RANDOM mode, the position represents a 1-based record number (byte offset = (position - 1) * LEN). In BINARY mode, the position represents a 1-based byte position.

The number of bytes written is determined by the data type of the source variable: 1 byte for BYTE, 2 bytes for WORD/INTEGER, 4 bytes for LONG, 8 bytes for QUAD/DOUBLE, and the record length for UDTs. V19 uses the packed scalar byte size instead of a fixed 8-byte default.

Parameters

Example

TYPE Employee
    id AS LONG
    nam AS STRING * 32
    salary AS SINGLE
END TYPE

FUNCTION PBMAIN() AS LONG
    LOCAL emp AS Employee
    LOCAL val AS LONG

    ' Binary mode: write LONG at byte position 1 (start of file)
    val = 12345
    OPEN "data.bin" FOR BINARY AS #1
    PUT #1, 1, val          ' write 4 bytes at offset 0
    CLOSE #1

    ' Random mode: write record 3 (each 40 bytes)
    emp.id = 100
    emp.nam = "Alice Johnson"
    emp.salary = 75000.0
    OPEN "employees.dat" FOR RANDOM AS #2 LEN = 40
    PUT #2, 3, emp          ' write at offset (3-1) * 40 = 80
    CLOSE #2

    FUNCTION = 0
END FUNCTION

Generated Assembly

PUT with Position (Seek + Write)

; Step 1: If position specified, seek to correct offset
; RANDOM mode: offset = (position - 1) * record_length
; BINARY mode: offset = (position - 1) * sizeof(variable)
cmp    rax, 1                           ; check position >= 1
jge    __pb_put_compute_offset
xor    rax, rax                         ; clamp to 0 if < 1
jmp    __pb_put_seek
__pb_put_compute_offset:
sub    rax, 1                           ; 1-based -> 0-based
imul   rax, <record_length_or_size>     ; multiply by record/element size
__pb_put_seek:
mov    rcx, [rbp - handle_offset]
mov    rdx, rax                         ; distance to move
xor    r8, r8                           ; 0 for low DWORD
mov    r9, 0                            ; FILE_BEGIN
call   [__imp_SetFilePointer]

; Step 2: Write data from variable to file
mov    rcx, [rbp - handle_offset]       ; file handle
lea    rdx, [rbp - buffer_offset]        ; address of source variable
mov    r8, <element_size>              ; bytes to write (depends on type)
lea    r9, [rbp - written_offset]        ; lpBytesWritten
mov    [rsp + 32], 0                    ; lpOverlapped = NULL
call   [__imp_WriteFile]

PUT without Position (Sequential Write)

; No seek: write at current file pointer
mov    rcx, [rbp - handle_offset]       ; file handle
lea    rdx, [rbp - buffer_offset]        ; address of source data
mov    r8, <element_size>              ; bytes to write
lea    r9, [rbp - written_offset]        ; lpBytesWritten
mov    [rsp + 32], 0                    ; lpOverlapped = NULL
call   [__imp_WriteFile]

Scalar Size Reference V19

Imported WinAPI Functions

Notes

• UDTs with dynamic STRING or WSTRING fields are rejected in BINARY/RANDOM mode V19.
• The file is NOT automatically truncated when writing past the current end of file; the file extends as needed.
• Use SEEK #n, pos to position the file pointer separately from a PUT.
• PUT and GET complement each other: data written with PUT can be read back with GET using the same variable type and position.