|
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 |
The GET statement has the following parts: |
|
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) length field at the beginning of each record which indicates the length of the string that follows. The length of the string is set by this value. The argument to the LEN clause of the OPEN statement must be at least 2 bytes greater than the actual string length. This 2-byte (WORD) length field is placed in the file by the PUT statement when used with dynamic (variable-length) strings. (no Var) 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
|
|
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. |
|
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$, LINE INPUT#, LSET, OPEN, PRINT#, 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 |