Rave Reports Visual Designer

Lesson - Custom Data Connection

Through the events in the data connection components, you can customize how the data is sent to your Rave reports. For non-database data using the TRvCustomConnection component, you will need to provide all access to your data through these events. For database data connection components such as TRvDataSetConnection, you will normally only want to override the OnValidateRow event. The data connection events are as follows:

The TRvCustomConnection component has a DataIndex and DataRows property of type integer. These are provided for use by custom connector events and if used, can alleviate the need to define the OnFirst, OnNext and OnEOF events. DataIndex is intended to be used as the data cursor position with 0 representing the first row. DataRows is intended to be used as the row count of the data. For example, if you were defining a custom data connection for a memory array, you would only need to initialize the Connection.DataRows property to the number of elements in the memory array and then let Rave handle the OnFirst, OnNext and OnEOF events. In the OnGetRow event you would then access the Connection.DataIndex property to determine which array element to pass back (remember that DataIndex is 0 for the first row).

OnGetCols Event

The OnGetCols event is called when Rave want to retrieve the meta-data information of the data. Inside this event you will want to call the Connection.WriteField method for each field (column) of your data. The definition of WriteField is as follows:

procedure WriteField(Name: string;

       DataType: TRPDataType;

       Width: integer;

       FullName: string;

       Description: string);

Name is the short name of the field and should only contain alphanumeric characters. DataType is the type of data that this field represents and should be one of the following values: dtString, dtInteger, dtBoolean, dtFloat, dtCurrency, dtBCD, dtDate, dtTime, dtDateTime, dtBlob, dtMemo or dtGraphic. Width is the relative character width of the field. Full name is a more descriptive name of the field and can include spaces and other non-alphanumeric characters. If FullName is blank then the short name is used as the field’s full name. Description is a full description of the field and is typically edited with memo component so it can contain multiple lines. Use the description property to define how the field is to be used and provide any other information about the field’s data.

Example:

procedure TDataForm.CustomCXNGetCols(Connection: TRvCustomConnection);

begin

       With Connection do begin

               WriteField('Index',dtInteger,8,'Index Field','Description 1');

               WriteField('Name',dtString,30,'Name Field','Description 2');

               WriteField('Amount',dtFloat,20,'Amount Field','Description 3');

       end; { with }

end;

OnOpen event

The OnOpen event is called to initialize a data session. In this event you can open up data files, initialize variables and save the current state of the data for the OnRestore event which will be called to terminate the data session.

Example:

procedure TDataForm.CustomCXNOpen(Connection: TRvCustomConnection);

begin

       AssignFile(DataFile,’DATAFILE.DAT’);

       Reset(DataFile,1);

end;

OnFirst event

The OnFirst event is called to position the data cursor to the first row of the data.

Example:

procedure TDataForm.CustomCXNFirst(Connection: TRvCustomConnection);

begin

       Seek(DataFile,0);

       BlockRead(DataFile,DataRecord,SizeOf(DataRecord),DataRead);

end;

OnNext event

The OnNext event is called to move the data cursor to the next row of data.

Example:

procedure TDataForm.CustomCXNNext(Connection: TRvCustomConnection);

begin

       BlockRead(DataFile,DataRecord,SizeOf(DataRecord),DataRead);

end;

OnEOF event

The OnEOF event is called to return whether the data cursor is beyond the EOF or not. A true value should be returned only if there are no rows or if a call to the OnNext event has moved past the last row.

Example:

procedure TMainForm.CustomCXNEOF(Connection: TRPCustomConnection; var EOF: Boolean);

begin

       EOF := DataRead < SizeOf(DataRecord);

end;

OnGetRow event

The OnGetRow event is called to retrieve the data for the current row. There are several methods used to write the data to a special buffer used by Rave. The order and types of the fields written must match exactly the field definitions provided in the OnGetCols event.

The following is a list of the methods provided by the Connection object for writing data out to the data buffer.

procedure WriteBCDData(FormatData: string;

       NativeData: currency); { dtBCD }

procedure WriteBlobData(var Buffer;

       Len: longint); { dtBlob, dtMemo and dtGraphic }

procedure WriteBoolData(FormatData: string;

       NativeData: boolean); { dtBoolean }

procedure WriteCurrData(FormatData: string;

       NativeData: currency); { dtCurrency }

procedure WriteFloatData(FormatData: string;

       NativeData: extended); { dtFloat }

procedure WriteDateTimeData(FormatData: string;

       NativeData: TDateTime); { dtDate, dtTime and dtDateTime }

procedure WriteIntData(FormatData: string;

       NativeData: integer); { dtInteger }

procedure WriteStrData(FormatData: string;

       NativeData: string); { dtString }

There is also a special method called WriteNullData (no parameters) that can be called for any field that contains uninitialized or null data. The FormatData parameter is used to pass a preformatted string of the data for this field. The NativeData parameter is intended to pass the unformatted or raw data of the field. If special formatting is defined in the Rave report then the formatting will be applied to NativeData. If no special formatting is defined in the Rave report then the FormatData value will be used for printing.

Example:

procedure TDataForm.CustomCXNGetRow(Connection: TRvCustomConnection);

begin

       With Connection do begin

               WriteIntData('',DataRecord.IntField);

               WriteStrData('',DataRecord.StrField);

               WriteFloatData('',DataRecord.FloatField);

       end; { with }

end;

OnValidateRow event

The OnValidateRow event is called for each row and allows you to control whether the current row will be included in the report or not. This is usually the only event that will be defined for non-custom data connections.

Example:

procedure TDataForm.CustomCXNValidateRow(Connection: TRvCustomConnection; var ValidRow: Boolean);

begin

       ValidRow := DataRecord.FloatField >= 0.0;

end;

OnRestore event

The OnRestore event is called to terminate and restore a data session to its previous state. In this event you can close data files, free resources and restore the state of the data to its state that it was before the OnOpen event was called.

Example:

procedure TDataForm.CustomCXNRestore(Connection: TRvCustomConnection);

begin

       CloseFile(DataFile);

end;

WARNING

In order for RAVE to be able to see your custom components, you will need to set the visible property to true and you will also need to be running the application that has the custom components. Custom components cannot be seen in RAVE while in design time only. So define your custom connections, run your application and then switch to the visual designer, while your application is still running, and then create/refresh your custom connection dataviews and your fields will then show up.