Overview

This article describes how to data to Dundas Gauge for Reporting Services™. All data is provided to the control by SQL Server, which uses data sets that you define using the Data tab of the Visual Studio designer shown in Figure 1 below.

 

Figure 1: The Data Tab of Visual Studio designer.

 

When a column of data is specified as a pointer value for the control, and no grouping is used, then SQL Server will only use the first value in the specified data set. Therefore, the pointer value will only show the first value in the data set. However, when grouping is used to group all of the values using a specified column, then those values will be made available to the control as a set, with the last value being held as the "current" value. This gives you the option to use an aggregating formula on your data, and use the end value of that calculation as a pointer or indicator value.

This is an important concept to grasp: grouping on a column allows for aggregating formulas to be used when specifying a value for the Gauge, and as a result duplicated values are then aggregated according to the formula used.

The concept of grouping is best illustrated by an example. Let's assume that we have the following raw data set shown in Figure 2 below, and that this data set was defined in the Data tab of the designer so that all of the columns can be used by the Gauge control. Notice in the data set that there are two values provided for the 3 second time interval. Namely, the first value for 3 seconds is 2, and the second value for 3 seconds is 5.

 

Time (seconds)	Value
0	0
1	5
2	7
3	2
3	5
4	7
5	9

Figure 2: Raw data in the dataset showing two values for the 3 second interval.

 

If we use the Value column for Gauge values, but do not group on the Time column, then only the first value (in this case 9) will be made available to the control. However, if we group using the Time column, then all Value column values will be made available to the control as shown in Figure 3 below.

 

Time (seconds)	Value
0	0
1	5
2	7
3	3.5
4	7
5	9

Figure 3: Data provided to Gauge control by SQL Server when grouping on the Time column.

 

Multiple values for the grouped column can then be aggregated using an aggregator formula when specifying values for a gauge element. For example, if we group on the Time column, and set the value of a pointer to "=AVE(Fields!Value.Value)", then the two values at 3 seconds will be aggregated, and have an averaged value of 3.5 (see Figure 3 above).

Now the questions arises: Why is it important to make all column values available to the Gauge control, when only one value can be plotted? The answer is that when statistical formulas are used, they only have an effect if applied to multiple values.

 

Gauge Elements that Use Data

The following are gauge elements that use data (i.e. display a value):

• All pointers (e.g. needle, bar and marker styles).
• State indicators.
• Numeric indicators.

 

For a pictorial listing of all gauge elements see the Main Elements of Dundas Gauge topic.

 

How to Specify Data

There are several ways to specify your data: (listed in order of increasing complexity):

• Use the Data Tab of the Gauge Wizard when creating your Main
  Gauge element. Specify a dataset and also an expression for the control's pointers, state and numeric indicator values. Note that this tab will let you set the value of all gauge elements in the control that take a value.
• If the main gauge is an indicator then use the General Tab of the Gauge Designer to specify their values.
• It the main gauge is a circular or linear gauge use the Pointers Tab to set the values of their pointers.

• Use the Report Designer and drag and drop a data field from the Datasets window onto the Value Fields landing zone (see figure 1 below). Note that these drop zones will already be populated with fields if set using a dialog.

   

  

  Figure 4: Drop zones of the Gauge control.

   

  There can only be one data field specified per instance of the control.

   

• Use the Code Editor and write script that either sets a Value property or a ValueSource property (this can be set to a CalculatedValue, used to represent the results of an applied formula).

 

Working with Data using Script

Scripting in the Code Editor to handle Gauge related events lets you access the Gauge control's data just before it is rendered.

Overview of Data and the API

The Gauge control stores input values in its Values collection, and these input values are then used as a value source for gauge elements that have a value (e.g. pointers and indicators).

Input values, represented by the InputValue class, can be used as the value for a gauge element by setting the element's ValueSource property to the name of an existing input value.

An InputValue object can itself be set:

• By setting the InputValue.Value property, in which case a history of values is automatically created for this input value. A DateTime stamp with a value of Now is also added to that record in the history.
• By setting the InputValue object's value using the SetValue method, which optionally allows for the explicit setting of the DateTime stamp.

Each input value also has a CalculatedValues collection property, which stores CalculatedValue-derived objects that represent the results of an applied formula.

These calculated values can be assigned as a gauge element's value and then displayed to end-users. For further information see the Data Analysis and Formulas topic.

Accessing Data using Script

If multiple data values are being used (for scales, pointers, or indicators), then there will be multiple input values in the control's Values collection, and getting a reference to a particular input value that is being used as a value source for a pointer, indicator, etc. can be confusing using a 0-based collection index (e.g. control.Values[0]).

Each InputValue object in the Values collection has a qualified name that is the name of the element the value is for, and you can obtain the name of a gauge element by calling the GetElementName method (this method is built into the Code Editor, and can be called without any qualification).

The syntax is 'GetElementName(object gaugeObject) : returns string'.

Example

This example demonstrates how to retrieve the current value and the history values of the first pointer in a circular gauge. We retrieve the value by name and by index, and also retrieve the entire history for that pointer.

[Visual Basic]

' We assume the first input value is for the pointer.
Dim lastValue As Double = gaugeContainer.Values(0).Value

' A better way to do this is to retrieve the input value by name. To do this
' we must get the name of the pointer.
Dim objectName As String = GetElementName(gaugeContainer.CircularGauges(0).Pointers(0))

' Now get the current value of the pointer from the container's Values collection.
lastValue = gaugeContainer.Values(objectName).Value

' To retrieve the entire data history for that pointer use the GetData method.
Dim table As System.Data.DataTable = gaugeContainer.Values(objectName).GetData()

' We will simply append the string value of the first pointer's value to a label.
lastValue = gaugeContainer.CircularGauges(0).Pointers(0).Value
gaugeContainer.Labels(0).Text += lastValue.ToString()

 

[C#]

// We assume the first input value is for the pointer.
double lastValue = gaugeContainer.Values[0].Value;

// A better way to do this is to retrieve the input value by name. To do this
// we must get the name of the pointer.
string objectName = GetElementName(gaugeContainer.CircularGauges[0].Pointers[0]);

// Now get the current value of the pointer from the container's Values collection.
lastValue = gaugeContainer.Values[objectName].Value;

// To retrieve the entire data history for that pointer use the GetData method.
System.Data.DataTable table = gaugeContainer.Values[objectName].GetData();

// We will simply append the string value of the first pointer's value to a label.
lastValue = gaugeContainer.CircularGauges[0].Pointers[0].Value;
gaugeContainer.Labels[0].Text += lastValue.ToString();

See Also

 

 

---

Copyright © 2005 - 2008, Dundas Data Visualization, Inc. and others.