Advanced Prompting

32
- Proven Practice Advanced Prompting and Prompt Performance Tuning Product(s): IBM Cognos 8.2 BI Area of Interest: Report Design

Transcript of Advanced Prompting

Page 1: Advanced Prompting

-

Proven Practice

Advanced Prompting and Prompt Performance Tuning

Product(s): IBM Cognos 8.2 BI

Area of Interest: Report Design

Page 2: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 2

IBM Cognos Proprietary Information

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 [email protected] .

Page 3: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 3

IBM Cognos Proprietary Information

Contents

1 INTRODUCTION ............................................................................................ 4

1.1 PURPOSE ............................................................................................................4 1.2 APPLICABILITY .....................................................................................................4

2 FIRST PROMPT PAGE PERFORMANCE .......................................................... 4

3 PROMPT RECONCILIATION .......................................................................... 4

3.1 WHAT IS PROMPT RECONCILIATION? ..........................................................................4 3.1.1 Filter Expressions...............................................................................................4 3.1.2 Data Item Expressions .......................................................................................5 3.1.3 Macro Expressions .............................................................................................6 3.2 HOW DOES PROMPT RECONCILIATION AFFECT PERFORMANCE? ...........................................6 3.3 HOW DOES PROMPT RECONCILIATION CHANGE IN COGNOS 8.2? .........................................6 3.4 FASTER PROMPT RECONCILIATION IN COGNOS 8.2..........................................................7 3.5 REPORT SERVER PROPERTIES FOR TUNING PROMPT RECONCILIATION ...................................7 3.5.1 What’s The Best Default Setting?.........................................................................9 3.6 QUERY PROPERTIES FOR PROMPT RECONCILIATION TUNING...............................................9 3.6.1 The Same Parameters are Used in Many Query Filters ......................................... 10 3.6.2 Different Parameters are Used in Each Query Filter ............................................. 10 3.6.3 Giving Bad Hints.............................................................................................. 11 3.7 SAP CONSIDERATIONS ......................................................................................... 11

4 PROMPT QUERY PERFORMANCE ................................................................ 11

4.1 THE NUMBER OF QUERIES ..................................................................................... 11 4.2 PROPER PROMPT CONTROLS................................................................................... 12 4.3 CACHE PROMPT QUERIES ...................................................................................... 12 4.4 RUN PROMPT QUERIES CONCURRENTLY ..................................................................... 13

5 SUMMARY ................................................................................................... 14

6 APPENDIX A – TABBED PROMPT PAGE....................................................... 15

6.1 FASTER TABBED PROMPT PAGES .............................................................................. 15 6.2 SOLUTION OVERVIEW........................................................................................... 15 6.3 APPLICABILITY ................................................................................................... 16 6.4 UNDOCUMENTED AND UNSUPPORTED CAPABILITIES USED................................................ 17 6.5 TABBED PROMPT REPORT WORKSHOP ....................................................................... 17 6.5.1 Create the Basic Report.................................................................................... 17 6.5.2 Create the Basic Prompt Page ........................................................................... 18 6.5.3 Create the Tab Body ........................................................................................ 19 6.5.4 Create the Tabs............................................................................................... 20 6.5.5 Style the Tabs ................................................................................................. 23 6.5.6 Cognos 8 Button Styling ................................................................................... 24 6.5.7 ReportNet Button Styling .................................................................................. 25 6.5.8 Run the report ................................................................................................ 25 6.5.9 Show Active and Inactive Tabs.......................................................................... 25 6.5.10 Format the Tab Body ...................................................................................29 6.5.11 Format the Page and Add Text ...................................................................... 31 6.6 CONCLUSION ..................................................................................................... 32

Page 4: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 4

IBM Cognos Proprietary Information

1 Introduction

1.1 Purpose

This document tells report authors how to deal with slow first prompt page performance issues.

1.2 Applicability

This information applies to IBM Cognos 8.2 BI only.

2 First Prompt Page Performance

Reports with many complex queries often see an undue delay when the user runs the report before the first prompt page displays. For example, in one customer scenario a report took about 40 seconds to display the first prompt

page.

We can look at two areas to improve this performance:

1. Reduce the time for prompt reconciliation

2. Reduce the time to retrieve the data for the prompt controls

3 Prompt Reconciliation

3.1 What is Prompt Reconciliation?

Prompt reconciliation ensures the parameter definition matches the

parameter usage. Parameters are defined in filters and calculations. The resulting parameters are used in prompts.

A parameter definition contains several key items

� Cardinality – The number of input values that can be supplied to the

parameter

� Discreteness – Whether an input value defines a single value or a value range

