General Usage Notes

Chart Unlimited macros can be inserted in any chart title field (i.e., title, subtitle, footnote, etc.) field in a chart. Chart titles can be defined in the Chart Titles dialog that is available from the Chart Properties dialog in Cognos Impromptu Administrator.

Even though macros are defined in the chart title fields, they will not appear as text in your chart. If you need to use a particular title field to define a chart title and to enter a macro, append a tilde (~) character and a space to the title and add the macro after the space. The space after the tilde is important. If it is not included, the macro will be ignored.


TitleText~ @3DSCAT

Macros are not case-sensitive. All macros begin with an at-sign (@). There should be no space between the at-sign and the macro (i.e., @SWAP, not @ SWAP). Most macros include one or more parameters that further define the action of the macro. There must be one space after the macro and before the first parameter and a space between each subsequent parameter.


@USER_LABEL_FONT 14 255 0 0 255 Splash

Multiple macros may be defined in a single title field. When multiple macros are used, separate each macro with a space.


@BP2 @MK 8

If the macro includes a string and multiple macros are defined in the same title field, a tilde (~) character must be appended to the end of the string parameter to indicate the end of the first macro and beginning of the next.


@AGL 2 Alias Label~ @BP2

For macros that can be applied to a particular series in a chart, the nSeries parameter defines the series to which the macro is applied. In most cases, the nSeries parameter can be assigned a value in the range: minus one (-1)...n (where: n is the total number of series in the chart). For these macros, minus one is a special value that will apply the macro to all series in the chart. A value of zero (0) applies the macro to series 1.

Order of Evaluation

Because chart enhancement macros can be defined in any chart title field (i.e., Y2 Axis Title, Y1 Axis Title, X Axis Title, Footnote, Subtitle, or Title), you could potentially define conflicting macros. To avoid this potential conflict, the macros are evaluated in the following order:

1) Value Title (Y2)

2) Value Title (Y1)

3) Category (or X-Axis) Title

4) Footnote

5) Subtitle

6) Title

For example, assume "@SWAP 0" is defined in the Footnote field and "@SWAP 1" is defined in the Group Title field.

In this example, the "@SWAP 0" macro would be used because it is evaluated after the "@SWAP 1" definition.

If multiple macros are defined in the same title field, macros are parsed from left-to-right. For example, assume the following macros are defined in the Footnote field:


In this example, "@SWAP 1" would be used because it is defined AFTER "@SWAP 0".


Many of the chart enhancement macros set a property of the chart and that property will remain set, even if the macro is removed from the field. For example, if "@SWAP 1" is used to reverse the series/groups in the chart, the series/groups will remain reversed even if the "@SWAP 1" macro is removed. A "@SWAP 0" macro is needed to return the series/groups to their normal/default order.

Some of the chart enhancement macros are NOT persistent and their effect will disappear when the macro is removed. For example the user-defined lines (set by @X, @Y, and @XY) and user-defined series labels (set by @ASL) only remain in the chart while the macro definition is in place. When the macro is removed, the user-defined line and/or series labels disappear.

The description of each macro in this document identifies whether or not the macro is persistent.

Error Reporting

If your macro encounters an error, a message will be displayed in the footnote area of the chart. Example:

The error message indicates the field (e.g., Group Title, Footnote, Subtitle, Title, etc.) and the macro where the error occurred. The most common errors are:

1) missing parameter(s)

2) parameter is assigned an out-of-range value

3) missing space between macro and parameter or consecutive parameters.

Return to Installation & Setup Next to Using Report Fields/Functions in Macros Return to Main Page