Comparison Operators in TM1

Operator Meaning
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to
= Equal to
<> Not equal to
To compare two string values, insert the @ symbol before the comparison operator, as in the following
example:
IF ('A' @= 'B',0,1) yields the number 1.

Arithmatic Operators in TM1

Operator Meaning
+ (plus sign) Addition
- (minus sign) Subtraction
* (asterisk) Multiplication
/ (forward slash) Division by zero using this operator returns an undefined value.
\ (back slash) Division by zero using this operator returns zero.
^ (caret/circumflex) Exponentiation

Logical Operators in TM1

Operator Meaning Example

& (ampersand) AND (Value1 > 5) & (Value1 < 10) Returns TRUE if the value is greater than 5
and less than 10.
% (percentage OR (Value1 > 10) % (Value1 < 5) Returns TRUE if the value is greater than 10
sign) or less than 5.
~ (tilde) NOT ~(Value1 > 5) Equivalent to (Value1 <= 5)
Cube Data Rules Functions

1. DB

Syntax: DB(cube, e1, e2, [...e256]);

Returns a value from a cube in a TM1 database.

Exp: [’Price’] = N:DB(’PriceCube’, !Actvsbud, !Region, !Model, !Month);

2. ISLEAF

Returns 1 if a specified cell is a leaf cell (identified solely by leaf/simple elements). If the specified cell is
identified by any consolidated elements, the function returns 0.

3. UNDEF

Returns the undefined value. This function can be used to prevent data from being stored in a cube
based on a logical test.

4. ISUNDEFINEDCELLVALUE

Syntax: ISUNDEFINEDCELLVALUE(TestValue, <Cube>);

compares the passed value to the default numeric cube value, which is influenced by the presence of
the UNDEFVALS declaration in that cube's rule. The function returns 1 if the passed value equals the
cube's default value, otherwise the function returns 0.

Arguments
Argument Description
TestValue The numerical value to compare against the cube's default value.
Cube An optional String argument that specifies the cube whose default value should
be compared.
When ISUNDEFINEDCELLVALUE is used in a rule, the cube is assumed to be the
subject cube unless otherwise specified.
Argument Description
When used in a TI, a cube should be specified.
If the cube is omitted in a TI, or is not valid when specified, 0 will be used for
comparison.

5. UNDEFINEDCELLVALUE

Syntax: UndifinedCellValue(<Cube>);

Returns the default numeric cube value, which is influenced by the presence of the UNDEFVALS
declaration in that cube's rule.

When UNDEFINEDCELLVALUE is used in a rule, the cube is assumed to be the subject cube unless
otherwise specified.

6. UNDEFVALS

Putting UNDEFVALS in the rules for a cube changes the default value for the cube from zero to an special
undefined value. This has ramifications for how data is stored in the cube and retrieved.

Attribute Rules Function

1. ATTRN

Returns a numeric attribute for a specified element of a dimension.

Syntax: ATTRN(dimension, element, attribute)

Exp: [ ]= ATTRN( 'scenario', 'actual', 'current') ;

2. ATTRS

Returns a string attribute for a specified element of a dimension.

Syntax: ATTRS(dimension, element, attribute)

ATTRS('plan_business_unit', '10100', 'Currency')

In this example, the function returns the string value of the Currency attribute of the 10100 element in
the plan_business_unit dimension.

3. CubeATTRN

CubeATTRN returns a numeric attribute for a specified cube.

Syntax
CubeATTRN(CubeName, AttrName);
Argument Description
CubeName A valid cube name.
AttrName The attribute for which you want to retrieve a value. This argument must be a valid
attribute of the cube.

Exp: [ ] = CubeATTRN('Sales_Cube', 'Sales' );

4. CubeATTRS

CubeATTRS returns a string attribute for a specified cube

Syntax
CubeATTRS(CubeName, AttrName);
Argument Description
CubeName A valid cube name.
AttrName The attribute for which you want to retrieve a value. This argument must be a valid
attribute of the cube.

Exp: CubeATTRS('PnLCube', 'Profit_Loss' );

5. DimATTRN

DimensionATTRN returns a numeric attribute for a specified dimension.

Syntax
DimensionATTRN(DimName, AttrName);
Argument Description
DimName A valid dimension name.
AttrName The attribute for which you want to retrieve a value. This argument must be a valid
attribute of the dimension.

6. DimATTRS

DimensionATTRS returns a string attribute for a specified dimension.

Syntax
DimensionATTRS(DimName, AttrName);
Argument Description
DimName A valid dimension name.
AttrName The attribute for which you want to retrieve a value. This argument must be a valid
attribute of the dimension.

Dimension Information Rules Functions

1. ConsolidateChildren

Forces consolidated values to be calculated by summing immediate children along a specified

dimension.

ConsolidateChildren(DimName1, DimName2, ...)

ConsolidateChildren forces consolidated values to be calculated by summing immediate children along a

