GET statement

Purpose	Read a record from a random-access file, or a variable or an array from a binary file.
Syntax	Random-Access files: GET [#] filenum&, [Rec], [ABS] Var GET [#] filenum& [, Rec] Binary files: GET [#] filenum&, [RecPos], Var GET [#] filenum&, [RecPos], Arr() [RECORDS rcds] [TO count]
Remarks	A string variable used to receive data may be either ANSI or WIDE, but it must match the CHR mode of the data read from the file. That is, if the data was written as an ANSI string, it should be read into an ANSI string variable. If it was written as a WIDE string, it should be read into a WIDE string variable. Failure to match this CHR mode can cause unpredictable interpretation of the data. GET never performs conversions of ANSI/WIDE characters, regardless of the CHR mode specified in the OPEN statement. It reads data from the file based upon the type of string variable you use. It is the responsibility of the programmer to choose the correct type.
filenum&	The file number under which the file was opened.
	Random Access files
Rec	For random-access files, Rec is the record number to be read, from 1 to 2^63-1 (the maximum positive value for a Quad-integer). If Rec is omitted, the next record in sequence (following the one specified by the most recent GET or PUT) is read. If the file was just opened, the first record is read.
Var	If Var is smaller than the defined record length, GET will read enough data to fill Var. The remainder of the record is discarded and the file pointer is placed at the next record position. If Var is larger than the defined record length, GET will read one record into Var, and the file pointer will be moved to the next record. When GET is used to retrieve data from a random access file into a dynamic (variable-length) string, PowerBASIC looks for a 2-byte (WORD) size field at the beginning of each record which indicates the number of data bytes which follow. If the data is in WIDE format, the size is double the number of characters because each character occupies two bytes. This 2-byte size field is placed in the file automatically by the PUT statement when used with dynamic (variable-length) strings. When the second form of GET is used (without a Var target string), GET reads the file data from the current file pointer into an internal buffer. This data can then be accessed using FIELD string variables.
ABS	When GET is used to read a random file into a dynamic string, it normally expects the first two bytes of the record to contain the length of the valid data contained in the record. The ABS keyword specifies that no length word exists in the data, and the number of bytes to read is defined by the current length of the dynamic string variable. If the variable length is greater than the file record length, the remainder of the string variable is filled with nul's (CHR$(0) or $NUL). This offers greater compatibility with the actual operation of other versions of BASIC, such as PowerBASIC for DOS. A random access file record is limited to 32768 bytes to ensure consistent behavior across all supported Win32 platforms. GET$ and other related functions are not constrained in this manner.
	Binary files
RecPos	For binary files, RecPos is the starting byte or seek position from where the GET should begin. The optional BASE = clause of the OPEN statement defines whether the first position is 0 or 1. The base position is 1 by default. If RecPos is greater than the number of records or bytes in the file, no error occurs but unpredictable data may be read. Use the EOF function to avoid reading past the end of the file.
Var	When used with a binary file, GET retrieves enough data from the file to fill Var. The Var parameter can be a simple (scalar) variable like an Integer or a dynamic (variable-length) string, an element in an array, or a variable of User-Defined Type. When GET is used to read a binary file into a dynamic string, the number of bytes to read is defined by the current size of the dynamic string variable. If the variable length is greater than the file record length, the remainder of the string variable is filled with nuls (CHR$(0) or $NUL). This offers greater compatibility with the actual operation of other versions of BASIC, such as PowerBASIC for DOS.
Arr()	When reading an array from the disk file, GET assigns data from the file into each element in the array, starting at the arrays LBOUND subscript. GET attempts to read the number of elements specified by rcds in the RECORDS option, or the number of elements in the array, whichever is smaller. The actual number of elements read is assigned to the variable count specified in the optional TO clause. With a dynamic string array, it is assumed the file was written in the PowerBASIC and/or VB packed string format using PUT of an entire string array. If a string is shorter than 65535 bytes, a 2-byte length WORD is followed by the string data. Otherwise, a 2-byte value of 65535 is followed by a length Double-word (DWORD), then finally the string data. With other array arrays types, the entire data area is read as a single block. In either case, it is presumed the file was created with the complementary PUT Array statement. EOF is set just as with other GET statements. You can use the FILESCAN statement to determine the number of records contained in the file, allowing an array of the appropriate type to be dimensioned before using the GET statement to read the file.
See also	CSET, CSET$, EOF, FIELD, FILESCAN, GET$, GET$$, LINE INPUT#, LSET, OPEN, PRINT#, PUT, PUT$, PUT$$, RSET, TYPE, SEEK, WRITE#
Example	' Random-access GET example DIM uName AS STRING * 20 DIM I AS QUAD DIM F AS LONG F = FREEFILE OPEN "TESTFILE.DTA" FOR RANDOM AS #F LEN = LEN(uName) WHILE uName <> SPACE$(20) PUT #F,, uName uName = GetInput() WEND IF SEEK(F) > 0 THEN ShowText "The file contains these names:" FOR ix = 1 TO SEEK(F) GET #F, ix, uName ShowText uName + NL NEXT ELSE ShowText "The file is empty" END IF CLOSE #F ' Binary GET Array example OPEN "Data file to read.dat" FOR BINARY AS #1 FILESCAN #1, RECORDS TO count& DIM TheData$(1 TO count&) GET #1, 1, TheData$() TO y& CLOSE #1