� Optionality – Whether a parameter is required or optional in the context of the filter or calculation.

� Data type – The required data type that is expected in the context of the filter or calculation to match other referenced data items or

constants. These types can be one of Numeric, Date, Time, Date Time, Interval, String, or Member Unique Name (MUN).

3.1.1 Filter Expressions

Consider an optional filter

[Order number] = ?pOrderNumber?

Page 5: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 5

IBM Cognos Proprietary Information

By examining this filter we can determine some characteristics about the parameter pOrderNumber:

Cardinality: Single value

� The equal sign indicates that only a single value can be used

� Multiple values require an appropriate operator such as “in”:

[Order number] in ?pOrderNumber?

Discreteness: Simple value

� As indicated by the equal sign.

� A range of values would require an appropriate operator such as “in_range”:

[Order number] in_range ?pOrderNumber?

o If a parameter is used in multiple contexts then all references must be range values for the parameter to be a range value.

Optionality: Optional

� The filter is defined as optional so the parameter would also be optional

� The parameter may also be mandatory. If a parameter is used in multiple contexts then all references must be optional for the parameter to be optional.

Data type: Numeric

� The parameter is numeric because the Order number data item is numeric.

The characteristics of the parameter are now applied to prompts that reference the parameter. This means that a prompt control will take on the more restrictive characteristics of the parameter to make the prompt control

compatible with the parameter definition. If the parameters are referenced in an authored prompt page, the prompt definition is modified at run time to match the parameter Cardinality, Optionality and Discreteness. A data type

mismatch may result in a run-time error. If there is no authored prompt page, then these characteristics are applied to prompts on a generated prompt page.

3.1.2 Data Item Expressions

Parameters used in data item expressions, other than those defined via macro expressions are considered mandatory.

Page 6: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 6

IBM Cognos Proprietary Information

3.1.3 Macro Expressions

Parameters defined in macro expressions1 can be optional or required, single or multi-valued.

Consider the macro expression

#prompt (‘pOrderNumber’, ‘integer’)#

Cardinality: Single value

� The prompt() macro function only accepts a single input value

� Multiple values can be defined with promptmany():

#promptmany (‘pOrderNumber’, ‘integer’)#

Discreteness: Simple value

� Prompt macros are always simple values rather than ranges

Optionality: Required

� As indicated by the absence of a default value (the third optional argument to this macro function)

� A example with an optional parameter would appear as so:

#prompt (‘pOrderNumber’, ‘integer’, ‘5’)#

3.2 How does Prompt Reconciliation Affect Performance?

In order to perform prompt reconciliation, IBM Cognos 8 examines the queries to determine which parameters exist and their characteristics. The larger and more complex the queries, the longer this process can take.

A customer report2 in IBM Cognos 8.1 with over 200 queries has been noted to require over 40 seconds to show the first prompt page. Most of this time was spent on prompt reconciliation.

3.3 How does Prompt Reconciliation Change in Cognos 8.2?

Prompt reconciliation changes in IBM Cognos 8.2 in three ways:

� Faster Prompt Reconciliation

� Report Server Properties for Tuning Prompt Reconciliation

� Query Properties for Prompt Reconciliation Tuning

1 For full details on macro functions and macro function syntax refer to either the Framework Manager User Guide or the Report Studio User Guide provided with your Cognos 8

installation. 2 Due to confidentiality concerns with proprietary data we cannot show this report but this

use case is real based on an actual customer report.

Page 7: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 7

IBM Cognos Proprietary Information

3.4 Faster Prompt Reconciliation in IBM Cognos 8.2

First, in IBM Cognos 8.2 the code prompt reconciliation process has been tuned to run much faster. One would expect this process to take 75% to 90% less time than in IBM Cognos 8.1.

For example, prompt reconciliation of our customer sample report takes 5 seconds in IBM Cognos 8.2 compared to more than 40 seconds in IBM

Cognos 8.1 a reduction of 80%.

This 80% performance advantage is realized by simply moving to IBM Cognos 8.2. No additional action was required.

3.5 Report Server Properties for Tuning Prompt Reconciliation

IBM Cognos 8.2 provides 3 interrelated options to tune the prompt reconciliation both for the entire system and for an individual report.

The first option is a report server advanced property3 that is enabled for an entire report server: RSVP.PROMPT.RECONCILIATION. This property has

several values:

COMPLETE - All queries are reconciled before the first prompt page is

displayed. This is the default setting to ensure compatibility with previous releases4.

CHUNKED - All queries are reconciled in sets until parameters required for first prompt page are reconciled. The queries are processed with no fixed

