NOTE: The actual sequence of calls made to invoke FieldMapping should follow this order:

●Set the ReportName property.

●Set any LogOn Information (if using ODBC or SQL tables) via either Connect, LogOnInfo, or LogOnServer.

●Set any new Table location information via the Tables object.

●Set the FieldMapping property.

●Call VerifyDatabase.

Example

The following example sets the FieldMapping property and then calls VerifyDatabase. If the Database has changed, a Field Mapping dialog will appear:

Crpe1.ReportName := 'C:\Company.rpt';

Crpe1.FieldMapping := fmPrompt;

Crpe1.VerifyDatabase;

Events

The following are the events of the Tcrpe VCL component.

OnError event, Page 166

OnExecuteBegin event, Page 168

OnExecuteDoneSend event, Page 169

OnExecuteEnd event, Page 169

OnFieldMapping event, Page 170

OnGetVersion event, Page 172

OnJobOpened event, Page 173

OnPrintEnded event, Page 174

OnPrinterSend event, Page 175

OnWindowClose event, Page 175

OnError event

Declaration

property OnError: TCrpeErrorEvent;

Type

TCrpeErrorEvent = procedure(Sender: TObject; const ErrorNum: smallint; const ErrorString: string; var IgnoreError: boolean) of object;

VCL Reference

166

Description

The OnError event occurs in two instances:

1.When an error is returned from the Crystal Reports Print Engine. The error can be related to the functioning of the Print Engine, but more often it is related to invalid values passed in.

2.When an error is generated within the component's internal code. This can be caused by problems allocating memory, values being passed that are invalid, specifying subscripts that are out-of-range, etc.

There are three ways in which an Error will be handled:

1.There is no OnError Event defined. In this case, the built-in Exception will be raised, showing the default Error Dialog, with the Error Number and Error String.

2.An OnError Event is defined, but the IgnoreError flag is set to False. In this case, the VCL will raise a silent Abort exception, but no Error dialog will be shown.

3.An OnError Event is defined, and the IgnoreError flag is set to True. In this case, the VCL will assume that the Error has been handled in the OnError event, and will proceed program execution, either continuing to the next iteration of a loop, or continuing to the next procedure (if there are any more to be run). Care must be taken in suppressing errors which would otherwise indicate a problem.

●The ErrorNum parameter passed in the OnEngineError event contains the number of the current Error, and the ErrorString parameter contains the Print Engine description of the current Error. These are also available via the LastErrorNumber and LastErrorString properties.

●The OnError event allows the programmer to handle the errors raised in a way that will suit the interface of the application. For example, a custom dialog could be built to display the ErrorString instead of the built-in one.

For a complete list of possible Errors, see: Error Codes - VCL Component, Page 207 or Error Codes - Crystal Reports Print Engine, Page 210.

Example

This procedure which is placed in the OnError event, causes a user-defined Dialog to appear with two buttons, one for Cancel, and one for Continue (ignore the error). If Continue is pressed, the IgnoreError flag is set to True:

procedure TForm1.Crpe1Error(const ErrorNum: Smallint; const ErrorString: string; var IgnoreError: Boolean);

begin

dlgError := TdlgError.Create(Application);

{Dialog Title}

if ErrorNum < 500 then

dlgError.lblTitle.Caption := 'Crystal Reports Component Error' else

dlgError.lblTitle.Caption := 'Crystal Reports Engine Error';

{Error Number}

if ErrorNum > 0 then

dlgError.lblErrorNumber.Caption := 'Error #: ' + IntToStr(ErrorNum) else

dlgError.lblErrorNumber.Caption := 'Error Number Undefined';

VCL Reference

167

{Error String}

dlgError.lblErrorString.Caption := ErrorString;

{Show Dialog} dlgError.ShowModal;

if dlgError.ModalResult = mrOk then IgnoreError := True;

end;

OnExecuteBegin event

Declaration

property OnExecuteBegin: TCrpeCancelEvent;

Type

TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;

Description

The OnExecuteBegin event takes place at the start of the Execute method, before the Crystal component values have been sent to the Crystal Reports Print Engine.

See Execute method, Page 142, for a fuller explanation of the order of events.

Example

The following example runs a Report to Window. When the Execute method begins, a message is shown:

procedure TForm1.RunReport; begin

Crpe1.ReportName := 'C:\Report1.rpt'; Crpe1.Output := toWindow; Crpe1.Execute;

end;

procedure TForm1.Crpe1OnExecuteBegin(Sender: TObject; var Cancel: Boolean); begin

ShowMessage('Starting Execute'); end;

VCL Reference

168

OnExecuteDoneSend event

Declaration

property OnExecuteDoneSend: TCrpeCancelEvent;

Type

TCrpeCancelEvent = procedure(Sender: TObject; var Cancel: Boolean) of object;

Description

The OnExecuteDoneSend event takes place within the Execute method, after the Crystal component values have been sent to the Crystal Reports Print Engine, but before the Report is actually run.

See Execute method, Page 142, for a fuller explanation of the order of events.

Example

The following example runs a Report to Window. When the Execute method has completed sending all the VCL settings to the Print Engine, a message is shown:

procedure TForm1.RunReport; begin

Crpe1.ReportName := 'C:\Report1.rpt'; Crpe1.Output := toWindow; Crpe1.Execute;

end;

procedure TForm1.Crpe1OnExecuteDoneSend(Sender: TObject; var Cancel: Boolean);

begin

ShowMessage('Finished Sending to Print Engine'); end;

OnExecuteEnd event

Declaration

property OnExecuteEnd: TNotifyEvent;

Type

TNotifyEvent = procedure(Sender: TObject) of object;

VCL Reference

169