Tag Archiv für Javascript

Cognos & Javascript – Part III: Prompt Api

Last week a customer had the challenge that in a report a maximum of 5 stores should be selected in a prompt. This case I want to take to explain the new Cognos prompt api and it’s features. The prompt api is delivered in Cognos versions higher than 10.2.

First of all you need a handle to your report and to the user prompt. This can be done with the following functions:

var ocr = cognos.Report.getReport(„_THIS_“);
var ctrl=ocr.prompt.getControlByName(„TestControl“);

TestControl can be changed to the Name of your prompt. The returned object then the following methods for accessing a control:

  • clearValues()
  • setValues(<values>)
  • <values>=getValues(<optionAll>)
  • setValidator(<function (promptvalue)> )
  • addValues(<values>)

<values> in this case is an array containing the following elements:

  • use
  • display
  • start
  • end

In this issue I will focus on the properties use and display, which are the use- and display-value of a user prompt.  If you want to clear the currently selected values you can use clearValues(). If you want to set the selected values you use the setValues(…) function with an array of the selected values. And getValues() returns an array with the selected items (if optionAll is set to false) or all items (optionAll=true). The setValidator function is used to add a handler function in case of a change event in the prompt. It was designed for adding functions that check the entered or selected value but can easily used for everything you want to do when the prompt selection changes. We see the correct use of setValues() and setValidator() functions later in the example code.

Unfortunately the addValues(values) function doesn’t work or at least I wasn’t able to use it correctly. But I also read that there is a bug. That means if you want to add items dynamically to the prompt you have to do it without the prompt api. For that you can check my articles on JavaScript & Cognos Part 1 & Part 2.

Back to the example of the beginning: We want to implement a function that counts the selected elements in a list and deletes the last selected item(s).

<script>var ocr = cognos.Report.getReport(„_THIS_“); 
var ctrl=ocr.prompt.getControlByName(„TestControl“);ctrl.setValidator(
           function(promptValue) {
                   if (promptValue.length>5)
                        alert („You’ve selected too many values!“);
                       return false;
                        return true;


The first two rows receive handles on the report and the specific control. We use the control-handle and the setValidator function to connect the handler function to the control. The handler- function is expected to have one parameter which is used to pass the selected values. In our case we name it promptValue and it is an array.

In the function itself we first check the length of the array. In our case a maximum of 5 items can be selected. If there are more values selected we inform the user and return false.

The validator function always has to return true or false. If the validator function returns false, the prompt is marked in red and the user has to change his selection until the validator function returns true. Otherwise it’s not possible to finish the report.

It is also possible to correct the selected values automatically. For that one should remove the “return false” statement and put the following instead:



These two lines remove the last items that are too much and re-sets the selected values to the prompt again. Of course you can do it in a better way but it’s just an example to show how to manipulate the user’s selection.

I hope this small example gave you an impression of what is possible with the prompt api and what not. In my opinion it was a good idea to introduce this api as there are many java script issues in adding dynamical interactions to the user prompts. With that api it’s easier to do that and saver for future updates. But still a lot of customers are using versions lower than 10.2 and they have to do it the classic way.

If you are interested in this or other advanced Cognos/SQL topics you can also attend training on my corporate homepage. At the moment my open courses are only available in German. Inhouse training and online courses are also available in English language. So check out my open trainings (German) or my online courses (English)!

Cognos & JavaScript – Part II: Dropdown prompts

In the second part of the Java Script series we want to access drop down lists. That also includes list boxes, radio button groups and check box groups as they work based on the same principles.

Again we are focusing on dates to be selected. In todays’ issue we need a Drop Down Box with months. The USE Value should be some number like 201201, 201202, 201203 and so on. The display value can be as you want it to be. It doesn’t really matter if you add the values by static choices or a query. Let’s name the Box “DropDownTest”.  My examples are based on the three entries above as static choices.

The general syntax to access for example the 2nd item in the drop down box is as follows:

<script language=“JavaScript“>

var frm = getFormWarpRequest();

alert (frm._oLstChoicesDropDownTest.options[3].text);


With the above snippet you can read the display value of the second item in the list. options[] is the array that contains all the items of the list or dropdown box. The parameter name and a separator line ‘———–‘ are normally also part of this array. Array indexes in Java Script starts with 0. That’s why we have to use an index of 3 for accessing the first “real” item.

We have several properties in the options[] array that might be interesting:

  • text -> display value
  • value -> use value
  • selected -> true, if item is selected.
  • length -> method to return the number of items in the array

With the next script you can select an item of the list:

<script language=“JavaScript“>

      var frm = getFormWarpRequest();



Now the 3rd item of the list is selected, i.e. the first relevant item.

With the above scripts you can easily select the value that is relevant in your case. For example you could check for the current date (also look at the article: Cognos & JavaScript Part 1) and depending on that you can select the current month or one month before.

In the next part of this series I will explain how to set up an event handler to react on choices that the user made to certain prompts.

If you are interested in this or other advanced Cognos/SQL topics you can also attend training on my corporate homepage. At the moment my open courses are only available in German. Inhouse training and online courses are also available in English language. So check out my open trainings (German) or my online courses (English)!