Class TMWBuffer (unit RFormat)

Inherits from

TComponent

:TMWBuffer is the component responsible for holding data to be transmitted between the client and the server (both directions). The buffer has a special format allowing to store records made of fields. Each record can have a variable number of fields of variable length. There are two types of fields: mwString (default) and mwBlob (also called stream fields because of the way they are read/written). } {$IFDEF MAKECOMPONENT

Constructors


constructor Create(AOwner : TComponent);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} {$IFDEF MAKECOMPONENT


Functions

procedure AppendFields(Args : array of const);

:Append fields to the current record.

procedure AppendStreamField(Data : TStream; FldType : TMWFieldType);

:Same as WriteStreamField, but append the field to the current record.

procedure Delete;

:Delete the current record.

destructor Destroy;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure First;

:Position the pointer to current position on the first record.

procedure FreeBookmark(Bookmark: TBookmark);

:Free resources used for bookmark keeping.

function GetBookmark: TBookmark;

:Get a bookmark on current record.

function GetStreamField(FieldNb : Integer; Data : TStream; var FieldType : TMWFieldType) : integer;

:Get a stream (blob) field value from the buffer.

procedure GotoBookmark(Bookmark: TBookmark);

:Return the current position to the bookmark setup by GetBookmark.

procedure Last;

:Position the pointer to current position on the last record.

function Locate(const KeyFields: String; const KeyValues: Variant; Options: TLocateOptions): Boolean;

:Locate a record by sequential search.

procedure Next;

:Position the pointer to current position on the next record.

procedure Prior;

:Position the pointer to current position on the previous record.

function RecordToString : String;

:Transform the current record to a convenient string representation.

procedure Rewrite;

:Clear the buffer content and prepare for wrting new data.

procedure Seek(nPos : TPosition);

:Position the current record to some arbitrary position.

function Tell : TPosition;

:Return the internal position for the current record.

procedure WriteFields(NewRec : Boolean; Args : array of const);

:Write a new record or append to current record some fields passed in argument in the array of const.

procedure WriteRecord(Args : array of const);

:Write a complete record with field values given by the argument.

procedure WriteRecordMarker;

:Terminate the current record (can makes an empty record)

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Terminate the current record (can makes an empty record)


procedure WriteStreamField(NewRec : Boolean; FldType : TMWFieldType; Data : TStream);

:Write a single stream (blob) field.

function ExpandBuffer(pSize : PInteger; Requested : LongInt) : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetBof : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetEof : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetFieldCount : Integer;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetFieldPtr(nIndex : Integer) : PChar;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Get the pointer on the given field in the current record.

function GetFields(nIndex : Integer) : String;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetFieldType(nIndex : Integer) : TMWFieldType;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

function GetNextFieldPtr(Cur : PChar) : PChar;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Given a field pointer, return the pointer to the next field } { If last field is passed, then the pointer point to the record separator.

function GetRecordCount : Integer;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure RaiseException(const Where: String);

How many we cab realloc

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure SetDataBuffer(newValue : PChar);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure SetDataBufferSize(newValue : LongInt);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure SetFields(nIndex : Integer; newValue : String);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure SetHasData(newValue : Boolean);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

procedure WriteDataBuffer(Src : PChar; Len : LongInt);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

Properties

property AutoExpand : LongInt

:This property teels the component if the data buffer can be expanded if it is too short for the data that needs to be written to it.

property DataBufferSize : LongInt

:The size in bytes of the current buffer.

property HeaderSize : LongInt

:Size in byte of the header in the data buffer.

property Bof : Boolean

:Returns the Begin Of File status.

property DataBuffer : PChar

:Gives access to the underlaying data buffer.

property DataBufferCount : LongInt

:The size in bytes of the data present in the buffer.

property Eof : Boolean

:Returns the End Of File status.

property FieldCount : Integer

:Returns the number of fields in the current record.

property Fields : String

:The indexed Fields[] property gives acces to the current record's fields.

property FieldType : TMWFieldType

:Returns the field type.

property HasData : Boolean

:Indicates if some data is in the buffer.

property RecordCount : Integer

:Returns the number of records by sequentially counting them.

Events

Variables

FAutoExpand : LongInt;

Do we have allocated memory

FDataBuffer : PChar;


FDataBufferCount : LongInt;

Total buffer size

FDataBufferSize : LongInt;

Buffer start

FEscSep : Char;

Record separator

FFieldCount : Integer;

Reserved space for a header

FFldSep : Char;

Total number of records

FHasAllocated : Boolean;

Is there any data in the buffer

FHasData : Boolean;

We hit the begin of file

FHeaderSize : LongInt;

How many characters used

FHitBof : Boolean;

We hit the end of file

FHitEof : Boolean;

Current record pointer

FRecordCount : Integer;

How many fileds in current rec

FRecordPointer : PChar;

Special character marker

FRecSep : Char;

Field separator


Constructors


constructor Create(AOwner : TComponent);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} {$IFDEF MAKECOMPONENT


Functions


procedure AppendFields(Args : array of const);

:Append fields to the current record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Append fields to the last record


procedure AppendStreamField(Data : TStream; FldType : TMWFieldType);

:Same as WriteStreamField, but append the field to the current record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Write stream data as field content. The stream is writen starting from } { current position to end of stream.


procedure Delete;

:Delete the current record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


destructor Destroy;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure First;

:Position the pointer to current position on the first record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure FreeBookmark(Bookmark: TBookmark);

:Free resources used for bookmark keeping.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetBookmark: TBookmark;

:Get a bookmark on current record. Use the value with GotoBookmark. When no more used, call FreeBookmark to release used resources.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetStreamField(FieldNb : Integer; Data : TStream; var FieldType : TMWFieldType) : integer;

:Get a stream (blob) field value from the buffer. Same as the Fields[] property but works with blob fields.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure GotoBookmark(Bookmark: TBookmark);

:Return the current position to the bookmark setup by GetBookmark.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure Last;

:Position the pointer to current position on the last record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function Locate(const KeyFields: String; const KeyValues: Variant; Options: TLocateOptions): Boolean;

:Locate a record by sequential search.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure Next;

:Position the pointer to current position on the next record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure Prior;

:Position the pointer to current position on the previous record.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function RecordToString : String;

:Transform the current record to a convenient string representation.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure Rewrite;

:Clear the buffer content and prepare for wrting new data.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure Seek(nPos : TPosition);

:Position the current record to some arbitrary position. The argument must be a value returned by the Tell method.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function Tell : TPosition;

:Return the internal position for the current record. The returned value can be used with the Seek method.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Returns the byte offset for the first character of the first field of the } { current record


procedure WriteFields(NewRec : Boolean; Args : array of const);

:Write a new record or append to current record some fields passed in argument in the array of const.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Append fields to the last record


procedure WriteRecord(Args : array of const);

:Write a complete record with field values given by the argument.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Append a record after the last one


procedure WriteRecordMarker;

:Terminate the current record (can makes an empty record)

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Terminate the current record (can makes an empty record)


procedure WriteStreamField(NewRec : Boolean; FldType : TMWFieldType; Data : TStream);

:Write a single stream (blob) field. This function can be used to place a complete file (for example a BMP file) into a single field.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Write stream data as field content. The stream is writen starting from } { current position to end of stream.


function ExpandBuffer(pSize : PInteger; Requested : LongInt) : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetBof : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetEof : Boolean;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetFieldCount : Integer;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetFieldPtr(nIndex : Integer) : PChar;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Get the pointer on the given field in the current record. } { If empty field, then the returned value point to the field separator, } { if non existent field, then returned value point to the record separator.


function GetFields(nIndex : Integer) : String;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetFieldType(nIndex : Integer) : TMWFieldType;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


function GetNextFieldPtr(Cur : PChar) : PChar;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *} { Given a field pointer, return the pointer to the next field } { If last field is passed, then the pointer point to the record separator.


function GetRecordCount : Integer;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure RaiseException(const Where: String);

How many we cab realloc

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure SetDataBuffer(newValue : PChar);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure SetDataBufferSize(newValue : LongInt);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure SetFields(nIndex : Integer; newValue : String);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure SetHasData(newValue : Boolean);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


procedure WriteDataBuffer(Src : PChar; Len : LongInt);

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


Properties


property AutoExpand : LongInt

:This property teels the component if the data buffer can be expanded if it is too short for the data that needs to be written to it.


property DataBufferSize : LongInt

:The size in bytes of the current buffer. Assigning a value to this property will allocate or reallocate the buffer.


property HeaderSize : LongInt

:Size in byte of the header in the data buffer. Default to 0.


property Bof : Boolean

:Returns the Begin Of File status. Usefull with First, Next, Prior and Last methods.


property DataBuffer : PChar

:Gives access to the underlaying data buffer. Writing this value allows to allocate a buffer for data storage. If the buffer is forced then the component cannot expand it as needed to write fields.


property DataBufferCount : LongInt

:The size in bytes of the data present in the buffer.


property Eof : Boolean

:Returns the End Of File status. Usefull with First, Next, Prior and Last methods.


property FieldCount : Integer

:Returns the number of fields in the current record.


property Fields : String

:The indexed Fields[] property gives acces to the current record's fields. Works with string type field only. For blobs, use GetStreamField method.


property FieldType : TMWFieldType

:Returns the field type.


property HasData : Boolean

:Indicates if some data is in the buffer. Usefull when using the back door and copying data directly in the underlaying buffer.


property RecordCount : Integer

:Returns the number of records by sequentially counting them. The value is cached because counting if CPU expensive.


Events


Variables


FAutoExpand : LongInt;

Do we have allocated memory


FDataBuffer : PChar;


FDataBufferCount : LongInt;

Total buffer size


FDataBufferSize : LongInt;

Buffer start


FEscSep : Char;

Record separator


FFieldCount : Integer;

Reserved space for a header


FFldSep : Char;

Total number of records


FHasAllocated : Boolean;

Is there any data in the buffer


FHasData : Boolean;

We hit the begin of file


FHeaderSize : LongInt;

How many characters used


FHitBof : Boolean;

We hit the end of file


FHitEof : Boolean;

Current record pointer


FRecordCount : Integer;

How many fileds in current rec


FRecordPointer : PChar;

Special character marker


FRecSep : Char;

Field separator