Advanced Prompting

5/20/2018 Advanced Prompting

1/32

-

Proven Practice

Advanced Prompting and PromptPerformance Tuning

Product(s): IBM Cognos 8.2 BI

Area of Interest: Report Design


2/32

Advanced Prompting and Prompt Performance Tuning 2

IBM Cognos Proprietary Information

Copyright

Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULCis an IBM Company. While every attempt has been made to ensure that theinformation in this document is accurate and complete, some typographicalerrors or technical inaccuracies may exist. Cognos does not accept

responsibility for any kind of loss resulting from the use of informationcontained in this document. This document shows the publication date. Theinformation contained in this document is subject to change without notice.Any improvements or changes to the information contained in this documentwill be documented in subsequent editions. This document containsproprietary information of Cognos. All rights are reserved. No part of thisdocument may be copied, photocopied, reproduced, stored in a retrievalsystem, transmitted in any form or by any means, or translated into anotherlanguage without the prior written consent of Cognos. Cognos and theCognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)in the United States and/or other countries. IBM and the IBM logo aretrademarks of International Business Machines Corporation in the UnitedStates, or other countries, or both. All other names are trademarks or

registered trademarks of their respective companies. Information aboutCognos products can be found at www.cognos.com

This document is maintained by the Best Practices, Product and Technologyteam. You can send comments, suggestions, and additions [email protected].


3/32



Contents

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

1.1 PURPOSE ............................................................................................................41.2 APPLICABILITY.....................................................................................................4

2

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

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

3.1 WHAT IS PROMPT RECONCILIATION? ..........................................................................43.1.1 Filter Expressions...............................................................................................43.1.2 Data Item Expressions .......................................................................................53.1.3 Macro Expressions .............................................................................................6

3.2 HOW DOES PROMPT RECONCILIATIONAFFECT PERFORMANCE? ...........................................63.3 HOW DOES PROMPT RECONCILIATION CHANGE IN COGNOS 8.2?.........................................6

3.4 FASTER PROMPT RECONCILIATION IN COGNOS 8.2..........................................................73.5 REPORT SERVER PROPERTIES FOR TUNING PROMPT RECONCILIATION ...................................7

3.5.1 Whats The Best Default Setting?.........................................................................9

3.6 QUERY PROPERTIES FOR PROMPT RECONCILIATION TUNING...............................................93.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..............................................................................................113.7 SAPCONSIDERATIONS .........................................................................................11

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

4.1 THE NUMBER OF QUERIES .....................................................................................114.2 PROPER PROMPT CONTROLS ................................................................................... 124.3 CACHE PROMPT QUERIES ......................................................................................124.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...................................................................................................166.4 UNDOCUMENTED AND UNSUPPORTED CAPABILITIES USED................................................ 17

6.5 TABBED PROMPT REPORT WORKSHOP .......................................................................17

6.5.1 Create the Basic Report....................................................................................176.5.2 Create the Basic Prompt Page...........................................................................18

6.5.3 Create the Tab Body........................................................................................196.5.4 Create the Tabs...............................................................................................206.5.5 Style the Tabs.................................................................................................236.5.6 Cognos 8 Button Styling ...................................................................................246.5.7 ReportNet Button Styling ..................................................................................256.5.8 Run the report ................................................................................................256.5.9 Show Active and Inactive Tabs..........................................................................25

6.5.10

Format the Tab Body ...................................................................................296.5.11 Format the Page and Add Text...................................................................... 31

6.6 CONCLUSION .....................................................................................................32


4/32



1 Introduction

1.1 Purpose

This document tells report authors how to deal with slow first prompt pageperformance 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 userruns the report before the first prompt page displays. For example, in onecustomer scenario a report took about 40 seconds to display the first promptpage.

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 theparameter usage. Parameters are definedin filters and calculations. Theresulting parameters are usedin 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 avalue range

Optionality Whether a parameter is required or optional in thecontext of the filter or calculation.

Data type The required data type that is expected in the context ofthe filter or calculation to match other referenced data items orconstants. These types can be one of Numeric, Date, Time, DateTime, Interval, String, or Member Unique Name (MUN).

