17.7 TDosStream

TDosStream is a stream that stores it’s contents in a file. it overrides a couple of methods of TSteam for this.

In addition to the fields inherited from TStream (see section 17.6, page 565), there are some extra fields, that describe the file. (mainly the name and the OS file handle)

No buffering in memory is done when using TDosStream. All data are written directly to the file. For a stream that buffers in memory, see section 17.8, page 582.

Here is the full declaration of the TDosStream object:

 TYPE
    TDosStream = OBJECT (TStream)
          Handle: THandle; { DOS file handle }
          FName : AsciiZ;  { AsciiZ filename }
       CONSTRUCTOR Init (FileName: FNameStr; Mode: Word);
       DESTRUCTOR Done; Virtual;
       PROCEDURE Close; 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;
    PDosStream = ^TDosStream;

TDosStream.Init

Declaration:

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

Description:

Init instantiates an instance of TDosStream. 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.

Errors:

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

See also:

Done (577)

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

TDosStream.Done

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

for an example, see e.g. TDosStream.Truncate (578).

TDosStream.Close

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

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

TDosStream.Truncate

Declaration:: Procedure TDosStream.Truncate; Virtual;
Description:: If the status of the stream is stOK, then Truncate tries to truncate the stream size to the current file position.
Errors:: If an error occurs, the stream’s status is set to stError and ErrorInfo is set to the OS error code.
See also:: TStream.Truncate (571), GetSize (568)

Listing: objectex/ex16.pp

Program ex16;

{ Program to demonstrate the TStream.Truncate method }

Uses Objects;

Var L : String;
    P : PString;
    S : PDosStream; { Only one with Truncate implemented. }

begin
  L:='Some constant string';
  { Buffer size of 100 }
  S:=New(PDosStream,Init('test.dat',stcreate));
  Writeln ('Writing "',L,'" to stream with handle ',S^.Handle);
  S^.WriteStr(@L);
  S^.WriteStr(@L);
  { Close calls flush first }
  S^.Close;
  S^.Open (stOpen);
  Writeln ('Size of stream is : ',S^.GetSize);
  P:=S^.ReadStr;
  L:=P^;
  DisposeStr(P);
  Writeln ('Read "',L,'" from stream with handle ',S^.Handle);
  S^.Truncate;
  Writeln ('Truncated stream. Size is : ',S^.GetSize);
  S^.Close;
  Dispose (S,Done);
end.

TDosStream.Seek

Declaration:: Procedure TDosStream.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)

Listing: objectex/ex17.pp

Program ex17;

{ Program to demonstrate the TStream.Seek method }

Uses Objects;

Var L : String;
    Marker : Word;
    P : PString;
    S : PDosStream;

begin
  L:='Some constant string';
  { Buffer size of 100 }
  S:=New(PDosStream,Init('test.dat',stcreate));
  Writeln ('Writing "',L,'" to stream.');
  S^.WriteStr(@L);
  Marker:=S^.GetPos;
  Writeln ('Set marker at ',Marker);
  L:='Some other constant String';
  Writeln ('Writing "',L,'" to stream.');
  S^.WriteStr(@L);
  S^.Close;
  S^.Open (stOpenRead);
  Writeln ('Size of stream is : ',S^.GetSize);
  Writeln ('Seeking to marker');
  S^.Seek(Marker);
  P:=S^.ReadStr;
  L:=P^;
  DisposeStr(P);
  Writeln ('Read "',L,'" from stream.');
  S^.Close;
  Dispose (S,Done);
end.

TDosStream.Open

Declaration:: Procedure TDosStream.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 (578) 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 (578)

Listing: objectex/ex14.pp

Program ex14;

{ Program to demonstrate the TStream.Close method }

Uses Objects;

Var L : String;
    P : PString;
    S : PDosStream; { Only one with Close implemented. }

begin
  L:='Some constant string';
  S:=New(PDosStream,Init('test.dat',stcreate));
  Writeln ('Writing "',L,'" to stream with handle ',S^.Handle);
  S^.WriteStr(@L);
  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.

TDosStream.Read

Declaration:: Procedure TDosStream.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.
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 (581)

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

TDosStream.Write

Declaration:: Procedure TDosStream.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.
Errors:: In case of an error, Status is set to StWriteError, and ErrorInfo gets the OS specific error.
See also:: TStream.Write (574), Read (581)

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

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