OPEN Statement
Syntax
Syntax: OPEN "filename" FOR mode AS #n [LEN = recLen] [ENCODING enc]
Source: pb_cg_emit_open (pb_codegen.c:6072)
Description
Opens a file and associates it with a numbered file handle (#n). The mode determines the Win32 access flags and creation disposition. V19 adds RANDOM mode with record length and ENCODING support for UTF-8, UTF-16LE, and UTF-16LE BOM files. Internally, OPEN calls CreateFileA to obtain a Win32 file handle, which is stored in the compiler-managed file handle table for subsequent operations.
Parameters
| Parameter | Description |
|---|
filename | Path to the file. A STRING literal or variable expression. |
mode | Access mode: OUTPUT (write, create new), APPEND (write, keep existing), INPUT (read), BINARY (read+write), RANDOM (read+write, fixed-length records). |
n | Integer file number in the range 1 to 255. Each file number represents a distinct open file. |
LEN = recLen | (Optional, RANDOM mode only) Record length in bytes. Determines the size of each record for GET/PUT operations. |
ENCODING enc | V19 (Optional) Text encoding: UTF8, UTF16LE, or UTF16LE_BOM. Affects LINE INPUT and text read operations. |
Access Modes
| Mode | dwDesiredAccess | dwCreationDisposition | Read | Write |
|---|
| INPUT | 0x80000000 (GENERIC_READ) | 3 (OPEN_EXISTING) | Yes | No |
| OUTPUT | 0x40000000 (GENERIC_WRITE) | 2 (CREATE_ALWAYS) | No | Yes |
| APPEND | 0x40000000 (GENERIC_WRITE) | 4 (OPEN_ALWAYS) | No | Yes |
| BINARY | 0xC0000000 (GENERIC_READ|WRITE) | 4 (OPEN_ALWAYS) | Yes | Yes |
| RANDOM V19 | 0xC0000000 (GENERIC_READ|WRITE) | 4 (OPEN_ALWAYS) | Yes | Yes |
Example
' Sequential text output
OPEN "output.txt" FOR OUTPUT AS #1
' Append to existing file
OPEN "log.txt" FOR APPEND AS #2
' Sequential text input
OPEN "input.txt" FOR INPUT AS #3
' Binary read+write
OPEN "data.bin" FOR BINARY AS #4
' Random access with fixed-length records
OPEN "records.dat" FOR RANDOM AS #5 LEN = 128
' Encoding-aware input V19
OPEN "unicode.txt" FOR INPUT ENCODING UTF16LE_BOM AS #6
Generated Assembly
CreateFileA Call
mov rcx, filename_ptr ; lpFileName
mov rdx, <desired_access> ; access flags per mode table
xor r8, r8 ; dwShareMode = 0
xor r9, r9 ; lpSecurityAttributes = NULL
mov [rsp + 32], <creation> ; dwCreationDisposition
mov [rsp + 40], 128 ; FILE_ATTRIBUTE_NORMAL
xor eax, eax
mov [rsp + 48], rax ; hTemplateFile = NULL
call [__imp_CreateFileA]
mov [rbp - handle_offset], rax ; save file handle to handle table
; FOR APPEND: seek to end of file
mov rcx, [rbp - handle_offset]
xor rdx, rdx ; distance = 0
xor r8, r8 ; hiword unused
mov r9, 2 ; FILE_END
call [__imp_SetFilePointer]
RANDOM Mode with LEN V19
; Same CreateFileA sequence as above with GENERIC_READ|GENERIC_WRITE
; LEN value is stored for calculating record offsets:
; record_offset = (record_number - 1) * LEN
; This LEN value is multiplied by the position argument in
; GET/PUT/SEEK to compute the 0-based byte offset for SetFilePointer.
ENCODING Handling V19
; Encoding metadata is stored alongside the file handle.
; LINE INPUT and text read operations check this flag:
; UTF8 - read as bytes, convert multi-byte sequences
; UTF16LE - read UTF-16LE code units, convert to ANSI/UTF-8
; UTF16LE_BOM - skip 2-byte BOM (0xFF 0xFE), then UTF16LE
; Without ENCODING, the file is treated as plain ANSI/ASCII.
Imported WinAPI Functions
| Function | DLL | Purpose |
|---|
CreateFileA | kernel32.dll | Open or create a file, returning a Win32 handle |
SetFilePointer | kernel32.dll | Seek to end of file on APPEND, and for SEEK/GET/PUT positioning |