3.1.1 Filter Expressions

Consider an optional filter

[Order number] = ?pOrderNumber?


5/32



By examining this filter we can determine some characteristics about theparameter 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 asin_range:

[Order number] in_range ?pOrderNumber?

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

Optionality: Optional

The filter is defined as optional so the parameter would also beoptional

The parameter may also be mandatory. If a parameter is used inmultiple contexts then all references must be optional for theparameter to be optional.

Data type: Numeric

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

The characteristics of the parameter are now applied to prompts thatreference the parameter. This means that a prompt control will take on themore restrictive characteristics of the parameter to make the prompt controlcompatible with the parameter definition. If the parameters are referenced inan authored prompt page, the prompt definition is modified at run time tomatch the parameter Cardinality, Optionality and Discreteness. A data typemismatch may result in a run-time error. If there is no authored promptpage, then these characteristics are applied to prompts on a generatedprompt page.

3.1.2 Data Item Expressions

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


6/32



3.1.3 Macro Expressions

Parameters defined in macro expressions1can be optional or required, singleor 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 thequeries to determine which parameters exist and their characteristics. Thelarger and more complex the queries, the longer this process can take.

A customer report

2

in IBM Cognos 8.1 with over 200 queries has been notedto require over 40 seconds to show the first prompt page. Most of this timewas 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

1For full details on macro functions and macro function syntax refer to either the FrameworkManager User Guide or the Report Studio User Guide provided with your Cognos 8installation.2Due to confidentiality concerns with proprietary data we cannot show this report but thisuse case is real based on an actual customer report.


7/32



3.4 Faster Prompt Reconciliation in IBM Cognos 8.2

First, in IBM Cognos 8.2 the code prompt reconciliation process has beentuned 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 5seconds in IBM Cognos 8.2 compared to more than 40 seconds in IBMCognos 8.1 a reduction of 80%.

This 80% performance advantage is realized by simply moving to IBM Cognos8.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 promptreconciliation both for the entire system and for an individual report.

The first option is a report server advanced property3that is enabled for an

entire report server: RSVP.PROMPT.RECONCILIATION. This property hasseveral values:

COMPLETE - All queries are reconciled before the first prompt page isdisplayed. This is the default setting to ensure compatibility with previousreleases4.

CHUNKED - All queries are reconciled in sets until parameters required forfirst prompt page are reconciled. The queries are processed with no fixedorder. You can change the CHUNK size with theRSVP.PROMPT.RECONCILIATION.CHUNKSIZE advanced server property. The

default is chunk size is 5 queries.

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

Filtered report queries

Filtered prompt queries5

Unfiltered report queries

Unfiltered prompt queries

3Please refer to the Administration and Security Guide for details on setting advanced serverproperties.4None of these settings is likely to introduce upgrade/compatibility issues so this is reallyerring on the safe side only.5A prompt query is a query used to provide the values that appear in an authored promptcontrol such as a picklist.


8/32



Queries are processed in order by these groups until all of the parametersreferenced on the first prompt page are reconciled. It is often the case thatonly 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 aparameter were referenced in a calculated query item in a prompt query forexample. Once the report server has reconciled the parameters for the first

prompt page, the page will be displayed to the user. Prior to display ofsubsequent prompt pages the report server may need to reconcile morequeries if those prompt pages refer to parameters that were not in thequeries already processed.

CHUNKED GROUPED - Queries are reconciled by evaluating the query groupsin chunks6until parameters required for first prompt page are reconciled.

Our customer scenario contained only one filtered query but imagine that all200 queries in our report are filtered using the same parameters. GROUPEDwill reconcile all 200 queries at once because all 200 queries would be part ofthe same filtered report query group. CHUNKED reconciles x number ofqueries at a time where x is the CHUNK size (defaults to 5). Thus withCHUNKED GROUPED, 5 queries will be reconciled. If the parameters requiredfor the first prompt page are found then the page is displayed. If not, thenext 5 queries are processed and so on until the parameters are found.

Using our customer report as an example, settingRSVP.PROMPT.RECONCILIATION = GROUPED focuses prompt reconciliationon the queries which contain filters first (of which we only have one query).