order. You can change the CHUNK size with the RSVP.PROMPT.RECONCILIATION.CHUNKSIZE advanced server property. The default is chunk size is 5 queries.

GROUPED - Queries are reconciled in groups until parameters required for first prompt page are reconciled. The groups are as follows:

� Filtered report queries

� Filtered prompt queries5

� Unfiltered report queries

� Unfiltered prompt queries

3 Please refer to the Administration and Security Guide for details on setting advanced server

properties. 4 None of these settings is likely to introduce upgrade/compatibility issues so this is really

erring on the safe side only. 5 A prompt query is a query used to provide the values that appear in an authored prompt

control such as a picklist.

Page 8: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 8

IBM Cognos Proprietary Information

Queries are processed in order by these groups until all of the parameters referenced on the first prompt page are reconciled. It is often the case that only the first group or first two groups need be processed. In some cases,

however, all queries will need to be processed. This could happen if a parameter were referenced in a calculated query item in a prompt query for example. Once the report server has reconciled the parameters for the first

prompt page, the page will be displayed to the user. Prior to display of subsequent prompt pages the report server may need to reconcile more queries if those prompt pages refer to parameters that were not in the

queries already processed.

CHUNKED GROUPED - Queries are reconciled by evaluating the query groups in chunks6 until parameters required for first prompt page are reconciled.

Our customer scenario contained only one filtered query but imagine that all 200 queries in our report are filtered using the same parameters. GROUPED will reconcile all 200 queries at once because all 200 queries would be part of

the same filtered report query group. CHUNKED reconciles x number of queries at a time where x is the CHUNK size (defaults to 5). Thus with CHUNKED GROUPED, 5 queries will be reconciled. If the parameters required

for the first prompt page are found then the page is displayed. If not, the next 5 queries are processed and so on until the parameters are found.

Using our customer report as an example, setting RSVP.PROMPT.RECONCILIATION = GROUPED focuses prompt reconciliation

on the queries which contain filters first (of which we only have one query).

This results in prompt reconciliation of our customer sample report taking less

than 1 second in IBM Cognos 8.2 compared to more than 40 seconds in Cognos 8.1 a performance improvement of more than 98%.

This 98% performance advantage is realized by simply setting a single advanced server property7. No additional action was required.

Admittedly, this example is a little atypical as the ratio of filtered to unfiltered queries is higher than average. However, this illustrates the strength of the GROUPED reconciliation option as only a fraction of all the queries needs to be evaluated. Please see the section Query Properties for Prompt Reconciliation Tuning for dealing with very large numbers of filtered queries.

6 A ‘CHUNK’ is a set of queries. 7 In addition to the base reconciliation improvements obtained by upgrading from IBM

Cognos 8.1 to IBM Cognos 8.2.

Page 9: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 9

IBM Cognos Proprietary Information

3.5.1 What’s The Best Default Setting?

There is a slight risk of run-time errors if you use a setting other than COMPLETE as the same parameter may be defined different two or more times in the same report.

Imagine a report with an optional filter such as X in ?P1? and a calculation Y + ?P1?.

The filter defines P1 as optional and multi-valued.

The calculation defines P1 as mandatory and single valued.

Were COMPLETE query reconciliation used, all queries would be processed and the most restrictive definition would be used to modify the prompt appropriately, resulting in a mandatory single value prompt.

Were GROUPED used, only the filtered query would be processed allowing an optional multi-value prompt to be used8. Was the user to skip the prompt or

select multiple values there will be a run-time error when the calculation was processed.

Having said that, when using the advanced reconciliation properties it is the author’s responsibility to use the parameters appropriately and resolve these mismatched parameter definitions.

Using CHUNKED GROUPED it would also be possible to have two or more filters define the same parameter differently. Again, this would be an example of poor planning and implementation in report authoring.

CHUNKED GROUPED is the recommended setting for performance as it allows processing of partial query groups. However, it should be used in tandem with proper report testing to ensure that no run-time errors will occur due to

inconsistent parameter usage by the report author. The default chunk size of 5 is sufficient for most applications.

3.6 Query Properties for Prompt Reconciliation Tuning

Some reports may not be well served by the advanced report server properties and may require hand tuning to achieve the best performance. The report author can use a new Report Studio query property called Use for Parameter Info to determine how prompt reconciliation takes place. This new property is used in tandem with the report server advanced property RSVP.PROMPT.RECONCILIATION GROUPED and CHUNKED GROUPED options only.

8 Note that prompts are never modified to be less restrictive so if the prompt were authored

as single value mandatory it would NOT be changed at run time.

Page 10: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 10

IBM Cognos Proprietary Information

