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:

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.

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 also

CSET, CSET$, FIELD, GET, GET$, GET$$, LOF, LSET, PUT$, PUT$$, RSET, SETEOF, TYPE, WRITE#

Example

' 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