In Chapter 3, we introduced parameters and explained how you can use them within reports and queries to limit the results returned from the data source. To this point you have been work-ing with a query instead of a stored procedure to build reports, but we have only touched the surface of how you can use parameters within SSRS. Parameters get their values primarily from user input and are most often associated with a dataset; they are used to limit the amount of data returned. When a parameter is used in this way, it is called a query parameter. Query parameters that are part of a dataset, such as a SQL query or stored procedure, automatically generate report parameters within SSRS.
In this section, you will modify the dataset of your Employee Service Cost report to use a parameterized stored procedure instead of a query. By default, report parameters generated from stored procedures do not have populated drop-down lists of data for users to select, so in this section you will also populate the report parameter lists with valid data for user-selectable input. Finally, you will see how SSRS works with NULLparameter values and how to generate aNULLvalue for the parameter. This will become especially important when retrieving data for your SSRS report, as we will explain later in this section.
You will return to the stored procedure you have already created, called Emp_Svc_Cost, which, as you might recall, will deliver the same dataset as the SQL query you have been using. The stored procedure has the added benefit of accepting all the parameters you want to use in the report. SSRS will automatically create the report parameters from the stored procedure. Let’s quickly review the parameters that will be passed into the report from the stored procedure:
• BranchID
• EmployeeTblID
• ServiceMonth
• ServiceYear
• ServiceLogCtgryID
To create the parameters automatically for your Employee Service Cost report, which is currently using a nonparameterized query, you will simply change the dataset for your report to be the stored procedure.
Open the EmployeeServiceCost_SPreport from the project included in the code download.
On the Data tab that has the dataset Emp_Svc_Cost, you can click the ellipsis button (...) next to the Datasetfield to open the Properties window. In the Command Type drop-down list, change the value from Text to Stored Procedure. Next, type the name of the stored procedure, Emp_Svc_Cost, in the Query String window. When you click OK and then execute the query in the generic query designer, you are prompted to input parameters (see Figure 4-16). Since the stored procedure is designed to accept NULLvalues, change the default input value in the Define Query Parameters dialog box from Blankto NULL, and click OK to complete the execution. If you do not select NULLinstead of Blank, the query will fail with an error message, “Failed to convert string to Int32.”
Figure 4-16. Parameters required for the stored procedure Emp_Svc_Cost
Allow Null Valuefield
In the Report Parameters Properties box, you can see that the report parameters were auto-matically created from the stored procedure. Though SSRS did correctly assign the datatype for each parameter, integer, and string, it did not automatically set the field to allow NULLvalues (see Figure 4-17). For the purpose of this report, which expects NULLvalues as possible param-eters, it is important that the Allow Null Value checkbox is selected for each parameter so that when the report is previewed, NULLwill be the default value, and the NULLcheckbox will be automatically checked so that the report executes without requiring user input.
Figure 4-18. No parameter values available via drop-down list
Default parameter values will also need to be manually configured. If no default parame-ter value is assigned to an available parameparame-ter, the report, when rendered or previewed, will not process the incoming data until a user supplies a value. Previewing the report without modifying the parameter selection reveals that the user would need to enter a value for each parameter that has no default value assigned. The user would not be able to choose from a list of values but would have to enter them manually. This is unacceptable because the user will not always know the correct values; good examples of this are the EmployeeTblIDfield that is used to select a specific employee and the BranchIDfield used to retrieve the branch name.
The first step is to provide valid query-assigned values for the parameter drop-down lists.
It would be beneficial to provide a view of the report in preview mode prior to adding descriptive parameter values from a new dataset (see Figure 4-18). Notice that there is aNULLcheckbox selected next to the parameter selections. The NULLcheckboxes appear when the parameter allows NULLvalues, as you set earlier, and there are no other available values.
The following list of procedures will add two datasets to populate the Branch and Employee drop-down lists for the parameters:
1. On the Data tab, create two new datasets, Employee_DSand Branch_DS, by dropping down the Dataset list and selecting New Data Set. For both datasets you create, you will add simple queries that will return the IDs and names for the employee and the branch. Notice in the WHEREclause of the employee query that you are including only a known set of employees for simplicity.
--Query for Employee Parameter
2. After you have created the datasets with the previous queries and verified that they exe-cute properly on the Data tab, go to the Layout tab, and from the menu select Report ➤ Report Parameters. Select the BranchIDparameter, and enter Branch for the prompt for clarity, as you will be selecting the branch name in the drop-down list. Do the same for the EmployeeTblIDparameter, entering Employee for the prompt.
3. In the available values for the branch parameters, select From Query, and then select the Branch_DSdataset. The Valuefield will be BranchID, and the Labelfield will be BranchName.
4. Follow the same steps to modify the Employeeparameters, assigning Employee_DSand choosing the Valueand Labelfields as EmployeeTblIDand Employee_Name, respectively.
When finished, select OK.
5. Finally, on the Layout tab you will add a grouping for Branch Name to the table in the report so that as the parameters are selected, you can see that the report is specific to a branch. To do this, right-click on the button to the left of the Table Header row, above Diagnosis, and select Insert Group. This will make the Diagnosis group, formerly the first group, now the second group and will add a new group. Assign the expression value of =Fields!BranchName.Valueto the new group, and click OK in the Grouping and Sorting dialog box. Next, drag the BranchNamefield from the Datasets window to the new first column row for the Branch group you just created. Also, make the field bold, and resize the font to 12 points.
The report will now have populated drop-down lists for the available parameter values, as shown in Figure 4-19. Notice that for the two parameters where you have added available values, the NULLcheckbox has disappeared.
Figure 4-19. Report with populated parameter selections
You could perform the same steps for the ServiceLog CtgryIDparameter and provide a valid drop-down list from the table values. However, since you may also be viewing the report in a custom report viewer that will also accept parameter values, this particular parameter value is of little use to you now for direct user input. That being the case, it will be beneficial to take advantage of another new and much needed feature, the ability to hide parameters. This func-tionality was added in Service Pack 2 for SSRS for SQL Server 2000 and is available in 2005 as well. Sometimes a parameter can and should be populated by events other than user input. In these instances, users will only be confused by seeing these additional parameters. In the Report Parameters dialog box, select the ServicesLogCtgryIDproperty, and check the Hidden box. It will also be beneficial to modify the time-based parameters (Service Yearand Service Month) for this report. Time-based values are often tricky to deal with because of the special formatting needs of the DateTime datatype, which can store years, months, and days as well as hours, minutes, and seconds. The procedures for setting up the Service Yearand Service Month parameters with valid values is almost identical to the Branchand Employeeprocedures covered earlier, with the exception that the Service Yearneeds to default to the current year and not NULL.
The first step is to create a dataset for the Service Yearand Monthparameters based on the service date, which is the field ChargeServiceStartDatein the stored procedure. You will use the DatePartand DateNamefunctions in the two queries to derive valid values. The valid values for the dates are contingent upon their existence in the table, so, for example, if your data con-tained values for 2003 and 2004, only those two years would show up in the drop-down list.
Populating the date values in this way precludes the user from having to enter a date and also prevents the report designer from having to hard-code year and month values into the report.
Listing 4-2 shows the two queries that drive the parameter values. Unlike with SSRS for SQL Server 2000, you don’t need to pass in aNULLvalue in the dataset, as SSRS for SQL Server 2005 supplies the NULLvalue by default when the parameter allows NULLvalues. This was a limitation with the previous version that has been addressed.
Listing 4-2. Parameter Value Queries
To finish the report, add the Service Yearfield to the report, formatting it with a distinct color (in this case, dark salmon), and then resize the field to 12 points. Before you preview the report, it is important to set the default value for the year so that a valid Service Month selec-tion is not based on the default Service Yearfield of NULL. This could potentially have undesired results; in other words, the user might select January and assume that it means January for the current year, when in fact it would be all occurrences of January.
To make the Service Yearparameter default to the current year, go to the Report Parameters dialog box and set the Default Value option to the following expression:
=cint(DatePart("yyyy",Now()))
You can preview the report and provide parameter values (see Figure 4-20).
■ Note
Most of the data in the Pro_SSRSdatabase is from 2003 and 2004. If the current year is defaulted to a different year, the data you see may not be the same as that shown in Figure 4-20.The EmployeeServiceCost_Parameters.rdlreport in the Pro_SSRSproject includes popu-lated parameters.
Figure 4-20. Report with valid year and month values