Put statement (LotusScript® Language)

Writes data from a variable to a binary file or a random file.

Syntax

Put [#] fileNumber , [ recordNumber ] , variableName

Elements

fileNumber

The file number assigned to the file when it was opened with the Open statement. Note that the pound sign (#), fileNumber, and variableName are all required.

recordNumber

Optional. The file position (the byte position in a binary file, or the record number in a random file) where data is written. If you omit the recordNumber, data is written starting at the current file position.

variableName

The variable holding the data to be written. variableName cannot be an array; however, a fixed-length array defined within a data type is allowed (this array could even contain other arrays as elements).

Usage

The first byte or record in a file is always file position 1. After each write operation, the file position is advanced:

For a binary file, by the size of the variable
For a random file, by the size of a record

If variableName is shorter than the length of a record in the file, Put does not overwrite or delete any data that may already be stored in the remainder of that record.

The following table shows how the Put statement behaves for different data types.


variableName data type	Put statement's behavior
Variant	The Put statement writes the DataType as the first two bytes before the value itself. If the DataType is EMPTY or NULL, the Put statement writes no more data. If the DataType is numeric, the Put statement writes the number of bytes of data appropriate for that DataType: Byte: 1 byte Boolean: 2 bytes Integer: 2 bytes Long: 4 bytes Single: 4 bytes Double: 8 bytes Currency: 8 bytes Date/time: 8 bytes
Fixed-length String	The Put statement writes the specified number of characters. For example, if a variable is declared as String * 10, then exactly 10 characters are written.
Variable-length String	The Put statement behaves differently, depending on the type of file you're using. Random files: The first two bytes written indicate the length of the string. Then the Put statement writes the number of characters specified by that length. If variableName is not initialized, the Put statement writes a string of length 0. If variableName is longer than a record, LotusScript® generates the "Bad record length" error. If variableName is shorter than a record, the remainder of the record is not cleared. Binary files: The number of bytes written to the file is equal to the length of the string currently stored in variableName. If variableName is not initialized, no data is written to the file. Note that in binary files, data is written without regard to record length.
User-defined data type	The Put statement writes the sum of the bytes required to write all members of the used-defined data type, which cannot contain a dynamic array, a list, or an object.

Note: Even though strings in LotusScript® 4 can be longer than 64K, there are still restrictions with the length of the string you can read or write using the GET and PUT statements. The only combination of filetypes that will work with long strings is with a binary file and a variable-length string. Fixed length strings, strings in variants, and random files will not work with strings greater than 64K in length because they have a two-byte header which contains the length of the string. Two bytes cannot represent more than 64K.

Example