SITUATIONAL EXAMPLES AND PROPER SYNTAX FOR VARIOUS CASES

BRYAN L . MACK

Cognos Macros

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?

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.

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

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.

Why Do We Need Macros?

Here is the SQL Cognos has generated:

The academic_period filter is being placed incorrectly within the query.

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

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.

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?

Macro Syntax

#prompt(ParameterName,Datatype,Defaultvalue,PreText,Source,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

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 functionEqual Operator (=) vs IN statementLIKE clauseHAVING clause

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

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:

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”

Inner-Join Optional Macro Examples

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’)#)

Outer-Join Mandatory Macro Example

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 statementand (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.

Outer-Join Optional Macro Examples

Conditional Outer/Inner Join Macro

Requirements:Have an optional promptIf optional prompt selected, use inner joinIf optional prompted ignored, use outer join

and ad.account_uid = sar.person_uid #prompt('ParameterStuAttr', 'string', '(+)', '/*', '', '*/' )#

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

Conditional Outer/Inner Join Macro Example

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

Date Prompt Examples

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

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.

Date Range Mandatory Prompt Example

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')#||'%'))

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)')#)

Having Clause Example

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','person_uid')#)

Case Statement/Function using Date Prompt Macro

Note: formatted in SQL developer for readability

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.

Thank You!

Bryan L. Mackfleetmack@gmail.com