In essence, this property creates a new query processing group that is processed before filtered report queries. The new order would be:

� Use for Parameter Info = True queries

� Filtered report queries

� Filtered prompt queries9

� Unfiltered report queries

� Unfiltered prompt queries

If the required parameters are found in the first group, then no more queries will be processed. This can be useful in two scenarios.

3.6.1 The Same Parameters are Used in Many Query Filters

Going back to our report with 200 queries, if all 200 queries had filters referring to these same parameters then we’d have to process all 200 queries to reconcile the parameters. In fact, were we to process any single one of those queries we could collect the required information. The report author can select any query and set the query property Use for Parameter Info = True10. That one query will be processed. The required parameters will be found and the first prompt page will be displayed without having to process the remainder of the query group.

3.6.2 Different Parameters are Used in Each Query Filter

Consider a vastly different (and somewhat unrealistic) use case. We have 200 queries and each refers to a different parameter and all 200 parameters are referenced on the first prompt page. All queries would have to be processed resulting in slower performance (back to the 5 second performance).

The author could be very clever. That is, create a query which defines all 200 parameters. Do not create any layout reference to this new query (i.e. no list,

crosstab or chart uses this query). Set the query property Use for Parameter Info = True on this one query only. Now when this report is run only this one query is processed. As this query is not referenced in the layout, it will not

actually be executed. Thus is solves the first prompt page performance issue without incurring any additional overhead.

While an example with 200 queries, each with different parameters, is a bit extreme, this technique could also be used if processing a given query or set of queries caused a performance issue.

9 A prompt query is a query used to provide the values that appear in a prompt control such

as a picklist. 10 Being sure to also set the report server RSVP.PROMPT.RECONCILIATION GROUPED

property also.

Page 11: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 11

IBM Cognos Proprietary Information

It is anticipated that very few reports will require the use of the Use for Parameter Info query property as the general performance improvements of IBM Cognos 8.2 combined with the use of RSVP.PROMPT.RECONCILIATION

GROUPED will resolve most performance issues.

3.6.3 Giving Bad Hints

Be sure that the queries you select supply all required parameters. If you have set the ‘Use For Parameter Info’ query hint on a set of queries that do

not define ALL of the parameters, there will be a negative performance impact since a separate request will be required to obtain parameter characteristics on those parameters that were not resolved in the first request.

3.7 SAP Considerations

In SAP environments where there are non-hierarchical data source variables, the number of variables along with the number of possible values for these

variables could have a significant negative impact.

It is recommended that the advanced server property not be used in these

environments; however, the use of the ‘Use For parameter Info’ query hint could offer performance benefits.

4 Prompt Query Performance

Prompt queries are used to populate the prompt controls. The prompt page cannot be displayed until the prompt queries have been run. By default,

these queries are run one at a time each time the prompt page is displayed to a user.

There are three areas of interest when trying to improve prompt query performance:

1. The number of queries

2. Avoiding re-running prompt queries

3. Running prompt queries concurrently

4.1 The Number of Queries

The larger the number of queries the longer it takes to process the prompt

page. While the mechanisms discussed below will reduce the time required, sometimes it will be a case of having just too much included on the initial prompt page that requires processing before the prompt page is displayed.

You might split the prompt across two or more page. This allows each prompt page to be displayed with a smaller number of queries.

You might use a tabbed prompt page. As we only run queries for prompt controls that actually appear to the user, prompt queries for inactive tabs are

not run. Appendix A shows how to create a tabbed prompt interface.

Page 12: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 12

IBM Cognos Proprietary Information

You might use prompts that are hidden in conditional blocks and only appear when the user has responded to some prompt(s) and is then re-prompted. Again, as we only run queries for prompt controls that actually appear to the user, prompt queries for hidden blocks are not run.

4.2 Proper Prompt Controls

Some prompt controls are not well suited to large volumes of data. For example, a value prompt (picklist) with 100,000 entries will both be slow and unusable. Better options for such volumes are Select & search prompts,

Cascading prompts, or Tree prompts as they do not load the entire data set to display the initial prompt control.

Note that if an author insists on using prompts with very large volumes of data then, by default, the data will be truncated without warning at 5000

rows. The Rows Per Page property of the prompt controls can be used to see a larger set of data.

4.3 Cache Prompt Queries

With IBM Cognos 8.1 it is now possible to cache prompt queries. This is

useful where the values in the prompt do not change often - perhaps every day rather than in real-time- and the prompt is not dependant on the value of another prompt to filter the prompt query. For example, we can cache the

values for a parent cascading prompt but not the (grand)child as the subsequent prompts are dependent on executing a query with the parent prompt value(s).

