Programming with the ReportDocument Class

The ReportDocument class manages every report object in the report. It has a collection class that is fully populated with every report parameter. Each parameter object can be assigned a value prior to printing the report.

To set a parameter’s value, first get a reference to parameter field object. In the ReportDocument class. A parameter field is represented with the ReportFieldDefinition class. Once you have a reference to it, you can modify any of its properties.

The ReportFieldDefinition class has two properties that you are most concerned with: the CurrentValues and DefaultValues collections. Both of these collection objects are of the ParameterValues class. If you recall from Chapter 5, a parameter can have a single value or it can have multiple values. Since it can have more than one value then a collection is needed to store the values. The ParameterValues collection class is where these values are stored.

A parameter is either a discrete value or a range value and each is represented by a different class. The ParameterDiscreteValue class is for discrete values. The ParameterRangeValue class is for range values.

The ParameterDiscreteValue class only has one property to set: Value. This is the parameter’s value. It is of type Object so that you can assign any data type to it as long as it is compatible with the data type that the parameter uses.

The ParameterRangeValue class has four values to set: StartValue, EndValue, LowerBoundType and UpperBoundType. The two value parameters are used to define the lower and upper bounds of the range. The two bound-type parameters are used to set whether the endpoint is inclusive or exclusive. If it is inclusive, then the value is included as part of the range. If it is exclusive, then the endpoint is not included as a part of the range. For example, let’s say the range is 0 to 10 and the LowerBoundType is BoundExclusive and the UpperBoundType is BoundInclusive. This range would include all numbers from 1 to 10. If the bound-type is NoBound, then there will be no bounds for that parameter and you do not need to enter a value for it.

After populating the ParameterValues collection with one or more values, you have to assign it to either the CurrentValues property or the DefaultValues property. Do this by calling the ApplyCurrentValues() method or the ApplyDefaultValues() method. Pass each method the ParameterValues collection object.

Programming parameters with the ReportDocument class consists of 8 steps:

Get a reference to the parameter field object that you want to modify. Use caution when declaring the variables because you have to declare an object of the ParameterFieldDefinition class, but get a reference to it using the ParameterFields property.
Instantiate a ParameterValues collection object.
Instantiate a parameter value object. This will either be of the ParameterDiscreteValue class or the ParameterRangeValue class.
Set the properties of the new parameter value object.
Add the parameter value object to the ParameterValues collection using the Add() method.
Repeat steps 3-5 for each parameter value object.
Assign the ParameterValues collection to the appropriate parameter field property using either the ApplyCurrentValues() method or the ApplyDefaultValues() method.
Set the ReportSource property of the CrystalReportViewer object so that the report gets displayed.

Listing 16-7 illustrates these steps. It modifies the DefaultValues collection by creating two discrete parameters and adding them to the collection. This gives the user a choice of two options to choose from when selecting the parameter value. Since we want the user to be prompted with the new default values, then there is no need to modify the CurrentValues property. The inline comments explain the steps that are taking place.

Listing 16-7. Use the report document to modify a discrete parameter.
[VB.NET]
Dim myReport As new CrystalDecisions.CrystalReports.Engine.ReportDocument
myReport.Load("SampleReport.rpt")
'Use the ReportDocument object to create two default parameters
Dim myParameterFieldDefinition As _
CrystalDecisions.CrystalReports.Engine.ParameterFieldDefinition
Dim myParameterValues As CrystalDecisions.Shared.ParameterValues
Dim myParameterDiscreteValue As _
CrystalDecisions.Shared.ParameterDiscreteValue
'Step 1:Get a reference to the parameter field to modify
myParameterFieldDefinition = _
myReport.DataDefinition.ParameterFields("Location")
'Step 2: Instantiate a ParameterValues collection object.
myParameterValues = New CrystalDecisions.Shared.ParameterValues()
'Step 3: Instatiate a ParameterValue object.
'This example uses a discrete value
myParameterDiscreteValue = _
New CrystalDecisions.Shared.ParameterDiscreteValue()
'Step 4: Assign a value to the object
myParameterDiscreteValue.Value = "Louisville, KY"
'Step 5: Add it to the ParameterValues collection using the Add() method
myParameterValues.Add(myParameterDiscreteValue)
'Step 6: Repeat steps 3-5 for additional parameters
myParameterDiscreteValue = _
New CrystalDecisions.Shared.ParameterDiscreteValue()
myParameterDiscreteValue.Value = "San Diego, CA"
myParameterValues.Add(myParameterDiscreteValue)
'Step 7: Assign the ParameterValues collection to the parameter field.
'Do this with either the CurrentValues or DefaultValues collection
myParameterFieldDefinition.ApplyDefaultValues(myParameterValues)
'Step 8: Print or Preview the report
CrystalReportViewer1.ReportSource = myReport
[C#]
CrystalDecisions.CrystalReports.Engine.ReportDocument myReport = new
CrystalDecisions.CrystalReports.Engine.ReportDocument();
myReport.Load("SampleReport.rpt");
CrystalDecisions.Shared.ParameterDiscreteValue ParameterDiscreteValue;
CrystalDecisions.Shared.ParameterValues ParameterValues;
//Use the ReportDocument object to create two default parameters
CrystalDecisions.CrystalReports.Engine.ParameterFieldDefinition ParameterFieldDefinition;
//Step 1: Get a reference to the property field to modify
ParameterFieldDefinition = myReport.DataDefinition.ParameterFields["Location"];
//Step 2: Instantiate a ParameterValues collection object
ParameterValues = new CrystalDecisions.Shared.ParameterValues();
//Step 3: Instantiate a ParameterValue object
//This example uses a discrete value
ParameterDiscreteValue = new CrystalDecisions.Shared.ParameterDiscreteValue();
//Step 4: Assign a value to the object
ParameterDiscreteValue.Value = "Louisville, KY";
//Step 5: Add it to the ParameterValues collection using the Add() method
ParameterValues.Add(ParameterDiscreteValue);
//Step 6: Repeat steps 3-5 for additional parameters
ParameterDiscreteValue = new CrystalDecisions.Shared.ParameterDiscreteValue();
ParameterDiscreteValue.Value = "San Diego, CA";
ParameterValues.Add(ParameterDiscreteValue);
//Step 7: Assign the ParameterValues collection to the parameter field
//Do this for either the CurrentValues or DefaultValues collection
ParameterFieldDefinition.ApplyDefaultValues(ParameterValues);
//Step 8: Print or Preview the report
crystalReportViewer1.ReportSource = myReport;