Get statement (LotusScript® Language)

Reads data from a binary file or a random file into a variable.

Syntax

Get # fileNumber , [ recordNumber ] , variableName

Elements

fileNumber

The 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 retrieval begins. If you omit recordNumber, LotusScript® retrieves data beginning from the current file position.

variableName

The variable to be used for storing the retrieved data. variableName cannot be an array. However, a fixed-length array defined within a data type is allowed (this array could also contain other arrays as elements).

Usage

The first byte or record in a file is always file position 1. After each read 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

The Get statement reads data into variableName depending on the variable's data type. The following table shows how the Get statement behaves for different data types.


variableName data type	Get statement's behavior
Variant	The Get statement interprets the first two bytes as the DataType of the data to be read. If the DataType is EMPTY or NULL, the Get statement stops reading data and sets variableName to EMPTY or NULL. If the DataType is numeric, the Get statement reads the appropriate number of bytes used to store data of that Data Type: 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 Get statement reads the specified number of characters. For example, if a variable is declared as String*10, the Get statement reads exactly 10 characters.
Variable-length string	The Get statement behaves differently, depending on the type of file you're using. Random file: The first two bytes read indicate the string's length. The Get statement reads exactly that number of characters. If variableName is larger than a random file record, data is read from the file until variableName is filled. After variableName is filled, the file position is advanced to the next record. Binary file: The number of bytes read from the file is equal to the length of the string currently assigned to variableName. If variableName has not been initialized, no data is read from the file.
A variable of a user-defined type	The number of bytes required to read the data is the sum of the number of bytes required to read 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