Using the JobNumber property

The Crystal Reports Print Engine (CRPE32.DLL) assigns a specific Job Number to each open Print Job. This Job Number is used internally in the VCL component, and is used when making calls to the CRPE so that it knows which Print Job the call is going to. Because this number is exposed in the JobNumber property of the VCL, it can be used to make direct calls to the CRPE, bypassing the VCL layer. While this is not normally recommended, since making changes to the Print Job without the VCL knowing about the changes can lead to problems, there are also times when this can be a powerful feature.

For example, the Execute method of the VCL has Events available within it, such as OnExecuteEnd, OnPrintEnded, etc. These events have protection which prevents the programmer from calling another Execute within the event (which would lead to an infinite loop). However, by the use of direct Print Engine calls, this limitation can be worked around. The call to run a Report in the Print Engine is

function PEStartPrintJob( JobNum : Word;

WaitUntilDone : Bool): Bool; stdcall;

The second parameter "WaitUntilDone" should always be True, and the first Parameter is the Print Job number, which is available in the VCL via Crpe1.JobNumber. Therefore, making this call within the OnExecuteEnd event (just as an example, not because it is meaningful!), causes the Report to be run immediately.

For a complete list of the available Print Engine calls, consult the DEVELOPR.HLP that came with Crystal Reports, or take a look at the CRDELPHI.PAS (if you have Crystal Reports 7), or CRPE32.PAS, which are also in the Crystal Reports install directory, or some of the VCL source code files.

TCrpeString

The following topics are discussed in this section.

Introduction, Page 213

TCrpeString VCL Properties, Page 214

Using the TCrpeString, Page 214

Seagate Crystal Visual Component Library

212

Introduction

TCrpeString = class(TStringList)

TCrpeString is the same as Delphi's TStringList, except the Put method defaults to Add if the subscript is one number larger than the number of strings in the StringList. With a normal StringList, the following code would cause an error:

var

slTemp : TStringList; begin

slTemp := TStringList.Create; slTemp[0] := 'The first line';

end;

The reason for the error is the code attempts to access the first string in the stringlist, but the first string does not exist yet. The proper way to do this would be:

var

slTemp : TStringList; begin

slTemp := TStringList.Create; slTemp.Add('The first line');

end;

However, with the TCrpeString type, the first example would work as well as the second one. Therefore, this is perfectly legal with the TCrpeString type:

var

slTemp : TCrpeString; begin

slTemp := TCrpeString.Create; slTemp[0] := 'The first line';

end;

Seagate Crystal Visual Component Library

213

TCrpeString VCL Properties

This type was primarily created for the previous versions of the Crystal Reports VCL, where string lists were used for almost every property that required multiple values or multiple lines, and where the subscript often represented the order of items in the report. It was decided to retain this type and continue using it in the new VCL, even though its added functionality is not quite as necessary as it used to be. The following properties all use the TCrpeString type:

Formulas	- Formula property
GroupSelection	- Formula property
Params	- Value property
Selection	- Formula property
SQL	- Query property
SummaryInfo	- Comments property

Using the TCrpeString

You can use any method that is legal for a TStringList to pass values to the TCrpeString as well as the subscript method described above. The following describes how this works:

var

crList : TCrpeString; begin

crList := TCrpeString.Create;

crList[0] := 'Subscript adds a new line if it doesn't currently exist, or replaces the value in the line specified if the line currently exists';

crList.Assign('Assign replaces anything in the List with this new value'); crList.Text := 'Text treats the stringlist as one block of text'; crList.SetText('SetText adds PChar strings to the List');

crList.Add('Add adds one new line to the List'); crList.Free;

end;

Seagate Crystal Visual Component Library

214