specified dimension.
This is a TM1® rules function, valid in both TM1 rules and TurboIntegrator processes.
ConsolidateChildren is useful when intermediate consolidations are calculated by rules and you want a
parent consolidation to be calculated by summing the intermediate consolidations rather than by
summing the underlying leaf values.
Syntax
ConsolidateChildren(DimName1, DimName2, ...)
Argument Description
Argument Description
DimName1, Names of the dimensions along which consolidations will be performed.
DimName2, ... The function requires at least one DimName argument, and can accept as
many DimName arguments as there are dimensions in the cube for which the
rule is written.
Example
Consider a cube named Sales composed of the dimensions ActVsBud, Region, Model,
Account1, and Month.
In this example, the Month dimension is defined as follows:

If no rule is in place for this cube, the value of the Year consolidation is calculated by summing
all the underlying leaf values, in this case Jan through Dec. The following figure illustrates this
consolidation.

Now, suppose you create the following rule for this cube, which indicates that all quarterly
values should be 1:

[{'1 Quarter', '2 Quarter', '3 Quarter', '4 Quarter'}]=1;

The result is as follows:

In the figure, you can see that quarterly values are indeed calculated by the rule, but the Year
consolidation is still calculated by summing all underlying leaf values. If this is not your desired
calculation path, you can use the ConsolidateChildren function to force TM1 to calculate the Year
consolidation by summing its immediate children, specifically 1 Quarter, 2 Quarter, 3 Quarter, and 4
Quarter.

['Year']=ConsolidateChildren('Month');[{'1 Quarter', '2 Quarter', '3 Quarter', '4 Quarter'}]=1;

In the rule, the statement ['Year']=ConsolidateChildren('Month') says that the Year consolidation should
be calculated by summing the immediate children of Year in the Month dimension.
The following figure shows the result of the ['Year']=ConsolidateChildren('Month') statement:

Note that the Year consolidation is now calculated by summing its immediate children.
It's important to remember that for a given consolidation, the ConsolidateChildren function applies only
to the immediate children of the consolidation.
The ConsolidateChildren function can also be used to specify how consolidations are calculated in
multiple dimensions, as in the following example:
Argument Description
['World','Year']= This statement applies the ConsolidateChildren
ConsolidateChildren('Region','Month') function to both the World and Year consolidations. In
this case, World is calculated by summing all its
immediate children in the Region dimension, while
Year is calculated by summing its immediate children
in the Month dimension.

2. DIMNM

Returns the element of a dimension that corresponds to the index argument.

Syntax
DIMNM(server_name:dimension, index)
Argument Description
dimension A valid dimension name qualified by the server name.
index A value less than or equal to the number of elements in the dimension.
If this argument is less than 1, or greater than the number of elements in the
dimension, the function returns 0.

Example
DIMNM(planning_sample:'Region',2)
This example returns 'Belgium', which is the element within the Region dimension with an index
value of 2.

3. DIMSIZ

Returns the number of elements within a specified dimension.

Syntax: DIMSIZ(dimension)

Exp:

4. DNEXT

Returns the element name that follows the element specified as an argument to the function.
Syntax: DNEXT(dimension, element)

Syntax
DNEXT(dimension, element)
Argument Description
dimension A valid dimension name.
Some installations may need to qualify the dimension name with the server name, as
in server_name:dimension.
element The name of an element within the dimension. This argument can also be the name
of an alias for a dimension element.

Exp:

5. DNLEV

Returns the number of levels in a dimension.

Syntax
DNLEV(dimension)
Argument Description
dimension A valid dimension name.
Some installations may need to qualify the dimension name with the server name, as
in server_name:dimension.
Exp: DNLEV('Region')
In the Region dimension, the various nations (Level 0) add up to regions (Level 1). The regions
then add up to super-regions (Level 2), which in turn add up to the world (Level 3).

There are four levels in the Region dimension, so the example returns the value 4.

6. TABDIM

Returns the dimension name that corresponds to the index argument.

Syntax
TABDIM(cube, index)
Argument Description
cube A valid cube name.
index A positive value less than or equal to the total number of dimensions in the cube.

Exp:

TABDIM('SalesCube',3)
The cube SalesCube contains five dimensions: account1, actvsbud, model, month, and region. The
example returns model, the third dimension of SalesCube.

Element Information Rules Functions

1 DIMIX

Returns the index number of an element within a dimension.

Syntax
DIMIX(server_name:dimension, element)
Argument Description
Argument Description
dimension A valid dimension name qualified by the server name.
element The name of an element within the dimension.
If the element is not a member of the dimension specified, the function returns 0.

2. DTYPE

Returns information about the element type of a specified element. It returns N for numeric, S for string,
C for consolidated.
Syntax: DTYPE(Dimsion, Element)

Exp:

DTYPE('Region','Europe')
The element Europe is a consolidated element of the Region dimension, so the example returns C.

3. ELCOMP

Returns the name of a child of a consolidated element in a specified dimension. If the element argument
is not a consolidated element, the function returns 0.

Syntax
ELCOMP(dimension, element, position)
Argument Description
dimension A valid dimension name.
element The name of a consolidated element within the dimension.
position A positive value less than or equal to the total number of children in the specified
element.

Exp:

ELCOMP('Region','Central Europe',2)
In the dimension Region, the consolidated element Central Europe is a consolidation of the children
France and Germany. Germany is in the second position in this consolidation. Accordingly, the example
returns Germany.
4. ELCOMPN

Returns the number of components in a specified element. If the element argument is not a
consolidated element, the function returns 0.

Syntax
ELCOMPN(dimension, element)
Argument Description
dimension A valid dimension name.
element The name of a consolidated element within the dimension.

Exp:

5. ELISANC

Determines whether element1 is an ancestor of element2 in the specified dimension. The function
returns 1 if element1 is an ancestor of element2, otherwise the function returns 0.

Syntax:

ELISANC(dimension, element1, element2)

Argument Description
dimension A valid dimension name.
element1 The name of an element within the dimension.
element2 The name of an element within the dimension.

Exp:

6. ELISCOMP

Determines whether element1 is a child of element2 in the specified dimension. The function returns 1
if element1 is a child of element2, otherwise the function returns 0.

Syntax:

ELISCOMP(dimension, element1, element2)

Argument Description
dimension A valid dimension name.
element1 The name of an element within the dimension.
element2 The name of an element within the dimension.

Exp:

ELISCOMP('Region','Germany','Central Europe')
In the dimension Region, the element Central Europe is a consolidation of two elements, Germany and
France. The example returns 1.

->Note - this function returns 1 only for immediate children. In the above example, Germany is a child
of Central Europe. Further, Central Europe is a child of Europe.

However, because the function returns 1 only for immediate children, the following example returns 0:
ELISCOMP('Region','Germany','Europe')

7. ELISPAR

Determines whether element1 is a parent of element2 in the specified dimension. The function returns
1 if element1 is a parent of element2, otherwise the function returns 0.

Syntax:

ELISPAR(dimension, element1, element2)

Argument Description
dimension A valid dimension name.
element1 The name of an element within the dimension.
element2 The name of an element within the dimension.

Exp:

ELISPAR('Region','Central Europe','Germany')
In the dimension Region, the consolidated element Central Europe is the parent of both Germany and
France. Accordingly, the example returns 1.
Note this function returns 1 only for immediate parents. In the above example, Europe is a parent of
Central Europe. Further, Central Europe is a parent of Germany. However, because Europe is not an
immediate parent of Germany, the following example returns 0:
Note ELISPAR('Region','Europe','Germany')
8. ELLEV

Returns the level of an element within a dimension.

Syntax:

ELLEV(dimension, element)
Argument Description
dimension A valid dimension name.
element The name of an element within the dimension.

Exp:

ELLEV('Region','Europe')
In the Region dimension, individual nations (Level 0) add up to regions (Level 1). The regions then add up
to super-regions (Level 2), which in turn add up to the world (Level 3). The example returns 2, as Europe
is a Level 2 element.

9. ELPAR

Returns the parent of an element in a specified dimension

Syntax:

ELPAR(dimension, element, index)

Argument Description
dimension A valid dimension name.
element The name of an element within the dimension.
index A positive value less than or equal to the total number of consolidated elements
(parents) that use the element argument as a child.
Exp:

ELPAR('Model','Wagon 4WD',2)
In the dimension Model, the element Wagon 4WD is a child of both Total Wagons and Total 4WD.
Therefore, both Total Wagons and Total 4WD are parents of Wagon 4WD. In the structure of the Model
dimension, Total Wagons is defined first, Total 4WD is defined second.

The example returns Total 4WD, as this is the second instance of a parent to Wagon 4WD within the
Model dimension.

10. ELPARN

Returns the number of parents of an element in a specified dimension.

Syntax:

ELPARN(dimension, element)
Argument Description
dimension A valid dimension name.
element The name of an element within the dimension.

Exp:

ELPARN('Model','Wagon 4WD')
In the Model dimension, the element Wagon 4WD is a child of both Total Wagons and Total 4WD.
Therefore, both Total Wagons and Total 4WD are parents of Wagon 4WD. The function returns 2.

11. ELWEIGHT

Returns the weight of a child in a consolidated element.

Syntax:

ELWEIGHT(dimension, element1, element2)

Argument Description
dimension A valid dimension name.
element1 The name of a consolidated element within the dimension.
element2 The name of a child of the consolidated element.
Exp:

ELWEIGHT('Account1','Gross margin','Variable Costs')

The element Variable Costs, which is a child of Gross margin, has a weight of -1.
The example returns -1.