This results in prompt reconciliation of our customer sample report taking lessthan 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 singleadvanced server property7. No additional action was required.

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

6A CHUNK is a set of queries.7In addition to the base reconciliation improvements obtained by upgrading from IBMCognos 8.1 to IBM Cognos 8.2.


9/32



3.5.1 Whats The Best Default Setting?

There is a slight risk of run-time errors if you use a setting other thanCOMPLETE as the same parameter may be defined different two or moretimes 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 processedand the most restrictive definition would be used to modify the promptappropriately, resulting in a mandatory single value prompt.

Were GROUPED used, only the filtered query would be processed allowing anoptional multi-value prompt to be used8. Was the user to skip the prompt orselect multiple values there will be a run-time error when the calculation wasprocessed.

Having said that, when using the advanced reconciliation properties it is theauthors responsibility to use the parameters appropriately and resolve thesemismatched parameter definitions.

Using CHUNKED GROUPED it would also be possible to have two or morefilters 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 allowsprocessing of partial query groups. However, it should be used in tandemwith proper report testing to ensure that no run-time errors will occur due toinconsistent parameter usage by the report author. The default chunk size of5 is sufficient for most applications.

3.6 Query Properties for Prompt Reconciliation Tuning

Some reports may not be well served by the advanced report serverproperties and may require hand tuning to achieve the best performance. Thereport author can use a new Report Studio query property called Use for

Parameter Infoto determine how prompt reconciliation takes place. This newproperty is used in tandem with the report server advanced propertyRSVP.PROMPT.RECONCILIATION GROUPED and CHUNKED GROUPED optionsonly.

8Note that prompts are never modified to be less restrictive so if the prompt were authoredas single value mandatory it would NOT be changed at run time.


10/32



In essence, this property creates a new query processing group that isprocessed 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 querieswill 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 filtersreferring to these same parameters then wed have to process all 200 queriesto reconcile the parameters. In fact, were we to process any single one ofthose queries we could collect the required information. The report authorcan select any query and set the query property Use for Parameter Info=True10. That one query will be processed. The required parameters will befound and the first prompt page will be displayed without having to processthe 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 200queries and each refers to a different parameter and all 200 parameters arereferenced on the first prompt page. All queries would have to be processedresulting in slower performance (back to the 5 second performance).

The author could be very clever. That is, create a query which defines all 200parameters. 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 ParameterInfo= Trueon this one query only. Now when this report is run only this onequery is processed. As this query is not referenced in the layout, it will notactually be executed. Thus is solves the first prompt page performance issuewithout incurring any additional overhead.

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

9A prompt query is a query used to provide the values that appear in a prompt control suchas a picklist.10Being sure to also set the report server RSVP.PROMPT.RECONCILIATION GROUPEDproperty also.


11/32



It is anticipated that very few reports will require the use of the Use forParameter Infoquery property as the general performance improvements ofIBM Cognos 8.2 combined with the use of RSVP.PROMPT.RECONCILIATIONGROUPED will resolve most performance issues.

3.6.3 Giving Bad Hints

Be sure that the queries you select supply all required parameters. If youhave set the Use For Parameter Info query hint on a set of queries that donot define ALL of the parameters, there will be a negative performanceimpact since a separate request will be required to obtain parametercharacteristics on those parameters that were not resolved in the firstrequest.

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 thesevariables could have a significant negative impact.

It is recommended that the advanced server property not be used in theseenvironments; however, the use of the Use For parameter Info query hintcould offer performance benefits.

4 Prompt Query Performance

Prompt queries are used to populate the prompt controls. The prompt pagecannot 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 displayedto a user.

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

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 promptpage. While the mechanisms discussed below will reduce the time required,sometimes it will be a case of having just too much included on the initialprompt page that requires processing before the prompt page is displayed.

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

You might use a tabbed prompt page. As we only run queries for promptcontrols that actually appear to the user, prompt queries for inactive tabs arenot run. Appendix A shows how to create a tabbed prompt interface.


12/32



You might use prompts that are hidden in conditional blocks and only appearwhen 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 theuser, prompt queries for hidden blocks are not run.