You would use a Job to execute the prompt queries and cache the values for a report. The Job would be created with an appropriate schedule – daily or weekly perhaps – to reflect the volatility of the prompt values. After adding the reports to the job for which to refresh the prompt queries, the Default

Run option would be set to Run the report to Refresh the Report Cache (or, alternatively, this can be set for each report step).

When the job runs it will execute the prompt queries only and cache the results in the Content Store. If you have prompts in multiple locales, set those locales in the job step and prompt values for all locales will be cached.

When the user runs the report the cached query values will be fetched; generally resulting in faster performance.

Note that regardless of performance considerations this is also a great way to

reduce the number of queries hitting your database as the prompt queries no longer need to be executed for each user request to run the report.

Page 13: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 13

IBM Cognos Proprietary Information

4.4 Run Prompt Queries Concurrently

If your prompt values are highly dynamic and caching is not a good option for you then it is possible to run multiple prompt queries concurrently.

By default all queries within a single report are run one by one. It is possible to run either prompt or data queries concurrently.

The report server uses the concept of helpers to manage how many queries can be executed concurrently within the report server. Setting this to 10 for example means that an additional 10 queries11 may be executed concurrently for the entire report server instance.

The report server advanced property RSVP.CONCURRENTQUERY. NUMHELPERSPERPROCESS is used to set the number of helpers available within the server. The default is zero. If this is not set then no concurrent queries may be run.

You must also configure how many helpers are available to each report using

the report server advanced property RSVP.CONCURRENTQUERY. MAXNUMHELPERSPERREPORT. The default is one which allows any report to execute 1 query at a time – i.e. you must set this to at least 2 to allow

parallel queries to run.

Once these two options are set, by default concurrent queries are only run for batch executions. This is because in interactive executions, it is possible for a query to be run but never be seen by the user and thus consume unnecessary resources. Imagine a report with two pages, each with a list. The user runs the report – concurrent query is enabled so both list queries are run. The user looks at the first page/list and closes the browser. The

second query would have been run concurrently but never used thus wasting resources. We’ll see how to better manage this in a moment.

To allow concurrent queries for interactive executions, set the report server advanced property RSVP.CONCURRENTQUERY.ENABLEDFORINTERACTIVEOUTPUT to True.

11 Remember that the report server can execute several reports at a time resulting in as many queries as the combined number of concurrent reports and concurrent queries within

the reports.

Page 14: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 14

IBM Cognos Proprietary Information

Within a given report, you must also determine which queries can be run concurrently using the query property Execution Method:

Setting this on the prompt queries allows them to run concurrently often resulting in better performance.

5 Summary

IBM Cognos 8.2 provides vastly improved first prompt page performance out of the box with no custom configuration.

You can further improve prompt performance via:

� Prompt reconciliation

� Clever prompt page design

� Prompt query caching

� Concurrent query execution

It is recommended that RSVP.PROMPT.RECONCILIATION CHUNKED GROUPED (with proper report testing) be set on all IBM Cognos 8.2 servers

to further improve prompt performance.

Page 15: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 15

IBM Cognos Proprietary Information

6 Appendix A – Tabbed Prompt Page

Note: this material first appeared as a separate Proven Practices document.

The content is the same here as in the original document.

6.1 Faster Tabbed Prompt Pages

The scenario here is that a customer would like to deliver a report to their end-users with a tabbed style user interface in the prompt page rather than a

series of prompt pages. The most-often used prompts would appear in the first tab with each tab presenting successively less used prompts.

Examples of applications we have seen have as many as 60 prompts across 6 to 8 tabs. There are 2 issues which drive performance in these reports. First, the sheer number of prompts means that Cognos 8 must analyze many queries before the report is run. Generally this means 1 query per prompt plus the report queries themselves. This can only be addressed by using fewer queries in a given report which is beyond the scope of this document. Secondly, the nature of the HTML/JavaScript techniques we have seen used result in very poor performance12. The standard technique is to create

HTML/JavaScript that generates the tabs allowing the user to switch tabs without hitting the server. This means that all prompts (as many as 60) must be populated prior to the first tab being displayed. As queries are run sequentially by default, the more prompt queries that are required the longer the user waits.

6.2 Solution Overview

This solution uses conditional blocks to show prompts. The tabs themselves are still created using HTML and JavaScript. The advantage to using conditional blocks is we understand that the prompts on hidden blocks are not visible and therefore we will not run the queries required to populate them. If the user changes tabs, the prompts become visible and the associated queries are run. The disadvantage is that we require a request to the server to change tabs.

