Announcement

Collapse
No announcement yet.

Get Statement

Collapse
X
  • Filter
  • Time
  • Show
Clear All
new posts

  • Get Statement

    Please add your comments and suggestions as a Reply to this thread.





    PB/WIN - 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 AlsoReferencesExamples
    Code:
    ' 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
    Last edited by Gary Beene; 28 Oct 2014, 09:04 PM.

  • #2
    For RANDOM access, I thought GET obtains the length of VAR from the relevant OPEN statement, but no! It appears that it's the programmer's responsibility to use a VAR of the proper length.
    (So instead of VAR being a dynamic string, it should be STRING * xx )

    So I think the text should mention that the programmer should ensure that the data type and LEN of VAR must match the LEN in the OPEN statement.

    -John

    Comment


    • #3
      See LONG Remark in Help for GET under Random Access Files
      Dale

      Comment


      • #4
        Dale,

        Knowing that you would only post something helpful, I've read and re-read the GET Help both here and in the compiler installation.

        It took me about 5 iterations to identify what you were referring to (actually in the remarks about VAR?), but it took about 10 more reads for me to grasp the connection between the OPEN length clause and how GET fills the VAR... Not that I'm dense or anything, it just wasn't saying what I was expecting it to!

        I think I now understand what it says, but I also still see how I missed the connection. I do think it could be explained better.

        This has been a very interesting exercise!

        Thanks,
        -John

        Comment

        Working...
        X