4.2 Proper Prompt ControlsSome prompt controls are not well suited to large volumes of data. Forexample, a value prompt (picklist) with 100,000 entries will both be slow andunusable. Better options for such volumes are Select & search prompts,Cascading prompts, or Tree prompts as they do not load the entire data setto display the initial prompt control.

Note that if an author insists on using prompts with very large volumes ofdata then, by default, the data will be truncated without warning at 5000rows. The Rows Per Page property of the prompt controls can be used to seea larger set of data.

4.3 Cache Prompt Queries

With IBM Cognos 8.1 it is now possible to cache prompt queries. This isuseful where the values in the prompt do not change often - perhaps everyday rather than in real-time- and the prompt is not dependant on the value ofanother prompt to filter the prompt query. For example, we can cache thevalues for a parent cascading prompt but not the (grand)child as thesubsequent prompts are dependent on executing a query with the parentprompt value(s).

You would use a Job to execute the prompt queries and cache the values fora report. The Job would be created with an appropriate schedule daily or

weekly perhaps to reflect the volatility of the prompt values. After addingthe reports to the job for which to refresh the prompt queries, the DefaultRun 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 theresults in the Content Store. If you have prompts in multiple locales, setthose 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 toreduce the number of queries hitting your database as the prompt queries nolonger need to be executed for each user request to run the report.


13/32



4.4 Run Prompt Queries Concurrently

If your prompt values are highly dynamic and caching is not a good option foryou 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 possibleto run either prompt or data queries concurrently.

The report server uses the concept of helpers to manage how many queriescan be executed concurrently within the report server. Setting this to 10 forexample means that an additional 10 queries11may be executed concurrentlyfor the entire report server instance.

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

You must also configure how many helpers are available to each report usingthe report server advanced property RSVP.CONCURRENTQUERY.MAXNUMHELPERSPERREPORT. The default is one which allows any report toexecute 1 query at a time i.e. you must set this to at least 2 to allowparallel queries to run.

Once these two options are set, by default concurrent queries are only runfor batch executions. This is because in interactive executions, it is possiblefor a query to be run but never be seen by the user and thus consumeunnecessary 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. Thesecond query would have been run concurrently but never used thus wastingresources. Well see how to better manage this in a moment.

To allow concurrent queries for interactive executions, set the report serveradvanced propertyRSVP.CONCURRENTQUERY.ENABLEDFORINTERACTIVEOUTPUT to True.

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


14/32



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

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

5 Summary

IBM Cognos 8.2 provides vastly improved first prompt page performance outof 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 CHUNKEDGROUPED (with proper report testing) be set on all IBM Cognos 8.2 serversto further improve prompt performance.


15/32



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 PagesThe scenario here is that a customer would like to deliver a report to theirend-users with a tabbed style user interface in the prompt page rather than aseries of prompt pages. The most-often used prompts would appear in thefirst tab with each tab presenting successively less used prompts.

Examples of applications we have seen have as many as 60 prompts across 6to 8 tabs. There are 2 issues which drive performance in these reports. First,the sheer number of prompts means that Cognos 8 must analyze manyqueries before the report is run. Generally this means 1 query per promptplus the report queries themselves. This can only be addressed by usingfewer queries in a given report which is beyond the scope of this document.Secondly, the nature of the HTML/JavaScript techniques we have seen usedresult in very poor performance12. The standard technique is to createHTML/JavaScript that generates the tabs allowing the user to switch tabswithout hitting the server. This means that all prompts (as many as 60) mustbe populatedprior to the first tab being displayed. As queries are run

sequentially by default, the more prompt queries that are required the longerthe user waits.

6.2 Solution Overview

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

12Also, 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 throughfrom lower layers.


16/32



The prompt page to accomplish this technique uses conditional blocks todetermine which prompts to show. Think of a series of overlapping rectanglesonly 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 arealways visible. The borders of the current tab and the text color are setblack to make it appear to be in front of the other tabs. The non-current tabsuse grey to make them less prominent.

At one level the report authoring is reasonable straight forward. We willcreate 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 associatedconditional block is displayed and the tab border and text color are changedand the associated block is displayed.