12 Also, depending on the technique and the web browser interpretation of windowed objects, the use of layering and html select objects would result in value prompts showing through

from lower layers.

Page 16: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 16

IBM Cognos Proprietary Information

The prompt page to accomplish this technique uses conditional blocks to determine which prompts to show. Think of a series of overlapping rectangles only one of which will be shown at a time.

Unlike the blocks, only one of which is visible at any time, all of the tabs are always visible. The borders of the ‘current’ tab and the text color are set

black to make it appear to be in front of the other tabs. The non-current tabs use grey to make them less prominent.

At one level the report authoring is reasonable straight forward. We will create a conditional block with as many blocks as tabs – 4 in the case above. We will create the basic tab structure (the rectangles) as cells in a table, setting the border as required. The text that appears in the tabs is created as HTML items with some simple JavaScript.

When the user clicks on a tab (actually, on the text in the tab), the associated conditional block is displayed and the tab border and text color are changed

and the associated block is displayed.

Behind the scenes, a parameter value is set to identify which tab is to be

displayed and the report is re-prompted. Ideally, we’d use a prompt control or prompt button to set the parameter value and re-prompt. But, there is neither a prompt control nor button that meets the bill. A prompt can both

set the parameter value and re-prompt (via auto-submit) but cannot look like a piece of text.

6.3 Applicability

The technique should work with any release of ReportNet or IBM Cognos 8.

Page 17: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 17

IBM Cognos Proprietary Information

6.4 Undocumented and Unsupported Capabilities Used

As discussed in detail below, this solution requires the use of two undocumented and unsupported capabilities in IBM Cognos 8. Therefore, there is a risk associated with this solution in the support for these two capabilities may change or be dropped entirely in some future release requiring a rework of this technique. However, that risk is low as no changes are planned in these areas at this time.

6.5 Tabbed Prompt Report Workshop

In our scenario, the first tab will allow the user to select an Order year(s) and

the second tab will allow the user to select a Product name(s) to run a very simple list report.

We will walk through creating a sample report from beginning to end. To keep things simple, we will use only two tabs with one prompt each.

6.5.1 Create the Basic Report

Open Report Studio with the GO Sales and Retailers package.

Create a new list report:

� \Orders\Order year

� \Orders\Product name

� \Orders\Revenue

As so13:

Create two optional detail filters:

� [Order year] in ?p_OrderYear?

� [Product name] in ?p_ProductName?

That’s it. That’s the basic report we will use to demo this technique.

13 You may see minor differences in colours, fonts and styles between ReportNet and IBM

Cognos 8.

Page 18: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 18

IBM Cognos Proprietary Information

6.5.2 Create the Basic Prompt Page

While the steps to create the tabbed prompt user interface are not difficult, they are long. Most of our time will be spent on formatting. The actual functionality takes little time.

First, we need a prompt page.

Add a prompt page to the report:

Drop a 1 row by 2 column table onto the prompt page body as so:

We’re going to ignore the table for a while but we will come back and use it a bit later.

Page 19: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 19

IBM Cognos Proprietary Information

6.5.3 Create the Tab Body

The conditional blocks will eventually hold the prompts that appear on each tab.

We will start by creating the basic tab body structure and using some text items to allow us to see which tab is current at a given time.

Drop a Conditional Block14 object onto the page body:

Select the conditional block object and then the Block Variable property.

Create a <New String Variable> as so:

� Name: TabToShow

� Values: Tab2

� Expression: ParamValue('pTabToShow')

The name of the Variable TabToShow, the value Tab2 and the parameter pTabToShow are critical as we will refer to them several times later in this

workshop.

With the block selected, set the Current Block property to Other.

14 In ReportNet 1.x, this object has the name Conditional Block List. It is the same object with

a different name.

Page 20: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 20

IBM Cognos Proprietary Information

Drop a text item ‘Tab 1’ into the block as so:

This text will serve to remind us which tab we are currently viewing.

Select the block and set the Current Block property to Tab2.

The ‘Tab 1’ text item will seem to disappear from the block.

Drop a text item ‘Tab 2’ into the block as so:

Again, this text will serve to remind us which tab we are currently viewing.

By selecting the block and alternating the Current Block property value between Other and Tab2, you should be able to switch tabs in Report Studio.

6.5.4 Create the Tabs

As I said previously, we will use HTML items with some undocumented and

unsupported tricks to make the tabs work.

The first thing we will do it to take advantage of how the Report Viewer

communicates parameter values to the server. Parameter values are passed as form variables15 with the name being the parameter name, such as pTabToShow, prefixed with p_ like p_pTabToShow.

