{"id":84917,"date":"2019-08-02T21:32:15","date_gmt":"2019-08-02T21:32:15","guid":{"rendered":"https:\/\/www.red-gate.com\/simple-talk\/?p=84917"},"modified":"2022-04-24T21:02:04","modified_gmt":"2022-04-24T21:02:04","slug":"reporting-services-basics-parameters","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/databases\/sql-server\/bi-sql-server\/reporting-services-basics-parameters\/","title":{"rendered":"Reporting Services Basics: Parameters"},"content":{"rendered":"<h4>The series so far:<\/h4>\n<ol>\n<li><a href=\"https:\/\/www.red-gate.com\/simple-talk\/sql\/bi\/reporting-services-basics-overview-and-installation\/\">Reporting Services Basics: Overview and Installation<\/a><\/li>\n<li><a href=\"https:\/\/www.red-gate.com\/simple-talk\/sql\/bi\/reporting-services-basics-creating-your-first-report\/\">Reporting Services Basics: Creating Your First Report<\/a><\/li>\n<li><a href=\"https:\/\/www.red-gate.com\/simple-talk\/sql\/bi\/reporting-services-basics-understanding-data-sources-and-datasets\/\">Reporting Services Basics: Data Sources and Datasets<\/a><\/li>\n<li><a href=\"https:\/\/www.red-gate.com\/simple-talk\/sql\/bi\/reporting-services-basics-parameters\/\">Reporting Services Basics: Parameters<\/a><\/li>\n<li><a href=\"https:\/\/www.red-gate.com\/simple-talk\/sql\/bi\/reporting-services-basics-adding-groups-to-reports\/\">Reporting Services Basics: Adding Groups to Reports<\/a><\/li>\n<\/ol>\n\n<p>Adding parameters is one of the essential skills to learn when you are new to SSRS. Parameters give end-users the ability to change the filter of the report on-the-fly. Imagine creating a separate report for every sales year or every department. Even worse, imagine creating a report for every combination of years and departments! With parameters, you can create one report that will work for any combination of these variables.<\/p>\n<h2>Starting with the Product List Report<\/h2>\n<p>To demonstrate parameters, this article will use the list of products found in the AdventureWorks database. To get started, create a new <em>Report Server Project<\/em> called <em>Parameters<\/em> with a shared data source. (See previous articles in this series if you need help understanding how to work with projects, data sources, or datasets.) Add a report named Product List with this embedded dataset:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT P.ProductID, P.Name AS ProductName, P.Color, P.Size, \r\n   P.ListPrice, PC.Name AS Category, PS.Name AS SubCategory\r\nFROM Production.Product AS P \r\nJOIN Production.ProductSubcategory AS PS \r\n  ON PS.ProductSubcategoryID = P.ProductSubcategoryID\r\nJOIN Production.ProductCategory AS PC\r\n  ON PC.ProductCategoryID = PS.ProductCategoryID;<\/pre>\n<p>Your <em>Solution Explorer<\/em> should look like Figure 1.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"362\" height=\"224\" class=\"wp-image-84918\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image.png\" \/><\/p>\n<p class=\"caption\">Figure 1: The Solution Explorer<\/p>\n<p>Your <em>Report<\/em> <em>Data<\/em> window should look like Figure 2.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"254\" height=\"320\" class=\"wp-image-84919\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-1.png\" \/><\/p>\n<p class=\"caption\">Figure 2: The Report Data window<\/p>\n<p>Add a <em>Table<\/em> control to the report\u2019s canvas and add these fields to the <em>Data<\/em> row.<\/p>\n<ul>\n<li>ProductID<\/li>\n<li>ProductName<\/li>\n<li>Color<\/li>\n<li>Size<\/li>\n<li>ListPrice<\/li>\n<\/ul>\n<p>The table on the report will look like Figure 3.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"529\" height=\"102\" class=\"wp-image-84920\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-2.png\" \/><\/p>\n<p class=\"caption\">Figure 3: The table<\/p>\n<p>Preview the report to make sure it works at this point. It should look something like Figure 4.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"515\" height=\"418\" class=\"wp-image-84921\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-3.png\" \/><\/p>\n<p class=\"caption\">Figure 4: The report in Preview mode<\/p>\n<p>Spend some time formatting the report. This is not required for learning about parameters, but if you are like me, the unformatted report is quite annoying! Your report might look something like Figure 5 when you are done.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"533\" height=\"271\" class=\"wp-image-84922\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-4.png\" \/><\/p>\n<p class=\"caption\">Figure 5: The formatted report<\/p>\n<p>The wizard report from the first article had a header, but you didn\u2019t learn how to add a header to a new report. To do so, make sure that the report is in <em>Design<\/em> view. Select the report canvas, which makes the <em>Report<\/em> menu show up in the menu bar. <em>Select Report Add Page Header,<\/em> as shown in Figure 6. Also, add a page footer.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"217\" height=\"155\" class=\"wp-image-84923\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-5.png\" \/><\/p>\n<p class=\"caption\">Figure 6: Add a page header and footer<\/p>\n<p>Move the table so that it is close to the header and the left of the page. Also, drag the top of the footer to the bottom of the table. Drag the right side of the canvas to the table. The canvas should look like Figure 7.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"553\" height=\"257\" class=\"wp-image-84924\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-6.png\" \/><\/p>\n<p class=\"caption\">Figure 7: The canvas with header and footer<\/p>\n<p>In the <em>Report<\/em> <em>Data<\/em> window, expand <em>Built-in Fields<\/em>. Drag the <em>Report<\/em> <em>Name<\/em> field into the page header, as shown in Figure 8.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"875\" height=\"491\" class=\"wp-image-84925\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-7.png\" \/><\/p>\n<p class=\"caption\">Figure 8: Drag the Report Name<\/p>\n<p>Expand the textbox width to the size of the canvas. Increase the font size to 22 and align the text in the centre. You can also drag <em>Execution Time<\/em> and <em>Page Number <\/em>to the footer. (Note that you may need to expand the are under the table where you can temporarily drag the first footer item before adding it to the footer.) The report canvas should now look like Figure 9.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"551\" height=\"218\" class=\"wp-image-84926\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-8.png\" \/><\/p>\n<p class=\"caption\">Figure 9: Formatted header and footer<\/p>\n<h2>Adding Simple Parameters<\/h2>\n<p>SSRS will automatically add parameters to your report when you have variables in the <code>WHERE<\/code> clause of the query. In this case, you\u2019ll add a parameter to filter on color. Double-click the dataset and change the query to this:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT P.ProductID, P.Name AS ProductName, P.Color, P.Size, \r\n   P.ListPrice, PC.Name AS Category, PS.Name AS SubCategory\r\nFROM Production.Product AS P \r\nJOIN Production.ProductSubcategory AS PS \r\n  ON PS.ProductSubcategoryID = P.ProductSubcategoryID\r\nJOIN Production.ProductCategory AS PC\r\n  ON PC.ProductCategoryID = PS.ProductCategoryID\r\nWHERE P.Color = @color;<\/pre>\n<p>Click <em>OK<\/em>, and you\u2019ll see the new parameter @color listed in the <em>Parameters<\/em> folder and the <em>Parameters<\/em> section of the report canvas, as shown in Figure 10.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"881\" height=\"275\" class=\"wp-image-84927\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-9.png\" \/><\/p>\n<p class=\"caption\">Figure 10: The @color parameter<\/p>\n<p>Preview the report. This time, it will not run automatically. Fill in the color \u201cblue\u201d and click <em>View Report<\/em>. The report should look like Figure 11 with only blue items displayed.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"813\" height=\"606\" class=\"wp-image-84928\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-10.png\" \/><\/p>\n<p class=\"caption\">Figure 11: Filtered by blue<\/p>\n<p>Right now, you must type in a valid color to get the report to return products. If you type in \u201cpurple,\u201d for example, no products will be returned.<\/p>\n<p>There are quite a few properties you can set to control the behaviour of parameters. You might allow a blank value, for example, or supply a list of values from which to choose. To see the properties, double-click the parameter. The <em>Report<\/em> <em>Parameter<\/em> <em>Properties<\/em> dialogue looks like Figure 12.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"633\" class=\"wp-image-84929\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-11.png\" \/><\/p>\n<p class=\"caption\">Figure 12: The parameter properties<\/p>\n<p>There are a few interesting items to note on the <em>General<\/em> page. For example, what is the difference between <em>Name<\/em> and <em>Prompt<\/em>? The <em>Name<\/em> refers to the actual name of the parameter that is used in the SQL query. The <em>Prompt<\/em> is what the user will see. So, you might want to change the \u201cc\u201d in color to uppercase make it more user-friendly.<\/p>\n<p>You can change the <em>Data<\/em> <em>Type<\/em> if you must restrict the type of values entered, such as numbers or dates. In fact, if you switch to date, the report will display a date picker control for the parameter when you run the report. There are three other options (<em>Allow blank value<\/em>, <em>Allow null value<\/em>, and <em>Allow multiple values<\/em>) that will be covered later in the article. And, finally, there is the visibility property of the parameter. Here is what each option means:<\/p>\n<p><strong>Visible:<\/strong> The parameter is shown to the end-user who can change the value<\/p>\n<p><strong>Hidden:<\/strong> The end-user is not prompted for the parameter, but the value is typically passed in from a calling report<\/p>\n<p><strong>Internal:<\/strong> The end-user is not prompted and cannot change the value. This might be used for passing in the user id to the server.<\/p>\n<p>There are three more pages to this dialogue. This article will cover <em>Available Values<\/em> and <em>Default Values<\/em>. Now, you\u2019ll learn how to provide a list of values for the parameter.<\/p>\n<h2>Adding a Parameter List<\/h2>\n<p>It can be difficult for the user to remember the valid values for a report, so report developers often provide lists of values from which to choose. To provide a list of colors, follow these steps.<\/p>\n<p>Switch to the parameter\u2019s <em>Available Values<\/em> page. Currently, the option is set to <em>None, <\/em>as shown in Figure 13, which means that no list is provided.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"269\" class=\"wp-image-84930\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-12.png\" \/><\/p>\n<p class=\"caption\">Figure 13: The Available Values page<\/p>\n<p>Switch to <em>Specify values<\/em> and click <em>Add<\/em>. You\u2019ll now have a space to type in the first value, as shown in Figure 14.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"368\" class=\"wp-image-84931\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-13.png\" \/><\/p>\n<p class=\"caption\">Figure 14: Type in values<\/p>\n<p>The <em>Label<\/em> is shown to the end-user, while the <em>Value<\/em> is passed to the SQL query. In this case, both values are the same. Enter the following list:<\/p>\n<ul>\n<li>Black<\/li>\n<li>Blue<\/li>\n<li>Grey<\/li>\n<li>Multi<\/li>\n<li>Red<\/li>\n<li>Silver<\/li>\n<li>Silver\/Black<\/li>\n<li>White<\/li>\n<li>Yellow<\/li>\n<\/ul>\n<p>The screen should look like Figure 15 when you are done. Click <em>OK<\/em> to save the list.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"906\" height=\"953\" class=\"wp-image-84932\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-14.png\" \/><\/p>\n<p class=\"caption\">Figure 15: The parameter list<\/p>\n<p>Now when you preview the report, you\u2019ll see a list of colors from which to choose, as shown in Figure 16.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"213\" height=\"273\" class=\"wp-image-84933\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-15.png\" \/><\/p>\n<p class=\"caption\">Figure 16: The parameter with the list<\/p>\n<p>Try running the report multiple times, each time with a different color to verify that the report works as expected.<\/p>\n<p>If you are familiar with this data, you\u2019ll know that there are several products with no color (<em>NULL<\/em>). How can you allow a user to see those products? You\u2019ll learn that next.<\/p>\n<h2>Searching for NULL values<\/h2>\n<p>You may recall that there is a parameter option to allow <em>NULL<\/em> (see Figure 12), but to use this option, you must make a change to your query that causes other complications later. It gets messy quickly, so I suggest substituting the <em>NULLs<\/em> instead.<\/p>\n<p>To get started, add another item to the available values in the <em>Color<\/em> parameter, <em>N\/A<\/em> for both <em>Value<\/em> and <em>Label<\/em>. Double-click the <em>ProductList<\/em> dataset and change the query to this:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT P.ProductID, P.Name AS ProductName, P.Color, P.Size, \r\n   P.ListPrice, PC.Name AS Category, PS.Name AS SubCategory\r\nFROM Production.Product AS P \r\nJOIN Production.ProductSubcategory AS PS \r\n  ON PS.ProductSubcategoryID = P.ProductSubcategoryID\r\nJOIN Production.ProductCategory AS PC\r\n  ON PC.ProductCategoryID = PS.ProductCategoryID\r\nWHERE COALESCE(P.Color,'N\/A') = @color;<\/pre>\n<p>When you rerun the report and select <em>N\/A<\/em>, you should see all the items with no color. So far, you are working with a static parameter list. Now, you\u2019ll learn how to create a dynamic list. Note that using a function like <code>COALESCE<\/code> on a column in the <code>WHERE<\/code> clause can often cause performance issues.<\/p>\n<h2>Using a Query for a Parameter List<\/h2>\n<p>What happens if AdventureWorks gets in a new purple or orange product? You would have to manually add those colors to keep the parameter list up to date. Instead, you might want to maintain the list using a query. To do so, switch back to <em>Design<\/em> view add a new <em>Dataset<\/em> called <em>Colors<\/em> to the report with this query that causes the <em>N\/A<\/em> row to show up first.<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT DISTINCT COALESCE(Color,'N\/A') AS Color, \r\n\tCASE WHEN Color IS NULL THEN 0 ELSE 1 END AS SortOrder\r\nFROM Production.Product AS P \r\nORDER BY SortOrder, Color;<\/pre>\n<p>Figure 17 shows how the dataset should look.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"905\" height=\"954\" class=\"wp-image-84934\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-16.png\" \/><\/p>\n<p class=\"caption\">Figure 17: The Colors dataset<\/p>\n<p>Click <em>OK<\/em> to create the dataset. Now open the parameter properties again and switch to the <em>Available Values<\/em> page. Select <em>Get values from a query<\/em>. Under <em>Dataset<\/em>, select <em>Colors<\/em>. In both the <em>Values<\/em> and Labels field, select <em>Color<\/em>. The properties should look like Figure 18.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"905\" height=\"489\" class=\"wp-image-84935\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-17.png\" \/><\/p>\n<p class=\"caption\">Figure 18: Using a query for the parameter list<\/p>\n<p>Click <em>OK<\/em> to save the change and be sure to test the report. If you don\u2019t mind modifying a row of the <em>Product<\/em> table, run this update statement in SSMS or Azure Data Studio.<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">UPDATE Production.Product \r\nSET Color = 'Orange'\r\nWHERE ProductID IN (802, 803);<\/pre>\n<p>If you rerun the report, you should see <em>Orange<\/em> in the parameter list and the orange items in the results. Figure 19 shows the report.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"612\" height=\"427\" class=\"wp-image-84936\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-18.png\" \/><\/p>\n<p class=\"caption\">Figure 19: The orange items<\/p>\n<p>You might want to give the ability to select multiple items at once. The next section will show you how to do that.<\/p>\n<h2>Selecting Multiple Values<\/h2>\n<p>The person running your report might want to see more than one color at a time, maybe even all of them. There is a setting on the General page of the parameter properties (see Figure 12) that allows you to select more than one item. If you do this, however, your query will error, and the report will not run. Figure 20 shows the error message:<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"348\" height=\"123\" class=\"wp-image-84937\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-19.png\" \/><\/p>\n<p class=\"caption\">Figure 20: The error message after setting <em>Allow multiple values<\/em>.<\/p>\n<p>The query sent to SQL Server uses = (equal to), but the variable holds a comma-delimited list of values. To fix this issue, you\u2019ll need to modify the <em>ProductList<\/em> query to this:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT P.ProductID, P.Name AS ProductName, P.Color, P.Size, \r\n   P.ListPrice, PC.Name AS Category, PS.Name AS SubCategory\r\nFROM Production.Product AS P \r\nJOIN Production.ProductSubcategory AS PS \r\n  ON PS.ProductSubcategoryID = P.ProductSubcategoryID\r\nJOIN Production.ProductCategory AS PC\r\n  ON PC.ProductCategoryID = PS.ProductCategoryID\r\nWHERE COALESCE(P.Color,'N\/A') IN (@color);<\/pre>\n<p>After running, the report should look something like Figure 21 when <em>Multi<\/em> and <em>Orange<\/em> are selected.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"590\" height=\"507\" class=\"wp-image-84938\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-20.png\" \/><\/p>\n<p class=\"caption\">Figure 21: Selecting multiple values<\/p>\n<p>So far, you have added just one parameter to the report. Many of the reports you run in the future will have more than that. Either the dataset will have multiple predicates in the <code>WHERE<\/code> clause, or you might also use parameters to control something about how the report looks. In the next section, you\u2019ll learn how to control the value of a textbox in the report with a parameter.<\/p>\n<h2>Displaying Parameter Values on the Report<\/h2>\n<p>Parameters are the \u201cworkhorse\u201d of SSRS. You can do so many things with them. In this section, you\u2019ll learn that you can display the value or label of a parameter in a textbox.<\/p>\n<p>Back in <em>Design<\/em> view, add a <em>Textbox<\/em> to the header section of the report. Drag it to the left of the page and expand the width. It should look like Figure 22.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"556\" height=\"222\" class=\"wp-image-84939\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-21.png\" \/><\/p>\n<p class=\"caption\">Figure 22: The new Textbox<\/p>\n<p>Right-click on the new <em>Textbox<\/em> and select <em>Expression<\/em>, as shown in Figure 23.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"585\" height=\"278\" class=\"wp-image-84940\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-22.png\" \/><\/p>\n<p class=\"caption\">Figure 23: Select Expression<\/p>\n<p>Just about any property in an SSRS report can be controlled with an <em>Expression<\/em>, i.e., a formula. You\u2019ll learn much more about expressions throughout these articles, but this is a simple example to get you started. Once you select <em>Expression<\/em> in the menu, the <em>Expression<\/em> dialogue should pop up, as shown in Figure 24.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"687\" height=\"642\" class=\"wp-image-84941\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-23.png\" \/><\/p>\n<p class=\"caption\">Figure 24: The Expression dialogue<\/p>\n<p>Any expression begins with an equal to sign (=) similar to formulas in Excel. The <em>Category<\/em> area contains dozens of built-in fields and functions that you can use to build these expressions. Change the expression to<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">=\"Colors chosen: \" +<\/pre>\n<p>Then, make sure your cursor is to the right of the plus sign (+), click <em>Parameters<\/em> and double-click <em>color<\/em> in the <em>Values<\/em> window, as shown in Figure 25.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"688\" height=\"643\" class=\"wp-image-84942\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-24.png\" \/><\/p>\n<p class=\"caption\">Figure 25: The expression<\/p>\n<p>The final expression should be:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">=\"Colors chosen: \" + Parameters!color.Value(0)<\/pre>\n<p>Click <em>OK<\/em> to save the expression. The <em>Textbox<\/em> will show <em>&lt;&lt;Expr&gt;&gt;<\/em> instead of a field name. Run the report but select only one color. The report should look like Figure 26 if you selected <em>Orange<\/em>. The value you chose is visible on the report.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"584\" height=\"322\" class=\"wp-image-84943\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-25.png\" \/><\/p>\n<p class=\"caption\">Figure 26: The parameter value displayed<\/p>\n<p>This works great, but it will only display one item. It\u2019s possible that you are allowing multiple values to be selected. When you select more than one, only the first item is displayed. The reason is that the parameter values are held in an array of strings. Right now, the formula displays the first item in the array.<\/p>\n<p>To display all the chosen values, go back to <em>Design<\/em> view and bring up the <em>Expression<\/em> dialogue again. Change the formula to this:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">=\"Colors chosen: \" + Join(Parameters!color.Value,\", \")<\/pre>\n<p>Notice that the index of the array (0) was removed. The <code>Join<\/code> function builds a string from the array values. Now when you run the report, it will look something like Figure 27.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"613\" height=\"591\" class=\"wp-image-84944\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-26.png\" \/><\/p>\n<p class=\"caption\">Figure 27: Displaying multiple values<\/p>\n<p>In this example, the <em>Values<\/em> and <em>Labels<\/em> of the parameter are identical. In many cases, they are different. For example, the query might need an ID number while the person running the report might like to see the name. To get around this, change the formula so that the user-friendly label is used instead of the value:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">=\"Colors chosen: \" + Join(Parameters!color.Label,\", \")<\/pre>\n<p>You can also use parameters to change the properties of objects on the report. You\u2019ll learn how to do this next.<\/p>\n<h2>Using Parameters to Control Properties<\/h2>\n<p>Just about any property in SSRS can be controlled with an expression. If you take a look at the <em>Text Box Properties<\/em> dialogue of the <em>Textbox<\/em> you created in the last section, you\u2019ll see the <em>fx<\/em> symbol next to two properties, as shown in Figure 28.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"905\" height=\"447\" class=\"wp-image-84945\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-27.png\" \/><\/p>\n<p class=\"caption\">Figure 28: The <em>fx<\/em> symbol<\/p>\n<p>Clicking this symbol anywhere you see it brings up the <em>Expression<\/em> box to control the associated property. Before adding in an expression, cancel out of this dialogue. Create a new parameter called <em>Background<\/em> by right-clicking the <em>Parameters<\/em> folder and selecting <em>Add<\/em> <em>Parameter<\/em>. Add these values\/labels on the <em>Available<\/em> <em>Values<\/em> page.<\/p>\n<ul>\n<li>Yellow<\/li>\n<li>LightBlue<\/li>\n<li>Plum<\/li>\n<\/ul>\n<p>Once all the parameter properties are in place, click <em>OK<\/em>. You\u2019ll then see the second parameter in the list of parameters. Remember that this one isn\u2019t connected to a dataset query; it will be used to control the background, or fill, color of the <em>Textbox<\/em>.<\/p>\n<p>The next step is to connect the parameter to the <em>Textbox<\/em>. Right-click and select <em>Text<\/em> <em>Box<\/em> <em>Properties<\/em>. Select the <em>Fill<\/em> page. Click the <em>fx<\/em> symbol, as shown in Figure 29.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"904\" height=\"397\" class=\"wp-image-84946\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-28.png\" \/><\/p>\n<p class=\"caption\">Figure 29: The Fill property<\/p>\n<p>The initial expression is \u201cNo Color.\u201d Replace it with this formula:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">=Parameters!Background.Value<\/pre>\n<p>The <em>Expression<\/em> dialogue should look like Figure 30.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"683\" height=\"641\" class=\"wp-image-84947\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-29.png\" \/><\/p>\n<p class=\"caption\">Figure 30: The background expression<\/p>\n<p>Click <em>OK<\/em> twice to save the property change. Now, try running the report. If you chose <em>LightBlue<\/em>, the report should look something like Figure 31.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"578\" height=\"294\" class=\"wp-image-84948\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-30.png\" \/><\/p>\n<p class=\"caption\">Figure 31: The textbox with a blue background<\/p>\n<p>This simple example demonstrated how powerful expressions and parameters are. Next, you\u2019ll see how to set default values for parameters.<\/p>\n<h2>Using Default Parameters<\/h2>\n<p>In some cases, the user is likely to select a specific value for a parameter and only rarely change it. To learn how to set up a default value for the parameter, open the properties of the <em>Background<\/em> parameter. Select the <em>Default<\/em> <em>Values<\/em> page and <em>Specify<\/em> <em>values<\/em>, as shown in Figure 32.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"905\" height=\"347\" class=\"wp-image-84949\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-31.png\" \/><\/p>\n<p class=\"caption\">Figure 32: The Default Values page<\/p>\n<p>Click <em>Add<\/em>. Type in your favourite of the three colors, <em>LightBlue<\/em>, <em>Plum<\/em>, or <em>Yellow<\/em>. The property should look like Figure 33. Click <em>OK<\/em> to save the changes.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"360\" class=\"wp-image-84950\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-32.png\" \/><\/p>\n<p class=\"caption\">Figure 33: Filling in the default value<\/p>\n<p>Now when you run the report, the background color will be automatically filled in. You can also get default values from a dataset. Open the <em>Default<\/em> <em>Values<\/em> properties of the color parameter. Select <em>Get<\/em> <em>values<\/em> <em>from<\/em> <em>a query<\/em>. Fill in the <em>Colors<\/em> <em>Dataset<\/em> and <em>Color<\/em> <em>Value<\/em> <em>field<\/em>. The properties should look like Figure 34.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"372\" class=\"wp-image-84951\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-33.png\" \/><\/p>\n<p class=\"caption\">Figure 34: The default values from a dataset<\/p>\n<p>In this case, all colors will be selected when you run the report.<\/p>\n<p>One of the most common requests is to make the selection of one parameter filter another one. You\u2019ll learn how to do that next.<\/p>\n<h2>Creating Cascading Parameters<\/h2>\n<p>Each product belongs to a subcategory, and each subcategory belongs to a category. This is the type of hierarchical relationship that works well when parameters work together with what\u2019s called <em>Cascading<\/em> <em>Parameters<\/em>. Figure 35 illustrates how this will work.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"1005\" height=\"158\" class=\"wp-image-84952\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-34.png\" \/><\/p>\n<p class=\"caption\">Figure 35: The product\/category hierarchy<\/p>\n<p>The first step is to modify the <em>ProductList<\/em> dataset query so that it prompts for the subcategory. Change the query to this:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT P.ProductID, P.Name AS ProductName, P.Color, P.Size, \r\n   P.ListPrice, PC.Name AS Category, PS.Name AS SubCategory\r\nFROM Production.Product AS P \r\nJOIN Production.ProductSubcategory AS PS \r\n  ON PS.ProductSubcategoryID = P.ProductSubcategoryID\r\nJOIN Production.ProductCategory AS PC\r\n  ON PC.ProductCategoryID = PS.ProductCategoryID\r\nWHERE COALESCE(P.Color,'N\/A') IN (@color)\r\n  AND P.ProductSubcategoryID = @subcategory;<\/pre>\n<p>To make sure that the query works, add the <em>SubCategory<\/em> and <em>Category<\/em> fields to the report. Preview the report. Enter subcategory 31. The report should look something like Figure 36.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"835\" height=\"382\" class=\"wp-image-84953\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-35.png\" \/><\/p>\n<p class=\"caption\">Figure 36: Filtering with subcategory<\/p>\n<p>At this point, the products are being filtered by subcategory, but the ID must be typed in. To get around this issue, add a new dataset called <em>Subcategory<\/em> with this query:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT PS.ProductSubcategoryID, PS.Name AS SubcategoryName\r\nFROM Production.ProductSubcategory AS PS\r\nORDER BY SubcategoryName;<\/pre>\n<p>Connect the <em>Subcategory<\/em> dataset to the <em>subcategory<\/em> parameter. The <em>Values<\/em> <em>field<\/em> should be <em>ProductSubcategoryID<\/em>, and the <em>Label<\/em> <em>field<\/em> should be <em>SubcategoryName<\/em>. In this case, the query needs the ID while the user needs the name. The <em>Available<\/em> <em>Values<\/em> properties should look like Figure 37.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"903\" height=\"447\" class=\"wp-image-84954\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-36.png\" \/><\/p>\n<p class=\"caption\">Figure 37: Connect the dataset to the parameter<\/p>\n<p>If you review Figure 35, you\u2019ll see that subcategories should be filtered by category. To do this, change the <em>Subcategory<\/em> dataset so that it\u2019s filtered by category:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT PS.ProductSubcategoryID, PS.Name AS SubcategoryName\r\nFROM Production.ProductSubcategory AS PS\r\nWHERE PS.ProductCategoryID = @category\r\nORDER BY SubcategoryName;<\/pre>\n<p>You now have four parameters in place. Notice that <em>Category<\/em> is listed before <em>Subcategory<\/em> in Figure 38. That\u2019s because you must choose <em>Category<\/em> before Subcategory. In this parameter area, you can rearrange the parameters by dragging them around. The report will break if <em>Category<\/em> is not located before <em>Subcategory<\/em>!<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"931\" height=\"136\" class=\"wp-image-84955\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-37.png\" \/><\/p>\n<p class=\"caption\">Figure 38: The four parameters<\/p>\n<p>The next logical step is to add a dataset for <em>Category<\/em>. Use this query:<\/p>\n<pre class=\"lang:tsql theme:ssms2012-simple-talk\">SELECT PC.ProductCategoryID, PC.Name AS CategoryName\r\nFROM Production.ProductCategory AS PC \r\nORDER BY CategoryName;<\/pre>\n<p>Connect the dataset to the new <em>Category<\/em> parameter. You guessed it! The <em>Value<\/em> <em>field<\/em> is <em>ProductCategoryID<\/em>, and the <em>Label<\/em> <em>field<\/em> is <em>CategoryName<\/em>. The <em>Available<\/em> <em>Values<\/em> page should look like Figure 39.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"904\" height=\"457\" class=\"wp-image-84956\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-38.png\" \/><\/p>\n<p class=\"caption\">Figure 39: The category Available Values<\/p>\n<p>If you did everything correctly, the parameters should look like Figure 40 when you preview the report. Notice that the <em>Subcategory<\/em> parameter is greyed out until you select a <em>Category<\/em>.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"799\" height=\"77\" class=\"wp-image-84957\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-39.png\" \/><\/p>\n<p class=\"caption\">Figure 40: The Subcategory parameter is not available<\/p>\n<p>When you select a <em>Category<\/em>, the <em>Subcategory<\/em> parameter refreshes. For example, if you select <em>Bikes<\/em>, only the available bike subcategories show up. Figure 41 shows how this looks.<\/p>\n<p><img loading=\"lazy\" decoding=\"async\" width=\"416\" height=\"116\" class=\"wp-image-84958\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/08\/word-image-40.png\" \/><\/p>\n<p class=\"caption\">Figure 41: The filtered subcategory<\/p>\n<p>Configuring <em>Cascading<\/em> <em>Parameters<\/em> is one of the most challenging things to understand in SSRS. Hopefully, I\u2019ve shown that by breaking the steps down and completing them one at a time, it is doable.<\/p>\n<h2>Conclusion<\/h2>\n<p>Learning about parameters is critical for SSRS developers. In this article, you learned many ways in which parameters are used, including with a list of available values from a query, multiple selections, defaults, cascading, and more. In the next article, you\u2019ll learn about more features that make SSRS reports dynamic.<\/p>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Kathi Kellenberger continues her series on SSRS. In this article you learn how to use parameters that let your report users control how the reports are filtered.&hellip;<\/p>\n","protected":false},"author":110218,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[143528],"tags":[95509],"coauthors":[11292],"class_list":["post-84917","post","type-post","status-publish","format-standard","hentry","category-bi-sql-server","tag-standardize"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/84917","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/110218"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=84917"}],"version-history":[{"count":3,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/84917\/revisions"}],"predecessor-version":[{"id":85083,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/84917\/revisions\/85083"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=84917"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=84917"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=84917"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=84917"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}