Modifying Report Parameters

Parameters in RAS use a totally different architecture than parameters in .NET. The RAS uses a ParameterFieldController to manage a report’s parameters. The ParameterFieldController is found in the DataDefController namespace. Modifying a parameter requires you getting a copy of the existing parameter object. Make changes to this copy and then tell the controller to use the copy to update the actual parameter in the report.

Before looking at the details of how to modify parameters, you need to understand how to work with the two types of parameters: discrete value and ranged value. Each type requires using a different report object and each works slightly different than the other.

Discrete parameters use the ParameterFieldDiscreteValue class. They are the easiest to change. Simply assign a value to the parameter using the Value property.

Range parameters use the ParameterFieldRangeValue class. You have to set both the beginning and ending values (the boundary) of the range. This is done using two properties: BeginValue and EndValue. Each of these values can either be inclusive or exclusive. Each range boundary is set using the properties LowerBoundType and UpperBoundType. There are three possible settings for determining whether a value is included in the range or not. These settings are listed in Table 20-2.

Table 20-2. Possible values for the bounds type.

The only part of the table that might need clarifying is the value crRangeValueBoundTypeNoBound. This setting isn’t available in .NET. It is used for ignoring either the lower or upper bounds. For example, if used for the lower bound, then there will be no lower bound and the range will only be limited to the upper bound.

Now that you’ve seen how to work with the different types of parameters, let’s build upon this information and look at the steps for modifying parameters during runtime. The RAS object model doesn’t let you modify a parameter directly. You have to temporarily build a new parameter field and set its properties. Pass this new parameter to the ParameterFieldController object and it updates the exiting parameter to have the new values. The detailed steps of how to implement are as follows.

Declare two parameter field objects. One is for the existing report parameter and the other is for creating the new parameter. Each object variable is of type ParameterField.

Get a reference to the existing parameter from the ParameterFields collection. The ParameterFields collection is found in the report’s DataDefinition class. The following line of code passes the value 0 so that the first parameter in the collection is retrieved.

OldParameter = myReport.DataDefinition.ParameterFields.Item(0)

This line of code requires that you know the field’s index number in the collection. If you don’t know the index number, you can get it by calling the collection’s Find() method. The Find() method is passed a string that is used for identifying the parameter you want. It returns an integer that is the index number of where that parameter is within the ParameterField collection.

The string that is used to find a parameter can actually be different things. A few examples of what the string could represent iare the parameter name, its header, or its formula. Since the string could represent a variety of things, you also have to pass an enumerator that states how to use the string. The following line of code finds a parameter field with the name “EmpId”. The first parameter is the string name and the second parameter is the enumerator.

Dim ParameterIndex as Integer
ParameterIndex = myReport.DataDefinition.ParameterFields.Find("EmpId", CrystalDecisions.ReportAppServer.DataDefModel.CrFieldDisplayNameTypeEnum.
crFieldDisplayNameName)
Due to the dynamic nature of reports as they are developed, it isn’t practical to track the index number of each parameter object. To make your application easier to read and maintain, you should always use the Find() method.

After getting a reference to the existing parameter object, copy it to the new parameter object. This is done by instantiating the new parameter field and calling the CopyTo() method of the existing parameter. The CopyTo() method copies all the properties of the existing parameter into the new parameter.

OldParameter.CopyTo(NewParameter, True)

Modify the new parameter object so that it stores the new value(s). To do this you have to instantiate a new value object based upon the type of parameter and then assign a value to it. As mentioned earlier, since a parameter can store either discrete values or range values, this code to update the parameter value(s) is different for each type.

Programming the discrete value only requires setting the Value property. The following code creates a discrete value object and assigns it a value from the generic variable myValue.

myParameterValue = New CrystalDecisions.ReportAppServer.DataDefModel.ParameterFieldDiscreteValue
myParameterValue.Value = myValue

Programming the range value requires setting the BeginValue and EndValue properties. You also have to specify whether the bounds are inclusive or exclusive using the LowerBoundType and UpperBoundType properties. The following code creates a range value object and assigns it the generic variables myBeginValue and myEndValue. Both the lower and upper bounds are set to be inclusive.

myParameterValue = New CrystalDecisions.ReportAppServer.DataDefModel.ParameterFieldRangeValue
myParameterValue.BeginValue = myBeginValue
myParameterValue.LowerBoundType = _
CrystalDecisions.ReportAppServer.DataDefModel.CrRangeValueBoundTypeEnum.
crRangeValueBoundTypeInclusive
myParameterValue.EndValue = myEndValue
myParameterValue.UpperBoundType = _
CrystalDecisions.ReportAppServer.DataDefModel.CrRangeValueBoundTypeEnum.
crRangeValueBoundTypeInclusive

After creating either the discrete value or range value, you have to assign it to the values collection of the new parameter object.

NewParameter.CurrentValues.Add(myParameterValue)

At this point, the new parameter has been created and assigned the new values. Now you have to copy this parameter back into existing parameter and overwrite the existing parameters’s values. The report object has a ParameterFieldController object which manages the parameters. Call the Modify() method and pass it both the existing parameter object and the new parameter object.

myReport.DataDefController.ParameterFieldController.Modify(OldParameter, NewParameter)

After calling the Modify() method, the parameter will have the current value(s) that the report needs to run. If there are more parameters in the report, then you have to call this code again for each parameter.

The following examples tie all the code samples into a single listing so that it is easier for you to see how all the objects work together.