15 Or using a URL, but we can’t use that approach here.

Page 21: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 21

IBM Cognos Proprietary Information

This parameter passing mechanism is undocumented and unsupported. Please see the provisos at the beginning of this document.

We will use an HTML object to create this form variable.

Drop an HTML item into the Page Header as so:

The location of this item is not critical as it will not appear to the user.

Select the HTML item and set the HTML property to:

<input type="hidden" name="p_pTabToShow" value="Tab1"/>

This is small bit of HTML creates a form variable called p_pTabToShow and sets the value to Tab1.

This form variable will trick the server into thinking that a parameter called pTabToShow has been defined in the report so the server will preserve the

value and pass it back to the Report Viewer when the report is reprompted.

Now, back to that table we added earlier in this workshop.

While it does not appear as such now, the two cells in this table will become

the tabs the user can click on.

The text items that appear on the tabs will be HTML items.

Page 22: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 22

IBM Cognos Proprietary Information

Drop an HTML item in the each table cell and center them in the cells:

Select the left HTML item and set the HTML property to:

<button title="Show Tab 1"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab1';SetPromptControl('reprompt')">Show Tab 1</button>

This JavaScript creates a button as so:

� Button title (tooltip text) – Show Tab 1

� Actions

o set the form variable called ‘p_pTabToShow’ to Tab1

o Run the function ‘reprompt’

� Button label – Show Tab 1

In other words, when the user presses this button it will set the form variable and reprompt the report.

Note that the reprompt function is undocumented and unsupported. Please see the provisos at the beginning of this document.

Select the right HTML item and set the HTML property to:

<button title="Show Tab 2"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab2';SetPromptControl('reprompt')">Show Tab 2</button>

Run the report16:

16 The appearance of the buttons may change between browsers and releases.

Page 23: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 23

IBM Cognos Proprietary Information

By clicking the buttons you can switch between ‘tabs’ as the text will show.

The core tab functionality is now complete. All that remains to be done is

cosmetics – the user interface may be working but it certainly does not look like a tabbed user interface – and placing our prompts onto the tabs.

Return to Report Studio.

6.5.5 Style the Tabs

We will use borders, alignment and other styling to change the appearance of the HTML buttons and block to look like tabs.

First, we will work with the HTML buttons.

Select the parent table and in the Table Properties property, select Fixed Size.

With the table still selected, select the Size and Overflow property and delete the current width setting.

Select each table cell and set the widths to 100 pixel (px) each.

In your real report, you’ll have to vary the width to match the text you put in

each tab. Remember that all tabs are usually the same width to make the tabs more aesthetically pleasing.

We now have the table cells and HTML buttons appearing a bit more tab-like as so:

Now, we need to re-style the HTML buttons so they show only the text.

Page 24: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 24

IBM Cognos Proprietary Information

Select one of the HTML objects and you’ll see there are no style properties:

With IBM Cognos 8 we can define styles in our report and apply them to

report objects. Likewise, we can also apply these styles to HTML objects.

6.5.6 IBM Cognos 8 Button Styling

In IBM Cognos 8 we can define a class and then reference in the HTML button definition.

Using the Page Explorer, open Classes.

Drop a Class object from the toolbox into the Local Classes area.

Select the new class object and set the properties as so:

� Name: HTMLButtons

� Border: None

� Box Type: Block

� Background Color: White

� Class or Selector: HB

Return to the prompt page.

The Class/Selector property is the identifier we will use when we apply a style to the HTML items.

Select the left HTML object for Tab 1 and change the HTML property to:

<button title="Show Tab 1"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab1';SetPromptControl('reprompt')" class="HB"Show Tab 1</button>

Page 25: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 25

IBM Cognos Proprietary Information

Select the right HTML object for Tab 2 and change the HTML property to:

<button title="Show Tab 2"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab2';SetPromptControl('reprompt')" class="HB">Show Tab 2</button>

6.5.7 ReportNet Button Styling

This approach can be used in either ReportNet or IBM Cognos 8.

We will apply the style in the HTML button definition directly by using the HTML style property rather than referencing a common style definition defined at the report level.

Select the left HTML object and change the HTML property to:

<button title="Show Tab 1"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab1';SetPromptControl('reprompt')" style="border-top-

style:none;border-left-style:none;border-right-style:none;border-

bottom-style:none;display:block;background-color:white">Show Tab

1</button>

Select the right HTML object and change the HTML property to:

<button title="Show Tab 2"

onclick="document.formWarpRequest.elements['p_pTabToShow'].value='

Tab2';SetPromptControl('reprompt')" style="border-top-

style:none;border-left-style:none;border-right-style:none;border-

