Pages GetLatest method, Page 434

Pages GetStart method, Page 435

Pages GoToPage method, Page 435

Pages Last method, Page 436

Pages Next method, Page 436

Pages Previous method, Page 437

ParamFields

Declaration

property ParamFields: TCrpeParamFields;

Type

TCrpeParamFields = class(TPersistent)

Description

The ParamFields object contains all the properties that apply to Parameter Fields. For Seagate Crystal Reports 7, ParamFields have been greatly expanded. The new features are documented at the bottom of this description, in the section New Features for SCR 7, Page 62.

●The Name property specifies the actual Parameter name, as defined in the Report, and acts as a lookup field.

●The default array property Item, and the ItemIndex property can be used to navigate through the various ParamField items (assuming there is more than one Parameter in the Report).

●The Value property holds the actual parameter value that is to be passed to the Parameter Field. Values are passed as strings, but are converted within the VCL to the correct Parameter Type required for the particular Parameter field. There are six other properties that can be used to read and write the Value property using native Delphi types:

AsNumber
AsCurrency
AsBoolean
AsDate
AsDateTime	//SCR 7.0	and higher
AsTime	//SCR 7.0	and higher

●If the Retrieve method is used to get Parameter Field information from the Report, the ParamType property will show what type each Parameter is.

●The Prompt property specifies the prompting text that appears on the Crystal Reports Parameter prompt dialog.

VCL Reference

61

●The ShowDialog property specifies whether the Value passed in will bypass the Parameter prompt dialog, or whether it will show up as the new default value in the Parameter prompt dialog.

●The ReportName property is read-only and specifies which Report the Parameter belongs to. Parameters are handled slightly differently than other Report properties. When the ParamFields are retrieved for the main Report, the resulting list contains all of the Parameter Fields in the Report, including those in Subreports. This is because when the main Report is run, the prompt dialog contains all of the Parameters (main & sub), and so they are considered as being partly "owned" by the main Report. Therefore, ReportName indicates which Subreport the Parameter belongs to.

●The NeedsCurrentValue property is a read-only and specifies whether the Parameter actually requires a value or not. If the Parameter is linked to a Subreport, or is not used in the Report, then NeedsCurrentValue will be False.

Here are some examples which show how to pass each Parameter type:

ParamType	Value	As[Type]	Delphi Type
pfNumber	'235'	AsNumber := 235	double
pfCurrency	'2.35'	AsCurrency := 2.35	currency
pfBoolean	'True'	AsBoolean := True	boolean
pfDate	'1999,01,30'	AsDate := EncodeDate(1999,01,30)	TDateTime
pfString	'Vancouver'	Value := 'Vancouver'	string
pfDateTime	'1999,01,30 1:12:14'	AsDateTime := StrToDateTime('01/30/99 1:12:14')	TDateTime
pfTime	'1:12:14'	AsTime := EncodeTime(1,12,14,0)	TDateTime

NOTE: When running a report, always retrieve and set the ParamFields from the main Report. The only time it is necessary to retrieve ParamFields for a Subreport specifically, is when that Subreport is going to be run as a separate report, apart from the main Report (see Subreports, Page 112 for more information on running a Subreport).

New Features for SCR 7

For Seagate Crystal Reports 7, the following main features have been added to the ParamFields class:

1.Stored Procedure Parameters are now handled through the ParamFields class instead of the SQL.Params class, as with the previous Crystal versions and the last VCL release. For this purpose, there is now a ParamSource property which specifies the source of the Parameter, whether it is a Crystal Reports Parameter Field, a Stored Procedure Parameter, or a Crystal Query Parameter.

2.ParamField prompts can now have a drop-down list of values, multiple values, a range of values, multiple ranges of values:

●The DefaultValues property is a TCrpeString (descendant of TStringList) which contains the multiple values that are to be presented in the Crystal Reports Parameter Field prompt dialog. If ShowDialog is set to true, the DefaultValues data takes precedence over the data contained in the Value property (i.e. DefaultValues[0] will over-ride Value if they are different).

VCL Reference

62

●The CurrentValues property is a TCrpeString (descendant of TStringList) which contains the multiple values that were entered in the Crystal Reports Parameter Field prompt dialog. This list will initially be blank unless the Report has been run already once (and then Retrieve is called after running the Report), or if the Report has Saved Data (see DiscardSavedData for more information). If ShowDialog is set to true, CurrentValues will not be used. If ShowDialog is set to False, and Info.ValueType is vtDiscrete, CurrentValues data will take precedence over the data contained in the Value property (i.e. CurrentValues[0] will over-ride Value if they are different).

●A Ranges sub-class has been added under the ParamFields class. This sub-class contains the properties that apply to Range Parameters (parameters that can take beginning and ending range values). This object only comes into play if you are passing range values direct to the Report, bypassing Crystal's Parameter prompt dialog, or if you wish to view the Range values that were either saved with the Report (if the Report has Saved Data), or that were entered when the Report was just run. In order to use Ranges, ShowDialog must be set to False, and Info.ValueType must be set to vtRanges. In this case, the Ranges data will take precedence over the data contained in the Value property.

3.An EditMask can be specified to control the formatting of values that are entered into the Crystal Report Parameter Field dialog box for a particular Parameter.

