Delphi in a Nutshell

Name

BlockWrite Procedure

Syntax

procedure BlockWrite(var F: File; const Buffer; Count: Integer);
procedure BlockWrite(var F: File; const Buffer; Count: Integer;
    var RecordCount: Integer);

Description

The BlockWrite procedure writes Count records from Buffer to a binary file. If you supply the RecordCount variable, BlockWrite stores in it the number of records actually written to the file. In the case of a disk-full or other error, RecordCount might be less than Count. BlockWrite is not a real procedure.

Errors

• If you do not supply the RecordCount argument, and BlockWrite encounters an error, it reports I/O error 101 or the Windows error code as an I/O error.

• If the file is not open, BlockWrite reports I/O error 103.

Tips and Tricks

• The Buffer argument is not a pointer, but an untyped var parameter. Pass the actual variable, not its address. If you have a pointer to a dynamically allocated buffer, dereference the pointer when calling BlockWrite.

• The two most common uses for BlockWrite are to write many records at once and to store complex data structures that do not fit neatly into a simple typed file. For example, to store a long string, you might want to write the string’s length as a four-byte binary number, followed by the string’s contents.

Example

// Write a string to a binary file. Preface the string with
// the string length, as a four-byte integer.
procedure WriteString(var F: File; const Str: string);
var
  Len: LongInt;
begin
  Len := Length(Str);
  BlockWrite(F, Len, SizeOf(Len));