bottom-style:none;display:block;background-color:white">Show Tab

2</button>

6.5.8 Run the report

Run the report. The button-like appearance of the buttons has been removed to leave only the text.

6.5.9 Show Active and Inactive Tabs

We now need to style the tabs to show which is active. The active tab will have black borders and text. The inactive tab will have grey borders and text.

Select the left table cell.

Set the Style Variable to TabToShow.

Page 26: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 26

IBM Cognos Proprietary Information

Using the Variable Explorer, select TabToShow to Other:

With the left table cell still selected, set the Border to Black, Solid Line, 1.5 point (pt) on the Left, Top and Right sides:

Using the Variable Explorer, select TabToShow to Tab2:

With the left table cell still selected, set the Border to Silver, Solid line, 1.5 point (pt) on the Left, Top and Right sides:

Page 27: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 27

IBM Cognos Proprietary Information

Run the report:

Click on Show Tab 2 so that Tab 1 becomes ‘not current’:

We will repeat a similar set of steps for Tab 2 (the right table cell).

Return to Report Studio.

Select the right table cell.

Set the Style Variable to TabToShow.

Using the Variable Explorer, select TabToShow to Other:

With the right table cell still selected, set the Border to Silver, Solid line, 1.5 point (pt) on the Left, Top and Right sides:

Using the Variable Explorer, select TabToShow to Tab2:

Page 28: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 28

IBM Cognos Proprietary Information

With the right table cell still selected, set the Border to Black, Solid Line, 1.5 point (pt) on the Left, Top and Right sides:

Run the report:

Click on Show Tab 2:

The border between the two table cells is grey but we set it to black for the right table cell. Actually, we set it to both grey and black. Each table cell actually has it’s own borders but by default they are collapsed.

That is, rather than seeing the borders side-by-side as so:

The borders are overlapped. When the borders overlap, there are rules to determine which border gets displayed (takes precedence). In this case, the

left cell border appears.

What we need to do it to adjust the borders so that the left table cell has no

border when the right cell is active.

Return to Report Studio.

Select the left table cell.

Using the Variable Explorer, select TabToShow to Tab2:

Page 29: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 29

IBM Cognos Proprietary Information

Remove the border from the right hand side of the cell:

Run the report:

Click on Tab 2:

We now have the appropriate border formatting to show the active and

inactive tabs.

6.5.10 Format the Tab Body

Now we need to tie the tabs and tab body together.

Return to Report Studio.

Using the Variable Explorer, select No variable:

Page 30: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 30

IBM Cognos Proprietary Information

Select the Block:

Set the Border to Black, Solid, 1.5 point (pt) on all 4 sides:

With the Block still selected, set the Current Block property to Tab2.

Set the borders the same Black, Solid, 1.5 point (pt) on all 4 sides:

Run the report:

The tabs are now in fully-formatted operation.

However, we would like to do some more formatting to tidy up the tab appearance a bit more.

First, we would like to move the tabs down the page and make the narrower.

Return to Report Studio.

Page 31: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 31

IBM Cognos Proprietary Information

6.5.11 Format the Page and Add Text

Select the Page Body object and set the Padding to 100 pixels (px) on the left, top and right.

This will provide a 100 pixel buffer on all sides of the tabs.

Lastly, we will provide some instructional text and actually put the report

prompts into the tabs.

Edit the title text to say ‘Revenue Report’:

Drop a block in as the last item in the page header:

Drop a text object into the block using ‘You may switch tabs to choose a different prompt.’:

Select the Conditional block in the page body.

Set the Current Block property to Other.

We want the primary prompt (on tab 1) to be for Order year.

Page 32: Advanced Prompting

Advanced Prompting and Prompt Performance Tuning 32

IBM Cognos Proprietary Information

Drop a Value Prompt object into the block:

� Use the existing parameter: p_OrderYear

� Create a new query with Order year (the default option)

Select the prompt and set the Required property to No (if it is not already defined as such).

Select the Conditional block and set the Current Block property to Tab2.

We want the secondary prompt (on tab 2) to be for Product name.

Drop a Value Prompt object into the block:

� Use the existing parameter: p_ProductName

� Create a new query with Product name (the default option)

Select the prompt and set the Required property to No (if it is not already defined as such).

Run the report.

As the filters are optional, you can select from either prompt, both or neither.

6.6 Conclusion

This is a handy technique. While it does use some undocumented and unsupported capabilities of the product, it also provides high value to the end-users.

Of course, you can use this technique as required with more tabs, different prompts, text, and many other objects and controls to satisfy the user preferences for their prompting interface experience.