Behind the scenes, a parameter value is set to identify which tab is to bedisplayed and the report is re-prompted. Ideally, wed use a prompt controlor prompt button to set the parameter value and re-prompt. But, there isneither a prompt control nor button that meets the bill. A prompt can bothset the parameter value and re-prompt (via auto-submit) but cannot look likea piece of text.

6.3 Applicability

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


17/32



6.4 Undocumented and Unsupported Capabilities Used

As discussed in detail below, this solution requires the use of twoundocumented and unsupported capabilities in IBM Cognos 8. Therefore,there is a risk associated with this solution in the support for these twocapabilities may change or be dropped entirely in some future releaserequiring 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) andthe second tab will allow the user to select a Product name(s) to run a verysimple list report.

We will walk through creating a sample report from beginning to end. Tokeep 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 optionaldetail filters:

[Order year] in ?p_OrderYear?

[Product name] in ?p_ProductName?

Thats it. Thats the basic report we will use to demo this technique.

13You may see minor differences in colours, fonts and styles between ReportNet and IBMCognos 8.


18/32



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 actualfunctionality 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:

Were going to ignore the table for a while but we will come back and use it abit later.


19/32



6.5.3 Create the Tab Body

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

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

Drop a Conditional Block14object onto the page body:

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

Create a as so:

Name: TabToShow

Values: Tab2

Expression: ParamValue('pTabToShow')

The name of the Variable TabToShow, the value Tab2 and the parameterpTabToShow are critical as we will refer to them several times later in thisworkshop.

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

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


20/32



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 valuebetween 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 andunsupported tricks to make the tabs work.

The first thing we will do it to take advantage of how the Report Viewercommunicates parameter values to the server. Parameter values are passedas form variables15with the name being the parameter name, such aspTabToShow, prefixed with p_ like p_pTabToShow.

15Or using a URL, but we cant use that approach here.


21/32



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:

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

This form variable will trick the server into thinking that a parameter calledpTabToShow 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 becomethe tabs the user can click on.

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


22/32



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:

Show Tab 1

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 variableand reprompt the report.

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

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

Show Tab 2

Run the report16:

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


23/32



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 iscosmetics the user interface may be working but it certainly does not looklike 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 deletethe current width setting.

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

In your real report, youll have to vary the width to match the text you put ineach tab. Remember that all tabs are usually the same width to make thetabs more aesthetically pleasing.

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

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


24/32



Select one of the HTML objects and youll see there are no style properties:

With IBM Cognos 8 we can define styles in our report and apply them toreport 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 HTMLbutton 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 styleto the HTML items.

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


25/32



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

Show Tab 2

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 theHTML style property rather than referencing a common style definitiondefined at the report level.

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

Show Tab1

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

Show Tab

2

6.5.8 Run the report

Run the report. The button-like appearance of the buttons has been removedto 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 willhave black borders and text. The inactive tab will have grey borders and text.

Select the left table cell.

Set the Style Variable to TabToShow.


26/32



Using the Variable Explorer, select TabToShow to Other:

With the left table cell still selected, set the Border to Black, Solid Line, 1.5point (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.5point (pt) on the Left, Top and Right sides:


27/32



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).


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.5point (pt) on the Left, Top and Right sides:



28/32



With the right table cell still selected, set the Border to Black, Solid Line, 1.5point (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 theright table cell. Actually, we set it to both grey and black. Each table cellactually has its 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 todetermine which border gets displayed (takes precedence). In this case, theleft cell border appears.

What we need to do it to adjust the borders so that the left table cell has noborder when the right cell is active.


Select the left table cell.



29/32



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 andinactive tabs.

6.5.10 Format the Tab Body

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


Using the Variable Explorer, select No variable:


30/32



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 tabappearance a bit more.

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



31/32



6.5.11 Format the Page and Add Text

Select the Page Body object and set the Padding to 100 pixels (px) on theleft, 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 reportprompts 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 adifferent 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.


32/32



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 alreadydefined 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 andunsupported capabilities of the product, it also provides high value to theend-users.

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

Documents

Advanced Prompting