Common Programming Tasks

The different delivery mechanisms for the report viewer have been discussed. Now lets look at some of the common programming tasks that go along with delivering reports. This includes passing parameters to the report viewer and setting or changing the data source. The following sections will discuss these topics.

Passing Parameters

One of the most common programming tasks with any Crystal product is to pass parameters to the report viewer. This really isn a hard task but developers often find this difficult because of a lack of proper examples in the product documentation. This chapter will attempt to provide concrete examples. Typically, reports are designed to be dynamic and so have multiple parameters that drive how the report functions. There are two ways to handle parameters: either have the report viewer prompt the user for the parameters automatically or pass the parameter values via code. Which method you choose is determined largely by whether you want the users to pick their own parameter values themselves.

Using the automatic parameter prompting requires no extra code or configuration. Simply view a report using either the viewer class or tag library and a default parameter prompting screen is displayed. Alternatively, you can pass the parameter values by code. This involves creating a series of objects as outlined below.

The first step in passing parameter values is to create an instance of the Fields class. This is a container class for parameter fields. This and the other objects are found in the com.crystaldecisions.sdk.occa.report.data package. Next, create an instance of the ParameterField object. To determine which parameter you are setting values for, call the setName method passing in the name of the parameter. Then to set the parameter values, create an instance of the Values class, which is a container for parameter value objects. Finally, create a ParameterFieldDiscreteValue object and call the setValue method to pass in the actual parameter value. This collection of objects is then passed to the report viewer via the setParameterFields method. Listing 28.5 shows a parameter being passed.

Listing 28.5. Passing a Simple Parameter

Fields fields = new Fields();

ParameterField param = new ParameterField();

param.setName("Country");

Values vals = new Values();

ParameterFieldDiscreteValue val = new ParameterFieldDiscreteValue();

val.setValue("Canada");

vals.add(val);

param.setCurrentValues(vals);

fields.add(param);

viewer.setParameterFields(fields);

Because there tends to be a bunch of objects you need to create, a nice way to handle this is to wrap up the parameter logic into a function. Listing 28.6 provides a sample function like this.

Listing 28.6. A Sample Parameter-Handling Function

public ParameterField createParam(string name, object value) {

 ParameterField param = new ParameterField();

 param.setName(name);

 Values vals = new Values();

 ParameterFieldDiscreteValue val = new ParameterFieldDiscreteValue();

 val.setValue(value);

 vals.add(val);

 param.setCurrentValues(vals);

 return param;

}

After you have a function like this in place, passing parameters looks as simple as in Listing 28.7.

Listing 28.7. Calling the Sample Parameter-Handling Function

Fields fields = new Fields();



field.add( createParam("Country", "Canada") );

field.add( createParam("Product Line", "Widgets") );



viewer.setParameterFields(fields) ;

Setting Data Source Information

Setting data source information works very similar to the way setting parameters works. There is a collection of objects that you create, which then gets passed to the report viewer. In this case, the method used is setDatabaseLogonInfos. This method takes a ConnectionInfos object, which is found in the com.crystaldecisions.sdk.occa.report.data package. The ConnectionInfos class is a container class for any data source information for a given report. Each connections information is held in an object called ConnectionInfo. This object has setUserName and setPassword methods for passing credentials. Also, each ConnectionInfo has a collection of properties associated with it called a property bag. The property bag contains information such as server name, database name, connection type, and so on. The property bag stores information in a name/value pair structure. There are variations as to what items are held in the ConnectionInfo, but the best way to figure it out is to look in the Set DataSource Location dialog from the Crystal Reports designer. There you can see which items are associated with a connection. Listing 28.8 shows how to pass logon information for a report.

Listing 28.8. Passing Data Source Credentials

ConnectionInfos connections = new ConnectionInfos();



ConnectionInfo connection as new ConnectionInfo();

connection.setUserName("Ryan");

connection.setPassword("123BAC");



connections.add(connection);

viewer.setDatabaseLogonInfos(connections);