Embedding dynamic filters into Custom SQL-based Cognos reports is necessary such that we can define where the filter should exist. This report shows why using the Cognos GUI for filtering is not wise, and how to properly use macros in your code.

1. S I T U A T I O N A L E X A M P L E S A N D P R O P E R
S Y N T A X F O R V A R I O U S C A S E S
B R Y A N L . M A C K
Cognos Macros

2. Why Do We Need Macros?
In Cognos, we dynamically filter data based on prompt
values input by the user.
When using Custom SQL for a report’s source, Cognos
provides filters for us to filter data.
But what exactly is it filtering?

3. Why Do We Need Macros?
Refer to the following 2 SQL scripts in SQL Developer:
 Query 1:
 Query 2:
The only difference in Query2 is the academic_period filter in the nested query; Query2
correctly filters our result set, as our desired output count is 2524.

4. Why Do We Need Macros?
Our first SQL Script is embedded to Cognos as a
Query, minus the academic period filter:
Then a filter is added to the query via Cognos

5. Why Do We Need Macros?
If we use term 201320, and export our result set to
Excel, we can see that we have 12148 results (the top 2
rows in Excel are header rows)
As we mentioned earlier, this is not our desired output.

6. Why Do We Need Macros?
Here is the SQL Cognos has generated:
The academic_period filter is being placed incorrectly within the query.

7. Why Do We Need Macros?
Let’s revisit slide 3’s results:
Query 1:
Query 2:
Shouldn’t we be limiting this to 2524 results? Cognos is not applying the
filter to the nested query

8. What is a Cognos Macro?
A Cognos macro allows you to place user-selected
prompt values wherever you’d like within custom SQL.
The macro allows you to manipulate the prompt values
where necessary, and use them for more precise
filtering and processing.
In our example, we want the filter to be placed in the
nested query rather than the outmost query.

9. Proof of Concept
We can filter the prompt values wherever we desire, in this case, within
the nested query:
We can see we now return 2524 rows
The macro worked and our results are correctly filtered. You can see the
macro in the SQL – but how does it work?

10. Macro Syntax
#prompt(ParameterName,Datatype,Defaultvalue,PreText,Sou
rce,PostText)#
ParameterName: Mandatory. This is what you named your prompt value’s parameter.
Datatype: Optional. The default value is ‘string’. Prompt values are validated. In the case of strings, the
provided value is enclosed in single quotation marks and embedded single quotation marks are doubled.
Defaultvalue: Optional. Value if the user makes no selection from an optional prompt
Pretext: Optional. Text to use before displaying the option the user inputs with the prompt.
Example: This is the open-parentheses when using #promptmany for an IN statement (we’ll get
to that in a bit)
Source: Optional. The value(s) selected in the prompt
Posttext: Optional. Text to use after displaying the option the user inputs with the prompt.
Example: This is the close-parentheses when using #promptmany for an IN statement

11. Ways I’ll Demonstrate Macros
Using Oracle join syntax, I will demonstrate all of the
following macro scenarios.
 Inner Join (Mandatory Prompts, Optional Prompts)
 Outer Join (Mandatory Prompts, Optional Prompts)
 Conditional Inner/Outer
 If optional prompt used – use inner join
 If optional prompt ignored – use outer join
 Date/Date Range (Mandatory Prompts, Optional Prompts)
 For use within a function
 Equal Operator (=) vs IN statement
 LIKE clause
 HAVING clause

12. Ways I Will NOT Demonstrate Macros
Many!
There are countless combinations of inner join, outer join,
mandatory/optional prompts, single/multi select,
characters/numbers/dates, etc. etc. etc.
I can’t possibly demonstrate every way to do this, so I will
try to build up your base knowledge so you can figure out
scenarios I have not demonstrated.
I will also not be using ANSI join syntax, I will be using
Oracle join syntax

