Announcement

Collapse
No announcement yet.

Put Statement

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

  • Put Statement

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





    PB/WIN - PUT statement

    Purpose
    Write a record to a random-access file or a variable/array to a binary file.
    Syntax
    Random-Access and Binary files:

    PUT [#] FileNum&, [RecPos], [ABS] Var
    PUT [#] FileNum& [, RecPos]
    Binary files:

    PUT [#] FileNum&, [RecPos], Arr()
    Remarks
    If a string variable is specified as Var, the CHR mode of the variable determines whether the data is written as ANSI or WIDE characters. That is, ANSI string variables are always written as 1- byte characters, while WIDE string variables are written as 2-byte WIDE characters. The data is always written to the file in the same format as it appears in the variable.

    FileNum&
    The file number under which the file was opened.

    RecPos
    Identifies the position in the file to write the data. If RecPos is greater than the number of existing records or bytes in the file, the file is extended to the appropriate length, and the record is written at the specified position.

    For random access files,RecPos is the record to be written, in the range 1 to (2^63)-1. If RecPos is omitted, the next record in sequence (following the one specified by the most recent GET, PUT or SEEK) is written. If the file was only just opened, the first record is written.

    For binary files, RecPos is the starting byte position where VarName should be written. The default byte position is 1, unless the BASE = 0 clause was used in the OPEN statement. RecPos may be no larger than 2^63-1. RecPos is optional. If it is omitted, PowerBASIC uses the current file pointer position.

    Var
    The name of a variable to write to the file. VarName can specify a simple variable, an element in an array, or a variable of User-Defined Type (UDT).

    When writing a dynamic string to a random access file, PUT writes a 2-byte descriptor containing the string's length, before the actual string data. This descriptor reduces the available space in a record by two bytes. The descriptor is written as a WORD value. If Var contains more characters than record, Var is truncated at record length less two bytes, and the descriptor is written to reflect the truncated string size.

    When writing a dynamic string to a binary file, PUT only writes the actual string data: no length descriptor is written.

    PUT is complementary to GET; it writes one record to a file. It is possible to PUT to records out of contiguous order, as in:

    Code:
    PUT #1, 1, MyVar
    PUT #1, 100, MyVar
    which creates a random-access file 100 records long. The data in records 2 through 99, however, are undefined until you explicitly PUT something there. PUT writes the contents of Var to the specified record or byte positions.

    (no VarName)
    When the second form of PUT is used (without a VarName source string), PUT writes the data from an internal buffer into the file at the point where the file pointer indicates. This data must first be assigned to the file buffer using FIELD string variables.

    ABS
    When PUT is used to write a dynamic string to a random file, it normally precedes the actual data with a two-byte binary length Word to define the number of valid bytes in the record. If you precede the variable name with ABS (i.e., PUT #1, , ABS x$), no length Word is written: only the actual data, subject to the defined random record length. This offers greater compatibility with the actual operation of other versions of BASIC, such as PowerBASIC for DOS.

    The record length in a random access file is limited to 32768 bytes, in order to ensure consistent behavior across all Win32 platforms.

    Arr()
    When PUT is used on a binary file, the entire array specified by Arr() is written to the file. With dynamic strings, the file is written in the PowerBASIC and/or VB packed string format. If the 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 data types, the entire data area is written as a single block.In either case, it is presumed the file will be read with the complementary GET Array statement.
    See AlsoReferencesExamples
    Code:
    ' Random-access PUT example
    TYPE TestRec
      uName   AS STRING * 10
      uNumber AS INTEGER
    END TYPE
    DIM Rec AS TestRec, Record AS QUAD
    OPEN "RANDOM.DTA" FOR RANDOM AS #1 LEN = LEN(TestRec)
    FOR Record = 1 TO 100
      Rec.uName = "Joe" + STR$(Record)
      Rec.uNumber = Record
      PUT #1,Record, Rec
    NEXT Record
    CLOSE #1
    ' Binary PUT Array example
    DIM TheData$(1 TO count&)
    TheData$(1) = "text"
    ' Assign more array values...
    
    OPEN "Data file to write.dat" FOR BINARY AS #1
    PUT #1, 1, TheData$()
    CLOSE #1
    Last edited by Gary Beene; 28 Oct 2014, 10:11 PM.
Working...
X