Tip or Technique

Using the AT and FOR Options with Relational Summary Functions

Product(s): IBM Cognos 8 Area of Interest: Report Design

Using the AT and FOR Options with Relational Summary Functions

Copyright Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to the information contained in this document will be documented in subsequent editions. This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos. Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries, or both. All other names are trademarks or registered trademarks of their respective companies. Information about Cognos products can be found at www.cognos.com This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com .

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

Contents
1 1.1 1.2 1.3 2 3 4 4.1 4.2 5 INTRODUCTION ............................................................................................ 4 PURPOSE ............................................................................................................4 APPLICABILITY .....................................................................................................4 EXCLUSIONS AND EXCEPTIONS ..................................................................................4 THE FOR CLAUSE........................................................................................... 4 THE AT CLAUSE ............................................................................................. 6 DISPLAYING A RUNNING-TOTAL IN A CROSSTAB ....................................... 8 LAYOUT AND DESIGN..............................................................................................8 FORMATTING ..................................................................................................... 10 CONCLUSION ................................................ERROR! BOOKMARK NOT DEFINED.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

1 Introduction
1.1 Purpose This document outlines the use of the AT clause in summary functions. An example is also provided with step by step instructions on how to create a cross tab report that displays the totals and running-total for a given measure. Applicability The following was built using IBM Cognos 8.1 MR2 Report Studio against the GO Sales and Retailers package. Exclusions and Exceptions This technique was built and tested against a relational database and has not been tested against an OLAP data source. For dimensional data sources and models the OLAP functions are often more applicable than the tabular/relational functions that leverage the AT clause. For example, the running-total can be replaced with a combination of the total() member summary function applied to a member set such as one produced by the periodsToDate() function.

1.2

1.3

2 The FOR clause

Tabular summary functions used for relational reporting have several optional arguments that can be used to define how the summary function is to be applied. One of the more common elements is the FOR clause. For example, the total function syntax is:
total ( [ distinct ] expr [ auto ] ) total ( [ distinct ] expr for [ all | any ] expr { , expr } ) total ( [ distinct ] expr for report )

The first form shows the auto operator applied within the total function. This operator is optional and is the default action if a FOR clause isnt used. This default behaviour will determine the level of aggregation from the current context of the data item to define how the values will be rolled up. So if the data item is placed in a footer or header then the lower level groupings or detail values will be rolled up and the total will be computed with only the higher level groupings. The for report option allows a fact data item to be rolled up over the entire data set. The effect is that the individual groups within the data are ignored and all the records are rolled up into a single summary value. The final syntax form allows you specify the data items that will be used when computing the aggregate. In essence it allows you to roll values up to a higher level of grouping and use that summarized value at lower levels in your report.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

The sample list report below will better illustrate the behaviour of the FOR clause. The report is grouped on Order year and Order month and displays Product line at the lowest level of detail. The Quantity column shows the default total aggregation of the data item from the model.

As we can see, the expression using the auto operator follows the same rollup rules as the model item and is rollup up according to the nested groupings in the report. The expression using for report displays the overall summary value as we would expect regardless of whether the data item is being used in a footer or at the lowest level of detail in the report. When we get to the for [Order year],[Order month] we begin to see some of the capabilities of the FOR clause. In this expression the Product line values are rolled up to the given grouping of Order year and Order month. This allows us to report the summary values within the context of the detail Product line records. This kind of operation is particularly useful when calculating some percent of base type expressions where the lower level values are compared to the value of a sub-total or grand total (although the percentage function can also be used in many cases).

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

Notice though that for the for [Order year], [Order month] calculation the summary footers for the Order year and overall summary are not the same as the overall summary in the prior calculations. At these footers the Order month (and also Order year for the overall summary) are not within the current scope. The result of the total function with this FOR clause is that many values are returned at these higher grouping levels and the first of the many values is displayed in the footer cell. The final calculation in the above report sets the FOR clause to for [Order month]. Here the Order year is not being included in our expression. The result is that the Quantity measure is rolled up for the Order month only and the Order year is not used to group the data. In the result set we have data for 2004, 2005, and 2006 and each year has months 1 through 12. The value that we see for month 1 above is the total Quantity from January 2004,January 2005, and January 2006 because the data is grouped by month only when the total is calculated. This type of calculation would allow us to break from the existing groupings in the report compare the monthly sales Quantity to the sales over all time (calculated using for [Product line]).

