Macro Functions
This list contains functions that can be used within a macro. A macro may contain one or more macro functions. A macro is delimited by a number sign (#) at the beginning and at the end. Everything between the number signs is treated as a macro expression and is executed at run time. For macro functions that accept expressions of datatype timestamp with time zone as arguments, the accepted format is 'yyyy-mm-dd hh:mm:ss[.ff]+hh:mm' where fractional seconds are optional and can be represented by 1 to 9 digits. In lieu of a space separating the date portion to the time portion, the character 'T' is also accepted. Also, in lieu of the time zone '+hh:mm', the character 'Z' is accepted and will be processed internally as '+00:00'. The macro functions that return expressions of datatype timestamp with time zone return 9 digits by default for their fractional seconds. The macro function timestampMask () can be used to trim the output if required.
- +
Concatenates two strings. - _add_seconds
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of seconds to "string_expression", where "string_expression" represents a timestamp with time zone. - _add_minutes
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of minutes to "string_expression", where "string_expression" represents a timestamp with time zone. - _add_hours
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of hours to "string_expression", where "string_expression" represents a timestamp with time zone. - _add_days
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of days to "string_expression", where "string_expression" represents a timestamp with time zone. - _add_months
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of months to "string_expression", where "string_expression" represents a timestamp with time zone. - _add_years
Returns the timestamp with time zone (as a string) that results from adding "integer_expression" number of years to "string_expression", where "string_expression" represents a timestamp with time zone. - array
Constructs an array out of the list of parameters. - csv
Constructs a string from the elements of the array where the values are separated by commas. Optionally, the separator and quote strings can be specified. The default separator is a comma ( , ) and the default quote character is a single quote ( ' ). - dq
Surrounds "string_expression" with double quotes. - getConfigurationEntry
Get an entry from the IBM® Cognos® configuration file. The force_decode_flag is optional and must be one of: 'true' , '1', 1 , 'false', '0', 0. The default is 'true'. When true, the value of the configuration entry will be decrypted into plain text if it is encrypted. - grep
Searches for and returns elements of an array that match the pattern specified in "pattern_string". - _first_of_month
Returns a timestamp with time zone (as a string) by converting the day value in "string_expression" to 1, where "string_expression" is a timestamp with time zone. - _last_of_month
Returns a timestamp with time zone (as a string) that is the last day of the month represented by "string_expression", where "string_expression" is a timestamp with time zone. - join
Joins the elements of an array using "separator_string". - lstrip
Strips the leading characters from the first argument. The optional second argument defines the set of characters to strip. By default, this function strips white space (ie. space, tab, carriage return and line feed). - prompt
Prompts the user for a single value or member. Only "prompt_name" is required. The datatype defaults to 'string' when it is not specified. The prompt is optional when "defaultText" is specified. "Text", when specified, will precede the value. "QueryItem" can be specified to take advantage of the prompt information properties of "queryItem". "Trailing_text", when specified, will be appended to the value. When the data type is 'memberuniquename', a single select member prompt is created. It is good practice to provide a default value, as 3rd argument. The default value must be a valid member unique name; it can also be an alias that references a member unique name as done in Report Studio. - promptmany
Prompts the user for one or more values or members. Only "prompt_name" is required. The datatype defaults to 'string' when it is not specified. The prompt is optional when "defaultText" is specified. "Text", when specified, will precede the list of values. "QueryItem" can be specified to take advantage of the prompt information properties of "queryItem". "Trailing_text", when specified, will be appended to the list of values. When the data type is 'memberuniquename', a multi select member prompt is created. It is good practice to provide a default value, as 3rd argument. The default value must be a valid member unique name; it can also be an alias that references a member unique name as done in Report Studio. - rstrip
Strips the trailing characters from the first argument. The optional second argument defines the set of characters to strip. By default, this function strips white space (ie. space, tab, carriage return and line feed). - sb
Surrounds "string_expression" with square brackets. - sq
Surrounds "string_expression" with single quotes. - sort
Sorts the elements of the array in alphabetical order. Duplicates are retained. - split
Splits a string or string elements of the array into separate elements. - strip
Strips the leading and trailing characters from the first argument. The optional second argument defines the set of characters to strip. By default, this function strips white space (ie. space, tab, carriage return and line feed). - substitute
Searches for a pattern in a string or in the string elements of an array and substitutes the first occurrence of "pattern_string" with "replacement_string". - timestampMask
Returns "string_expression1", representing a timestamp with time zone, trimmed to the format specified in "string_expression2". The format in "string_expression2" must be one of the following: 'yyyy', 'mm', 'dd', 'yyyy-mm', 'yyyymm', 'yyyy-mm-dd', 'yyyymmdd', 'yyyy-mm-dd hh:mm:ss', 'yyyy-mm-dd hh:mm:ss+hh:mm', 'yyyy-mm-dd hh:mm:ss.ff3', 'yyyy-mm-dd hh:mm:ss.ff3+hh:mm', 'yyyy-mm-ddThh:mm:ss', 'yyyy-mm-ddThh:mm:ss+hh:mm', 'yyyy-mm-ddThh:mm:ss.ff3+hh:mm', or 'yyyy-mm-ddThh:mm:ss.ff3+hh:mm'. The macro functions that return a string representation of a timestamp with time zone show a precision of 9 digits for the fractional part of the seconds by default. The format options allow this to be trimmed down to a precision of 3 or 0. - toLocal
Returns the string representing a timestamp with time zone resulting from adjusting "string_expression" to the time zone of the operating system. Note that the macro function timestampMask () can be used to trim the output. - tolower
Returns the string "string_expression" with all the characters converted to lower case using the rules of the locale "locale_string". If no locale is specified, the locale 'en' is used. - toupper
Returns the string "string_expression" with all the characters converted to upper case using the rules of the locale defined in "locale_string". If "locale_string" is not specified, the locale 'en' is used. - toUTC
Returns the string representing a timestamp with time zone resulting from adjusting "string_expression" to the zero-point reference UTC time zone, also known as GMT time. Note that the macro function timestampMask () can be used to trim the output. - unique
Removes duplicate entries from the array. The order of the elements is retained. - urlencode
URL-encodes the passed argument. This function is useful when specifying XML connection strings. - CSVIdentityName
Uses the identity information of the current authenticated user to look up values in the specified parameter map. Each individual piece of the user's identity (account name, group names, role names) is used as a key into the map. The unique list of values that is retrieved from the parameter map is then returned as a string, where each value is surrounded by single quotes and where multiple values are separated by commas. - CSVIdentityNameList
Returns the pieces of the user's identity (account name, group names, role names) as a list of strings. The unique list of values is returned as a string, where each value is surrounded by single quotes and where multiple values are separated by commas. - CAMPassport
Returns the Cognos® Access Manager passport. - CAMIDList
Returns the pieces of the user's Cognos® Access Manager ID (CAMID), such as account name, group names, or role names, as a list of values separated by commas. - CAMIDListForType
Returns an array of the user's Cognos® Access Manager IDs (CAMIDs) based on the identity type (account, group, or role). CAMIDListForType can be used with the macro functions csv or join. - simple case
This macro construct is the template for a simple case, including the case, when, then, else, and end functions. Note that this macro construct is only supported in DQM mode.