17.8 TBufStream

Bufstream implements a buffered file stream. That is, all data written to the stream is written to memory first. Only when the buffer is full, or on explicit request, the data is written to disk.

Also, when reading from the stream, first the buffer is checked if there is any unread data in it. If so, this is read first. If not the buffer is filled again, and then the data is read from the buffer.

The size of the buffer is fixed and is set when constructing the file.

This is useful if you need heavy throughput for your stream, because it speeds up operations.

 TYPE
    TBufStream = OBJECT (TDosStream)
          LastMode: Byte;       { Last buffer mode }
          BufSize : Sw_Word;    { Buffer size }
          BufPtr  : Sw_Word;    { Buffer start }
          BufEnd  : Sw_Word;    { Buffer end }
          Buffer  : PByteArray; { Buffer allocated }
       CONSTRUCTOR Init (FileName: FNameStr; Mode, Size: Word);
       DESTRUCTOR Done; Virtual;
       PROCEDURE Close; Virtual;
       PROCEDURE Flush; Virtual;
       PROCEDURE Truncate; Virtual;
       PROCEDURE Seek (Pos: LongInt); Virtual;
       PROCEDURE Open (OpenMode: Word); Virtual;
       PROCEDURE Read (Var Buf; Count: Sw_Word); Virtual;
       PROCEDURE Write (Var Buf; Count: Sw_Word); Virtual;
    END;
    PBufStream = ^TBufStream;

TBufStream.Init

Declaration:

Constructor Init (FileName: FNameStr; Mode,Size: Word);

Description:

Init instantiates an instance of TBufStream. The name of the file that contains (or will contain) the data of the stream is given in FileName. The Mode parameter determines whether a new file should be created and what access rights you have on the file. It can be one of the following constants:

stCreate: Creates a new file.
stOpenRead: Read access only.
stOpenWrite: Write access only.
stOpen: Read and write access.

The Size parameter determines the size of the buffer that will be created. It should be different from zero.

Errors:

On error, Status is set to stInitError, and ErrorInfo is set to the DOS error code.

See also:

TDosStream.Init (577), Done (584)

For an example see TBufStream.Flush (584).

TBufStream.Done

Declaration:: Destructor TBufStream.Done; Virtual;
Description:: Done flushes and closes the file if it was open and cleans up the instance of TBufStream.
Errors:: None.
See also:: TDosStream.Done (577), Init (583), Close (584)

For an example see TBufStream.Flush (584).

TBufStream.Close

Declaration:: Pocedure TBufStream.Close; Virtual;
Description:: Close flushes and closes the file if it was open, and sets Handle to -1. Contrary to Done (584) it does not clean up the instance of TBufStream
Errors:: None.
See also:: TStream.Close (570), Init (583), Done (584)

For an example see TBufStream.Flush (584).

TBufStream.Flush

Declaration:: Pocedure TBufStream.Flush; Virtual;
Description:: When the stream is in write mode, the contents of the buffer are written to disk, and the buffer position is set to zero.
When the stream is in read mode, the buffer position is set to zero.
Errors:: Write errors may occur if the file was in write mode. see Write (586) for more info on the errors.
See also:: TStream.Close (570), Init (583), Done (584)

Listing: objectex/ex15.pp

Program ex15;

{ Program to demonstrate the TStream.Flush method }

Uses Objects;

Var L : String;
    P : PString;
    S : PBufStream; { Only one with Flush implemented. }

begin
  L:='Some constant string';
  { Buffer size of 100 }
  S:=New(PBufStream,Init('test.dat',stcreate,100));
  Writeln ('Writing "',L,'" to stream with handle ',S^.Handle);
  S^.WriteStr(@L);
  { At this moment, there is no data on disk yet. }
  S^.Flush;
  { Now there is. }
  S^.WriteStr(@L);
  { Close calls flush first }
  S^.Close;
  Writeln ('Closed stream. File handle is ',S^.Handle);
  S^.Open (stOpenRead);
  P:=S^.ReadStr;
  L:=P^;
  DisposeStr(P);
  Writeln ('Read "',L,'" from stream with handle ',S^.Handle);
  S^.Close;
  Dispose (S,Done);
end.

TBufStream.Truncate

Declaration:: Procedure TBufStream.Truncate; Virtual;
Description:: If the status of the stream is stOK, then Truncate tries to flush the buffer, and then truncates the stream size to the current file position.
Errors:: Errors can be those of Flush (584) or TDosStream.Truncate (578).
See also:: TStream.Truncate (571), TDosStream.Truncate (578), GetSize (568)

For an example, see TDosStream.Truncate (578).

TBufStream.Seek

Declaration:: Procedure TBufStream.Seek (Pos: LongInt); Virtual;
Description:: If the stream’s status is stOK, then Seek sets the file position to Pos. Pos is a zero-based offset, counted from the beginning of the file.
Errors:: In case an error occurs, the stream’s status is set to stSeekError, and the OS error code is stored in ErrorInfo.
See also:: TStream.Seek (572), GetPos (568)

For an example, see TStream.Seek (572);

TBufStream.Open

Declaration:: Procedure TBufStream.Open (OpenMode: Word); Virtual;
Description:: If the stream’s status is stOK, and the stream is closed then Open re-opens the file stream with mode OpenMode. This call can be used after a Close (584) call.
Errors:: If an error occurs when re-opening the file, then Status is set to stOpenError, and the OS error code is stored in ErrorInfo
See also:: TStream.Open (570), Close (584)

For an example, see TDosStream.Open (580).

TBufStream.Read

Declaration:: Procedure TBufStream.Read (Var Buf; Count: Sw_Word); Virtual;
Description:: If the Stream is open and the stream status is stOK then Read will read Count bytes from the stream and place them in Buf.
Read will first try to read the data from the stream’s internal buffer. If insufficient data is available, the buffer will be filled before contiunuing to read. This process is repeated until all needed data has been read.
Errors:: In case of an error, Status is set to StReadError, and ErrorInfo gets the OS specific error, or 0 when an attempt was made to read beyond the end of the stream.
See also:: TStream.Read (573), Write (586)

For an example, see TStream.Read (573).

TBufStream.Write

Declaration:: Procedure TBufStream.Write (Var Buf; Count: Sw_Word); Virtual;
Description:: If the Stream is open and the stream status is stOK then Write will write Count bytes from Buf and place them in the stream.
Write will first try to write the data to the stream’s internal buffer. When the internal buffer is full, then the contents will be written to disk. This process is repeated until all data has been written.
Errors:: In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS specific error.
See also:: TStream.Write (574), Read (586)

For an example, see TStream.Read (573).

[next] [prev] [prev-tail] [front] [up]