3 The AT clause
The AT clause plays a role in some of the more advanced summary functions such as rank or any of the running aggregates such as running-total. What the AT clause allows you to do is to specify that the measure used in the summary function should be rolled up before the function is applied. The list of columns specified in the AT clause defines what level of grouping should be used when rolling up the measure prior to calculation. For example, in the report below there are two calculations using the AT clause: [running-count AT], and [running-maximum AT]. These calculations use the following expressions:
running-count([Quantity] at [Order year], [Order month] for [Order year])

and
running-maximum([Quantity] at [Order year], [Order month] for [Order year])

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

The at [Order year], [Order month] specifies that the Quantity should be aggregated to the grouping of Order year and Order month before the running-count or running-maximum is calculated. The result of the running-count shows that the AT clause generates a smaller data set over which the running aggregates are applied. The running-count shows 1 for January 2004 because there is only one aggregated value for the year and month combination. Without the AT clause the running-count would be applied to the lowest level of detail and the summary value for January 2004 would be 4, the count of the Quantity values for each Product line. The running-maximum shows us some of the utility of the AT clause. The results show that instead of evaluating the running-maximum on the set of the lowest level Quantity values we are evaluating the maximum for the summarized Quantity at the month level instead of for each Product line.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

4 Displaying a running-total in a Crosstab

Here we will leverage the FOR and AT clauses to create a report similar to the one shown below, where the measure is displayed as a total for the nested dimension as well as a running total for the months of the report.

4.1

Layout and Design Open Report Studio using the GO Sales and Retailers sample package and create a new cross tab report using the following definition: Columns: [gosales_goretailers].[Orders].[Order month] Rows: [gosales_goretailers].[Orders].[Order year] Nested Rows: [gosales_goretailers].[Products].[Product line] Measure: [gosales_goretailers].[Orders].[Quantity] The result should look like the following:

Select [Product line] in the cross tab and select Total from the Aggregate drop down icon in the toolbar. This will create the first regular summary that will perform the simple total of the Quantity across all the individual Product lines.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions Repeat the process to create a second summary row for Product line1. This second entry will be used to generate the running-total aggregate.

Change the data item expression2 for the [Total(Product line)] field from
total(currentMeasure within detail [Product line])

to
running-total([Quantity] at [Order year], [Order month] for [Order year])

Here we have defined, using the AT clause, that the running total to should use the summarized Quantity values for the intersection of Order year and Order month. This means that the query will roll up the Product line values before computing the running-total. The FOR clause specifies that the running-total will be evaluated across the months within each individual year rather than across both years and months. Select [Order month] in the cross tab and select Total from the Aggregate drop down icon in the toolbar. This will define the overall summary column as below.

The report layout is now complete. The following section will walk through some of the formatting steps.

Rather than using the Aggregate button we could have also inserted a Calculation from the Insertable Objects panel. However, to obtain the same formatting we would have had to perform a few extra steps to apply the appropriate class properties to the crosstab member and the crosstab member fact cells for the new calculation. 2 Note that the running-total is a tabular/relational summary and as such cannot be used with OLAP style constructs such as currentMeasure.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions 4.2

10

Formatting Select the cell intersection of <#Total(Order month)#> and <#Total(Product line)#> and in the properties pane, change the Define Contents property to Yes. This allows us to override the cell and leave the intersection blank where the total of the running-total is not applicable.

With the report specification unlocked, select the <#Total(Order month)#> text item and change the Source Type property from Member Caption to Text and then change the Text property to read Total. Select the <#Total(Product line)1#> text item and change the Source Type property from Member Caption to Data Item Label and then change the Label property of the [Total(Product line)1] to be Total. The difference between the Text and Data Item Label settings is that Data Item Label can be reused wherever the data item is used in a report while a Text item stands alone and would need to be recreated if the same text is required elsewhere. For our purposes one method is as good as the other. Select the <#Total(Product line)#> text item and change the Source Type property from Member Caption to Text and then change the Text property to read Running Total.

5 Conclusion
The FOR and AT clauses come in very handy when calculating summary functions outside the current scope of a data item. The FOR clause allows us to specify what grouping context the summary function will be evaluated for and the AT clause allows us to define how the values will be grouped and aggregated before a summary function is applied.

IBM Cognos Proprietary Information

Using the AT and FOR Options with Relational Summary Functions

11

These options extend the tabular summary functions and allow for considerably more complex reports to be created from a relational model. For OLAP style reporting using dimensional models there are other features and functions available that are better suited to leveraging the hierarchical structure of a dimensional data source. Please refer to the additional materials available within the product documentation and within the collection of Proven Practice documents for additional details on these capabilities.

IBM Cognos Proprietary Information