4.Limits can be set to the length or size of the value that can be entered into the Crystal Reports Parameter Field dialog box for a particular Parameter. This is handled by three properties: ValueLimit, ValueMax, and ValueMin. ValueLimit determines if the Limit feature is enabled or not. ValueMax and ValueMin determine the upper and lower limits. If the Parameter is a string, the limits apply to the length of the string. If the Parameter is any other type, the limits apply to the maximum and minimum values that can be entered. Limits and EditMask are mutually exclusive. If you define an EditMask, Limits will be ignored.

5.A Parameter Fields Info sub-class has been added under the ParamFields class. This sub-class contains various properties that specify whether the Parameter can be edited, whether it can have null values (for Stored Procedure Parameters), whether it can contain multiple values, whether it is a Range Parameter, and whether it belongs to a group (and if so, which group number).

ParamFields Example

The following code fills a ListBox with all the ParamField Names for the current Report:

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

for cnt := 0 to (Crpe1.ParamFields.Count - 1) do ListBox1.Items.Add(Crpe1.ParamFields[cnt].Name);

This example illustrates the Value and AsDate, etc. properties to set Parameter Field values:

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

Crpe1.ParamFields.Retrieve;

Crpe1.ParamFields[0].Value := 'CA';

Crpe1.ParamFields[1].AsDate := Now;

Crpe1.ParamFields[2].AsNumber := 3;

Crpe1.ParamFields[3].AsBoolean := True;

Crpe1.Output := toWindow;

Crpe1.Execute;

VCL Reference

63

This example sets 3 default values for the first ParamField that will appear in the drop-down list when the Crystal Parameter prompt dialog appears. The user will only be able to choose from these values; they cannot enter new ones (AllowEditing is false):

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

Crpe1.ParamFields.Retrieve;

Crpe1.ParamFields[0].DefaultValues.Clear;

Crpe1.ParamFields[0].DefaultValues[0] := 'AK';

Crpe1.ParamFields[0].DefaultValues[1] := 'CA';

Crpe1.ParamFields[0].DefaultValues[2] := 'WA';

Crpe1.ParamFields[0].ShowDialog := True;

Crpe1.ParamFields[0].Info.AllowEditing := False;

Crpe1.Output := toWindow;

Crpe1.Execute;

This example sets 2 Range values for the first ParamField. These will be passed directly into the report, bypassing the Crystal Parameter prompt dialog:

Crpe1.ReportName := 'C:\Company.rpt'; Crpe1.ParamFields.Retrieve; Crpe1.ParamFields[0].Info.ValueType := vtRanges; Crpe1.ParamFields[0].ShowDialog := False; Crpe1.ParamFields[0].Ranges.Clear; Crpe1.ParamFields[0].Ranges.Add(0); Crpe1.ParamFields[0].Ranges[0].RangeStart := 'Atkinson'; Crpe1.ParamFields[0].Ranges[0].RangeEnd := 'Jones';

Crpe1.ParamFields[0].Ranges[0].RangeBounds := IncludeStartAndEnd; Crpe1.ParamFields[0].Ranges.Add(1); Crpe1.ParamFields[0].Ranges[1].RangeStart := 'Smith'; Crpe1.ParamFields[0].Ranges[1].RangeEnd := 'Wilson'; Crpe1.ParamFields[0].Ranges[1].RangeBounds := IncludeStartAndEnd; Crpe1.Output := toWindow;

Crpe1.Execute;

ParamFields Properties

ParamFields AsBoolean property, Page 437

ParamFields AsCurrency property, Page 438

ParamFields AsDate property, Page 438

ParamFields AsDateTime property, Page 439

ParamFields AsNumber property, Page 439

ParamFields AsTime property, Page 440

ParamFields CurrentValue property, Page 440

ParamFields CurrentValues property, Page 441

ParamFields DefaultValue property, Page 442

ParamFields DefaultValues property, Page 443

VCL Reference

64

ParamFields EditMask property, Page 445

ParamFields Info property, Page 446

●Properties

●ParamFields Info AllowEditing property, Page 447

●ParamFields Info AllowMultipleValues property, Page 448

●ParamFields Info AllowNull property, Page 448

●ParamFields Info GroupNum property, Page 449

●ParamFields Info MutuallyExclusiveGroup property, Page 450

●ParamFields Info PartOfGroup property, Page 450

●ParamFields Info ValueType property, Page 451

●Methods

●ParamFields Info Clear method, Page 452

●ParamFields Info CopyFrom method, Page 453

●ParamFields Info Create method, Page 454

●ParamFields Info Retrieve method, Page 454

●ParamFields Info Send method, Page 455

ParamFields Item property, Page 455

ParamFields ItemIndex property, Page 456

ParamFields Name property, Page 456

ParamFields NeedsCurrentValue property, Page 457 ParamFields ParamSource property, Page 458 ParamFields ParamType property, Page 459 ParamFields Prompt property, Page 460 ParamFields Ranges property, Page 460

●Properties

●ParamFields Ranges Item property, Page 462

●ParamFields Ranges ItemIndex property, Page 462

●ParamFields Ranges Number property, Page 463

●ParamFields Ranges RangeBounds property, Page 464

●ParamFields Ranges RangeEnd property, Page 464

●ParamFields Ranges RangeStart property, Page 465

VCL Reference

65