13. Inner-Join Mandatory Macro
Compare characters (=)
<field> = #prompt('parm_multi_source')#
Compare characters (in)
<field> IN (#promptmany('parm_carrier')#)
Real example from a Cognos report:

14. Inner-Join Optional Macro
Compare Characters (=)
<field> =
(#prompt('parm_carrier','string',’<field>’)#)
Let’s say the field is “myfield” and the user selects the prompt value “I Hate
Cognos”. The generated SQL will be:
myfield = ‘I Hate Cognos’
If the user does not use the optional prompt, the macro will generate the following
SQL:
myfield = myfield
Note: You can convert to “IN” by changing the equal to the word IN, and change “prompt” to
“promptmany”

15. Inner-Join Optional Macro Examples

16. Outer-Join Mandatory Macro
Follow the same logic as Inner-Join Mandatory, just
add the plus sign for Oracle’s outer-join logic
and s.spriden_id(+) = (#prompt(‘myparam')#)
and s.spriden_id(+) IN (#promptmany(‘myparam’)#)

17. Outer-Join Mandatory Macro Example

18. Outer-Join Optional Macro
Compare Characters (=)
This will build out the entire AND statement for you
#prompt('parmYEAR','string','and 1=1','and pdrhioc_year(+) = ')#
Read this as: parmYear is my string parameter used in my prompt, when the user doesn’t use the prompt, insert
the text “and 1=1”, when the user uses the prompt insert “and pdrhioc_year(+) = “ followed by the value they
input.
Compare Characters (IN)
Option 1: build out the entire AND statement
#promptmany('parmYEAR','string','and 1=1','and pdrhioc_year(+) IN (','',')')#
The last 3 parameters are: (1) what to insert before the prompt value (2) The prompt value itself (3) what to insert
after the prompt value
Option 2: This requires the macro to be within an AND statement
and (a.account_entity_ind IN (#promptmany('ParameterEnt','string',sq('NotSelected'))#)
OR
('NotSelected') in (#promptmany('ParameterEnt','string',sq('NotSelected'))#)
)
The first part of the OR statement addresses the outer-join, the second part of the OR statement keeps the join in
tact when the optional prompt is not used.

19. Outer-Join Optional Macro Examples

20. Conditional Outer/Inner Join Macro
Requirements:
 Have an optional prompt
 If optional prompt selected, use inner join
 If optional prompted ignored, use outer join
and ad.account_uid = sar.person_uid
#prompt('ParameterStuAttr', 'string', '(+)', '/*', '', '*/'
)#

21. Conditional Outer/Inner Join Macro
 and ad.account_uid = sar.person_uid #prompt(
 'ParameterStuAttr', --parameter name
 'string', --DataType
 '(+)', --Default text (when prompt ignored)
 '/*', --text to precede the prompt text when used
 '', --inputs the value selected in the prompt
 '*/' --text to follow the value in prompt when used
 )#
When the prompt is used, the macro puts /* comments around the prompt value it is
inserting*/, so the code processes nothing and leaves the join (account_uid =
person_uid) as inner.
When the prompt is NOT used, the macro places (+) after the hard-coded join, thus
creating an outer join
Reminder: I am using Oracle outer-join syntax

22. Conditional Outer/Inner Join Macro Example

23. Date Prompts
Mandatory Inner:
Option 1: when using ISO 8601 date format
<field> = to_timestamp(#prompt(‘parm_date')#,'YYYY-
MM-DD"T"HH24:MI:SS.ff3')
Option 2: when using other date format standards
<field> = to_date(#prompt('parm_date')#,'yyyy-mm-dd')

24. Date Prompt Examples

25. Date Range
After exhaustive searching and testing, I have been
unable to find a way to extract the date range values
from a date range prompt with a macro, so you need to
create two individual date prompts (date_from and
date_to)….

26. Date Range Optional Prompt Example
(
(trunc(ad.entry_date) >=
trunc(to_date(#prompt('ParameterEntryFrom','string',sq('NotSelected'))#,'YYYY-MM-DD'))
OR
('NotSelected') = #prompt('ParameterEntryFrom','string',sq('NotSelected'))#
)
and
(trunc(ad.entry_date) <=
trunc(to_date(#prompt('ParameterEntryTo','string',sq('NotSelected'))#,'YYYY-MM-DD'))
OR
('NotSelected') = #prompt('ParameterEntryTo','string',sq('NotSelected'))#
)
)
This syntax uses an OR statement for each of the two parameters. The first
half of each OR block is for if the optional prompt is used, the second half is
for if the prompt is not used.
Note: I typed the code instead of screen shot here so I could color-code the parentheses and make the code
more readable for the example.

27. Date Range Mandatory Prompt Example

28. LIKE clause
To use a LIKE clause with optional, multi-select
prompt:
and eec.earn_code IN (select m.allowance from
mappings m where m.deductions like
('%'||#promptmany('parm_carrier','string','bd.carrier'
)#||'%'))

29. HAVING clause
Sometimes we need to filter on the aggregates, which
is used in SQL with the HAVING clause. Suppose we
have a prompt filtering on an aggregate amount that a
user types into a text prompt – how would we write
this in a macro? Add a caveat: this is an optional
prompt
having sum(ad.balance) >=
(#prompt('ParameterBalance','string','sum(ad.balance
)')#)

30. Having Clause Example

31. Function on top of Prompt Value
Sometimes we will get a prompt value and need to use
it to calculate the proper filter. In this case, we use the
prompt value (parm_s) as a parameter to a function
(odsmgr.f_get_pidm) to return a different value upon
which we will filter. We simply wrap the entire macro
within the function call:
And person_uid in
odsmgr.f_get_pidm(#promptmany('parm_s','string','p
erson_uid')#)

32. Case Statement/Function using Date Prompt Macro
Note: formatted in SQL developer for readability

33. Wrapping Up
I hope you find this somewhat helpful.
Even if you aren’t using the Oracle RDBMS, you can
use these syntax examples to create macros that work
for you.
If you have other concrete examples you’d like me to
add to this presentation, feel free to let me know and
I’ll consider adding them here.

34. Thank You!
Bryan L. Mack
fleetmack@gmail.com