5.4.5.11 Put Statement
Note
This section describes the implementation of MS-VBAL §5.4.5.11 Put Statement.
Syntax
| AST node | Instruction kind(s) | Notes |
|---|---|---|
| KeywordStatementNode | Simple |
Token: Put. |
See RD-VBAL §3.4.3 File Statements.
Runtime Semantics
Put writes through the record surface of a file channel, which it shares with Get
(RD-VBAL §5.4.5 File Statements). This section describes the record
format and record positioning of both statements; see also
RD-VBAL §5.4.5.12 Get Statement.
Record Format
Put and Get use MS-VBAL §5.4.5.11's Variant type descriptors and binary widths. The record format is a wire
format rather than a behaviour.
The record format follows MS-VBA's, so that a file RD-VBA writes is a file MS-VBA reads.
| Data | In a record |
|---|---|
Boolean |
Two bytes. True is FF FF. |
String, in Random mode |
Carries a two-byte length prefix. |
String, in Binary mode |
Carries no length prefix. A String that a Variant holds, an array element and a UDT field carry one. |
Variant |
Preceded by its two-byte type descriptor. |
A Variant that holds a Byte |
The descriptor vbByte (11 00), then the one byte. |
An array variable, in Binary mode |
Its elements, the first subscript varying fastest. A String element carries a two-byte length prefix; a Variant element, its descriptor. An array that was never sized writes nothing. |
A resizable array variable, in Random mode |
Its number of dimensions (two bytes), then the element count and lower bound of each dimension (four bytes each), the last dimension first, then its elements. |
A fixed-size array variable, in Random mode |
Its elements. |
A record longer than the Len of a Random channel |
Nothing: error 59, as in MS-VBA (recorded in Excel). |
A Variant that holds an object, or Nothing |
No record: error 13, as in MS-VBA (recorded in Excel) - once its descriptor, vbObject (09 00), is written in Binary mode; nothing is written in Random mode. A variable declared as an object, or a UDT with one in it, is a compile error. |
A variable or a field of an Enum |
The Long it holds, four bytes (RD-VBAL §5.2.3.4). |
| A UDT | Each member of the UDT, in declaration order, recursively through a nested UDT (see User-Defined Types). |
User-Defined Types
MS-VBAL §5.4.5.11 and
MS-VBAL §5.4.5.12 Get Statement
say "the value of each member of the UDT is written to the file... in the order in which the members are
declared". Put writes, and Get reads, each member of a UDT in declaration order, recursively through a nested
UDT.
UDT field declaration order is the order Put writes a record in
(RD-VBAL §2.5.2.1.3 User-Defined Type (UDT) Values).
Put #1, , myRecord and Get #1, , myRecord serialize and deserialize a whole UDT in one statement.
Put and Get move the serialized size of a UDT: its fields concatenated, with no padding.
Memory widths of UDT fields are not file widths. See RD-VBAL §2.5.2.1.3 User-Defined Type (UDT) Values for the in-memory side.
| UDT field | In a record |
|---|---|
Variable-length String |
A two-byte length prefix, then its characters, in Random and Binary mode alike. |
Fixed-length String |
Its characters in ANSI, padded with spaces or cut to its length. No length prefix. |
Record Positioning
MS-VBAL leaves two gaps in record positioning, and RD-VBA names its choice for each:
| Gap | RD-VBA's choice |
|---|---|
The record length of a Random channel opened without a Len clause |
The channel counts positions in 128-byte records. |
| The byte position of record 1 | Record number 1 is byte 0 of the file. |
Record length. A Random channel whose Open statement declared no Len clause counts positions in 128-byte
records. 128 bytes is MS-VBA's own default record length, and a longer record is error 59, as with a Len clause.
MS-VBAL §5.4.5.1 Open Statement
constrains the Len clause but does not say what an absent Len clause means.
Record 1. MS-VBAL §5.4.5.11 says the file position becomes "exactly <record-number> number of bytes
from the start". It also defaults the Put record number to the current file-pointer-position, which
MS-VBAL §5.4.5.3 Seek Statement
counts from 1.
The record number and the file-pointer-position are one quantity, and Seek and Get must agree on it. That is
why record number 1 is byte 0 of the file
(RD-VBAL §5.4.5.3 Seek Statement).
The next record. On a Random channel, a Put or a Get leaves the file-pointer-position at the start of the
next record, however much of its own record it wrote or read, as in MS-VBA (recorded in Excel). The next Put or
Get without a record number reads or writes the next record, and Loc is the number of the record just written or
read. After a Get, EOF is True when the file ends inside the record read, even when the file holds all of the
variable read.
Implementation
| Name | Role |
|---|---|
RecordDataFormat |
Implements the Put/Get record format: MS-VBAL §5.4.5.11's Variant type descriptors and binary widths. |
| IFileChannel | A file channel. Its record surface is the one Put and Get use. |