IBM Planning Analytics

2.0

Reference

IBM
 Note
Before you use this information and the product it supports, read the information in “Notices” on page
423.

Product Information
This document applies to IBM Planning Analytics Version 2.0 and might also apply to subsequent releases.
Licensed Materials - Property of IBM
Last updated: 2025-10-03
© Copyright International Business Machines Corporation 2007, 2025.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Introduction........................................................................................................ xv

Chapter 1. Windows and Dialog Boxes....................................................................1

Action Button Properties Dialog Box........................................................................................................... 1
Process Tab.............................................................................................................................................2
Worksheet Tab........................................................................................................................................ 2
Appearance Tab...................................................................................................................................... 4
Advanced Options Dialog Box......................................................................................................................4
Advanced Mapping Grid......................................................................................................................... 5
Attributes Editor........................................................................................................................................... 6
File Menu................................................................................................................................................ 7
Edit Menu................................................................................................................................................ 7
Format Options....................................................................................................................................... 7
Audit Log Window........................................................................................................................................ 9
Query Panel............................................................................................................................................ 9
Results Panel........................................................................................................................................ 11
Audit Log Details Window.......................................................................................................................... 12
Details Toolbar......................................................................................................................................12
Details Grid........................................................................................................................................... 13
Chore Setup Wizard................................................................................................................................... 13
Screen 1 (Step 1)..................................................................................................................................13
Screen 2 (Step 2)..................................................................................................................................14
Clients/Groups Window............................................................................................................................. 14
Security Menu.......................................................................................................................................14
Clients Menu......................................................................................................................................... 15
Groups Menu........................................................................................................................................ 15
Clients/Groups Grid..............................................................................................................................15
Clients Messaging Center Dialog Box........................................................................................................ 16
Create a Dimension Dialog Box................................................................................................................. 17
Create Server Replication Object Dialog Box............................................................................................ 17
Creating Cube Dialog Box.......................................................................................................................... 17
Cube Optimizer Dialog Box........................................................................................................................ 18
Cube Properties Dialog Box....................................................................................................................... 19
View section icons..................................................................................................................................... 19
Cube Viewer............................................................................................................................................... 20
File Menu.............................................................................................................................................. 20
Edit Menu..............................................................................................................................................21
View Menu............................................................................................................................................ 21
Options Menu....................................................................................................................................... 22
Delete Named Subsets Dialog Box............................................................................................................23
Delete Named Views Dialog Box............................................................................................................... 23
Dimension Editor........................................................................................................................................23
Dimension Menu...................................................................................................................................23
Edit Menu..............................................................................................................................................24
View Menu............................................................................................................................................ 26
Dimension Element Insert Dialog Box...................................................................................................... 27
Dimension Element Ordering Dialog Box.................................................................................................. 27
Dimension Element Properties Dialog Box............................................................................................... 28
Drill ............................................................................................................................................................ 28
Edit Formula Dialog Box.............................................................................................................................29

iii
 Edit Reference to Cube Dialog Box............................................................................................................29
Filter Elements by Attribute Dialog Box.................................................................................................... 30
Filter Elements by Level Dialog Box.......................................................................................................... 30
Filter Subset Dialog Box.............................................................................................................................30
Filter View Dialog Box................................................................................................................................ 32
Get View Dialog Box (In-Spreadsheet Browser)....................................................................................... 34
In-Spreadsheet Browser Menu................................................................................................................. 34
Message Log Window.................................................................................................................................35
File Menu.............................................................................................................................................. 35
Edit Menu..............................................................................................................................................35
Help Menu.............................................................................................................................................36
New Attribute Dialog Box...........................................................................................................................36
Open Subset Dialog Box............................................................................................................................ 36
Open View Dialog Box................................................................................................................................36
Print Report Wizard....................................................................................................................................36
All Screens............................................................................................................................................ 36
Screen 1 of 3.........................................................................................................................................37
Screen 2 of 3.........................................................................................................................................37
Screen 3 of 3.........................................................................................................................................38
Process Options Dialog Box.......................................................................................................................40
Replicate Cube Dialog Box.........................................................................................................................41
Cube Information................................................................................................................................. 41
Rule Information.................................................................................................................................. 41
Dimension Information........................................................................................................................ 42
Rules Editor................................................................................................................................................ 43
File Menu.............................................................................................................................................. 43
Edit Menu..............................................................................................................................................43
View Menu............................................................................................................................................ 45
Insert Menu.......................................................................................................................................... 45
Tools Menu............................................................................................................................................45
Save Subset Dialog Box............................................................................................................................. 46
Save View Dialog Box.................................................................................................................................46
Save View Dialog Box (In-Spreadsheet Browser)..................................................................................... 46
Security Assignments Dialog Box..............................................................................................................47
Assignments Grid................................................................................................................................. 47
Access Privileges.................................................................................................................................. 47
Select Dimension..................................................................................................................................51
Select Cube Dialog Box..............................................................................................................................51
Select Cube for Rules Dialog Box.............................................................................................................. 51
Select Dimension Dialog Box.....................................................................................................................51
Select Element Dialog Box.........................................................................................................................51
Server Explorer (Main Window)................................................................................................................. 51
File Menu.............................................................................................................................................. 51
Dynamic Menu...................................................................................................................................... 52
Edit Menu..............................................................................................................................................62
View Menu............................................................................................................................................ 62
Subset Editor..............................................................................................................................................62
Subset Menu.........................................................................................................................................63
Edit Menu..............................................................................................................................................63
View Menu............................................................................................................................................ 65
Tools Menu............................................................................................................................................66
Aliases Dialog Box......................................................................................................................................67
TM1 Options Dialog Box............................................................................................................................ 67
Login Parameters..................................................................................................................................67
Local Server.......................................................................................................................................... 67
Admin Server Transport Layer Security............................................................................................... 68
Transaction Log Query Dialog Box.............................................................................................................68
Transaction Log Query Results Dialog Box................................................................................................69

iv
 TurboIntegrator Editor...............................................................................................................................70
File Menu.............................................................................................................................................. 70
Edit Menu..............................................................................................................................................70
Data Source Tab....................................................................................................................................71
Preview Grid......................................................................................................................................... 83
Variables Tab........................................................................................................................................ 83
Maps Tab...............................................................................................................................................85
Advanced Tab....................................................................................................................................... 89
Schedule Tab........................................................................................................................................ 90
View Extract Window................................................................................................................................. 91
View Styles Dialog Box...............................................................................................................................91

Chapter 2. Rules functions................................................................................... 93

Arithmetic operators in Planning Analytics rules......................................................................................93
Comparison operators in Planning Analytics rules................................................................................... 93
Logical operators in Planning Analytics rules........................................................................................... 93
Attribute rules functions............................................................................................................................94
ATTRN................................................................................................................................................... 94
ATTRS................................................................................................................................................... 95
CubeATTRN.......................................................................................................................................... 96
CubeATTRS........................................................................................................................................... 96
DimensionATTRN................................................................................................................................. 97
DimensionATTRS..................................................................................................................................97
ElementAttrN........................................................................................................................................98
ElementAttrS........................................................................................................................................ 98
Consolidation calculation rules functions................................................................................................. 99
ConsolidatedAvg...................................................................................................................................99
ConsolidateChildren...........................................................................................................................100
ConsolidatedCount.............................................................................................................................102
ConsolidatedCountUnique.................................................................................................................103
ConsolidatedMax................................................................................................................................104
ConsolidatedMin................................................................................................................................ 106
Cube data rules functions........................................................................................................................107
CellValueN.......................................................................................................................................... 107
CellValueS...........................................................................................................................................107
DB....................................................................................................................................................... 108
ISLEAF................................................................................................................................................ 109
ISUNDEFINEDCELLVALUE................................................................................................................. 109
UNDEF................................................................................................................................................ 110
UNDEFINEDCELLVALUE..................................................................................................................... 110
UNDEFVALS........................................................................................................................................ 111
Date and time rules functions................................................................................................................. 112
DATE................................................................................................................................................... 112
DATES................................................................................................................................................. 113
DAY..................................................................................................................................................... 114
DAYNO................................................................................................................................................ 114
MONTH............................................................................................................................................... 114
NOW....................................................................................................................................................115
TIME................................................................................................................................................... 115
TIMST................................................................................................................................................. 115
TIMVL .................................................................................................................................................117
TODAY.................................................................................................................................................119
YEAR................................................................................................................................................... 120
Dimension Information Rules Functions................................................................................................ 120
DIMIX................................................................................................................................................. 121
DIMNM................................................................................................................................................121
DIMSIZ ...............................................................................................................................................122

v
 DNEXT.................................................................................................................................................122
DNLEV.................................................................................................................................................122
DTYPE ................................................................................................................................................ 123
TABDIM...............................................................................................................................................123
Element Information Rules Functions.................................................................................................... 124
ELCOMP ............................................................................................................................................. 124
ELCOMPN............................................................................................................................................124
ElementComponent .......................................................................................................................... 125
ElementComponentCount................................................................................................................. 125
ElementCount ....................................................................................................................................126
ElementFirst....................................................................................................................................... 126
ElementIndex.....................................................................................................................................127
ElementIsAncestor............................................................................................................................ 127
ElementIsComponent........................................................................................................................128
ElementIsParent ............................................................................................................................... 128
ElementLevel......................................................................................................................................129
ElementName.....................................................................................................................................130
ElementNext.......................................................................................................................................130
ElementParent................................................................................................................................... 131
ElementParentCount..........................................................................................................................131
ElementType ......................................................................................................................................132
ElementWeight .................................................................................................................................. 132
ELISANC............................................................................................................................................. 133
ELISCOMP ..........................................................................................................................................133
ELISPAR ............................................................................................................................................. 134
ELLEV.................................................................................................................................................. 135
ELPAR................................................................................................................................................. 135
ELPARN...............................................................................................................................................136
ELWEIGHT ......................................................................................................................................... 136
LevelCount..........................................................................................................................................137
Financial Rules Functions........................................................................................................................137
FV........................................................................................................................................................137
PAYMT ................................................................................................................................................138
PV........................................................................................................................................................138
Hierarchy Rules Functions.......................................................................................................................139
Hierarchy............................................................................................................................................ 139
HierarchyCount.................................................................................................................................. 139
HierarchyIndex...................................................................................................................................140
HierarchyN..........................................................................................................................................140
Logical Rules Functions........................................................................................................................... 141
CONTINUE.......................................................................................................................................... 141
IF.........................................................................................................................................................141
STET....................................................................................................................................................142
Mathematical Rules Functions................................................................................................................ 142
ABS..................................................................................................................................................... 142
ACOS...................................................................................................................................................143
ASIN....................................................................................................................................................143
ATAN................................................................................................................................................... 143
COS..................................................................................................................................................... 144
EXP..................................................................................................................................................... 144
INT...................................................................................................................................................... 144
ISUND................................................................................................................................................. 145
LN........................................................................................................................................................145
LOG..................................................................................................................................................... 145
MAX.....................................................................................................................................................146
MIN .................................................................................................................................................... 146
MOD.................................................................................................................................................... 146
RAND.................................................................................................................................................. 147

vi
 ROUND................................................................................................................................................147
ROUNDP............................................................................................................................................. 148
SIGN................................................................................................................................................... 148
SIN...................................................................................................................................................... 149
SQRT................................................................................................................................................... 149
TAN..................................................................................................................................................... 149
Text Rules Functions................................................................................................................................150
CAPIT..................................................................................................................................................150
CHAR...................................................................................................................................................150
CODE...................................................................................................................................................151
CODEW............................................................................................................................................... 151
DELET................................................................................................................................................. 151
FILL..................................................................................................................................................... 152
INSRT..................................................................................................................................................152
LONG...................................................................................................................................................153
LOWER................................................................................................................................................ 153
NUMBR .............................................................................................................................................. 153
SCAN...................................................................................................................................................154
STR......................................................................................................................................................154
SUBST................................................................................................................................................. 156
TRIM................................................................................................................................................... 157
UPPER.................................................................................................................................................157
Miscellaneous Rules Functions............................................................................................................... 157
FEEDERS.............................................................................................................................................157
FEEDSTRINGS.................................................................................................................................... 158
SKIPCHECK........................................................................................................................................ 158

Chapter 3. Macro Functions............................................................................... 159

Accessing Macro Functions from Microsoft Excel 2010 and Later........................................................ 159
Accessing Macro Functions from VBA Modules......................................................................................159
D_PICK..................................................................................................................................................... 159
D_FSAVE...................................................................................................................................................160
D_SAVE.....................................................................................................................................................160
DBProportionalSpread.............................................................................................................................161
E_PICK..................................................................................................................................................... 161
I_EXPORT................................................................................................................................................ 163
I_NAMES ................................................................................................................................................. 163
I_PROCESS.............................................................................................................................................. 164
M_CLEAR.................................................................................................................................................. 164
OPTGET.................................................................................................................................................... 165
OPTSET.................................................................................................................................................... 165
PublishSubset.......................................................................................................................................... 166
PublishView..............................................................................................................................................167
QUDEFINE................................................................................................................................................167
QUDEFINEEX........................................................................................................................................... 169
QUEXPORT............................................................................................................................................... 170
QULOOP................................................................................................................................................... 171
QUSUBSET............................................................................................................................................... 172
R_SAVE.....................................................................................................................................................172
SUBDEFINE..............................................................................................................................................173
SUBPICK.................................................................................................................................................. 173
T_CLEAR................................................................................................................................................... 174
T_CREATE................................................................................................................................................. 174
T_CREATE16............................................................................................................................................ 175
T_PICK..................................................................................................................................................... 175
T_SAVE..................................................................................................................................................... 176
TM1RECALC............................................................................................................................................. 176

vii
 TM1RECALC1........................................................................................................................................... 176
VUSLICE................................................................................................................................................... 177
W_DBSENABLE........................................................................................................................................ 177

Chapter 4. Worksheet Functions........................................................................ 179

DBR.......................................................................................................................................................... 179
DBRA........................................................................................................................................................ 180
DBRW....................................................................................................................................................... 180
DBS...........................................................................................................................................................181
DBSA........................................................................................................................................................ 182
DBSS.........................................................................................................................................................183
DBSW....................................................................................................................................................... 183
DFRST.......................................................................................................................................................184
DIMIX....................................................................................................................................................... 184
DIMNM..................................................................................................................................................... 185
DIMSIZ..................................................................................................................................................... 185
DNEXT...................................................................................................................................................... 186
DNLEV...................................................................................................................................................... 186
DTYPE.......................................................................................................................................................187
ELCOMP....................................................................................................................................................187
ELCOMPN................................................................................................................................................. 188
ELISCOMP................................................................................................................................................ 188
ELISPAR................................................................................................................................................... 189
ELLEV....................................................................................................................................................... 190
ELPAR....................................................................................................................................................... 190
ELPARN.................................................................................................................................................... 191
ELSLEN..................................................................................................................................................... 191
ELWEIGHT................................................................................................................................................192
MakeQuery3.............................................................................................................................................193
SUBNM..................................................................................................................................................... 194
SUBSIZ.....................................................................................................................................................194
TABDIM.................................................................................................................................................... 195
TM1ELLIST...............................................................................................................................................195
TM1GLOBALSANDBOX............................................................................................................................ 198
TM1INFO..................................................................................................................................................198
TM1PRIMARYDBNAME............................................................................................................................200
TM1RptElIsConsolidated........................................................................................................................ 200
TM1RptElIsExpanded..............................................................................................................................200
TM1RptElLev............................................................................................................................................201
TM1RptFilter............................................................................................................................................ 201
TM1RptRow............................................................................................................................................. 202
TM1RptTitle............................................................................................................................................. 203
TM1RptView.............................................................................................................................................204
TM1User...................................................................................................................................................205
TM1Val..................................................................................................................................................... 205
VIEW.........................................................................................................................................................207

Chapter 5. TurboIntegrator Functions.................................................................209

TurboIntegrator reserved words............................................................................................................. 209
ASCII and Text TurboIntegrator Functions.............................................................................................209
ASCIIDelete........................................................................................................................................210
ASCIIOutput....................................................................................................................................... 210
ASCIIOutputOpen.............................................................................................................................. 211
NumberToString................................................................................................................................. 212
NumberToStringEx............................................................................................................................. 213
SetInputCharacterSet........................................................................................................................ 213
SetOutputCharacterSet......................................................................................................................216

viii
 SetOutputEscapeDoubleQuote......................................................................................................... 216
StringToNumber................................................................................................................................. 217
StringToNumberEx............................................................................................................................. 217
TextOutput..........................................................................................................................................218
Attribute Manipulation TurboIntegrator Functions................................................................................ 219
ATTRNL............................................................................................................................................... 219
ATTRSL............................................................................................................................................... 220
AttrDelete........................................................................................................................................... 221
AttrInsert............................................................................................................................................222
AttrPutN..............................................................................................................................................222
AttrPutS.............................................................................................................................................. 223
ChoreAttrDelete................................................................................................................................. 224
ChoreAttrInsert.................................................................................................................................. 224
ChoreAttrN......................................................................................................................................... 225
ChoreAttrNL........................................................................................................................................225
ChoreAttrPutN.................................................................................................................................... 226
ChoreAttrPutS.................................................................................................................................... 227
ChoreAttrS.......................................................................................................................................... 228
ChoreAttrSL........................................................................................................................................ 228
CubeAttrDelete...................................................................................................................................229
CubeAttrInsert................................................................................................................................... 230
CubeAttrPutN..................................................................................................................................... 230
CubeAttrPutS......................................................................................................................................231
CubeATTRNL...................................................................................................................................... 232
CubeATTRSL.......................................................................................................................................232
DimensionAttrDelete..........................................................................................................................233
DimensionAttrInsert.......................................................................................................................... 234
DimensionAttrPutN............................................................................................................................ 234
DimensionAttrPutS.............................................................................................................................235
DimensionATTRNL............................................................................................................................. 236
DimensionATTRSL..............................................................................................................................237
ElementATTRNL................................................................................................................................. 238
ElementATTRSL..................................................................................................................................239
ElementAttrPutN................................................................................................................................ 240
ElementAttrPutS................................................................................................................................ 241
ElementAttrInsert.............................................................................................................................. 242
ElementAttrDelete............................................................................................................................. 242
HierarchyAttrPutN..............................................................................................................................243
HierarchyAttrPutS.............................................................................................................................. 244
HierarchyATTRN................................................................................................................................. 244
HierarchyATTRS................................................................................................................................. 245
HierarchyATTRNL............................................................................................................................... 245
HierarchyATTRSL................................................................................................................................246
HierarchySubsetATTRS......................................................................................................................247
HierarchySubsetATTRN..................................................................................................................... 248
HierarchySubsetATTRSL.................................................................................................................... 248
HierarchySubsetATTRNL....................................................................................................................249
HierarchySubsetAttrPutS...................................................................................................................250
HierarchySubsetAttrPutN.................................................................................................................. 251
HierarchySubsetAttrInsert................................................................................................................ 252
HierarchySubsetAttrDelete................................................................................................................253
ProcessAttrDelete.............................................................................................................................. 253
ProcessAttrInsert............................................................................................................................... 254
ProcessAttrN...................................................................................................................................... 254
ProcessAttrNL.................................................................................................................................... 255
ProcessAttrPutN.................................................................................................................................256
ProcessAttrPutS................................................................................................................................. 257
ProcessAttrS.......................................................................................................................................258

ix
 ProcessAttrSL..................................................................................................................................... 258
SubsetATTRS......................................................................................................................................259
SubsetATTRN..................................................................................................................................... 260
SubsetATTRSL.................................................................................................................................... 260
SubsetATTRNL................................................................................................................................... 261
SubsetAttrPutS...................................................................................................................................262
SubsetAttrPutN.................................................................................................................................. 263
SubsetAttrInsert................................................................................................................................ 264
SubsetAttrDelete................................................................................................................................264
ViewAttrDelete................................................................................................................................... 265
ViewAttrInsert.................................................................................................................................... 265
ViewAttrN........................................................................................................................................... 266
ViewAttrNL......................................................................................................................................... 266
ViewAttrPutN......................................................................................................................................267
ViewAttrPutS...................................................................................................................................... 268
ViewAttrS............................................................................................................................................269
ViewAttrSL.......................................................................................................................................... 269
Chore Management TurboIntegrator Functions..................................................................................... 270
ChoreError.......................................................................................................................................... 270
ChoreQuit........................................................................................................................................... 271
ChoreRollback.................................................................................................................................... 271
SetChoreVerboseMessages............................................................................................................... 271
Cube Manipulation TurboIntegrator Functions.......................................................................................272
AddCubeDependency........................................................................................................................ 272
CellGetN............................................................................................................................................. 273
CellGetS..............................................................................................................................................274
CellIncrementN.................................................................................................................................. 274
CellIsUpdateable............................................................................................................................... 275
CellPutN..............................................................................................................................................276
CellPutProportionalSpread................................................................................................................ 276
CellPutS.............................................................................................................................................. 277
CubeClearData................................................................................................................................... 278
CubeCreate.........................................................................................................................................278
CubeDestroy.......................................................................................................................................279
CubeDimensionCountGet.................................................................................................................. 279
CubeExists..........................................................................................................................................280
CubeGetLogChanges..........................................................................................................................280
CubeSaveData.................................................................................................................................... 281
CubeSetConnParams......................................................................................................................... 282
CubeSetLogChanges.......................................................................................................................... 282
CubeTimeLastUpdated.......................................................................................................................283
CubeUnload........................................................................................................................................283
Data Reservation TurboIntegrator Functions......................................................................................... 284
CubeDataReservationAcquire............................................................................................................284
CubeDataReservationRelease........................................................................................................... 285
CubeDataReservationReleaseAll.......................................................................................................286
CubeDataReservationGet.................................................................................................................. 286
CubeDataReservationGetConflicts.................................................................................................... 288
Date and Time TurboIntegrator Functions..............................................................................................288
FormatDate.........................................................................................................................................289
NewDateFormatter.............................................................................................................................289
ParseDate........................................................................................................................................... 290
Dimension Manipulation TurboIntegrator Functions..............................................................................291
DimensionCreate................................................................................................................................291
DimensionDeleteAllElements............................................................................................................291
DimensionDeleteElements................................................................................................................ 292
DimensionDestroy..............................................................................................................................292
DimensionElementComponentAdd................................................................................................... 293

x
 DimensionElementComponentAddDirect......................................................................................... 293
DimensionElementComponentDelete...............................................................................................294
DimensionElementComponentDeleteDirect..................................................................................... 294
DimensionElementDelete.................................................................................................................. 295
DimensionElementDeleteDirect........................................................................................................ 296
DimensionElementExists................................................................................................................... 297
DimensionElementInsert...................................................................................................................297
DimensionElementInsertDirect......................................................................................................... 298
DimensionElementPrincipalName.....................................................................................................299
DimensionExists.................................................................................................................................300
DimensionHierarchyCreate................................................................................................................300
DimensionSortOrder.......................................................................................................................... 301
DimensionTimeLastUpdated..............................................................................................................302
DimensionTopElementInsert............................................................................................................. 302
DimensionTopElementInsertDirect................................................................................................... 303
DimensionUpdateDirect.....................................................................................................................304
Hierarchy Manipulation TurboIntegrator Functions............................................................................... 304
CreateHierarchyByAttribute.............................................................................................................. 305
HierarchyContainsAllLeaves.............................................................................................................. 305
HierarchyCreate................................................................................................................................. 306
HierarchyDeleteAllElements..............................................................................................................306
HierarchyDeleteElements..................................................................................................................307
HierarchyDestroy............................................................................................................................... 307
HierarchyElementComponentAdd.....................................................................................................308
HierarchyElementComponentAddDirect...........................................................................................308
HierarchyElementComponentDelete................................................................................................ 309
HierarchyElementComponentDeleteDirect.......................................................................................310
HierarchyElementDelete....................................................................................................................311
HierarchyElementDeleteDirect..........................................................................................................311
HierarchyElementExists.....................................................................................................................312
HierarchyElementInsert.................................................................................................................... 312
HierarchyElementInsertDirect...........................................................................................................313
HierarchyElementPrincipalName...................................................................................................... 314
HierarchyExists.................................................................................................................................. 315
HierarchyHasOrphanedLeaves.......................................................................................................... 315
HierarchySortOrder............................................................................................................................ 316
HierarchyTimeLastUpdated............................................................................................................... 317
HierarchyTopElementInsert...............................................................................................................318
HierarchyTopElementInsertDirect.....................................................................................................318
HierarchyUpdateDirect...................................................................................................................... 319
ODBC TurboIntegrator Functions............................................................................................................320
ODBCClose......................................................................................................................................... 320
ODBCOpen..........................................................................................................................................320
ODBCOPENEx.....................................................................................................................................321
ODBCOutput....................................................................................................................................... 321
SetODBCUnicodeInterface................................................................................................................ 322
Process Control TurboIntegrator Functions........................................................................................... 322
ExecuteCommand.............................................................................................................................. 322
ExecuteProcess.................................................................................................................................. 323
GetProcessErrorFileDirectory............................................................................................................ 325
GetProcessErrorFilename..................................................................................................................325
GetProcessName............................................................................................................................... 325
If......................................................................................................................................................... 326
ItemReject..........................................................................................................................................326
ItemSkip............................................................................................................................................. 327
ProcessBreak..................................................................................................................................... 327
ProcessError....................................................................................................................................... 327
ProcessExists..................................................................................................................................... 328

xi
 ProcessExitByChoreRollback.............................................................................................................328
ProcessExitByProcessRollback......................................................................................................... 328
ProcessQuit........................................................................................................................................ 329
ProcessRollback................................................................................................................................. 329
RunProcess.........................................................................................................................................330
Sleep...................................................................................................................................................330
Synchronized...................................................................................................................................... 331
While...................................................................................................................................................332
Rules Management TurboIntegrator Functions......................................................................................333
CubeProcessFeeders......................................................................................................................... 333
CubeRuleAppend............................................................................................................................... 333
CubeRuleDestroy............................................................................................................................... 334
CubeRuleGet...................................................................................................................................... 335
CubeRuleSet.......................................................................................................................................335
DeleteAllPersistentFeeders............................................................................................................... 336
ForceSkipCheck..................................................................................................................................337
RuleLoadFromFile.............................................................................................................................. 337
RuleLoadFromFileEx.......................................................................................................................... 338
Sandbox Functions.................................................................................................................................. 339
GetUseActiveSandboxProperty......................................................................................................... 339
ServerActiveSandboxGet................................................................................................................... 339
ServerActiveSandboxSet....................................................................................................................340
ServerSandboxClone..........................................................................................................................340
ServerSandboxCreate........................................................................................................................ 341
ServerSandboxesDelete.....................................................................................................................341
ServerSandboxDiscardAllChanges.................................................................................................... 344
ServerSandboxMerge.........................................................................................................................345
ServerSandboxExists......................................................................................................................... 346
ServerSandboxGet............................................................................................................................. 346
ServerSandboxListCountGet..............................................................................................................347
SetUseActiveSandboxProperty..........................................................................................................348
Security TurboIntegrator Functions........................................................................................................ 348
AddClient............................................................................................................................................ 349
AddGroup........................................................................................................................................... 349
AssignClientToGroup..........................................................................................................................349
AssignClientPassword........................................................................................................................350
AssociateCAMIDToGroup...................................................................................................................350
CellSecurityCubeCreate..................................................................................................................... 351
CellSecurityCubeDestroy................................................................................................................... 351
DeleteClient........................................................................................................................................352
DeleteGroup....................................................................................................................................... 352
ElementSecurityGet........................................................................................................................... 353
ElementSecurityPut........................................................................................................................... 353
HierarchyElementSecurityGet........................................................................................................... 354
HierarchyElementSecurityPut........................................................................................................... 354
RemoveCAMIDAssociation................................................................................................................ 355
RemoveCAMIDAssociationFromGroup............................................................................................. 356
RemoveClientFromGroup.................................................................................................................. 356
SetHierarchyGroupsSecurity............................................................................................................. 357
SetHierarchyElementGroupsSecurity................................................................................................357
SetDimensionGroupsSecurity............................................................................................................358
SetElementGroupsSecurity............................................................................................................... 359
SecurityOverlayGlobalLockCell......................................................................................................... 359
SecurityOverlayCreateGlobalDefault................................................................................................ 360
SecurityOverlayDestroyGlobalDefault...............................................................................................361
SecurityOverlayGlobalLockNode....................................................................................................... 361
SecurityRefresh.................................................................................................................................. 362
Server Manipulation TurboIntegrator Functions.................................................................................... 362

xii
 BatchUpdateFinish.............................................................................................................................362
BatchUpdateFinishWait..................................................................................................................... 363
DisableBulkLoadMode....................................................................................................................... 364
EnableBulkLoadMode........................................................................................................................ 365
RefreshMdxHierarchy........................................................................................................................ 365
SaveDataAll........................................................................................................................................ 366
ServerShutdown.................................................................................................................................367
Subset Manipulation TurboIntegrator Functions....................................................................................367
HierarchySubsetAliasGet...................................................................................................................368
HierarchySubsetAliasSet................................................................................................................... 368
HierarchySubsetCreate......................................................................................................................368
HierarchySubsetDeleteAllElements.................................................................................................. 369
HierarchySubsetDestroy.................................................................................................................... 370
HierarchySubsetElementExists......................................................................................................... 370
HierarchySubsetElementDelete........................................................................................................ 371
HierarchySubsetElementGetIndex....................................................................................................371
HierarchySubsetElementInsert......................................................................................................... 372
HierarchySubsetExists....................................................................................................................... 373
HierarchySubsetGetSize.................................................................................................................... 373
HierarchySubsetGetElementName................................................................................................... 374
HierarchySubsetIsAllSet....................................................................................................................374
HierarchySubsetMDXGet................................................................................................................... 375
HierarchySubsetMDXSet....................................................................................................................375
PublishSubset.................................................................................................................................... 376
SubsetAliasGet...................................................................................................................................377
SubsetAliasSet................................................................................................................................... 377
SubsetCreate......................................................................................................................................377
SubsetCreateByMDX.......................................................................................................................... 379
SubsetDeleteAllElements.................................................................................................................. 380
SubsetDestroy.................................................................................................................................... 381
SubsetElementDelete........................................................................................................................ 381
SubsetElementExists......................................................................................................................... 382
SubsetElementGetIndex................................................................................................................... 382
SubsetElementInsert......................................................................................................................... 383
SubsetExists....................................................................................................................................... 383
SubsetExpandAboveSet.....................................................................................................................384
SubsetFormatStyleSet....................................................................................................................... 384
SubsetGetElementName................................................................................................................... 385
SubsetGetSize.................................................................................................................................... 385
SubsetIsAllSet....................................................................................................................................386
SubsetMDXGet................................................................................................................................... 386
SubsetMDXSet....................................................................................................................................387
View Manipulation TurboIntegrator Functions....................................................................................... 388
PublishView........................................................................................................................................ 388
DisableMTQViewConstruct................................................................................................................ 389
EnableMTQViewConstruct................................................................................................................. 389
ViewColumnDimensionSet................................................................................................................ 390
ViewColumnSuppressZeroesSet....................................................................................................... 391
ViewConstruct.................................................................................................................................... 391
ViewCreate......................................................................................................................................... 392
ViewCreateByMDX............................................................................................................................. 393
ViewDestroy....................................................................................................................................... 394
ViewExists.......................................................................................................................................... 394
ViewExtractFilterByTitlesSet............................................................................................................. 395
ViewExtractSkipCalcsSet................................................................................................................... 396
ViewExtractSkipConsolidatedStringsSet...........................................................................................397
ViewExtractSkipRuleValuesSet......................................................................................................... 397
ViewExtractSkipZeroesSet................................................................................................................ 398

xiii
 ViewMDXSet....................................................................................................................................... 399
ViewMDXGet.......................................................................................................................................399
ViewRowDimensionSet...................................................................................................................... 400
ViewRowSuppressZeroesSet.............................................................................................................400
ViewSubsetAssign..............................................................................................................................401
ViewSuppressZeroesSet.................................................................................................................... 402
ViewTitleDimensionSet...................................................................................................................... 402
ViewTitleElementSet..........................................................................................................................403
ViewZeroOut.......................................................................................................................................403
Miscellaneous TurboIntegrator Functions.............................................................................................. 404
AddInfoCubeRestriction.................................................................................................................... 404
ExecuteJavaN.....................................................................................................................................405
ExecuteJavaS..................................................................................................................................... 406
Expand................................................................................................................................................407
FileExists............................................................................................................................................ 407
LogOutput...........................................................................................................................................408
TM1User............................................................................................................................................. 409
WildcardFileSearch............................................................................................................................ 409

Chapter 6. TurboIntegrator Variables................................................................. 411

TurboIntegrator Local Variables..............................................................................................................411
DatasourceASCIIDecimalSeparator.................................................................................................. 411
DatasourceASCIIDelimiter................................................................................................................ 411
DatasourceASCIIHeaderRecords...................................................................................................... 412
DatasourceASCIIQuoteCharacter..................................................................................................... 412
DatasourceASCIIThousandSeparator............................................................................................... 413
DatasourceCubeview......................................................................................................................... 413
DatasourceDimensionSubset............................................................................................................ 413
DatasourceJsonRootPointer.............................................................................................................. 414
DatasourceJsonVariableMapping...................................................................................................... 414
DatasourceNameForServer............................................................................................................... 415
DatasourceNameForClient.................................................................................................................415
DatasourcePassword......................................................................................................................... 415
DatasourceQuery............................................................................................................................... 416
DatasourceType..................................................................................................................................416
DatasourceUsername........................................................................................................................ 416
MinorErrorLogMax..............................................................................................................................416
NValue................................................................................................................................................ 417
OnMinorErrorDoItemSkip.................................................................................................................. 417
SValue.................................................................................................................................................418
[Link] file.................................................................................................................... 418
Value_Is_String.................................................................................................................................. 419
TurboIntegrator Global Variables............................................................................................................419
NumericGlobalVariable('VariableName');......................................................................................... 420
StringGlobalVariable('VariableName');..............................................................................................420
Implicit Global Variables......................................................................................................................... 420
DataMinorErrorCount......................................................................................................................... 420
MetadataMinorErrorCount................................................................................................................. 420
ProcessReturnCode............................................................................................................................421
PrologMinorErrorCount...................................................................................................................... 421
TurboIntegrator User Variables...............................................................................................................422

Notices..............................................................................................................423

Index................................................................................................................ 427

xiv
Introduction
This document is intended for use with IBM® Planning Analytics.
This document is a collection of reference material for the IBM Planning Analytics software functions,
variables, and other programming elements.
Planning Analytics provides software solutions for the continuous management and monitoring of
Financial And Operational Performance Management across the enterprise.

Samples disclaimer
The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the Sample
Outdoors or Great Outdoors names, and Planning Sample depict fictitious business operations with
sample data used to develop sample applications for IBM and IBM customers. These fictitious records
include sample data for sales transactions, product distribution, finance, and human resources. Any
resemblance to actual names, addresses, contact numbers, or transaction values is coincidental. Other
sample files may contain fictional data manually or machine generated, factual data compiled from
academic or public sources, or data used with permission of the copyright holder, for use as sample data
to develop sample applications. Product names referenced may be the trademarks of their respective
owners. Unauthorized duplication is prohibited.

Accessibility features
Accessibility features help users who have a physical disability, such as restricted mobility or limited
vision, to use information technology products.
This product does not currently support accessibility features that help users with a physical disability,
such as restricted mobility or limited vision, to use this product.

Forward-looking statements
This documentation describes the current functionality of the product. References to items that are
not currently available may be included. No implication of any future availability should be inferred.
Any such references are not a commitment, promise, or legal obligation to deliver any material, code,
or functionality. The development, release, and timing of features or functionality remain at the sole
discretion of IBM.

Security considerations
For security considerations for IBM Planning Analytics, see Planning Analytics Installation and
Configuration. Information on managing user and group authentication can be found in the Managing
Users and Groups chapter of the TM1 Operations documentation.

© Copyright IBM Corp. 2007, 2025 xv

xvi IBM Planning Analytics: Reference
Chapter 1. Windows and Dialog Boxes
This section describes all significant IBM Planning Analytics windows and dialog boxes.

Action Button Properties Dialog Box

Use the Action Button Properties dialog box to add TM1® Action buttons to a worksheet. You can configure
the button to run a process and/or navigate to another worksheet.
For examples and steps on using Action buttons in worksheets, see TM1 for Developers in the IBM
Knowledge Center ([Link]
Server
This list includes the names of all TM1 servers currently available on your network.
Select the server where the process or target worksheet is located for your Action button.
Connect
This button is available only when you are not connected to the server currently selected in the server
list box.
Click this button to connect to the server that you selected in the server list box.
Disconnect
This button is available only when you are connected to the server currently selected in the server list
box.
Click this button to disconnect from the server that you selected in the server box.
Action
Select the action that you want the Action button to perform when it is clicked.
• Run a TurboIntegrator Process
Select this option to configure an Action button that runs a process. When you select this option, the
Process tab becomes enabled.
• Go to another Worksheet
Select this option to configure an Action button that navigates to another worksheet. When you
select this option, the Worksheet tab becomes enabled.
• Run a Process, then go to a Worksheet
Select this option to configure an Action button that runs a process and then navigates to another
worksheet. When you select this option, both the Process and Worksheet tabs become enabled.
• Calculate/Rebuild Only
Select this option to recalculate or rebuild without running a TI process or navigating to a new
worksheet. This can be useful if you want to update only the current sheet or reload the original
version of an Active Form.
You can also use the Calculate tab to select the calculation operation that you want TM1 to perform
before running a TI process or navigating to another worksheet.
OK
Closes the Action Button Properties dialog box and inserts an Action button into your worksheet.
Cancel
Closes the Action Button Properties dialog box without inserting an Action button.

© Copyright IBM Corp. 2007, 2025 1

Process Tab
Use the Process tab to configure an Action button to run a process.
Process
Use this list to select the process you want to run in one of the following ways:
• To run a process that is available on the current server, select the process name from the list.
• To retrieve both the process name and parameter values from the current worksheet, select Get
Process info from Worksheet.
Options
Opens the Process Options dialog where you can control the behavior of the Action button before and
after the process is run.
For details, see the section “Process Options Dialog Box” on page 40.
Process Name
This option appears only when you select the Get Process info from Worksheet in the Process list.
Enter an Excel reference that provides the name of the process to run in one of the following ways.
• To reference a single cell, use the following format: =ColumnNameRowName. For example: =A1.
• To reference a named range in Excel, use the following format: =NameOfRange
• To select the cell from the current worksheet, click the Excel Reference button next to the Process
Name box.
Parameters
Enter values for the process parameters, depending on how you selected the process name from the
Process list.
• If you selected a process from the Process list, the Parameters grid appears with a list of the
parameters for the selected process. You can enter values for each parameter directly into the grid
or use an Excel reference that dynamically retrieves a parameter value from the current worksheet.
• If you selected the Get Process info from Worksheet option in the Process list, you must use
an Excel reference to retrieve the parameter values from the current worksheet. You can enter
a reference to a single cell, a range of cells, or a named range. Any reference must point to the
appropriate number of cells, depending on the number of parameters that the process is expecting.

Click the Excel Reference button to directly select the cell or range of cells from the worksheet.
For examples, see the TM1 for Developers documentation.
Excel Reference
Creates an Excel reference that dynamically retrieves the process name or parameter value(s) from
the current worksheet when the Action button is clicked.

Worksheet Tab
Use the Worksheet tab to configure an Action button to navigate to another Excel worksheet.
Look In
Use one of the following methods to select a worksheet:
• TM1 Applications - Select this option if you want to choose a worksheet from the TM1 Applications
tree.
• Files - Select this option if you want to choose a worksheet from your computer.
Browse
Click this button to select the worksheet to which you want to navigate.

2 IBM Planning Analytics: Reference

 • If you selected the TM1 Applications option, a dialog box opens where you can select a worksheet
from the TM1 Applications tree.
• If you selected the Files option, the Open dialog box appears where you can browse and select a file
from your computer.
Workbook
Contains the path and name of the Excel workbook to which you want to navigate. You can enter this
value in one of the following ways:
• Click the Browse button next to the Look In option to select a workbook from either the TM1
Applications tree or from the files on your computer.
• Click the Excel Reference button to select a cell that evaluates to a workbook path and name.
• Manually enter a workbook name and path.
• Manually enter an Excel reference that evaluates to a workbook path and name.
The path for a workbook in the TM1 Applications tree uses the format:
<FolderName>\<FolderName>\<WorkbookName>
For example:
Planning Sample\Bottom Up Input\Budget Input
The path for a network file uses the format:
\\<ComputerName>\<FolderName>\<WorkbookName>
For example:
\\boston\reports\2007_summary.xls
For details and examples, see the IBM Cognos® TM1 for Developers documentation.
Sheet
Contains the name of the worksheet to which you want to navigate. You can enter this value in one of
the following ways:
• Click the Browse button to select a workbook and then select a worksheet from the Sheet list.
• Manually enter a worksheet name.
• Manually enter an Excel reference that evaluates to a worksheet name.
• Click the Excel Reference button to select a cell that evaluates to a worksheet name.
For details and examples, see the IBM Cognos TM1 for Developers documentation.
Match Title Elements
This option automatically matches and sets the title dimensions between the source and target
worksheets when a user clicks the Action button to navigate to the target worksheet.
For details and examples, see the IBM Cognos TM1 for Developers documentation.
Replace Current Workbook
This option determines how the target worksheet is opened.
• If this option is not selected (default), the target worksheet is opened in a new window in Excel or on
a new tab in TM1 Web.
• If this option is selected, the target worksheet is opened in the same window or tab, replacing the
source worksheet.
CAUTION: If you enable this option, remember to save your workbook before testing the new
button. You could lose your changes if you click the button and cause the current workbook to
close.

Chapter 1. Windows and Dialog Boxes 3

 Advanced Options
Click this button to open the Advanced Options dialog box where you can manually map fields
between the source and target worksheets for an Action button that navigates from one worksheet to
another.
For details, see “Advanced Options Dialog Box” on page 4.

Appearance Tab
Use the Appearance tab to configure the visual appearance of the Action button.
Caption
Sets the caption text that displays on the Action button.
Font
Click this button to display the Font dialog box where you can set the font style and size for the button
text.
Show Background Image
Allows you to select an image file (bmp, gif, or jpg format) that will be stretched to fit the Action
button.
Select this option and then click Browse to locate and select the image file that you want to use.
Display as Hyperlink
Displays the Action button as a hyperlink with blue, underlined text instead of a standard button.
This option is not available when you select the Show Background Image option.
Preview
This area shows a preview of the text caption, font style, font color and background color for the
button.
Colors
Allows you to set the text and background colors for the Action button.
Click the Text or Background color sample to display the Color dialog box where you can select a
standard color or define a custom color.
This option is not available when you select the Display as Hyperlink option.

Advanced Options Dialog Box

Use the Advanced Options dialog box to manually map fields between the source and target worksheets
when you insert an Action button that navigates from one worksheet to another. This tool helps you map
dimensions, cells, and values from the source worksheet to the target worksheet.
Note: Advanced mapping is applied after any automatic mapping has been performed by the Match Title
Elements option.

Field Description

Add Adds a new row to the Advanced Mapping grid.

Delete Deletes the selected row from the Advanced

Mapping grid.

OK Closes the Advanced Options dialog box and saves

your settings.

4 IBM Planning Analytics: Reference

 Field Description

Cancel Closes the Advanced Options dialog box without

saving your settings.

For examples on using the Advanced Options dialog box, see TM1 for Developers in the IBM Knowledge
Center ([Link]

Advanced Mapping Grid

Use the Advanced Mapping grid to define the mapping of fields between the source and target
worksheets. You can use the grid to specify how elements in the source and target worksheets get
matched up when the target sheet opens. Each row in the grid defines one mapping configuration.

Field Description

Source Type This field represents the type of object for the value
you want to map.
Select the Source Type as follows:
• SUBNM - Indicates that you are mapping from a
cell that contains a title dimension in the source
worksheet.
• Selected DBRW - Indicates that you are mapping
from a cell that contains a DBRW formula in the
source worksheet.
• Value - Indicates that you will enter a string or
numeric value that will be sent to the target.

Source Object This field takes a value depending on what is

selected in the Source Type field.
Enter the Source Object as follows:
• If Source Type is set to SUBNM, then you need
to specify the name of the title dimension that
exists in the source worksheet.
• If Source Type is set to Selected DBRW, then you
need to specify the name of a row or column title
dimension that exists in the source worksheet.
• If Source Type is set to Value, then you need to
enter a string or numeric value that will be sent
to the target worksheet.
You can also retrieve these values from the source
worksheet by using the = symbol to create an Excel
reference.

Chapter 1. Windows and Dialog Boxes 5

 Field Description

Target Type This field is the type of cell in the target worksheet
where the value from the Source Object field will
be inserted.
Select the Target Type as follows:
• SUBNM - Indicates the target is a title dimension
in the target worksheet.
• Named Range - Indicates the target is a named
range in the target worksheet.
• Range - Indicates the target location is a cell in
the target worksheet.
CAUTION: If you set Target Type to either
a Named Range or Range, any pre-existing
data or formula in the target cell will be
overwritten when you navigate with the
Action button. If the target cell contains
a TM1DBRW function, then the function
will be lost and the cell will not be able
to connect to, read from, or write to the
server.

Target Object This field represents the location in the target

worksheet where the value from the Source Object
will be inserted.
Enter the Target Object as follows, depending on
your selection for Target Type:
• If Target Type is set to SUBNM, you need to
specify the name of the title dimension in the
target worksheet.
• If Target Type is set to Named Range, you need
to specify the name of the range in the target
worksheet.
• If Target Type is set to Range, you need to specify
the cell location in the target worksheet.
You can also use an Excel reference to retrieve the
value for the Target Object field.
For a detailed example, see the IBM CognosTM1
for Developers documentation.

Subset Enter a value for the Subset field when the Target
Type field is set to SUBNM.

Alias Enter a value for the Alias field when the Target
Type field is set to SUBNM.

Attributes Editor
Use the Attributes Editor to create and edit attributes for cubes, dimensions, elements, and replications.
Note that all elements include a Format attribute, which defines how element values display in the Cube
Viewer. The default Format attribute value is Unstyled.

6 IBM Planning Analytics: Reference

File Menu

Menu Item Description

Close Closes the Attributes Editor.

Edit Menu

Menu Item Description

Undo cell Undoes the last cell action. This option applies only
to individual cells. You cannot undo actions applied
to a range of cells.

Cut Cuts the contents of selected cells to the

Clipboard.

Copy Copies the contents of selected cells to the

Clipboard.

Paste Pastes the contents of the Clipboard to selected

cells.

Add new attribute Opens the New Attribute dialog box, from which
you can create a new attribute for the elements in
the dimension.

Delete selected attribute Deletes a selected attribute. You must delete

attributes individually; you cannot delete multiple
attributes simultaneously.

Clear Clears the contents of selected cells.

Edit Element Format Opens the Number Format dialog box, from which
you can assign Format attribute values.

Format Options
The Format option is available only when you select cells at the intersection of the Format column and
element rows. Click the Format button to display the Number Format dialog box.
Select an option from the Category list box to specify a display format for the selected cells.
The following number formats are available:

Chapter 1. Windows and Dialog Boxes 7

 Format Category Description

General This format displays numbers without commas

separating digits to the left of the decimal point.
Negative values are prefixed with a minus sign (-).
Use the Precision option to specify the number
of digits that follow the decimal point. Note that
Rules-derived values return integers only when set
to General format.

Fixed This format displays numbers without commas

separating digits to the left of the decimal point.
Negative values are prefixed with a minus sign
(-); users have the option to use parentheses for
negatives if preferred.
Use the Precision option to specify the number of
digits that follow the decimal point.

Currency This format displays numbers with the

currency symbol specified in your Windows
RegionalSettingsProperties, and uses commas to
separate every third digit to the left of the decimal
point. Negative values are prefixed with a minus
sign (-).
Use the Precision option to specify the number of
digits that follow the decimal point.

Date Displays a list of predefined date formats.

Time Displays a list of predefined time formats.

Percentage This format multiplies numbers by 100 and

displays a following percent sign (%). Digits to the
left of the decimal point do not use commas, and
negative values are prefixed with a minus sign (-).
Use the Precision option to specify the number of
digits that follow the decimal point.

Scientific This format displays numbers in scientific notation.

Negative values are prefixed with a minus sign (-).
Use the Precision option to specify the number of
digits that follow the decimal point.

Custom You can define a custom format expression as

needed.

Precision This option determines the number of decimal

places to display for a selected format. If a
value has more decimal places than the specified
precision, it is rounded off for display purposes
only; the entire value is stored in the TM1
database.

8 IBM Planning Analytics: Reference

Audit Log Window
Use the Audit Log window to query and view records contained in the TM1 audit log.
The Audit Log window contains two main panels; the Query panel and the Results panel. Use these panels
to search the audit log and view the records retrieved by your search.

Query Panel
Use the Query panel to build queries that search the TM1 audit log.

The Query panel toolbar contains a Run Query icon to query the audit log after you set the query
options.
The query options are organized into the following groups:
• Date and Time
• Event Owner
• Event Type

Date and Time Options

The Date and Time options include set the time period that you want to query.

Option Description

Time Period Contains a list of predefined time periods for the

query.
Select a predefined time period or select Custom
Time Period to enable the Start and End time
options.

Start Time The start date/time for the query.

This option is enabled only when you select
Custom Time Period for the Time Period option.
TM1 queries against all records written to the audit
log on or after this date/time.

Click to open the calendar tool where you can

select a date and time.

End Time The end date and time for the query.
This option is enabled only when you select
Custom Time Period for the Time Period option.
TM1 queries against all audit records up to the end
time you specify.

Click the Calendar icon to open the calendar

tool where you can select a date and time.
The default end time is the current date and time.

Event Owner Options

The Event Owner options answer the question "Who caused this event". The owner of the event can be an
actual TM1 user or a scheduled chore.

Chapter 1. Windows and Dialog Boxes 9

 The Event Owner options include the following parameters:

Option Description

All Sets the query to search for audit events caused by

any TM1 user or scheduled chore.

Client Sets the query to search for audit events caused

only by TM1 users.
To search for events caused by a specific TM1 user,
click the Select Client button . You can select
a single client or multiple clients.
The default is all clients.

Scheduled Chore Sets the query to search for audit events caused
only by scheduled chores.
To search for events caused by a specific
scheduled chore, click the Select Scheduled
Chore button . You can select a single
scheduled chore or multiple scheduled chores.
The default is all scheduled chore.

Event Type Options

The Event Type options let you the select the type of object or event for which you want to search. For
example, you can use these search options to "find unsuccessful login attempts" or "find events where a
dimension was deleted".

Option Description

All Sets the query to search for both types of audit

events; system-wide and object related events.

System-wide Sets the query to search for only system-wide audit

events.
To search for a specific system-wide event, select
the event from the list.
The default setting searches for all system-wide
events.

10 IBM Planning Analytics: Reference

 Option Description

Object Sets the query to search for only object type audit
events.
To search for a specific object event, use the
options as follows:
• Object Type - Limits the query to only a specific
type of TM1 object. For example, events related
only to dimensions.
• Object Name - Allows you to select a specific
object name.

Click to display a dialog box where you can

select objects by name.
Note: When you set the Object Type option
to Element, the Object Name Selection button
becomes disabled because the element list could
be too large to display. To search for events
related to a specific element, you must manually
enter an element name using the following
format: DimensionName:ElementName. For
example: region:italy
• Event Type - Limits the query to only a specific
type of object event. The default setting searches
for all object type events.

Results Panel
Use the Results panel to view and navigate the records retrieved by your search.

Results Panel Toolbar

The Results toolbar has the following buttons:

Action Button Description

Copy Copies the value in the currently

selected cell to the Windows
clipboard.

Find Opens the Find dialog box where

you can search for text in the
event records.

Export Opens the Save As dialog box

where you can save the event
records to a file in one of the
following formats:
• XML
• Comma delimited
• Tab delimited

Chapter 1. Windows and Dialog Boxes 11

 Results Grid
The Results panel includes a grid that displays the audit log records retrieved by the query. The retrieved
records are organized into the following columns:

Column Description

Date Date and time of the event.

User TM1 client (user) or scheduled chore that was

responsible for causing the event.

Event Type/ Description Brief description of the event.

Object Type Type of TM1 object associated with the event.

Object Name Name of the TM1 object associated with the event.

Details Displays an icon to indicate that detailed

information exists for the specific event.
If an event has details, you can view the details by
clicking on the Details icon for that record.

You can sort the records in the grid in ascending or descending order for any column by clicking on the
column title.

Audit Log Details Window

The Audit Log Details window displays the sub-events for an audit log event that was displayed in the
query results of the main Audit Log window.

Details Toolbar
The Details toolbar has the following buttons:

Button Description

Copy Copies the value in the currently selected cell to

the Windows clipboard.

Find Opens the Find dialog box where you can search
for text in the event records.

Export Opens the Save As dialog box where you can save
the event records to a file in one of the following
formats:
• XML
• comma separated
• tab separated

12 IBM Planning Analytics: Reference

Details Grid
The Details grid displays the sub-event detail records that belong to the parent event.
The detail records are organized into the following columns:

Column Description

Date Date and time of the event.

User TM1 client (user) or scheduled chore that was

responsible for causing the event.

Event Type/ Description Brief description of the event.

Object Type Type of TM1 object associated with the event.

Object Name Name of the TM1 object associated with the event.

You can sort the records in the grid in ascending or descending order for any column by clicking on the
column title.

Chore Setup Wizard

Use the Chore Setup Wizard to schedule a replication or process for synchronization or execution at a
regular interval.
The Wizard consists of two screens:
• Screen 1 - Select the replications and processes to be included in the chore.
• Screen 2 - Specify the start time for the initial execution of the chore and the subsequent interval at
which the chore should execute.

Screen 1 (Step 1)

Field Description

Available list Lists all replications and processes available for

scheduling as chores.

Selected list Lists the replications or processes selected for

inclusion in the current chore.

Click this button to move selected replications or

Add processes from the Available list to the Selected
list

Click this button to move all replications or

Add All processes from the Available list to the Selected
list.

Click this button to move selected replications or

Remove processes from the Selected list to the Available
list.

Chapter 1. Windows and Dialog Boxes 13

 Field Description

Click this button to move all replications or

Remove All processes from the Selected list to the Available
list.

Specify Values for Parameters Click to open the Parameter Values dialog box,
from which you can specify values for any
parameters associated with the selected process.

Screen 2 (Step 2)

Field Description

Chore Start Date and Time Select a start date on the calendar and specify a
start time in the Time field.

Chore Execution Frequency Fill the appropriate fields to establish the interval
at which the chore should be executed.

Chore Schedule is Active Fill this box to activate the chore for execution at
the specified start time and interval. Clear this box
to activate the chore at a later time.

Clients/Groups Window
The Clients/Groups window lets you create and modify clients and user groups on a server.

Clients/Groups grid
The Clients/Groups grid displays client names as row headings and user groups as column headings. An
'X' at the intersection of a client name and user group indicates the group to which the user belongs.
Users can belong to multiple groups.
The grid also includes several columns that display properties for clients on the server.
• The cell at the intersection of a client name and the Password column contains the password for the
client.
• The cell at the intersection of a client name and the Expiration Days column contains the number of
days for which the password is valid for the client. After this number of days elapses, the client can no
longer log into the server with the assigned password. A client whose password is soon to expire begins
receiving notification of the expiration five days before the expiration date.
• The cell at the intersection of the client name and the Status column indicates whether the client is
active on the server.
• The cell at the intersection of the client name and the Max Connections column indicates the maximum
number of connections that can be established to the server with the associated client name and
password.

Security Menu

14 IBM Planning Analytics: Reference

 Menu Item Description

Close Closes the Clients/Groups dialog box.

Clients Menu

Menu Item Description

Add New Client Opens the Creating New Client dialog box, from
which you can create a new client on the server.

Delete Client Deletes the currently selected client from the

server.

Disconnect Client Disconnects the currently selected client from the

server.

Set Password Sets the password for the currently selected client.

Clear Password Clears the password for the currently selected

client.

Groups Menu

Menu Item Description

Add New Group Opens the Creating New Group dialog box, from
which you can create a new user group on the
server.

Delete Group Deletes the currently selected user group from the
server.

Clients/Groups Grid
You can enter data for clients directly in the Clients/Groups grid.
The grid includes several columns, as described in the following table.

Column Description

Username Displays the usernames of all clients on the server.

Password Identifies whether a password is defined for a

given client.
You can click in a cell at the intersection of the
Password column and a client row, then type a
password to assign a password to the client.
After entering a password, TM1 prompts you to
re-enter the password for confirmation.

Chapter 1. Windows and Dialog Boxes 15

 Column Description

Expiration Days Indicates the number of days that a given client's

password is valid.
To assign expiration for a client's password, click in
the cell at the intersection of the Expiration Days
column and the client row, then type an expiration
value.

Max Connections Identifies the maximum number of connections

that can be made to the server by a given client.
To assign a maximum number of connections for a
client, click in the cell at the intersection of the Max
Connections column and the client row, then type
the maximum number of connections for the client.

Status Indicates the current connection status of a given

client.

User Groups There is one column for every user group on the
server.
To assign a client to a user group, fill the check box
at the intersection of the user group column and
the client name.
Clients can belong to multiple user groups.

Clients Messaging Center Dialog Box

The Clients Messaging Center dialog box lets you manage client connections to a server. You can also use
this dialog box to remotely shut down a server. You must be a member of the ADMIN group for a server to
access this dialog box.
Select a server in the left pane of the Server Explorer, then choose Server, Server Manager to open the
Clients Messaging Center dialog box.

Field Description

Shutdown Server Select this option to shut down the server, then
specify a Minutes interval.

Disconnect Clients Select this option to disconnect clients from the

server, then specify a Minutes interval.
You must click Select Clients to create or select a
subset of clients to be disconnected.

Broadcast Message to Selected Clients Select this option to broadcast a text message to
clients connected to the server.
Enter the message in the text box then click Select
Clients to create or select a subset of clients to
receive the message.

16 IBM Planning Analytics: Reference

Create a Dimension Dialog Box
Enter a name for the dimension you want to create in the field at the top of the dialog box then click OK.
To create a dimension on your local server, enter only the dimension name.
To create a dimension on a remote server, prefix the dimension name with the server name and a colon.
For example, enter Sales:Product to create the Product dimension on the Sales server.

Create Server Replication Object Dialog Box

Use the Create Server Replication Object dialog box to establish a new replication connection, or to
modify an existing connection.

Field Description

To Server Select a source server from the list. The list

includes the names of all servers currently
available on your network.

As User Enter your user name on the selected source

server.

With Password Enter your password for the selected source server.

With Namespace If the object uses CAM Passport security, enter

the IBM Cognos Namespace ID. Do not enter the
descriptive name here.

Use Integrated Login Check this box to use Integrated Login

authentication instead of standard TM1 security.

Creating Cube Dialog Box

Use the following options on the Creating Cube dialog box to create a new cube from previously-defined
dimensions.

Field Description

Cube Name Type the name for the cube you are creating in this
field.

Available Dimensions A list of all dimensions available on the server on

which you are creating the cube.

Dimensions in New Cube The list of dimensions in the cube you are creating.

Add Click this button to move selected dimensions from

the Available Dimensions list to the Dimensions in
New Cube list

Remove Click this button to move selected dimensions from

the Dimensions in New Cube list to the Available
Dimensions list.

Chapter 1. Windows and Dialog Boxes 17

 Field Description

Move up Click this button to move selected dimensions up

through the Dimensions in New Cube list. Each
click of the button moves the selected dimensions
up one position.

Move down Click this button to move selected dimensions

down through the Dimensions in New Cube list.
Each click of the button moves the selected
dimensions down one position.

Cancel Click to cancel the cube creation and exit the

Creating Cube dialog box.

Reset Click to reset the Available Dimensions list and

clear the Dimensions in New Cube list.

Refresh Click to refresh the Available Dimensions list. This

option polls the server for any new dimensions,
and adds any new dimensions to the Available
Dimensions list.

Properties Click this button to assign cube properties.

You can assign properties that define a measures
dimension, a time dimension, and load-on-demand
status for the cube.

OK Click to accept the configuration of the dialog box

and create the cube.

Cube Optimizer Dialog Box

TM1 includes a feature that lets you optimize the order of dimensions in a cube, thereby consuming less
memory and improving performance.
If you're not familiar with your data, you might specify an order of dimensions during cube creation that
results in less than optimal performance. It's possible for the distribution of data in a cube to change over
time, which makes the order of dimensions specified during cube creation inefficient.
When you optimize the order of dimensions in a cube, TM1 does not change the actual order of
dimensions in the cube structure. TM1 does change the way dimensions are ordered internally on the
server, but because the cube structure is not changed, any rules, functions, or applications referencing
the cube remain valid.
As you change the order of dimensions, you can instantly view a report detailing the impact your changes
have on cube memory consumption.
For the following reasons, you should optimize the order of dimensions in a cube only in a development
environment while you are trying to determine optimal cube configuration:
• Significant memory resources are required for the server to reconfigure the order of dimensions in a
cube. During the re-ordering process, the temporary RAM on the server increases by a factor of two for
the cube that you are re-ordering. For example, a 50 MB cube requires 100 MB of RAM to reconfigure.
• Re-ordering puts a read lock on the server, locking all user requests while the re-order is performed.
Note: You must be a member of the ADMIN group to optimize the order of dimensions in cubes. The
optimization option is only available for cubes on remote servers; you cannot optimize the order of

18 IBM Planning Analytics: Reference

 dimensions in cubes on a local server. Also, when you optimize the order of dimensions in a cube, you
should not move the string dimensions from the last position, nor move the string dimensions to the last
position.

Procedure
1. In the Tree pane of the Server Explorer, select the cube you want to optimize.
2. Click Cube, Re-order Dimensions.
The Cube Optimizer dialog box opens.
3. Select a dimension in the New Order of Dimensions list box.
4. Click the up or down arrows to change the order of the dimension in the cube.
5. Click Test.
Note the value next to the Percent Change label. If this value is negative, the new order of dimensions
consumes less memory and is therefore more efficient.
6. Repeat steps 3 through 5 until you achieve the most efficient ordering of dimensions.
7. Click OK.

Cube Properties Dialog Box

Use the Cube Properties dialog box to set properties for individual cubes.

Field Description

Measures Dimension Select a measures dimension from the list.

Time Dimension Select a time dimension from the list.

Load on Demand Fill the box to load the cube into server memory
only when a client requests cube data. Clear this
box to load the cube automatically when the server
starts.

View section icons

Section icons can now be enabled in a view independent of section header strings.
To enable or disable section icons in the cube viewer, click View options, and then toggle section icons by
clicking the check box next to Section icons.
When section icons are enabled, they are displayed on the context, row, and column sections.

Chapter 1. Windows and Dialog Boxes 19

Cube Viewer

Title dimensions
Title dimensions appear directly beneath the Toolbar at the top of the Cube Viewer window. Each
dimension displays in a list box.

Row dimensions
Row dimensions appear at the top of the row axis of the Cube Viewer. The current dimension elements
appear as row headings in the Cube Viewer.

Column dimensions
Column dimensions appear at the left of the column axis of the Cube Viewer. The current dimension
elements appear as column headings in the Cube Viewer.

File Menu
The following options are available on the File Menu in the Cube Viewer.

Option Description

Open Opens the TM1 Open View dialog box, from which
you can open other views associated with the
current cube.

Reload Reloads the current view definition.

Calculate Calculates the current view.

Save Saves the current view configuration.

Save as Saves the current view configuration under a new

name.

20 IBM Planning Analytics: Reference

 Option Description

Delete Views Opens the Delete Named Views dialog box, from
which you can delete saved views.

Slice Exports the current view into an Excel worksheet.

The Excel worksheet is populated with formulae
that retrieve values from and write values to the
server from which the view originates.

Active Form Launches the Insert Active Form option to let you
add an Active Form connection to data in the
current cell of the worksheet.

Snapshot Exports the current view to an Excel worksheet as

simple values. The worksheet does not maintain
a connection to the server from which the view
originates.

Close Closes the Cube Viewer window.

Edit Menu
The following options are available on the Edit Menu in the Cube Viewer.

Option Description

TransAction Undoes the last cell action. Save or Close ends the
collection of actions that can be undone or redone.
Redo restores the last cell action.

Cut Cuts the contents of selected cells to the

Clipboard.

Copy Copies the contents of selected cells, as currently

formatted, to the Clipboard.

Copy Unformatted Value Copies the unformatted contents of selected cells

to the Clipboard.

Paste Pastes the contents of the Clipboard to selected

cells.

Delete Deletes the selected cell values.

Edit Cube Attributes Opens the Attributes Editor window, from which
you can assign and edit attributes for all cubes on
the current server.

View Menu
The following options are available on the View Menu in the Cube Viewer.

Chapter 1. Windows and Dialog Boxes 21

 Option Description

Toolbar Hides or displays the Toolbar at the top of the Cube

Viewer. A check mark indicates that the Toolbar is
displayed.

Status Bar Hides or displays the Status Bar at the bottom of

the Cube Viewer. A check mark indicates that the
Status Bar is displayed.

Right to Left This toggle changes the position of column

dimensions in the Cube Viewer.
A right pointing arrow indicates that the columns
layout right to left. A left pointing arrow means
columns are laid out left to right.

Options Menu
The following options are available on the Options Menu in the Cube Viewer

Option Description

Suppress Zeros This option suppresses or displays all rows and

columns containing only zero values in the cube
view. A check mark indicates that rows and
columns containing only zeros are suppressed in
the current view.

Suppress Zeros on Rows This option suppresses or displays all rows

containing only zero values in the cube view. A
check mark indicates that rows containing only
zeros are suppressed in the current view.

Suppress Zeros on Columns This option suppresses or displays all columns

containing only zero values in the cube view. A
check mark indicates that columns containing only
zeros are suppressed in the current view.

Automatic Recalculate This option enables or disables automatic

recalculation upon view reconfiguration. A check
mark indicates that the view is automatically
recalculated whenever the view configuration
changes.

Format Opens the Number Format dialog box, from which

you can define the number format for values in
the current view. Note that the format you select
applies only to those values for which there is no
Format attribute specified.

Column Width Opens the Column Width dialog box, which lets you
set a minimum and maximum width for columns in
the Cube Viewer.

22 IBM Planning Analytics: Reference

 Option Description

Slice to New Workbook This option determines how slices are created.
A check mark indicates that slices are inserted in a
new workbook when you choose File, Slice.
If this option is not turned on, slices are inserted in
a new sheet of the current workbook.

Delete Named Subsets Dialog Box

This dialog box displays the subsets associated with the current dimension. To delete a subset, select the
subset and click OK.
To select multiple adjacent subsets, click and drag across the subsets. To select multiple non-adjacent
subsets, CTRL-click each subset.

Delete Named Views Dialog Box

This dialog box displays the views associated with the current cube. To delete a view, select the view and
click OK.
To select multiple adjacent views, click and drag across the views. To select multiple non-adjacent views,
CTRL-click each view.

Dimension Editor

Elements Pane
Displays elements of the dimension you are currently viewing.

Properties Pane
When you select a consolidated element in the Elements pane, the Properties pane displays the
properties of the immediate children of the consolidated element.
When you select a leaf element, the Properties pane displays the properties of the leaf element.
Note: When viewing an exceptionally large dimension set in the Dimension Editor with the Properties
pane on, you might experience performance issues. This can happen when you select a consolidation
in the Elements pane and TM1has to display the entire list of related elements and properties in the
Properties pane.
If you are working with large dimension sets, you may want to turn off the Properties pane. To turn off the
Properties pane, click the Properties Window option in the View Menu to remove the check mark next to
the option.

Dimension Menu

Menu Item Description

Save Saves the current dimension structure.

Chapter 1. Windows and Dialog Boxes 23

 Menu Item Description

Save as Saves the current dimension structure under a new

name.

Close Closes the Dimension Editor.

Edit Menu

Menu Item Description

Cut Cuts selected elements to the Clipboard.

Copy Copies selected elements to the Clipboard.

Paste Pastes the contents of the Clipboard as a new

element.
• When no elements are selected in the Dimension
Editor, this option inserts a new element above
the first displayed element in the Elements pane.
• When an element is selected in the Elements
pane, this option displays a sub-menu with the
options Paste Above, Paste as Child, and Paste
Below.

Paste Above Pastes the contents of the Clipboard above a

selected element.

Paste Below Pastes the contents of the Clipboard below a

selected element.

Paste as Child Pastes the contents of the Clipboard as a child of a

selected element.

Insert Child Opens the Dimension Element Insert dialog box,

from which you can insert a child or children of a
selected element.

Insert Element Opens the Dimension Element Insert dialog box,

from which you can insert leaf (simple) elements
into the dimension.

Select All Selects all the elements in the Elements pane.

Filter by, Level Opens the Filter by Level dialog box, from which
you can select elements by hierarchy level.
This option affects only the display of elements; it
does not affect the dimension structure. When you
use this option the Elements pane displays only the
elements of the level you specify.

24 IBM Planning Analytics: Reference

Menu Item Description

Filter by, Attribute Opens the Filter by Attribute dialog box, from
which you can select elements by attribute value.
This option affects only the display of elements;
it does not affect the dimension structure. When
you use this option the Elements pane displays
only those elements with the attribute value you
specify.

Filter by, Wildcard Lets you select elements that match a user-defined
search expression.
This option affects only the display of elements; it
does not affect the dimension structure. When you
use this option the Elements pane displays only
those elements matching the search expression
you specify.

Select Alias Opens the TM1 Aliases dialog box, from which
you can select an alias to use for display in the
Dimension Editor.

Sort, Ascending Sorts all elements in the Elements pane in

alphabetically ascending order.
This option affects only the display of elements; it
does not affect the dimension structure.

Sort, Descending Sorts all elements in the Elements pane in

alphabetically descending order.
This option affects only the display of elements; it
does not affect the dimension structure.

Sort, Hierarchy Sorts all elements in the Elements pane in

hierarchical order, so you can see the parent/child
relationship of elements.
This option affects only the display of elements; it
does not affect the dimension structure.

Sort, Index Ascending Sorts all elements in the Elements pane in

ascending order according to element index value.
This option affects only the display of elements; it
does not affect the dimension structure.

Sort, Index Descending Sorts all elements in the Elements pane in

descending order according to element index
value.
This option affects only the display of elements; it
does not affect the dimension structure.

Chapter 1. Windows and Dialog Boxes 25

 Menu Item Description

Keep Alters the Elements pane so that only currently

selected elements are displayed.
This option affects only the display of elements; it
does not affect the dimension structure.

Hide Alters the Elements pane so that currently selected

elements are hidden.
This option affects only the display of elements; it
does not affect the dimension structure.

Delete Element Deletes all instances of a selected element from

the dimension.

Delete from Consolidation Deletes the instance of a selected element from

the current consolidation.

Edit Element Formats Opens the Edit Element Formats worksheet, from
which you can define element display styles. These
display styles are applied in dynamic slices and in
TM1 Web websheets.

Expand Element Displays all children of a selected element.

Collapse Element Hides all children of a selected element.

Properties Opens the Dimension Element Properties dialog

box, from which you can assign element type and
weight for a selected element.

View Menu

Menu Item Description

Toolbars Hides or displays the various toolbars at the top

of the Dimension Editor window. A check mark
indicates that a toolbar is displayed.

Status Bar Hides or displays the Status Bar at the bottom

of the Dimension Editor window. A check mark
indicates that the Status Bar is displayed.

Properties Window Hides or displays the Properties pane. A check

mark indicates that the Properties pane is
displayed.

Refresh Updates the display of the Elements pane.

26 IBM Planning Analytics: Reference

Dimension Element Insert Dialog Box
Use this dialog box to add simple, string, or consolidated elements to a dimension. The dialog contains
the following options.

Option Description

Dimension Name The name of the dimension to which you are

adding elements. This is not an editable option.

Parent Name The name of the parent element to which you are
adding elements. This is not an editable option.
If an element was selected in the dimension editor
when you opened the Dimension Element Insert
dialog box, that element displays as the Parent
Name. If no element was selected, the Parent
Name is Root.

Insert Element Name Enter a name for the new element in this box.

Element Type Make a selection appropriate to the element you

want to insert.

Element Weight If the element type is Simple and the Parent Name
is anything other than Root, enter a weight in this
box. The weight is a multiplication factor applied to
an element during consolidation.
A weight associated with an element of a
consolidation does not alter the value of the
element elsewhere in the dimension.

Add Click Add each time you specify a new element,

type, and weight.

OK Click this button when you are done adding

elements to commit the new elements to the
dimension.

Dimension Element Ordering Dialog Box

Use this dialog box to set the order of elements in a dimension.
The order of elements within a dimension determines the index value for each element in the dimension.
The first element in a dimension has an index value of 1, the second element has an index value of 2, and
so on. The order of elements in a dimension is important because many TM1 functions (worksheet, rules,
and TurboIntegrator) reference element index values.
Note: If you change the order of elements in a dimension, any functions that reference element index
values return new and possibly unexpected values.
Use the following steps to set the order of elements.

Procedure
1. Select a sort type.

Chapter 1. Windows and Dialog Boxes 27

 Type Description

Automatic Enables the Automatic Sort By options: Name,

Level, and Hierarchy.

Manual Orders elements as they currently exist in the

dimension structure and sets the dimension
sorting property to Manual.

2. If you select the Manual sort type, skip to step 5.

3. Select an Automatic Sort By option.

Type Description

Name Sorts elements alphabetically

Level Sorts elements by hierarchy level.

Hierarchy Sorts elements according to the dimension

hierarchy.

4. If applicable, select a Sort Direction.

5. Click OK.
You have now set the order of the dimension elements. When you open the dimension, you will see the
elements in order according to the Sort By option you specified in step 3.

Results
You have now set the order of the dimension elements. When you open the dimension, you will see the
elements in order according to the Sort By option you specified in step 3.

Dimension Element Properties Dialog Box

Displays the name, type, and weight of the current element.

Properties Pane

Options Description

Element Type To change the type of the current element, select

a new type from the list. There are three possible
element types: simple, consolidated, and string.

Element Weight To change the weight of the current element,

double-click in the Element Weight field and enter
a new weight value.

Drill
The Drill menu lists the options used to create and manage a drill process and drill assignment. Drill
processes and assignments are used to create links between cube cells with related detailed data.

28 IBM Planning Analytics: Reference

 Options Description

Create/Edit/Delete Drill Assignment Rules Choose these options to create, edit or delete drill
assignments. The Create option opens the rules
editor so you can design the rule.

Create/Edit Drill Process A drill process is a TurboIntegrator process that

defines the detailed data, which opens in a
new window. These options edit an existing drill
assignment rule or allow you to create a new one.
The Create options display the parameters and
values to use and the details for the data source.
If you change the data source for a drill process,
TurboIntegrator does not update the function
with the new data source because the function
is outside the Generated Statements area. You
must edit the Cube View data source in the
ReturnViewHandle function for the drill process.

Edit Formula Dialog Box

The Edit Formula dialog box steps you through the creation of DBR, DBRW, and DBS functions. You can
also use the Edit Formula dialog box to edit any TM1 function in a worksheet.
To display the Edit Formula dialog box, click a cell in a worksheet and choose TM1, Edit Formula. If the
cell contains a TM1 function, the function displays in the entry field of the dialog box.

Field Description

DB Ref Click this button to insert a DBR function in the

current cell. TM1 steps you through several dialog
boxes that help you create the function.

DBRW Click this button to insert a DBRW function in the

current cell. TM1 steps you through several dialog
boxes that help you create the function.

DB Send Click this button to insert a DBS function in the

current cell. TM1 steps you through several dialog
boxes that help you create the function.

Cell Ref Click this button to insert a cell reference into

a function. TM1 prompts you to select the cell
to which you want to refer, and prompts for a
reference type.

Names Click this button to insert a cube, dimension, or

element name into a function

The Formula Editor can be used to create functions that reference cubes of up to 29 dimensions.

Edit Reference to Cube Dialog Box

This dialog box lets you set the element references used in TM1 worksheet functions such as DBRW and
DBSW.

Chapter 1. Windows and Dialog Boxes 29

 The dialog box contains buttons and fields corresponding to each dimension in the cube that the TM1
worksheet function references. For example, the following image shows the Edit Reference to Cube dialog
box for a DBRW function that references the SalesCube cube in the TM1 sample database. The dialog box
includes buttons for all the dimensions in the SalesCube cube.
When you insert a TM1 function into a worksheet, TM1 attempts to determine if any relevant element
references exist in the worksheet. If so, those references are automatically inserted into the appropriate
fields on the Edit Reference to Cube dialog box. If relevant element references cannot be determined,
TM1 inserts "Undef" in the fields.
You can set references in this dialog box by either:
• clicking a dimension button and selecting an element. In this case, the reference is inserted as a string
into the appropriate field.
• entering a cell reference directly in a field. You can use row-relative, column-relative, or absolute cell
references.
If the cube for which you are creating a reference contains more than 16 dimensions, click Previous to
page backward to the previous 16 dimensions, or click Next to page forward to the next 16 dimensions.

Filter Elements by Attribute Dialog Box

Use this dialog box to select only those subset elements that have a specified attribute value.
Select the desired attribute from the Select an Attribute list.
Select a corresponding value from the Select a Value list.

Filter Elements by Level Dialog Box

The list box displays the hierarchy levels available in the current subset. To view only elements of a given
level, select the level and click OK.
To select multiple adjacent levels, click and drag across the levels. To select multiple non-adjacent levels,
CTRL-click each level.

Filter Subset Dialog Box

The Filter Subset dialog box lets you create a dynamic subset based on values in a specified cube. For
example you can create a subset of the Region dimension that returns the 10 elements with the largest
values for actual yearly sales of the 1.8L Sedan in the Sales cube.
The dialog box contains the following options.

Option Description

CubeName The cube for which you want to filter values.

30 IBM Planning Analytics: Reference

Option Description

Filter The type of filter you want to apply to the current

view.
TopCount
Filters the subset to return only the largest n
elements, where n is a number specified in the
Value option.
BottomCount
Filters the subset to return only the smallest n
elements, where n is a number specified in the
Value option.
TopSum
Filters the subset to return only the largest
elements whose sum is greater than or equal
to n, where n is a number specified in the Value
option.
BottomSum
Filters the subset to return only the smallest
elements whose sum is greater than or equal to
n, where n is a number specified in the Value
option.
TopPercent
Filters the subset to return only the largest
elements whose sum is greater than or equal
to n, where n is a percentage of the dimension
total specified in the Value option.
BottomPercent
Filters the subset to return only the smallest
elements whose sum is greater than or equal
to n, where n is a percentage of the dimension
total specified in the Value option.
None
Not applicable to filtering subsets.

Value A value for the Filter type.

Select Column Member The column element(s) against which the filter or
sort is applied. Click the dimension buttons to
select a single element for each column dimension.

Chapter 1. Windows and Dialog Boxes 31

 Option Description

Sort The sort order you want to apply to the selected

column element(s).
Ascending
Sorts values for the specified column
element(s) from lowest to highest.
Descending
Sorts values for the specified column
element(s) from highest to lowest.
None
No sort order.

Select Column Members You must select a single element from each
remaining cube dimension. For example, if you
are filtering the Region dimension in the sample
database against values in the Sales cube, you
must specify a single element each of the Model,
Month, ActVsBud, and Account1 dimensions.
For each dimension, click the appropriate button
and select a single element.
If the cube contains more than 16 dimensions,
click to page backward to the previous 16
dimensions, or click to page forward to the
next 16 dimensions.

Filter View Dialog Box

The Filter View dialog box lets you filter and sort columns in the Cube Viewer or In-Spreadsheet Browser.
The dialog contains the following options.

Option Filter/Description

CubeName The cube for which you want to filter or sort values.
This option is always set to the cube associated
with the current view. It cannot be edited.

Filter The type of filter you want to apply to the current

view.

TopCount
Filters the view to display only the largest n
elements, where n is a number specified in the
Value option.

32 IBM Planning Analytics: Reference

Option Filter/Description

BottomCount
Filters the view to display only the smallest n
elements, where n is a number specified in the
Value option.

TopSum
Filters the view to display only the largest elements
whose sum is greater than or equal to n, where n is
a number specified in the Value option.

BottomSum
Filters the view to display only the smallest
elements whose sum is greater than or equal to n,
where n is a number specified in the Value option.

TopPercent
Filters the view to display only the largest elements
whose sum is greater than or equal to n, where n is
a percentage of the dimension total specified in the
Value option.

BottomPercent
Filters the view to display only the smallest
elements whose sum is greater than or equal to
n, where n is a percentage of the dimension total
specified in the Value option.

None
No filter. Select this option if you want to sort
values without filtering.

Value A value for the Filter type.

Select Column Member The column element(s) against which the filter or
sort is applied. Click the dimension buttons to
select a single element for each column dimension.

Sort The sort order you want to apply to the selected

column element(s).

Ascending
Sorts values for the specified column element(s)
from lowest to highest.

Descending
Sorts values for the specified column element(s)
from highest to lowest.

Chapter 1. Windows and Dialog Boxes 33

 Option Filter/Description

None
No sort order.

Get View Dialog Box (In-Spreadsheet Browser)

The Get View dialog box lets you open a view on your local server or on any servers available on your
network.

Field Description

Server The Server list displays all servers available on

your network. Select the server on which the view
you want to open resides.
If you are not logged on to the server containing
the view you want to open, click Connect to open
the Connect Server dialog box and log on to the
server. Click Start Local Server to start your local
server.

Cube The Cube list displays all cubes available on the

selected server. Select the cube associated with
the view you want to open.

View The View list displays all views available on the

selected cube. Select the view you want to open.

In-Spreadsheet Browser Menu

The In-Spreadsheet Browser Menu is available from a right-click on the TM1 View Control. The menu lets
you open, update, format, slice and save a view. It also includes several options that control the behavior
of the In-Spreadsheet Browser.

Menu Item Description

Update View Updates the current view by sending any edited values to the TM1 database and
retrieving current values from the database.

Get View Opens the Get View dialog box, from which you can open a view on any available
server.

Styles Opens the View Styles dialog box, which lets you format a view.

Save Opens the Save View dialog box, which lets you save a TM1 view.

Clear Display Clears all data associated with a view, including title, row, and column labels.

Delete Deletes the TM1 View Control. Note that all data associated with the view,
including values and labels, remain in the spreadsheet.

Cut Cuts the TM1 View Control to the Clipboard.

34 IBM Planning Analytics: Reference

 Menu Item Description

Copy Copies the TM1 View Control to the Clipboard.

Slice Slices the current view into a new Excel spreadsheet.

Suppress Zeroes This toggle suppresses or displays zero values in the cube view. A check mark
indicates that zeros are suppressed in the current view.

Show Automatically This toggle enables or disables automatic view update upon view reconfiguration.
A check mark indicates that the view is automatically updated whenever the view
configuration changes.

Update View on This toggle enables or disables automatic view update upon spreadsheet
Recalc recalculation (F9). A check mark indicates that the view is updated whenever
the spreadsheet is recalculated.

Help Open the In-Spreadsheet Browser help topic.

Message Log Window

The TM1 Message Log window displays status messages on the activity of the server. These messages
are saved to the server message log and contain details on activity such as executed processes, chores,
loaded cubes and dimensions, and synchronized replication.
For detailed information about the server message log, see TM1 Operations.

Message Log pane

This pane displays status messages contained in the server message log.
Each row in the pane represents one unique message. If a message in the log shows an error condition
for an executed process or replication, you can double-click the message to view the details of why the
activity generated the error.
For details about the fields in the Message Log pane, see TM1 Operations.

File Menu

Menu Item Description

Exit Closes the Message Log window.

Edit Menu

Menu Item Description

Copy Copies the selected text from the Message Log

pane to the Clipboard.

Find Opens the Find dialog box where you can search
for text in the Message Log pane.

Chapter 1. Windows and Dialog Boxes 35

Help Menu

Menu Item Description

Message Log Help Opens the Message Log help topic.

Contents and Index Opens the full TM1 Documentation Library.

New Attribute Dialog Box

Field Description

New Attribute Name Enter a name for the new attribute in this field.

Numeric Select this option if the attribute values are

numbers.

String Select this option if the attribute values are

character strings.

Alias Select this option if the attribute values are

alternative names for current element, dimension,
cube, or server names.

Open Subset Dialog Box

Use the Open Subset Dialog Box to open an existing dimension subset.
To open the public default subset, select the Default box and click Open.

Open View Dialog Box

Use the Open View Dialog Box to open an existing cube view.
To open the public default view, select the Default box and click Open.

Print Report Wizard

Use the Print Report Wizard to generate "briefing book"-style reports from TM1 slices.
The Wizard consists of three screens.
• Screen 1 - Select the sheets to include in the report
• Screen 2 - Select the title dimensions to use in the report, set the order in which they appear in the
report, and set workbook print options
• Screen 3 - Select a print destination for the report (printer, Excel file, or PDF file)
The Print Report Wizard also allows you to save your report settings.

All Screens

36 IBM Planning Analytics: Reference

 Button Description

Load Click this button to load an existing TM1 Print Job.

Save Click this button to save the current report settings

as a TM1 Print Job.

Save As Click this button to save the current report settings

as a TM1 Print Job under a new name.

Next Click this button to advance to the next Wizard

screen.

Cancel Click this button to close the Wizard window

without generating a report.

Screen 1 of 3

Item Description

Include these sheets in the report list Lists the available worksheets in the current Excel
workbook that you can include in the report.
To include a worksheet in the report, select the
check box next to the sheet name.

Select All Click this button to include all sheets in the report.

Clear All Click this button to exclude all sheets from the
report.

Screen 2 of 3

Item Description

Available Title Dimensions list Lists the available title dimensions that you can
use in the report.
For each dimension, this list displays the subset
name (if applicable), number of elements in the
dimension or subset, and cell address of the title
dimension in the worksheet.

Selected Title Dimensions list Lists the title dimensions to include in the report.
The order of this list is used when TM1 generates
the report.

Add Click this button to move selected dimensions from

the Available Title Dimensions list to the Selected
Title Dimensions list.

Chapter 1. Windows and Dialog Boxes 37

 Item Description

Add All Click this button to move all dimensions from the
Available Title Dimensions list to the Selected Title
Dimensions list.

Remove Click this button to move selected dimensions from

the Selected Title Dimensions list to the Available
Title Dimensions list.

Remove All Click this button to move all dimensions from the
Selected Title Dimensions list to the Available Title
Dimensions list.

Move Up Click this button to move the selected dimension

up in the Selected Title Dimensions list. The order
in this list is used when TM1 generates the report.

Move Down Click this button to move the selected dimension

down in the Selected Title Dimensions list. The
order in this list is used when TM1 generates the
report.

Subset Editor Click this button to open the Subset Editor if you
want to select a subset of elements from the
currently selected dimension in the Selected Title
Dimensions list.

Print Single Workbook Select this option to create a report arranged into
one complete group of worksheets.
Each sheet in the report is printed only once,
including sheets that do not contain TM1 slice
data.

Print Multiple Workbooks Select this option to create a report arranged into
multiple groups based on dimension elements.
This option creates a report with a larger number of
sheets because a copy of each sheet is printed for
each title element.

Total Excel Workbooks that will be generated Displays the total number of Excel sheets that TM1
will generate for the current report.

Screen 3 of 3

Field Description

Print to Printer Select this option if you want to print the report to
a printer.

Save As Excel Files Select this option if you want to generate the report
as an Excel file.

38 IBM Planning Analytics: Reference

Field Description

Save As PDF Files Select this option if you want to generate the report
as a PDF file.

Preview This button becomes available when you select the

Print to Printer option.
Click this button to preview the report before
printing.

Printer Name This option becomes available when you select the
Print to Printer option.
Use this option to specify the printer to which TM1
prints the report.

Number of Copies This option becomes available when you select the
Print to Printer option.
Use this option to specify the number of copies of
the report to print.

Print To File This option becomes available when you select the
Print to Printer option.
Select this option to save the report as a printer-
ready file.

File Name This option becomes available when you select

both the Print to Printer and Print to File options.
Enter a full path and file name to which you want
to save the report. You must also specify a file type.
For example, if you print to a file using a PostScript
printer, you should append the .ps file type to the
file name.

Browse This button becomes available when you select the

option to print or save the report to a file.
Click this button to choose the directory in which
you want to save the report.

Collate This option becomes available when you select the

Print to Printer option.
Select this option to group pages together when
printing multiple copies of the report.

Generate New Workbook for Each Title This option becomes available when you choose to
save the report as an Excel or PDF file.
Select this option if you want to create a separate
file for each title dimension in the report.

Chapter 1. Windows and Dialog Boxes 39

 Field Description

Directory Name This option is available when saving a report as an

Excel or PDF file and you select the Generate New
Workbook for Each Title option.
Enter a directory in which to save the report files.
To choose a directory location, click the Browse
button.

Create Snapshot This option becomes available when you select the
Save As Excel Files option.
Select this option when you want to save the report
as an Excel file that contains actual values and not
TM1 functions that retrieve values.

Back Click this button to step back to the previous

Wizard screen.

Finish Click this button to generate the report based on

the options you have selected.

Process Options Dialog Box

Use the Process Options dialog box to control the behavior of the Action button before and after the
process is run.
You can use one of the following methods to set the text for confirmation and status messages that
display when the Action button is clicked:
• Enter text for a message directly into the text box.
• Use an Excel reference to dynamically retrieve the text for a message from the worksheet.
For example, to retrieve the text for a message from the contents of cell A1, enter =A1 into the text box for
that message. To reference a named range, use the format: =Named Range.
For more information about using the Process Options dialog, see IBM Cognos TM1 for Developers.

Field Description

Automatically Recalculate Book Select this option to have TM1 automatically

recalculate the full workbook after the process has
run.

Show Success Message Select this option to display a message after the
process has run successfully.
Enter your message text into the box as described
above.

Show Failure Message Select this option to display a message if the

process does not run successfully.
Enter your message text into the box as described
above.

40 IBM Planning Analytics: Reference

 Field Description

Show Confirmation Dialog Select this option to display a Yes/No confirmation

message box before the process starts. The user
can click either Yes, to run the process, or No, to
cancel.
Enter your message text into the box as described
above.

OK Click this button to save your settings and close the

dialog box.

Cancel Click this button to close the dialog box without

saving your settings.

Replicate Cube Dialog Box

Use the Replicate Cube dialog box to replicate a cube from a source server to a target server.

Cube Information

Item Description

Name The name of the mirror cube on the target server.

By default, TM1 names the mirror cube by
concatenating the source server name with the
source cube name.
Do not change the default name if you are
replicating rules in that cube.

Copy Data and Set to Synchronize Select this option to copy data when the replication
is established and to synchronize data when
synchronization occurs between the source and
target servers.

Copy Data but Do Not Set to Synchronize Select this option to copy data when the replication
is established but to disable later synchronization
of data.

Replicate Views Select this option to replicate all views associated

with the source cube.

Rule Information

Item Description

Copy Rule Select this option to copy any rules from the source
cube to the mirror cube.

Chapter 1. Windows and Dialog Boxes 41

 Item Description

Set Rule to Synchronize Fill this box to synchronize rules when

synchronization occurs between the source and
target servers.
Clear this box to disable synchronization of the
rule.

Do Not Copy Rule If you select this option, TM1 does not copy the
rule from the source cube to the mirror cube.

Dimension Information

Item Description

Dimension Information box This box displays information about the

dimensions in the mirror cube.
If the source cube does not contain rules, TM1
renames the mirror dimensions by concatenating
the source server names with the source
dimension names.
If the source cube contains rules, TM1 does not
change the dimension names in the mirror cube.
The Dimension Information box also displays the
name of the source dimension, source server, and
replication status for each dimension in the cube.

Select Local Dimension To use a local dimension in the place of a source

dimension, click the source dimension in the
Dimension Information box and click Select local
dimension. Select the local dimension you want to
use and click OK.

Reset Current Selection to Default If you change any Dimension Information options
for a dimension in a replicated cube, you can
restore all options to default values by selecting
the dimension in the Dimension Information box
and clicking this button.

Overwrite Dimension This option becomes available when you select a

local dimension.
Select this option to overwrite the local dimension
with the definition of the source dimension.

Set Dimension to Synchronize Fill this box to synchronize changes to between the
source and mirror dimension when synchronization
occurs between the source and target servers.
Clear this box to disable synchronization of the
dimension.

42 IBM Planning Analytics: Reference

 Item Description

Don't overwrite dimension This option becomes available when you select a
local dimension.
Select this option to use the local dimension as-is.

Replicate Subsets Select this option to replicate all subsets

associated with the source dimension.

Rules Editor
The Rules Editor has a full set of menus for creating, editing, and managing TM1 rules. Keyboard shortcuts
are provided for the more commonly used menu options.

File Menu
The following table describes the options in the File Menu.

Name Description

Import Opens a file browse dialog so you can select a

text file to import. Imported text will overwrite the
current rule if one exists.

Save Saves the current rule to the server.

Save As Saves the current rule to an external TM1 rule .rux

file.

Check Syntax Checks the current rule for syntax errors.

Print Opens the Print dialog box so you can print the
current rule.

Print Preview Opens the Print Preview window where you can
view a sample printed version of the rule before
sending it to a printer.

Exit Closes the Rules Editor.

Edit Menu
The following table describes the options in the Edit Menu.

Name Description

Undo Undoes the last edit.

Multiple levels of undo are supported.

Redo Reverses the last undo command.

Cut Removes the selected text and places it in the

clipboard.

Chapter 1. Windows and Dialog Boxes 43

 Name Description

Copy Copies the selected text to the clipboard.

Paste Pastes the contents of the clipboard into the Rules

Editor.

Select All Selects the entire contents of the Rules Editor.

Find Opens the Find dialog box so you can search for
text in the rule.

Find / Replace... Opens the Find/Replace dialog box to search for

and replace text.

Find Next Locates the next occurrence of the text for which
you are searching.

Toggle Bookmark Turns a bookmark on or off for the current line of

code.

Next Bookmark Moves the cursor to the next available bookmark.

Previous Bookmark Moves the cursor to the previous available

bookmark.

Clear All Bookmarks Removes all bookmarks.

Comment Selection Adds a comment symbol # in front of all lines in the

currently selected text to exclude the lines from
the compiled rule.
Note: Comment length is limited to 255 bytes.
For Western character sets, such as English,
a single character is represented by a single
byte, allowing you to enter comments with 255
characters. However, large character sets, such as
Chinese, Japanese, and Korean, use multiple bytes
to represent one character. In this case, the 255
byte limit may be exceeded sooner and not actually
allow the entry of 255 characters.

Uncomment Selection Removes the comment symbol # from in front of

all lines in the currently selected text to include the
lines in the rule.

Indent Indents the currently selected lines.

Unindent Removes the indent from the currently selected

lines.

Goto Line... Displays the Go To Line dialog box so you can enter
and jump to a specific line number in the Rules
Editor.

44 IBM Planning Analytics: Reference

View Menu
The following table describes the options in the View Menu.
Note: Any changes you make to the settings on the View Menu are saved when you exit the Rules Editor
and are automatically re-applied the next time you open the Rules Editor.

Name Description

Word Wrap Turns on/off the word wrap feature so lines of text
either extend to the right or wrap to display within
the Edit pane.

Line Numbers Turns on/off line numbers.

Function Tooltips Turns on/off the display of function tooltips.

Auto-Complete Turns on/off the auto-complete feature when

typing in the Edit pane.

Toolbar Turns on/off the display of the main toolbar.

Status Bar Turns on/off the display of the status bar at the
bottom of the Rules Editor.

Control Objects Turns on/off the display of TM1 control objects

when selecting cubes.

Expand All Regions Expands all of the user-defined regions in the

current rule to show all lines.

Collapse All Regions Collapses all of the user-defined regions in the

current rule to hide all lines that are included in
a region.

Insert Menu
The following table describes the options in the Insert Menu.

Name Description

Function Displays the Insert a Function dialog box to enter a

new function into the current rule.

Cube Reference Displays the Insert Cube Reference dialog so you

can insert a DB function.

Tools Menu
The following table describes the options in the Tools Menu.

Name Description

Preferences... Displays the Preferences dialog where you can set

the font attributes such as font type, size, and color
to be used in the Edit pane.

Chapter 1. Windows and Dialog Boxes 45

 Name Description

Options... Displays the Control Options dialog where you can

adjust the global settings for the Rules Editor.

Save Subset Dialog Box

Field Description

Select or Enter Subset Name Enter a name for the saved subset, or select a
name from the list.

Private Toggle this option on to save the subset as a

private object. Toggle this option off to save the
subset as a public object.

Default Toggle this option on to save the subset as a

default subset.

Save Expression If the subset is dynamic, toggle this option on to

save the MDX expression with the subset.
If the subset is dynamic and you do not toggle this
option on, the MDX expression is not saved and the
resulting subset is static, containing the elements
present when saved.

Save View Dialog Box

Field Description

Select or Enter Named View Enter a name for the saved view, or select a name
from the list.

Private Toggle this option on to save the view as a private

object. Toggle this option off to save the view as a
public object.

Default Toggle this option on to save the view as a default

view.

Save View Dialog Box (In-Spreadsheet Browser)

Field Description

View Name Enter a name for the view in this field.

46 IBM Planning Analytics: Reference

 Field Description

Private Toggle this option on to save the view as a private

object. Toggle this option off to save the view as a
public object.

Default Toggle this option on to save the view as a default

view.

Security Assignments Dialog Box

The Security Assignments dialog box lets you assign access privileges for cubes, dimensions, individual
elements, processes, and chores. Access privileges are assigned by user group.

Assignments Grid
The Assignments grid displays object names as row headings and user groups as column headings.
Access privileges appear as cell values at the intersection of a given object and user group.
When you access the Security Assignment dialog box from a Cubes group, the grid includes a Logging
column. This column includes a check box for each cube. To enable logging for a cube, turn on the check
box at the intersection of the cube name and the Logging column. To disable logging, turn off the check
box. The default is on.

Access Privileges
Click one of the following options to assign an access privileges to a selected cell in the Assignments grid:

None Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
the None privilege for an object.

Object Description

Cube Members of the group cannot see the cube in the

Server Explorer, and thus cannot browse the cube.

Element Members of the group cannot see the element in

the Subset Editor or Dimension Editor, and cannot
view cells identified by the element when browsing
a cube.

Dimension Members of the group cannot see the dimension in

the Server Explorer, and cannot browse any cubes
that contain the dimension.

Process Members of the group cannot see the process in

the Server Explorer.
Note: Privileges assigned to processes are ignored
when a process is executed from within a chore.

Chore Members of the group cannot see the chore in the

Server Explorer.

Chapter 1. Windows and Dialog Boxes 47

 Object Description

Application Members of the group cannot see the application

or its contents in the Server Explorer.

Reference Members of the group cannot see the reference in

the Server Explorer.

Read Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
Read privilege for an object

Object Description

Cube Members of the group can view data in the cube,

but cannot edit the data.

Element Members of the group can view data identified by

the element, but cannot edit the data.

Dimension Members of the group can view the elements

in a dimension, but cannot edit the dimension
structure.

Process Members of the group can see the process in the

Server Explorer and can execute the process, but
cannot edit the process.
Note: Privileges assigned to processes are ignored
when a process is executed from within a chore.

Chore Members of the group can see the chore in the

Server Explorer and can manually execute the
chore, but cannot edit the chore or change the
activation status.

Application Members of the group can see the application and

use any references within the application to which
you have at least Read privilege. You can create
private references in the application, as well as
private sub-applications

Reference Members of the group can open and use the

reference, but cannot update the reference in the
parent application. You can, however, perform a
"save-as" operation to save a new private version
of the reference in any application to which you
have at least Read privilege.

Write Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
Write privilege for an object.

48 IBM Planning Analytics: Reference

Object Description

Cube Members of the group can view and edit cube data,
and can create private views of the cube.
Write access does not allow you to edit data
identified by consolidated elements or derived
from rules. By definition, values derived by
consolidation or by rules cannot be edited.

Element Members of the group can view and edit data

identified by the element.

Dimension Members of the group can edit element attributes,

edit element formats, and create private subsets
for the dimension. Members of the group can also
edit attributes for the dimension itself.

Reserve Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
Reserve privilege for an object.
Note that when you reserve an object, that reservation expires when the server containing the object
shuts down.

Object Description

Cube Members of the group can view and edit data in the
cube, and can reserve the cube to prevent other
clients from editing cube data. You can release a
cube you have reserved.

Element Members of the group can view and edit data

identified by the element, and can reserve the
element to prevent other users from editing data.
You can release an element you have reserved.

Dimension Members of the group can add, remove, and

reorder elements in the dimension, and can
reserve the dimension to prevent other users from
editing the dimension structure. You can release a
dimension you have reserved.

Lock Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
Lock privilege for an object.
Note that there is no Unlock privilege, and that only users with Admin privilege for an object can unlock
that object.

Chapter 1. Windows and Dialog Boxes 49

 Object Description

Cube Members of the group can view and edit data in the
cube, and can lock the cube.
When a cube is locked, nobody can update its data.

Element Members of the group can view and edit data

identified by the element, and can lock the
element.
When an element is locked, nobody can update
data identified by the element.

Dimension Members of the group can add, remove, and

reorder elements in the dimension, and can lock
the dimension to prevent other users from editing
the dimension structure.
When a dimension is locked, nobody can edit the
dimension structure.

Admin Privilege
The following table describes the ability of TM1 user groups to access various TM1 objects when assigned
Admin privilege for an object.

Object Description

Cube Members of the group can read, write, reserve,

release, lock, unlock, and delete the cube.

Element Members of the group can view, update, and delete

cells identified by the element. They can reserve,
release, lock, and unlock the element. They can
also grant access privileges for this element to
other users.

Dimension Members of the group can add, remove, and

reorder elements in the dimension. They can
reserve, release, lock, and unlock the dimension.
They can also create public subsets for the
dimension and grant access privileges for the
dimension to other users.

Application Members of the group can see the application, use

references within the application, and create both
public and private references in the application.
They can also create both public and private sub-
applications.
When a group has Admin privilege to an
application, members of the group can set security
privileges for all references and sub-applications
within the application for other groups but not their
own group.

50 IBM Planning Analytics: Reference

 Object Description

Reference Members of the group can use the reference, as

well as update or delete the reference. They can
publish private references, and privatize public
references.

Select Dimension
When you access the Security Assignment dialog box from an individual dimension, the Select Dimension
option is available. This option lets you assign access privileges for elements in multiple dimensions.
After you assign access privileges for one dimension, click Save then select a new dimension from the
Select Dimension list. When you complete assigning privileges for all desired dimensions, click OK to
dismiss the dialog box.

Select Cube Dialog Box

Select the cube name you want to insert into your worksheet or formula and click OK.

Select Cube for Rules Dialog Box

Select the cube for which you want to create a new rule and click OK.

Select Dimension Dialog Box

Select the dimension name you want to insert into your worksheet or formula and click OK.

Select Element Dialog Box

Select the element name you want to insert into your worksheet or formula and click OK.

Server Explorer (Main Window)

Left pane (Tree pane)

Displays a hierarchical representation of all objects on servers to which you are currently connected.

Right pane (Properties pane)

Displays the properties of the object selected in the left pane of the Server Explorer. Properties vary
according to the object selected.

File Menu
The following options are available on the File Menu in the Server Explorer.

Menu Item Description

Options Opens the TM1 Options dialog box.

Shutdown local server Shuts down the local server and prompts you to
save changes to data. This option is available only
when the local server is running.

Chapter 1. Windows and Dialog Boxes 51

 Menu Item Description

Start local server Starts the local server. This option is available only
when the local server is not running.

Refresh Available Servers Updates the display of available servers in the left
pane of the Server Explorer.

Exit Closes the Server Explorer and any other windows

associated with TM1 Perspectives/TM1 Architect.

Dynamic Menu
The options available from the second menu in the Server Explorer vary according to the type of object
currently selected.

Servers Group
The following options are available from the TM1 menu when you select the servers Group in the Server
Explorer.

Option Description

Save Data All Saves data on all servers to which you are currently
connected.

Server
The following options are available from the Server Menu when you select an individual server in the
Server Explorer.

Option Description

Save Data Saves all edits to data on the selected server.

Recycle (Clear memory for Local Server) Shuts down and restarts the local server. When
choosing this option you have the choice of
recycling and saving data on the local server, or
recycling and abandoning changes on the local
server.

Shutdown Shuts down the local server. This option is

available only when the local server is selected.

Security, Clients/Groups Opens the Clients/Groups Editor for the selected

server. You must have Admin privileges for the
server to access the Clients/Groups Editor.

Security, Change Password Opens the Password Change dialog box, from
which you can change your password on the
selected server.

Security, Refresh Security Update all security structures/assignments on the

selected server.

52 IBM Planning Analytics: Reference

Option Description

Capability Assignments Allows the administrator to set permissions for

specific features by usergroup. At the intersection
of the usergroup and the capability, administrators
can set Grant or Deny (same as blank) to enable
or disable that capability. Some capability settings
may be ignored depending on the configuration
settings made on the server.
The following capabilities can be set per
usergroup:
• Block Access to Server Explorer
To prevent the Server Explorer from launching,
click the intersection of this capability and the
usergroup and select Grant. Blank or Deny
means the Server Explorer is used by this
usergroup.
• Personal Workspace Writeback Mode
To enable a usergroup to use Personal
Workspaces, click the intersection of the
usergroup and this capability and select Grant.
Blank or Deny means this usergroup does not use
Personal Workspaces.
If DisableSandboxing is set to T, this capability
assignment is ignored.
• Sandbox
To enable a usergroup to use Sandboxes to
create multiple what-if scenarios, click the
intersection of the usergroup and this capability
and select Grant. Blank or Deny means this
usergroup cannot use multiple Sandboxes.
If DisableSandboxing is set to T, this capability
assignment is ignored.
See the TM1 Operations and TM1 Architect,
Perspectives, and TM1 Web documentation for
more information.

View Transaction Log Opens the Transaction Log Query dialog box, from
which you can view a log of transactions on the
selected server.

View Message Log Opens the Message Log dialog box, which displays
messages recorded on the selected server.

Start Performance Monitor Initiates performance monitoring. When the

Performance Monitor is running TM1 populates
several control cubes that let you track statistics
for cubes, clients, and server.

Stop Performance Monitor Stops performance monitoring.

Chapter 1. Windows and Dialog Boxes 53

 Option Description

Deferred Updates, Start Batch Updates Starts batching updates to be sent to the selected
server.

Deferred Updates, End Batch Updates Ends batching updates and sends all edits to the
selected server.

Server Manager Opens the Clients Messaging Center dialog box,

from which you can shutdown the selected server,
disconnect clients, and broadcast messages.

Cancel Shutdown Cancels a previously executed server shutdown.

Disconnect Self Disconnects your client from the selected server.

Who Am I Returns a message indicating your user name on

the server.

Applications
The following options are available from the Applications Menu when you select either the Applications
group or an individual application in the Server Explorer.

Option Description

Open Expands the selected application or Applications

group to reveal references and sub-applications.

Close Collapses the selected application or Applications

group to hide references and sub-applications.

Delete Deletes the selected application. When you delete

an application, all sub-applications and references
within the application are automatically deleted.
This option is not available when the Applications
group is selected.

Rename Sets the selected application name in edit mode,

so you can type a new name for the application.
This option is not available when the Applications
group is selected.

Security, Security Assignments Opens the TM1 Security Assignments window,

from which you can assign security privileges for
the references and immediate sub-applications
contained within the selected application or
Applications group.

Security, Make Public Choose this option to publish a private application.

When you publish an application, all sub-
applications and private references to public
objects within the application are automatically
published as well. This option is not available when
the Applications group is selected.

54 IBM Planning Analytics: Reference

Option Description

Security, Make Private Choose this option to privatize a public application.

When you privatize an application, all sub-
applications and public references within the
application are automatically privatized as well.
This option is not available when the Applications
group is selected.

Cubes
The following options are available from the Cubes Menu when you select a cubes group in the Server
Explorer.

Option Description

Create New Cube Opens the Creating Cube dialog box.

Edit Attributes Opens the Attributes Editor for the selected cube.

Security Assignments Opens the TM1 Security Assignments dialog box

for the cubes in the selected cube group. You must
be a member of the Admin group on the server
containing the cube group to access this dialog
box.

Cube
The following options are available from the Cube Menu when you select a cube in the Server Explorer.

Option Description

Browse Opens the cube for browsing in the Cube Viewer

window.

Browse in Excel Opens the cube for browsing in the In-Spreadsheet

Browser.

Pick Copies the cube name to the Clipboard.

Create New Cube Opens the Creating Cube dialog box.

Unload Cube Unload the selected cube from the server's

memory.

Delete Cube Deletes the selected cube and all associated data.
You must have Admin privileges to delete a cube

Re-order Dimensions Opens the Cube Optimizer window, from which

you can optimize the order of dimensions in the
selected cube.

Create Rule Opens the Rules Editor, from which you can create
a rule for the selected cube.

Chapter 1. Windows and Dialog Boxes 55

 Option Description

Delete Rule Deletes the rule associated with the selected cube.
You must have Admin privileges for a cube to
delete the associated rule.

Export as ASCII Data Exports the data contained in the selected cube to
a comma-delimited (.cma) ASCII file.

Synchronize Data Synchronizes the data in the selected cube with

data from the associated replication server.

Security, Reserve Temporarily reserves the selected cube so that

other clients cannot edit data in the cube. You must
have Reserve privileges to reserve a cube.

Security, Release Releases a cube you have reserved so that other

clients can edit data in the cube. You must have
Reserve privileges to release a cube.

Security, Lock Permanently locks the selected cube so that other

clients cannot edit data in the cube. The client
you are logged in with also becomes locked out of
these elements. You must have Lock privileges to
lock a cube.

Security, Unlock Unlocks the selected cube so that other clients

can edit data. You must have Admin privileges to
unlock a cube.

Properties Opens the Cube Properties dialog box, from which

you can set measure and time dimensions.

Dimensions
The following options are available from the Dimensions Menu when you select a dimensions group in the
Server Explorer.

Option Description

Create New Dimension Opens the Dimension Editor window, from which
you can create a new dimension.

Edit Attributes Opens the Attributes Editor window, from which

you can assign and edit attributes for all
dimensions in the selected group.

Security Assignments Opens the TM1 Security Assignments dialog box,

from which you can assign security privileges for
each dimension in the group. You must be a
member of the Admin group to use this option.

Dimension
The following options are available from the Dimension Menu when you select a dimension in the Server
Explorer.

56 IBM Planning Analytics: Reference

Option Description

Insert New Subset Opens the Subset Editor window for the dimension.

Pick Copies the dimension name to the Clipboard.

Edit Dimension Structure Opens the selected dimension for editing in the
Dimension Editor window. You must have Write
privileges for the selected dimension to use this
option.

Create New Dimension Opens an empty Dimension Editor window, from

which you can create a new dimension. You must
be a member of the Admin group to create a new
dimension.

Export Dimension Exports the selected dimensions as a comma-

delimited (.cma) file.

Delete Dimension Deletes the selected dimension. You must be a

member of the Admin group to delete a dimension.

Set Elements Order Opens the Dimension Element Ordering dialog box,
from which you can set the order of elements in the
selected dimension.

Edit Element Attributes Opens the Attributes Editor window, from which
you can assign and edit attributes for all elements
in the selected dimension.

Synchronize Data Synchronizes the data in the selected dimension

with associated data from any replicated servers.

Security, Reserve Temporarily reserves the selected dimension so

that other clients cannot edit the dimension
structure. You must have Reserve privileges to
reserve a dimension. Note that this option reserves
only the dimension structure. It does not reserve
any data identified by elements in the selected
dimension.

Security, Release Releases a reserved dimension so that other

clients can edit the dimension structure. You must
have Reserve privileges to release a dimension.
Note that this option releases only the dimension
structure. It does not release any data identified by
elements in the selected dimension.

Security, Lock Permanently locks the selected dimension so that

other clients cannot edit the dimension structure.
You must have Lock privileges to lock a dimension.
Note that this option locks only the dimension
structure. It does not lock any data identified by
elements in the selected dimension.

Chapter 1. Windows and Dialog Boxes 57

 Option Description

Security, Unlock Unlocks the selected dimension so that other

clients can edit the dimension structure. You must
have Admin privileges to unlock a dimension.
Note that this option unlocks only the dimension
structure. It does not unlock any data identified by
elements in the selected dimension.

Security, Elements Security Assignments Opens the TM1 Security Assignments dialog box,
from which you can assign security privileges for
each element in the dimension. You must have
Write privileges for the selected dimension to use
this option.

CubeViews
The following options are available from the CubeViews Menu when you select a views group in the Server
Explorer.

Option Description

Create New View Opens the Cube Viewer window, from which you
can configure a new view.

CubeView
The following options are available from the CubeView Menu when you select a view in the Server
Explorer.

Option Description

Browse Opens the view in the Cube Viewer window.

Browse in Excel Opens the view in the In-Spreadsheet Browser.

Export as Text Data Opens the View Extract window, from which you
can export the view as a comma-delimited (.cma)
file.

Publish This option is available when you select a private

view. Choose this option to convert a view from
private to public. Public views are available to all
clients with Read privileges for the cube containing
the view.

Delete View Deletes the selected view. Note that this option
only deletes the view configuration, and not the
data contained in the view.

Subsets
The following options are available from the Subsets Menu when you select a subsets group in the Server
Explorer.

58 IBM Planning Analytics: Reference

Option Description

Insert New Subset Opens the Subset Editor window, from which you
can define a new subset.

Subset
The following options are available from the Subset Menu when you select a subset in the Server Explorer.

Option Description

Open Opens the selected subset in the Subset Editor

window.

Create New Subset Opens the Subset Editor window for the dimension
to which the selected subset belongs. You can
define a new subset in this window

Publish This option is available when you select a private

subset. Choose this option to convert a subset from
private to public. Public subsets are available to
all clients with Read privileges for the dimension
containing the subset.

Delete Subset Deletes the selected subset. Note that this option
only deletes the subset configuration, and does not
delete the elements contained in the subset from
the parent dimension.

Replications
The following options are available from the Replications Menu when you select a replications group in
the Server Explorer.

Option Description

Insert New Replication Opens the Create Server Replication Object

dialog box, from which you can establish a new
replication connection.

Replication
The following options are available from the Replication Menu when you select a replication in the Server
Explorer.

Option Description

Synchronize Data Synchronizes data between the target and source

servers.

Modify Replication Parameters Opens the Create Server Replication Object dialog
box, from which you can modify the parameters for
the selected replication connection.

Delete Replication Deletes the selected replication connection.

Chapter 1. Windows and Dialog Boxes 59

 Option Description

Display Chores Involved Opens the Select Chores to Modify dialog box. You
can use this dialog box to remove the selected
replication from any associated chores.

Replicated Cube
The following options are available from the Cube Menu when you select a replicated cube in the Server
Explorer.

Option Description

Replicate Opens the Replicate Cube dialog box for the

selected cube, from which you can define
replication parameters and replicate the cube.

Synchronize Data Synchronizes data between the replicated cube

and the source server.

Processes
The following options are available from the Processes Menu when you select a processes group in the
Server Explorer.

Option Description

Create New Process Opens TurboIntegrator, from which you can create
a new process.

Security Assignments Opens the TM1 Security Assignments dialog box,

from which you can set security privileges for
processes on the current server.

Process
The following options are available from the Process Menu when you select a process in the Server
Explorer.

Option Description

Display Chores Involved Opens the Select Chores to Modify dialog box. You
can use this dialog box to remove the selected
process from any associated chores.

Edit Process Opens the selected process in a TurboIntegrator

window.

Run Process Runs the selected process.

View Views a process in read-only mode. Allows

members of the DataAdmin and SecurityAdmin
groups to view a process in read-only mode when
the Security Access option is enabled for the
process.

60 IBM Planning Analytics: Reference

Option Description

Security Access Controls whether a process is allowed to modify

security data in the script of the process. Only
members of the ADMIN and SecurityAdmin groups
are allowed to set this option. You set this option
on a process-by-process basis.

Delete Process Deletes the selected process.

Use Active Sandbox Configures the process to use the data in the
current active sandbox instead of base data
when you run the process. The active sandbox is
determined by which sandbox is currently selected
in the Cube Viewer.

Chores
The following options are available from the Chores Menu when you select a chores group in the Server
Explorer.

Option Description

Create New Chore Opens the Chore Setup Wizard, from which you can
schedule a new chore.

Security Assignments Opens the TM1 Security Assignments dialog box,

from which you can set security privileges for
chores on the current server.

Chore
The following options are available from the Chore Menu when you select an individual chore in the Server
Explorer.

Option Description

Activate Schedule This option toggles the chores execution status.

Select this option to activate the selected chore
for execution. A check mark displays next to this
option when a chore is activated.
Select this option again to deactivate the selected
chore.

Edit Opens the chore for editing in the Chore SetUp

Wizard.
You must deactivate a chore before editing.

Run Runs the selected chore.

Delete Deletes the selected chore.

You must deactivate a chore before deleting.

Chapter 1. Windows and Dialog Boxes 61

Edit Menu
The following options are available on the Edit Menu in the Server Explorer.

Option Description

Copy Copies the selected object label to the Clipboard.

Delete Deletes the selected object from the server.

View Menu
The following options are available on the View Menu in the Server Explorer.

Option Description

Status Bar Hides or displays the status bar at the bottom

of the Server Explorer window. A check mark
indicates that the status bar is displayed.

Toolbar Hides or displays the toolbar at the top of the

Server Explorer window. A check mark indicates
that the toolbar is displayed.

Properties Window Hides or displays the Properties pane of the

Server Explorer. A check mark indicates that the
Properties pane is displayed.

Objects: Hides or displays any of the objects in the Server

Explorer's left pane (Tree pane).
Applications
A check mark indicates that the selected object is
Cubes
displayed.
Dimensions
Replications
Processes
Chores

Collapse All Children Contracts the tree in the left pane of the Server
Explorer to hide all children of a selected object.

Expand All Children Expands the tree in the left pane of the Server
Explorer to show all children of a selected object.

Display Control Objects Hides or displays the control cubes and

dimensions in the left pane of the Server Explorer
window. A check mark indicates that the control
objects are displayed.

Refresh Updates the current hierarchical display of objects

in the left pane of the Server Explorer.

Subset Editor

62 IBM Planning Analytics: Reference

 Elements pane
Displays a hierarchical representation of all elements in the subset you are currently viewing.

Properties pane
Displays the properties of the elements selected in the Elements pane of the Subset Editor. When you
select a consolidated element, this pane displays the names, types, and weights of all children of the
consolidated element.
Note: When viewing an exceptionally large dimension set in the Subset Editor with the Properties pane
on, you might experience performance issues. This can happen when you select a consolidation in the
Elements pane and TM1has to display the entire list of related elements and properties in the Properties
pane.
If you are working with large dimension sets, you may want to turn off the Properties pane. To turn off the
Properties pane, click the Properties Window option in the View Menu to remove the check mark next to
the option.

Subset Menu

Menu Item Description

Open Opens the TM1 Save Subset dialog box. Select

a subset from the list and click OK to open the
subset.

Reload Reloads the current subset definition.

Save Saves the current subset definition.

Save as Saves the current subset definition under a new

name.

Close Closes the Subset Editor.

Edit Menu

Menu Item Description

Undo Undoes last action.

Redo Restores the last "undo" action.

Cut Cuts selected elements to the Clipboard.

Copy Copies selected elements to the Clipboard.

Copy Unique Name Copies the element name, as an MDX expression,

to the Clipboard. The copied element name can
then be pasted into the Expression Window of the
Subset Editor.

Chapter 1. Windows and Dialog Boxes 63

 Menu Item Description

Paste Pastes the contents of the Clipboard at the current

insertion point.

Paste Above Paste the contents of the Clipboard above the

currently selected element.

Paste Below Paste the contents of the Clipboard below the

currently selected element.

Insert Subset Opens a new instance of the Subset Editor so you

can add a user-defined consolidation to the current
subset.

Keep Keeps only the currently selected elements in the

Elements pane of the Subset Editor, and removes
all other elements.

Delete Removes selected elements from the current

subset definition.

Pick Elements, Horizontal Copies selected elements to the Clipboard in a

horizontal orientation, so they can be pasted into
a worksheet row.

Pick Elements, Vertical Copies selected elements to the Clipboard in a

vertical orientation, so they can be pasted into a
worksheet column.

Sort, Descending Sorts all elements in the Elements pane in

alphabetically descending order.

Sort, Ascending Sorts all elements in the Elements pane in

alphabetically ascending order.

Sort, Hierarchy Sorts all elements in the Elements pane in

hierarchical order, so you can see the parent/child
relationship of elements.

Sort, Index Ascending Sorts all elements in the Elements pane in

ascending order according to element index value.

Sort, Index Descending Sorts all elements in the Elements pane in

descending order according to element index
value.

Drill Down Displays the immediate children of selected

elements.

Roll Up Displays the immediate parents of selected

elements.

Expand Element Displays all children of selected elements.

64 IBM Planning Analytics: Reference

 Menu Item Description

Collapse Element Collapses selected consolidations so that children

are not displayed.

Filter by, Levels Opens the Filter by Level dialog box, from which
you can select elements by hierarchy level.

Filter by, Attribute Opens the Filter by Attribute dialog box, from
which you can select elements by attribute value.

FIlter by, View Extract Lets you select only those elements that satisfy a
user-defined query.
This option is available only when you open the
Subset Editor by clicking on a dimension label in
the Cube Viewer window.

Filter by, Wildcard Lets you select elements that match a user-defined
search string.

Select Alias Opens the TM1 Aliases dialog box, from which you
can select a previously defined alias by which to
display element names.

Security, Reserve Temporarily reserves the selected element so that

other clients cannot edit data identified by the
element. You must have Reserve privileges to
reserve an element.

Security, Release Releases a reserved element so that other clients

can edit data identified by the element. You must
have Reserve privileges to release an element.

Security, Lock Permanently locks the selected element so that

other clients cannot edit data identified by the
element. You must have Lock privileges to lock an
element.

Security, Unlock Unlocks the selected element so that other clients

can edit data identified by the element. You must
have Admin privileges to unlock a dimension.

Edit Element Formats Opens the Edit Element Formats worksheet, where
you can define display styles for dynamic slices
and TM1 Websheets.

View Menu

Chapter 1. Windows and Dialog Boxes 65

 Menu Item Description

Toolbars Opens a submenu that lets you enable or disable

the display of all Subset Editor toolbars.
A check mark indicates that a toolbar is displayed.

Status Bar Hides or displays the Status Bar at the bottom of

the Subset Editor window.
A check mark indicates that the Status Bar is
displayed.

Properties Window Hides or displays the Properties pane.

A check mark indicates that the Properties pane is
displayed.

Expression Window Hides or displays the Expression Window at

the bottom of the Subset Editor. A check mark
indicates that the Expression Window is displayed.

Expand Above This option determines how consolidations expand

and contract when you drill down.
When this option is turned on, children of a
consolidation expand above the consolidation
when you drill down.
When this option is turned off, children of a
consolidation expand below the consolidation
when you drill down.
When the Expand Above option is enabled in a
subset, drilling down on a consolidation in either
the Cube Viewer, In-Spreadsheet Browser, or slice
results in the following behavior:
If the option is enabled in a row subset, drilling
down on a consolidation displays the children
above the consolidation.
If the option is enabled in a column subset, drilling
down on a consolidation displays the children to
the left of the consolidation.

Refresh Updates the display of the Elements pane.

Tools Menu

Menu Item Description

Record Expression Starts recording your actions in the Subset Editor.

66 IBM Planning Analytics: Reference

 Menu Item Description

Stop Recording Stops recording your actions in the Subset Editor.

When you stop recording, TM1 generates an MDX
expression that can be saved to create a dynamic
subset.

Clear Expression Clears the contents of the Expression Window.

Filter Opens the Filter Subset dialog box, which lets you
create a dynamic subset based on cube values.

Aliases Dialog Box

To view current subset elements by assigned aliases, select an alias name from the list and click OK.

TM1 Options Dialog Box

The following options can be set in the TM1 Options dialog box.

Login Parameters

Option Description

Admin Host Enter the computer name of your Admin Host. The
Admin Host is the computer on which your Admin
Server runs.

Integrated Login Toggle this option on to use Integrated Login.

Toggle this option off to use standard TM1 login
security.
The default is off.

Local Server

Option Description

Local Server Data Directory Enter the full path to your Local Server Data
Directory, or click the accompanying Browse
button to browse to the directory. You can also
click the down arrow to select from a list of
recently accessed directories.

Connect to Local Server on Startup Toggle this option off to start TM1
Perspectives/TM1 Architect without launching the
local server.
The default is on.

Chapter 1. Windows and Dialog Boxes 67

 Note: The local server is supported only on 32-bit versions of TM1. The default data directory for the local
server is Pdata. If you are running a 64-bit version of TM1, the Sdata sample server, which is installed by
default with the TM1 server, contains the same objects and data as are found in Pdata.

Admin Server Transport Layer Security

Option Description

Certificate Authority The full path of the certificate authority file that
issued the Admin Server's certificate.

Certificate Revocation List The full path of the certificate revocation file
issued by the certificate authority that originally
issued the Admin Server's certificate. A certificate
revocation file will only exist in the event a
certificate had been revoked.

Certificated ID The name of the principal to whom the Admin

Server's certificate is issued.

Use Certificate Store Select this option if you want the certificate
authority certificate which originally issued the
Admin Server's certificate to be exported from the
Windows certificate store at runtime.
When this option is selected, you must also set a
value for Export Certificate ID in the TM1 Options
dialog box.

Export Certificate ID The identity key used to export the certificate

authority certificate, which originally issued the
Admin Server's certificate, from the certificate
store.
This parameter is required only if you enable the
Use Certificate Store option.

Transaction Log Query Dialog Box

The Transaction Log Query dialog box lets you query and view records in the TM1 transaction log
([Link]). The dialog box contains fields for four parameters that you must specify to execute a query.

Option Description

Start Time The start date/time for the query.

TM1 queries against all records written to the
transaction log on or after this date/time. You must
use the format MM/DD/YYYY HH:MM:SS to specify
a start time.
The default start date/time is 00:01:00 GMT on the
date the query is launched.

68 IBM Planning Analytics: Reference

 Option Description

End Time The end date/time for the query.

The default is __/__/____ __:__:__, which is an
open-end date/time. If you accept the default, TM1
queries against all records up to the time the query
is launched.

Client(s) The client(s) against which the query is applied.

You can query against either a single client or all
clients. The default is all clients (*).

Cubes(s) The cube(s) against which the query is applied. You

can query against either a single cube or all cubes.
The default is all cubes (*).

To set any of the above parameters, click the arrow next to the appropriate field.

Transaction Log Query Results Dialog Box

The Transaction Log Query Results dialog box presents the result of a transaction log query in table
format. The table contains the following columns for each record returned by the query:

Column Description

LOGTIME The time at which a value was edited.

REPLICATIONTIME The time at which a value was replicated.

CLIENT The name of the client who wrote the value.

OLDVALUE Data value before editing.

NEWVALUE Data value after editing.

CUBENAME The cube to which the value was written.

KEY N There are multiple Key N columns in the table,

each column representing the elements that
identify the value.

The Transaction Log Query Results dialog box includes three menus.
The File Menu contains a single item: Exit.
The Help Menu contains a single item to open help for the dialog box.
The Edit Menu contains the following items:

Menu Item Description

Copy Copies a single selected cell to the clipboard.

Chapter 1. Windows and Dialog Boxes 69

 Menu Item Description

Hide Suppresses the display of selected record(s) in the

table.
You can click Refresh to restore the display of
hidden records.

Sort Opens a sub-menu from which you can choose

columns to sort or a sort order to apply.

Find Opens the Find/Replace dialog box, which allows

you to search the current table.

Select Selects highlighted record(s)

Unselect Unselects highlighted record(s).

Select All Selects all records in the table.

Unselect All Unselects all records in the table.

Back Out Backs out selected record(s). When a record is

backed out, the OLDVALUE for the record replaces
the NEWVALUE for the record.
When multiple records for a single cube location
are selected, records are backed out to OLDVALUE
of the earliest LOGTIME.

TurboIntegrator Editor
The TurboIntegrator Editor lets you define processes for importing data or metadata from several possible
sources. The editor is comprised of five tabs, several of which are dynamic or contain sub-tabs. You define
a process by completing each tab in sequential order.

File Menu

Menu Item Description

Save Saves the current process definition.

Save As Saves the current process definition with a new

name.

Run Runs the current process.

Exit Closes the TurboIntegrator Editor.

Edit Menu

70 IBM Planning Analytics: Reference

 Menu Item Description

Undo Undoes the last typing action that was performed

on the Prolog, Metadata, Data, or Epilog procedure
sub-tab.

Cut Cuts the selected text to the Clipboard.

Copy Copies the selected text to the Clipboard.

Paste Pastes the contents of the Clipboard to the current

field or cell.

Data Source Tab

Use the Data Source tab to identify and access the source from which you want to import data.
Note: When defining a process from the TM1 client, the path to an ASCII or ODBC data source may differ
from the path used by the server. If this happens, the process will fail. To ensure that your processes work
correctly:
• Define processes involving ODBC data sources on the actual server where the process is to reside. Do
not use a remote client to define such a process.
• Use the Windows Network Neighborhood to define the path to ASCII data sources. This ensures that the
path is unambiguous to both clients and servers.
The fields and options available on the Data Source tab vary according to the Datasource Type you select.
The following tables describes the required fields and options for each source.

ODBC
Define an ODBC datasource:

Fields Description

Data Source Name The full path to the ODBC data source.

UserName Your user name on the source.

Password Your password.

Query An SQL query to extract data from the source.

Use Unicode Check here to use Unicode for this source.

Preview Displays the first 10 records.

Text
Define an ASCII or Text datasource:

Chapter 1. Windows and Dialog Boxes 71

 Fields Description

Data Source Name The full path to the source text file. To ensure that
this path is recognizable to both client and server,
click the Browse button and use the Network
Neighborhood to define the path.

Data Source Name On Server When you create a new process, TurboIntegrator
assumes that the data source name on the server
is identical to the data source name used to create
the process.
If the data source name on the server is different
from the local data source used to create the
process, enter the full path to the data source file
on the server.

Delimiter Type If the source uses a character to define the

columns, select Delimited, then choose the
character in the Delimiter box.

Fixed Width If the source uses a fixed width, select Fixed

Width, then use the Set Field Widths button to
open the Preview dialog box to set column widths.

Quote Char Specify the quote character used in your source

data.

Number of title records If the title records span more than one row, enter
the number of rows here. Otherwise, leave this
field blank.

Number Delimiters Enter the character to use for the Decimal

Separator and Thousand Separator in the source.

ODBO
Although the ODBO option remains as a data source selection in the TurboIntegrator editor in Architect
and Perspectives, support for ODBO is deprecated as of Planning Analytics [Link].

SAP
Defines the SAP RFC datasource:

Tab Field Description

Connection System The name of the SAP system you

want to connect to.
If the system name includes
spaces, enclose the name in
double quotes.

Client A number that corresponds to

the UI version on the SAP server.
For example, 498.

User Your username on the SAP

system.

72 IBM Planning Analytics: Reference

Tab Field Description

Password Your password on the SAP

system.

Language The language you want to use to

logon to the SAP system.
All textual descriptions are
returned in the language
specified, if available.
The language parameter is a two-
letter abbreviation, for example,
EN=English.

Additional Connection Enter any other parameters and

Parameters values you use to connect to your
SAP BW system.

Packet Size A value that limits the number

of rows in each packet sent
from SAP to TM1. A smaller
packet size will result in
increased network traffic with
small packets, while a larger
packet size results in decreased
network traffic but larger packets
per transmission.
The default packet size, which is
also the minimum packet size, is
50,000.

Info Cube
Area Field Description
Info Cube Show SAP Technical Names To use technical names, select
this checkbox. Leave this
box unchecked to display by
descriptive name.

Select InfoCube to Load from Use the option to indicate the

InfoCube from which you want to
import data.

Select TM1 Cube to Load to To import the SAP InfoCube to

an existing TM1 cube, click this
option and select the cube to
receive the SAP InfoCube data.

Select TM1 Cube to Load to To create a new TM1 cube when

you import the InfoCube, enter a
name for the new TM1 cube in
this to field.

Chapter 1. Windows and Dialog Boxes 73

 Area Field Description

TM1 Cube Action Create Imports data and metadata from

the SAP InfoCube and creates
a new cube in TM1. Use this
option only when none of the
cubes and dimensions you are
importing exist on the server.

Recreate Destroys an existing TM1 cube

and rebuilds it using data and
metadata from the SAP InfoCube.
Use this option only when the
TM1 cube and dimensions exist,
and you want to replace them
with new structures and data
from the SAP InfoCube.

Update Imports data from an existing

SAP InfoCube cube and inserts
it into an existing TM1 cube.
This option does not change
the structure of cubes and
dimensions on the server.

Processes that specify No Action

do not affect the data or
metadata of TM1 cubes.
Use this option to test and debug
processes or to define your own
custom operations.

Data Action Store Values This option writes cell values

from the SAP InfoCube to the
TM1 cube.
If you choose this option when
the Update Cube option is
selected, existing TM1 cube
values are overwritten by values
imported from the InfoCube.

Accumulate Values The Accumulate Values option

allows you to aggregate existing
TM1 Cube values with values
imported from the SAP InfoCube.

74 IBM Planning Analytics: Reference

Area Field Description

Zero Out Portion of Target Cube This option becomes available

when you select the Update Cube
action.
Select this option if you want to
set all data points in a specified
cube view to zero.
To define the cube view to be
zeroed, you can:
• Click the View list to select an
existing view to be zeroed.
• Click the More button next to
the View option list to define a
new view to be zeroed.

Enable Cube Logging To log changes to cube data while

importing from an SAP InfoCube,
select this option.
To disable logging while
importing, clear this option.
Note: Disabling logging
accelerates data loading and
updating, but makes it
impossible to recover any
updates in the event of a system
failure.

Characteristics tab
Field Description

Select Hierarchies Identify the hierarchies in the Identify the hierarchies in the
datasource. datasource.

Evaluation Date Date when all time-dependent Date when all time-dependent
SAP attributes are imported into SAP attributes are imported into
TM1 as they existed on the TM1 as they existed on the
specified date. Attributes that are specified date. Attributes that are
not time-dependent are imported not time-dependent are imported
as they exist at the time of as they exist at the time of
process execution. process execution.
If this date is cleared, all SAP If this date is cleared, all SAP
attributes are imported as they attributes are imported as they
exist on the date the TM1 exist on the date the TM1
process runs. process runs.
Do not import a hierarchy with Do not import a hierarchy with
intervals. intervals.

Chapter 1. Windows and Dialog Boxes 75

 Field Description

TM1 Dimension Select the existing TM1 Select the existing TM1
dimension that maps to this dimension that maps to this
characteristic. characteristic.
Leave this field empty if you Leave this field empty if you
do not want to import the do not want to import the
characteristic in to your TM1 characteristic in to your TM1
cube. cube.

TM1 Dimension Action Create Create a new TM1 dimension

from the SAP characteristic.

Recreate Entirely recreate an existing

TM1 dimension with elements
imported from the SAP
characteristic.

Update Update an existing dimension

structure by adding new
elements imported from the SAP
characteristic.

AsIs Process the characteristic

through TurboIntegrator, but do
not use the characteristic to
create or modify any TM1
dimensions.
Use this option to test and debug
processes or to manipulate the
characteristic in the Advanced
tab of TurboIntegrator.

Don't Load Do not import the SAP

characteristic into TM1. The
characteristic is entirely
excluded when the SAP
InfoCube is processed through
TurboIntegrator.

Select Attributes Characteristic Attributes Define the attributes for this data
source.

Text Identifies attributes with a string

value.

Numeric Identifies attributes with a

numeric value.

76 IBM Planning Analytics: Reference

Field Description

Alias Identifies attributes that are

alternative names for the
dimensions with which they
are associated. A dimension
alias must be unique from all
other dimension aliases or actual
dimension names

Select Key Figure Select each key figure you want Select each key figure you want
to import into TM1. to import into TM1.
If the key figures map to an If the key figures map to an
existing TM1 dimension, click existing TM1 dimension, click
the TM1 Dimension column the TM1 Dimension column
and select the dimension that and select the dimension that
corresponds to the key figures. corresponds to the key figures.

Restrictions Add Restrictions Create a new restriction for this

characteristic.

SAP Characteristic Select the characteristic to set a

restriction on.

Sign Indicates if the restriction is

inclusive or exclusive.
Choose Include if you want
the TurboIntegrator process to
import only those values that fall
within the restriction definition.
Choose Exclude if you want the
TurboIntegrator process import
only those values that fall outside
of the restriction definition.

Option The Operator used for the

restriction.
There are eight operators to
choose from, as described in the
following table.

Option Restriction Operators

Operator Description

= The restriction identifies only characteristics equal

to the specified Low Value.

<> The restriction identifies only characteristics less

than or greater than the specified Low Value.

< The restriction identifies only characteristics less

than the specified Low Value.

Chapter 1. Windows and Dialog Boxes 77

 Operator Description

> The restriction identifies only characteristics

greater than the specified Low Value.

<= The restriction identifies only characteristics less

than or equal to the specified Low Value.

>= The restriction identifies only characteristics

greater than or equal to the specified Low Value.

[] The restriction identifies only characteristics that

fall between the specified Low Value and High
Value, inclusive.

][ The restriction identifies only characteristics that

fall outside of the specified Low Value and High
Value, inclusive.

There are eight operators to choose from, as described in the following table.
Enter a low value for the restriction in the Low Value column.
Enter a high value for the restriction, if required, in the High Value column.
Note: Restrictions are not validated through TurboIntegrator. You must ensure that the restrictions you
enter are accurate and valid for your SAP data.

Security

Field Description

Import Security Indicates that the security assignments for this

characteristic should be imported.

Top Consolidation Creates a top-level consolidation for the TM1

dimension created using the name entered here.

78 IBM Planning Analytics: Reference

Field Description

Make Texts Unique To generate unique aliases for all elements

created from the SAP characteristic, select this
option. When you import an SAP characteristic
into TM1, characteristic values become TM1
dimension elements while SAP value descriptions
become TM1 element aliases. In TM1, all element
aliases within a dimension must be unique. If a
TurboIntegrator process attempts to assign the
same alias to multiple elements, the process will
generate errors and alias creation will fail.
When Make Texts Unique option is selected, TM1
examines the SAP descriptions that are imported
and converted into TM1 aliases. If TM1 detects
that multiple values use identical descriptions,
TM1 appends the value name to the description to
generate unique aliases.
If Make Texts Unique is not checked, no SAP_Text
data is fetched.
When Make Text Unique is not checked, you
can add DataSourceSAPUsingTexts=1;in the
prolog to import the alias attribute values.
See the AttrPutS function to get the same behavior
using a TI script.

Evaluation Date All characteristic values that existed between the

selected date and the date of process execution
will be imported into TM1. When there is no
evaluation date specified, the default is the date
on which the TurboIntegrator process is executed.

SAP Table

Field Description

SAP Table Indicates that the data source is an SAP table

query.

Table Name Name of the SAP table to use.

Filter string An SQL filter string to be used in the WHERE clause

when the SQL SELECT statement that is generated
by TurboIntegrator is executed against the SAP
table.

Chapter 1. Windows and Dialog Boxes 79

 ODS Table

Field Description

ODS Table Used to export TM1 data to an ODS table which

can then be used to import data through a SAP
Infocube.

ODS Setup Define the details of the ODS table.

Browse Select the TM1 View to use as the data source.

Show Technical Names To use technical names, select this checkbox.

Leave this box unchecked to display by descriptive
name.

Select ODS Table Select the ODS table to export to.

Columns Columns may be either SAP characteristics or

key figures. You must be familiar with the
structure of the ODS table to know which columns
are characteristics and which are key figures;
TurboIntegrator does not differentiate the ODS
table column types.
You should be aware of the following details when
mapping dimensions to characteristics:
• You do not have to map a dimension to every
characteristic column in the ODS table. Some
columns may not have a corresponding TM1
dimension when the mapping is complete. In
this case, any characteristic column that is
not mapped will be empty when the export is
completed.
• You should not map a single TM1 dimension to
multiple ODS characteristic table columns. The
TurboIntegrator user interface does not prevent
you from doing so, but such mapping will result in
redundant column values in the ODS table.
• When you map a TM1 view title dimension to a
characteristic, and the title dimension does not
use a named subset, only the last element in
the current unnamed title subset is exported to
the ODS table. If the title dimension does use a
named subset, all subset elements are exported
to the ODS table.

80 IBM Planning Analytics: Reference

Field Description

Select Measure The last dimension in the source cube view is

assumed to be the measures dimension. When
you map a measures dimension to an ODS table
column, the Select Measure button becomes
available.
Select the single element that maps directly to the
key figure column in the ODS table
If your ODS table includes a single key figure
column, you can also use the alternate key figure.

TM1 Dimension If your ODS table includes a single key figure

column, you can use the _TM1CellValue_ option to
map TM1 cube values to the ODS table. You cannot
use the _TM1CellValue_ option if your ODS table
contains multiple key figure columns.
To use this option, do not map the TM1 measures
dimension to the key figure column. Instead,
click the TM1 Dimension column and select
_TM1CellValue_.
When you use this alternate method to map TM1
cube values, the TM1 measures dimension should
not be mapped to any ODS column.

Currency

Field Description

SAP Currency Used to import currency data to a new or existing

three-dimensional cube on your server.

Show SAP Technical Names To use technical names, select this checkbox.
Leave this box unchecked to display by descriptive
name.

Enter Cube Name Enter an existing three-dimensional cube or enter a

new cube name.

From Currency Select the initial currency to import from SAP.

The list of available currencies reflects the
currencies defined in your SAP system.

Target Dimension Specify the TM1 dimension to receive the SAP

currency strings.

To Currency Select the second currency to import from SAP.

Conversion Type Select the conversion method to use when

converting the initial currency to the second
currency.

Chapter 1. Windows and Dialog Boxes 81

 TM1
Uses a TM1 cube or dimension as the datasource.

Field Description

Cube View Use the Browse button to select an available TM1

view or Dimension to use as the data source. Click
Dimension Subset
the Preview button. Then complete the fields on
the other tabs.

IBM Cognos Package Connector

Removed in v2.0.8 Indicates that the datasource is a published IBM Cognos Package created from an SAP
query.

Package

Field Description

Connection Define the connection to this data Define the connection to this data
source. source.

Authentication Namespace Displays all created IBM Cognos

Namespaces currently available.

UserID Password

Package Select Package Click the Browse button to select

an available publish Package.

Select TM1 cube to load to If you are importing the data

directly into an existing TM1
cube, enter the cube name here
or use the pull-down.

Data Action, Cube Action, Enable See the descriptions of these

Cube Logging fields in the SAP Info Cube
above.

Dimension

Field Description

Dimension Package Identify the Package to use for

this dimension.

Dimension to load from Identify the dimension to use.

Dimension to load into Identify the dimension to import

into.

TM1 Dimension Action See the description for the

Characteristics tab for details.

82 IBM Planning Analytics: Reference

 Field Description

Retrieve Security Settings Use the security on the

dimension.

Top Consolidation The name of a top-level

consolidation for the TM1
dimension with all imported
elements as children of the
consolidation.

Select Hierarchies Select and map the hierarchies

to use in this import and define
how they are mapped into the
new TM1 dimension. See the
IBM Cognos TM1 TurboIntegrator
documentation for details.

Select Attributes Select the Attributes to use and

define the mapping. See the
IBM Cognos TM1 TurboIntegrator
documentation for details.

None
Used to add a user-defined prolog to a process.
If the data source for the process is None, TurboIntegrator immediately executes the Epilog procedure
after the Prolog finishes processing.
Note: When the data source for a process is None, the Metadata and Data procedures are ignored. In this
case, all scripts for the process must be created in either the Prolog or Epilog procedures.

Preview Grid
The preview grid displays the first ten records in your data source. Use this grid to confirm that the source
is correct and to help determine the structure of records.
If you change your data source, click Preview again to refresh the display of the grid.

Variables Tab
The Variables tab includes a grid and two buttons.

Grid
Use the Variables grid to assign variables and identify the contents of each column in your data source.
The Variables grid includes the following columns.

Column Description

Column ID Lists each unique field or column identified in your

data source. Cells in this column cannot be edited.

Chapter 1. Windows and Dialog Boxes 83

 Column Description

Variable Name Contains an automatically generated variable for

each column in your data source. All generated
variables are named Vn, where n is 0 for the
first column and is incremented by 1 for each
subsequent column in the source.
To assign a different variable, click the appropriate
cell and enter the new variable.

Variable Type Contains a list for each column in your data source.
Use the list to specify whether a variable is string
or numeric.

Sample Value Contains sample values from the first record of

your source. These sample values help you identify
the contents of each column of your source. Cells
in the Sample Value column cannot be edited.

Contents Contains a list for each column in your data source.

Use the list to specify the type of value contained
in each column of your source.

Formula This column is grayed-out for all fields in your

source, and becomes available only when you
create a new variable.
When you create a new variable, double-click
the associated Formula cell to open the Process
Variable Formula dialog box, from which you can
define a formula for the variable.

Buttons

Button Description

New variable Click to create a new variable.

Delete Click to delete a user-created variable.

Process Variable Formula

The Process Variable Formula dialog box displays and allows editing of formulas used in a TurboIntegrator
process. When a formula exists, and you click Formula on the Variables tab, the currently set formula
displays in the Formula window. Click New Variable to define a new formula.

Option Description

Formula The currently entered formula displays in this

window. As you enter formula text this window
updates.

84 IBM Planning Analytics: Reference

 Option Description

Destination Choose the location for this formula depending on

your programming needs for this process. Select
Data to put this formula into the Data section of
the TurboIntegrator process. Select Metadata to
position the formula in the MetaData section. Both
puts the formula in both locations.

Evaluate Click here to validate the formula.

Sample value When the formula is evaluated, information about

the formula displays here. For example, Line 1:
Syntax error on or before: \n (end of line) missing
semicolon.

Show automatically everytime the variable name Click here to display this dialog box if the variable
changes name is changed. If the box is cleared, you must
manually request it by clicking the Formula box on
the Variables tab,

Maps Tab
Use the Maps tab to specify how source data maps to cubes, dimensions, data, consolidations, and
attributes in the TM1 database.
The Maps tab consists of a series of sub-tabs, each containing options that let you map variables for your
source data to existing TM1 metadata structures. The sub-tabs that are available vary according to the
type of values contained in your source data, as specified in the Contents column of the Variables tab.
The Maps tab contains the following sub-tabs.

Cube
Use the Cube sub-tab to specify how TurboIntegrator maps imported data to TM1 cubes. The Cube
sub-tab includes the following options.

Option Description

Cube Action Select an option to create, update, recreate, or

apply no action to a cube.

Cube Name Specify the cube to which the action applies.

If creating a new cube, type the cube name in the
entry field. Otherwise, select an existing cube from
the list.

Zero Out Portion This option becomes available when you select the
Update Cube action. Select this box if you want to
set all data points in a cube view to zero.

View Name This option becomes available when you select the
Update Cube and Zero Out Portion options.
Select or define the view that encompasses the
data points you want to zero out.

Chapter 1. Windows and Dialog Boxes 85

 Option Description

Data Action Select an option that determines how processed

data is stored in the cube.
Store Values overwrites existing cube values with
values imported by the process.
Accumulate Values adds values imported by the
process to existing cube values.

Enable Cube Logging Fill this check box to write cube changes to the
[Link] file. Clear this box to process cubes
without recording changes in [Link].

Dimensions
Use the Dimensions sub-tab to map element variables to dimension elements.
The sub-tab includes a grid you use to map individual variables to dimensions in the TM1 database. The
grid includes the following columns.

Column Description

Element Variable Contains the name of each variable for which

you specified a Contents value of Element. The
Contents value is specified in the Variables tab.
This column also contains the label (Data
Variables) for any variables with a Contents value
of Data.

Sample Value A sample value from the first record of your

data source. Use this value to help identify the
dimension to which the element variable maps.

Dimension Lists all dimensions available on the server. Select

the dimension to which the element variable maps.
To map the element variable to a new dimension,
type the new dimension name in the entry field.

Order in Cube This option becomes available when the Cube

Action is Create.
Specify the order of each dimension in the cube
you are creating.

Action Lists available dimension actions. Select an action.

To create a new dimension, you must specify an
action of Create.

Element Type Select an element type for the variable, either

Numeric or String.

86 IBM Planning Analytics: Reference

Column Description

Element Order Select an option for ordering elements in any

dimensions you are creating or updating. There are
four sort orders:
Input - Sorts elements in the order they are
created in the dimension.
Name - Sorts elements in alphabetical order, either
ascending or descending.
Level - Sorts elements by hierarchy level, either
ascending or descending.
Hierarchy - Sorts elements as they exist in the
dimension hierarchy.

Data
Use the Data sub-tab to map data variables to specific elements.
The sub-tab includes a grid you use to map individual variables to elements in the TM1 database. The grid
includes the following columns.

Column Description

Data Variable Contains the name of each variable for which you
specified a Contents value of Data. The Contents
value is specified in the Variables tab.

Element Click the right arrow button to open the Subset

Editor, where you can choose the element to which
the variable maps.
To map the variable to a new element, type the
element name in the entry field.

Element Type Select an element type here.

Sample Value A sample value from the first record of your data
source. Use this value to help identify the element
to which the data variable maps.

Consolidations
Use the Consolidations sub-tab to map children to consolidated elements.
The sub-tab includes a grid you use to map individual variables to dimensions in the TM1 database. The
grid includes the following columns.

Column Description

Cons. Variable Contains the name of each variable for which you
specified a Contents value of Consolidation. The
Contents value is specified in the Variables tab.

Chapter 1. Windows and Dialog Boxes 87

 Column Description

Dimension List of dimensions to which the consolidation can

map.

Child Variable Lists the variables from which you select the
immediate child of the consolidation.

Weight Assigns a weight to the specified child variable.

Sample Value A sample value from the first record of your data
source. Use this value to help identify the element
to which the consolidation maps.

Element Order Select an option for ordering elements in any

consolidations you are creating or updating. There
are four sort orders:
Input - Sorts elements in the order they are
created in the dimension.
Name - Sorts elements in alphabetical order, either
ascending or descending.
Level - Sorts elements by hierarchy level, either
ascending or descending.
Hierarchy - Sorts elements as they exist in the
dimension hierarchy.

Attributes
Use the Attributes sub-tab to map attribute variables to specific attributes.
The sub-tab includes a grid you use to map individual variables to dimensions in the TM1 database. The
grid includes the following columns.

Column Description

Attribute Variable Contains the name of each variable for which

you specified a Contents value of Attribute. The
Contents value is specified in the Variables tab.

Sample Value Displays a sample value from the data source. Use
this sample to help map the attribute.

Dimension Lists all dimensions available on the server. Select

the dimension to which the attribute applies.

Element Variable Lists the element variables. Select the variable for
the element to which the attribute variable applies.

Attribute Lists the attributes to which the variable can map.

Select the appropriate attribute from this list.

Action Choose to either Create a new attribute or Update

an existing one.

88 IBM Planning Analytics: Reference

 Column Description

Attribute Type Identifies the type of attribute selected in the

Attribute column.

Advanced Tab
The Advanced tab contains several sub-tabs that display statements generated by TM1 based on the
options you select elsewhere in the TurboIntegrator Editor. The Advanced tab also includes a sub-tab
where you can define parameters for the process.

Parameters

Item Description

Insert Click to insert a new parameter.

Delete Click to delete a selected parameter.

Parameters Type a name for each new parameter.

Type For each parameter, select a type here.

Default Value Enter a value to use as the default value for this
parameter when the TurboIntegrator process runs.

Prompt Question Enter a prompt to use for this parameter when the
TurboIntegrator process runs.

Prolog

Item Description

Statement text box Displays generated statements that define a series

of actions to be executed before the data source is
processed.
You can enhance a process by creating additional
statements with rules or TurboIntegrator functions.

Goto Line button Click this button, enter the line you want to go to,
then click OK to go directly to a line of code in the
statement text box.

Metadata

Item Description

Statement text box Displays generated statements that define a series

of actions to be executed on TM1 metadata before
the data source is processed.
You can enhance a process by creating additional
statements with rules or TurboIntegrator functions.

Chapter 1. Windows and Dialog Boxes 89

 Item Description

Got Line button Click this button, enter the line you want to go to,
then click OK to go directly to a line of code in the
statement text box.

Data

Item Description

Statement text box Displays generated statements that define a series

of actions to be executed when the data source is
processed.
You can enhance a process by creating additional
statements with rules or TurboIntegrator functions.

Goto Line button Click this button, enter the line you want to go to,
then click OK to go directly to a line of code in the
statement text box.

Epilog

Item Description

Statement text box Displays generated statements that define a series

of actions to be executed after the data source is
processed.
You can enhance a process by creating additional
statements with rules or TurboIntegrator functions.

Goto Line button Click this button, enter the line you want to go to,
then click OK to go directly to a line of code in the
statement text box.

Schedule Tab
Use this tab to schedule a process to execute at regular intervals.

Item Description

Schedule this Process as a Chore Named Check here to execute this process as a chore at
regular intervals. By default, the chore bears the
same name as the process. If you want to assign
the chore a different name, type it in the entry field.

Chore Start Date and Time Select a start date on the calendar and specify a
start time in the Time field.

Chore Execution Frequency Fill the appropriate fields to establish the interval
at which the chore should be executed.

90 IBM Planning Analytics: Reference

View Extract Window
Use the View Extract window to create a view that includes only those values satisfying user-defined
criteria, or to define a view for export.

Skip parameters

Parameter Description

Skip Consolidated Values Turn this option on to ignore values derived

through consolidation when extracting the view.
Turn this option off to include values derived
through consolidation when extracting the view.
The default is off.

Skip Rule Calculated Values Turn this option on to ignore values derived
through rules when extracting the view. Turn this
option off to include values derived through rules
when extracting the view. The default is off.

Skip Zero/Blank Values Turn this option on to ignore zeros or blank values
when extracting the view. Turn this option off to
include zeros or blank values when extracting the
view. The default is on.

Range parameters

Parameter Description

Operator Select an operator that defines the values you want

to extract.

Numeric Limits Enter a numeric value for the variable(s) in the

Operator.

Text Limits Enter a string value for the variable(s) in the

Operator.

Dimension Elements selection

For each dimension, click the Subset button and select the elements or subset that defines the
parameters for the view extract.

If the view from which you are creating the extract contains more than 16 dimensions, click to page
backward to the previous 16 dimensions, or click to page forward to the next 16 dimensions.

View Styles Dialog Box

The View Styles dialog box lets you apply Excel styles to the TM1 cube view in the In-Spreadsheet
Browser. The dialog box contains several lists that let you apply an existing Excel style to a range of cells,
as well as buttons that let you edit or create styles.

Chapter 1. Windows and Dialog Boxes 91

 Item Description

Background Select a style from this list to apply to the

background of the In-Spreadsheet Browser.

Data Cells Select a style from this list to apply to data cells.
The Data Cells style takes precedence over the
Background style.

Row Header Cells Select a style from this list to apply to row header
cells.
The Row Header Cells style takes precedence over
the Background style.

Column Header Cells Select a style from this list to apply to column
header cells.
The Column Header Cells style takes precedence
over the Background style.

Edit Style buttons Click the appropriate Edit Style button to edit or
create styles for the associated range of the In-
Spreadsheet Browser.

Freeze Panes Toggle this option to freeze and unfreeze panes in

the In-Spreadsheet Browser.
When this option is toggled on, row element names
remain visible when you scroll horizontally through
a view, and column element names remain visible
when you scroll vertically.
When this option is toggled off, row and column
element names move along with cube values as
you scroll through a view.

92 IBM Planning Analytics: Reference

Chapter 2. Rules functions
This section contains a complete list of all Planning Analytics rules functions. You can use any of these
functions when writing rules.

Arithmetic operators in Planning Analytics rules

The following mathematical operators can be used when constructing rules.

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

Comparison operators in Planning Analytics rules

The comparison operators compare values in the formula portion of a rule calculation statement.
To compare two string values, insert the @ symbol before the comparison operator. For example, IF
('A' @= 'B',0,1) yields the number 1.

Operator Meaning

> Greater than

< Less than

>= Greater than or equal to

<= Less than or equal to

= Equal to

<> Not equal to

Logical operators in Planning Analytics rules

You can combine expressions in a rules calculation statement using logical operators.

© Copyright IBM Corp. 2007, 2025 93

 Operator Meaning Example

& (ampersand) AND (Value1 > 5) & (Value1 < 10)

Returns TRUE if the value is
greater than 5 and less than 10.

% (percentage sign) OR (Value1 > 10) % (Value1 < 5)

Returns TRUE if the value is
greater than 10 or less than 5.

~ (tilde) NOT ~(Value1 > 5) Equivalent to

(Value1 <= 5)

Attribute rules functions

Rules functions that work on attributes.

ATTRN
ATTRN returns a numeric attribute for a specified element of a dimension or a dimension hierarchy.
This function is valid in both rules and processes.

Syntax
ATTRN(dimension, element, attribute)

Argument Description

dimension A valid dimension name.

element An element of the dimension or a hierarchy/

element pair.
If specifying a hierarchy/element
pair, you must use this syntax:
'hierarchy_name:element_name'. Note that
the hierarchy name and element name are
enclosed in one set of single quotes.

94 IBM Planning Analytics: Reference

 Argument Description

attribute The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.
Note: : When this function is used in a conditional
statement (IF), the statement is the portion
containing the condition, not the entire conditional
block. After a minor error, execution continues with
the next statement. TurboIntegrator processing
has no knowledge that it was in a conditional once
the minor error is processed, so the next statement
is the next line, not the line after the endif.
To avoid this situation, use variables for any
operation that could encounter a minor error and
then use the variables in the conditional statement.
For example:

V1 = CELLGETN('PNLCube', 'fred',
'argentina','Sales','Jan');
IF(V1 = 454);ASCIIOUTPUT
('[Link]', 'if logic not working
properly');
ENDIF;

Example
In this example, the function returns the numeric value of the Engine Size attribute of the L Series 1.8L
Sedan element in the New Offerings hierarchy of the Model dimension.

ATTRN('Model', 'New offerings:L Series 1.8L Sedan', 'Engine Size')

ATTRS
ATTRS returns a string attribute for a specified element of a dimension or a dimension hierarchy.
This function is valid in both rules and processes.

Syntax
ATTRS(dimension, element, attribute)

Argument Description

dimension A valid dimension name.

element An element of the dimension or a hierarchy/

element pair.
If specifying a hierarchy/element
pair, you must use this syntax:
'hierarchy_name:element_name'. Note that
the hierarchy name and element name are
enclosed in one set of single quotes.

Chapter 2. Rules functions 95

 Argument Description

attribute The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

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

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

CubeATTRN
CubeATTRN returns a numeric attribute for a specified cube.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Product
cube.

CubeATTRN('Product', 'Accounting_Code');

CubeATTRS
CubeATTRS returns a string attribute for a specified cube.
This function is valid in both rules and TurboIntegrator processes.

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.

96 IBM Planning Analytics: Reference

 Example
In this example, the function returns the string value of the Owner attribute of the Product cube.

CubeATTRS('Product', 'Owner');

DimensionATTRN
DimensionATTRN returns a numeric attribute for a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the
Plan_Business_Unit dimension.

DimensionATTRN('Plan_Business_Unit', 'Accounting_Code');

DimensionATTRS
DimensionATTRS returns a string attribute for a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
In this example, the function returns the string value of the Manager attribute of the Plan_Business_Unit
dimension.

DimensionATTRS('Plan_Business_Unit', 'Manager');

Chapter 2. Rules functions 97

ElementAttrN
ElementAttrN returns a numeric attribute for a specified element of a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementAttrN(dimension, hierarchy, element, attribute)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element An element of the dimension.

attribute The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.
Note: : When this function is used in a conditional
statement (IF), the statement is the portion
containing the condition, not the entire conditional
block. After a minor error, execution continues
with the next statement. TI processing has no
knowledge that it was in a conditional once the
minor error is processed, so the next statement is
the next line, not the line after the endif.
To avoid this situation, use variables for any
operation that could encounter a minor error and
then use the variables in the conditional statement.
For example:

V1 = CELLGETN('PNLCube', 'fred',
'argentina','Sales','Jan');
IF(V1 = 454);ASCIIOUTPUT
('[Link]', 'if logic not working
properly');
ENDIF;

Example
In this example, the function returns the numeric value of the Engine Size attribute of the L Series 1.8L
Sedan element in the Automobile hierarchy of the Model dimension.

ElementAttrN('Model', 'Automobile', 'L Series 1.8L Sedan', 'Engine Size')

ElementAttrS
ElementAttrS returns a string attribute for a specified element of a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementAttrS(dimension, hierarchy, element, attribute)

98 IBM Planning Analytics: Reference

 Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element An element of the dimension.

attribute The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

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

ElementAttrS('plan_business_unit', 'expense', '10100', 'Currency')

Consolidation calculation rules functions

The ConsolidatedMax; ConsolidatedMin; ConsolidatedAvg; ConsolidatedCount; and Consolidated
CountUnique perform mathematical calculations on consolidations.

ConsolidatedAvg
ConsolidatedAvg calculates the average value in a consolidation and returns that single value.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ConsolidatedAvg(flag-value, cube-name, element_1, element_2,… );

Arguments
flag-value
The flag-value is the sum of the following option values:
• 1 - Use weighting when computing the value of consolidated values within the consolidation for
which you are determining the average. If this option value is not included in the flag-value sum,
the raw value of a consolidated element is used.
The following conditions might affect whether zeros are included in the calculation.
– If zero is specified as the weighting of some consolidated elements, then the Planning
Analytics database configuration parameter ZeroWeightOptimization=F must be set for
these elements to be included in the calculation of the average value in a consolidation. Without
this configuration parameter, the elements for which the weighting is zero are eliminated from
the consolidation list, and are therefore not included when calculating the average value in a
consolidation.
– If you want cells containing the value zero to be included when calculating the average,
UNDEFVALS must be set in the rules for the cube that is specified by the cube-name argument.
This ensures that when a zero is assigned to a cell of the cube, an actual zero value is stored in
the cell and the zero value is included when calculating the average value in a consolidation.

Chapter 2. Rules functions 99

 – If the rules for the cube that is specified by the cube-name argument include a SKIPCHECK
statement, zeros are always ignored when calculating the average value in a consolidation.
Remove the SKIPCHECK statement from the rule to include zeros in the consolidation average.
• 2 - Ignore zero values. If this value is included in the flag-value sum, zero values will not be
included in the calculation of the average value in a consolidation.
There are three valid values for flag-value.
• 1 - Use consolidation weighting when computing the consolidation average.
• 2 - Ignore zero values when computing the consolidation average.
• 3 - Use consolidation weighting and ignore zero values when computing the consolidation average.
cube-name
Name of the cube where the values reside.
If the function is running as part of a cube rule, and NOT as part of a TurboIntegrator process, the
cube-name argument can be specified as an empty string to mean the current cube. This means you
can write a rule such as ['Apr']=ConsolidatedAvg( 0, '', !actvsbud, '1 Quarter' );
element_1, element_2, …
Dimension element names that define the intersection of the cube containing the consolidation for
which you want to determine the average value.
Arguments element_1 through element_n are sequence-sensitive. element_1 must be an element
from the first dimension of the cube, element_2 must be an element from the second dimension, and
so on. These arguments can also be the names of aliases for dimension elements or TurboIntegrator
variables.

Example
In a cube that is called Income Statement with three dimensions that are named Regions, Time, and
Income Statement, the Income Statement dimension contains an element that is called Gross Sales for
the overall sales number.
To calculate the average sales across all regions in the year 2010, write:

ConsolidatedAvg( 1, 'Income Statement', 'All Regions', '2010', 'Gross Sales' );

ConsolidateChildren
ConsolidateChildren forces consolidated values to be calculated by summing immediate children along
a specified dimension. 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.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ConsolidateChildren(DimName1, DimName2, ...)

100 IBM Planning Analytics: Reference

Argument Description

DimName1, DimName2, ... Names of the dimensions along which

consolidations will be performed.
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 image 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:

Chapter 2. Rules functions 101

 In the following image, 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 image 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.

ConsolidatedCount
ConsolidatedCount returns the number of values in a consolidation.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ConsolidatedCount(flag-value, cube-name, element_1, element_2,… );

Arguments
flag-value
The flag-value is the sum of the following option values:
• 1 - Use weighting when computing the value of consolidated values within the consolidation for
which you are counting values. If this option value is not included in the flag-value sum, the raw
value of the consolidated element is used.
The following conditions might affect whether zeros are included in the calculation.
– If zero is specified as the weighting of some consolidated elements, then the Planning
Analytics database configuration parameter ZeroWeightOptimization=F must be set for
these elements to be included in the count of values in a consolidation. Without this configuration

102 IBM Planning Analytics: Reference

 parameter, the elements for which the weighting is zero are eliminated from the consolidation list,
and are therefore not included when counting the number of values in a consolidation.
– If you want cells containing the value zero to be included when counting the number of values
in a consolidation, UNDEFVALS must be set in the rules for the cube that is specified by the
cube-name argument. This ensures that when a zero is assigned to a cell of the cube, an actual
zero value is stored in the cell and the zero value is included when counting the number of values
in a consolidation.
– If the rules for the cube that is specified by the cube-name argument include a SKIPCHECK
statement, zeros are always ignored when counting the number of values in a consolidation.
Remove the SKIPCHECK statement from the rule to include zeros when counting the number of
values in a consolidation.
• 2 - Ignore zero values. If this value is included in the flag-value sum, zero values will not be
includedwhen counting the number of values in a consolidation.
There are three valid values for flag-value.
• 1 - Use consolidation weighting when counting the number of values in a consolidation.
• 2 - Ignore zero values when counting the number of values in a consolidation.
• 3 - Use consolidation weighting and ignore zero values when counting the number of values in a
consolidation.
cube-name
Name of the cube where the values reside.
If the function is running as part of a cube rule, and NOT as part of a TurboIntegrator process,
the cube-name argument can be specified as an empty string to mean the current cube. This
means you may write a rule such as:['Apr']=ConsolidatedCount( 1, '', !actvsbud, '1
Quarter' );
element_1, element_2, …
Dimension element names that define the intersection of the cube containing the consolidation for
which you want to count the number of values.
Arguments element_1 through element_n are sequence-sensitive. element_1 must be an element
from the first dimension of the cube, element_2 must be an element from the second dimension, and
so on. These arguments can also be the names of aliases for dimension elements or TurboIntegrator
variables.

ConsolidatedCountUnique
ConsolidatedCountUnique counts the number of unique elements for which data points actually exist for
the specified consolidation. The unique elements are counted along one dimension of the consolidated
cell.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ConsolidatedCountUnique( flag-value, unique-along-dimension-name, cube-name,elem_1,
elem_2, . . . );

Arguments
flag-value
The flag-value is the sum of the following option values:
• 1 - Use weighting when computing the number of unique elements for which data points actually
exist. If this option value is not included in the flag-value sum, the raw values of elements within
the consolidation are used.

Chapter 2. Rules functions 103

 The following conditions might affect whether zeros are included in the calculation.
– If zero is specified as the weighting of some elements, then the Planning Analytics database
configuration parameter ZeroWeightOptimization=F must be set for these elements to
be included in the calculation of the number of unique elements. Without this configuration
parameter, the elements for which the weighting is zero are eliminated from the consolidation list,
and are therefore not included when calculating the number of unique elements.
– If you want cells containing the value zero to be included when calculating the number of unique
elements with actual values, UNDEFVALS must be set in the rules for the cube that is specified
by the cube-name argument. This ensures that when a zero is assigned to a cell of the cube, an
actual zero value is stored in the cell and the zero value is included when calculating the number
of unique elements with actual values.
– If the rules for the cube that is specified by the cube-name argument include a SKIPCHECK
statement, zeros are always ignored when calculating the number of unique elements with actual
values. Remove the SKIPCHECK statement from the rule to include zeros in the calculation of the
number of unique elements with actual values.
• 2 - Ignore zero values. If this value is included in the flag-value sum, zero values will not be
included in the calculation of the number of unique elements with actual values.
There are three valid values for flag-value.
• 1 - Use consolidation weighting when computing the number of unique elements with actual values.
• 2 - Ignore zero values when computing the number of unique elements with actual values.
• 3 - Use consolidation weighting and ignore zero values when computing the number of unique
elements with actual values.
unique-along-dimension-name
The dimension along which unique element entries with real data are to be counted.
cube-name
Name of the cube where the values reside.
If the function is running as part of a cube rule, and NOT as part of a TurboIntegrator process, the
cube-name argument can be specified as an empty string to mean the current cube.
element_1, element_2, …
Dimension element names that define the intersection of the cube which is the consolidated value to
be processed.
Arguments element_1 through element_n are sequence-sensitive. element_1 must be an element
from the first dimension of the cube, element_2 must be an element from the second dimension, and
so on. These arguments can also be the names of aliases for dimension elements or TurboIntegrator
variables.

Example
In a cube called Income Statement with three dimensions: Regions, Time, and Income Statement, the
Income Statement dimension contains an element called Gross Sales for the overall sales number. To
count how many regions had some gross sales in the year 2010 write:

ConsolidatedCountUnique( 3, 'Regions', 'Income Statement', 'All Regions', '2010', 'Gross

Sales' );

This example uses consolidation weighting and ignores zero values when computing the number of
unique elements with actual values.

ConsolidatedMax
ConsolidatedMax calculates the maximum value in a consolidation and returns that single value.
This function is valid in both rules and TurboIntegrator processes.

104 IBM Planning Analytics: Reference

Syntax
ConsolidatedMax(flag-value, cube-name, element_1, element_2,… );

Arguments
flag-value
The flag-value is the sum of the following option values:
• 1 - Use weighting when computing the value of consolidated values within the consolidation for
which you are determining the maximum. If this option value is not included in the flag-value
sum, the raw value of the consolidated element is used.
The following conditions might affect whether zeros are included in the calculation.
– If zero is specified as the weighting of some consolidated elements, then the [Link]
configuration parameter ZeroWeightOptimization=F must be set for these elements to be
included in the calculation of the maximum value in a consolidation. Without this configuration
parameter, the elements for which the weighting is zero are eliminated from the consolidation list,
and are therefore not included when calculating the maximum value in a consolidation.
– If you want cells containing the value zero to be included when calculating the average,
UNDEFVALS must be set in the rules for the cube that is specified by the cube-name argument.
This ensures that when a zero is assigned to a cell of the cube, an actual zero value is stored in
the cell and the zero value is included when calculating the maximum value in a consolidation.
– If the rules for the cube that is specified by the cube-name argument include a SKIPCHECK
statement, zeros are always ignored when calculating the maximum value in a consolidation.
Remove the SKIPCHECK statement from the rule to include zeros in the calculation of the
maximum value.
• 2 - Ignore zero values. If this value is included in the flag-value sum, zero values will not be
included in the calculation of the maximum value in a consolidation.
There are three valid values for flag-value.
• 1 - Use consolidation weighting when computing the maximum value in a consolidation.
• 2 - Ignore zero values when computing the maximum value in a consolidation.
• 3 - Use consolidation weighting and ignore zero values when computing the maximum value in a
consolidation.
cube-name
Name of the cube where the values reside.
If the function is running as part of a cube rule, and NOT as part of a TurboIntegrator process, the
cube-name argument can be specified as an empty string to mean the current cube. This means you
may write a rule such as:['Apr']=ConsolidatedMax( 1, '', !actvsbud, '1 Quarter' );
element_1, element_2, …
Dimension element names that define the intersection of the cube containing the consolidation for
which you want to determine the maximum value.
Arguments element_1 through element_n are sequence-sensitive. element_1 must be an element
from the first dimension of the cube, element_2 must be an element from the second dimension, and
so on. These arguments can also be the names of aliases for dimension elements or TurboIntegrator
variables.

Example
Consider a cube called Income Statement with three dimensions, "Area", "Time", and "Income
Statement". The Income Statement dimension contains an element "Gross Sales" for the overall sales
number.

Chapter 2. Rules functions 105

 To calculate the maximum sales across all regions in the year 2010 use:

ConsolidatedMax( 1, 'Income Statement', 'All Regions', '2010', 'Gross Sales' );

ConsolidatedMin
ConsolidatedMin calculates the minimum value in a consolidation and returns that single value.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ConsolidatedMin(flag-value, cube-name, element_1, element_2,… );

Arguments
flag-value
The flag-value is the sum of the following option values:
• 1 - Use weighting when computing the value of consolidated values within the consolidation for
which you are determining the minimum. If this option value is not included in the flag-value
sum, the raw value of the consolidated element is used.
The following conditions might affect whether zeros are included in the calculation.
– If zero is specified as the weighting of some consolidated elements, then the Planning
Analytics database configuration parameter ZeroWeightOptimization=F must be set for
these elements to be included in the calculation of the minimum value in a consolidation. Without
this configuration parameter, the elements for which the weighting is zero are eliminated from
the consolidation list, and are therefore not included when calculating the minimum value in a
consolidation.
– If you want cells containing the value zero to be included when calculating the average,
UNDEFVALS must be set in the rules for the cube that is specified by the cube-name argument.
This ensures that when a zero is assigned to a cell of the cube, an actual zero value is stored in
the cell and the zero value is included when calculating the minimum value in a consolidation.
– If the rules for the cube that is specified by the cube-name argument include a SKIPCHECK
statement, zeros are always ignored when calculating the minimum value in a consolidation.
Remove the SKIPCHECK statement from the rule to include zeros in the calculation of the
minimum value.
• 2 - Ignore zero values. If this value is included in the flag-value sum, zero values will not be
included in the calculation of the minimum value in a consolidation.
There are three valid values for flag-value.
• 1 - Use consolidation weighting when computing the minimum value in a consolidation.
• 2 - Ignore zero values when computing the minimum value in a consolidation.
• 3 - Use consolidation weighting and ignore zero values when computing the minimum value in a
consolidation.
cube-name
Name of the cube where the values reside.
If the function is running as part of a cube rule, and NOT as part of a TurboIntegrator process, the
cube-name argument can be specified as an empty string to mean the current cube. This means you
may write a rule such as:['Apr']=ConsolidatedMin( 1, '', !actvsbud, '1 Quarter' );
element_1, element_2, …
Dimension element names that define the intersection of the cube containing the consolidation for
which you want to determine the minimum value.

106 IBM Planning Analytics: Reference

 Arguments element_1 through element_n are sequence-sensitive. element_1 must be an element
from the first dimension of the cube, element_2 must be an element from the second dimension, and
so on. These arguments can also be the names of aliases for dimension elements or TurboIntegrator
variables.

Cube data rules functions

Rules functions that work on cube data.

CellValueN
CellValueN returns the numeric value of the specified elements in a cube. This function is valid only in
rules. Use of this function in a TurboIntegrator process will result in an error. Use of this function in a
TurboIntegrator process will result in an error.
For dimensions not among the element parameters, coordinates are retrieved from the rule target (the
cell being retrieved and triggering rule evaluation). The function behavior is analogous to the intra-cube
reference expression (e.g. [ 'Measures':'Count' ] ), as used in the formula component of a rule .
The element parameters may be specified in any order, and for CellValueN, multiple elements from the
same dimension (but different hierarchies of the dimension) may be specified. Since the elements list is
not required to be in cube dimension order, it is necessary to dimension-qualify all element parameters.
Element parameters from multi-hierarchy dimensions must also be hierarchy-qualified.

Syntax
CellValueN(cube, element1,..., elementN);

Argument Description

cube Name of the cube.

elementN Element name that defines the cell. A minimum of

one element must be specified.

Example
CellValueS('ForecastCube', 'Products':'ProductsByChannel':'Channel2', 'Measures':'Count');

This example returns the numeric value of the specified cell. The Products dimension has multiple
hierarchies while the Measures dimension has one hierarchy.
The intra-cube reference is restricted to literal parameters, while CellValueN is not. This behavior is
analogous to the DB() rules function. The element parameters may be specified using string-valued
expressions. For example, the previous Products element parameter could be specified as:

'Products' : 'ProductsByChannel' : AttrS( … )

Unlike DB() and the intra-cube reference expression, CellValueN element parameters must be either
dimension-qualified, or dimension and hierarchy qualified.

CellValueS
CellValueS returns the string value of the specified element(s) in a cube. This function is valid only in
rules. Use of this function in a TurboIntegrator process will result in an error.
For dimensions not among the element parameters, coordinates are retrieved from the rule target (the
cell being retrieved and triggering rule evaluation). The function behavior is analogous to the intra-cube
reference expression (e.g. [ 'Measures':'Count' ] ), as used on formula portion of a rule statement.

Chapter 2. Rules functions 107

 The element parameters may be specified in any order, and for CellValueS, multiple elements from the
same dimension (but different hierarchies of the dimension) may be specified. Since the elements list is
not required to be in cube dimension order, it is necessary to dimension-qualify all element parameters.
Element parameters from multi-hierarchy dimensions must also be hierarchy-qualified.

Syntax
CellValueS(cube, element1,..., elementN);

Argument Description

cube Name of the cube.

elementN Element name that defines the cell. A minimum of

one element must be specified.

Example
CellValueS('ForecastCube', 'Products':'ProductsByChannel':'Channel2', 'Measures':'Location');

This example returns the string value of the specified cell. The Products dimension has multiple
hierarchies while the Measures dimension has one hierarchy.
The intra-cube reference is restricted to literal parameters, while CellValueS is not. This behavior is
analogous to the DB() rules function. The element parameters may be specified using string-valued
expressions. For example, the previous Products element parameter could be specified as:

'Products' : 'ProductsByChannel' : AttrS( … )

Unlike DB() and the intra-cube reference expression, CellValueS element parameters must be either
dimension-qualified, or dimension and hierarchy qualified.

DB
DB returns a value from a cube in a Planning Analytics database. DB returns a numeric value if used in a
numeric expression and a string value if used in a string expression.
This function is valid only in rules. Use of this function in a TurboIntegrator process will result in an error.

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

Parameters
cube
The name of the cube from which to retrieve the value.
e1,...en
Dimension element names that define the intersection containing the value to be retrieved.
Arguments e1 through en are sequence-sensitive. e1 must be an element from the first dimension of
the cube, e2 must be an element from the second dimension, and so on.

108 IBM Planning Analytics: Reference

 Example
In this example, Budget is the cube name, and the function returns the value at the intersection of
California, 15" Flat Panel Monitors, Net Sales, and January.

DB('Budget', 'California', '15" Flat Panel Monitors', 'Net Sales', 'January')

When used to reference multi-hierarchy dimensions, you must specify the particular hierarchy. In this
example, the Category2 element exists in the ByCategory hierarchy of the ProductsCube dimension.

DB('ProductsCube', 'ByCategory':'Category2',...)

Related information
Using cube references

ISLEAF
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.
The ISLEAF function cannot be used in TurboIntegrator processes. The presence of this function in a
process will prevent the process from compiling.

Syntax
ISLEAF

Arguments
None.

Example
You can use ISLEAF in an IF statement to test if a current cell is a leaf cell. For example:

[]=IF((ISLEAF=1),TrueStatement, FalseStatement);

Executes the TrueStatement if the current cell is a leaf cell, otherwise it executes the FalseStatement.

ISUNDEFINEDCELLVALUE
ISUNDEFINEDCELLVALUE 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.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ISUNDEFINEDCELLVALUE(TestValue, <Cube>)

Arguments

Argument Description

TestValue The numerical value to compare against the cube's default value.

Chapter 2. Rules functions 109

 Argument Description

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.
When used in a process, a cube should be specified.
If the cube is omitted in a process, or is not valid when specified, 0 will be used
for comparison.

Example
ISUNDEFINEDCELLVALUE(TestValue) returns 1 when TestValue is the special undefined value and is
used in the rule of a cube with UNDEFVALS declared.

UNDEF
UNDEF returns the undefined value. This function can be used to prevent data from being stored in a cube
based on a logical test.
This function is valid in both rules and TurboIntegrator processes.

Syntax
UNDEF

Arguments
None.

Example
UNDEF returns the undefined value.

UNDEFINEDCELLVALUE
UNDEFINEDCELLVALUE returns the default numeric cube value, which is influenced by the presence of
the UNDEFVALS declaration in that cube's rule.
This function is valid in both rules and TurboIntegrator processes.

Syntax
UNDEFINEDCELLVALUE(<Cube>)

110 IBM Planning Analytics: Reference

 Arguments

Argument Description

Cube An optional String argument that specifies the cube whose default value should
be returned.
When UNDEFINEDCELLVALUE is used in a rule, the cube is assumed to be the
subject cube unless otherwise specified.
When used in a process, a cube should be specified.
If the cube is omitted in a process, or is not valid when specified, 0 will be
returned.

Example
UNDEFINEDCELLVALUE returns 0 when used in the rule of a cube without UNDEFVALS declared, or when
used in a process.
UNDEFINEDCELLVALUE returns the special undefined value when used in the rule of a cube with
UNDEFVALS declared.
UNDEFINEDCELLVALUE('ExampleCube') returns the default value of ExampleCube or 0 if
ExampleCube does not exist.

UNDEFVALS
Putting UNDEFVALS in the rules for a cube changes the default value for the cube from zero to a special
undefined value. Like other rules functions, UNDEFVALS applies only to the cube associated with the rule
in which the function appears.
This function is valid only in rules. Use of this function in a TurboIntegrator process will result in an error.
Use of UNDEFVALS has ramifications regarding how data is stored in the cube and retrieved.
• Data Storage
For a cube without UNDEFVALS in the rules, the default value is zero. If an attempt is made to store a
zero in a cell of the cube, that storage request is ignored, as this is a redundant attempt to store the
default value, and it would needlessly consume memory space. Similarly, if a cell already contains a
value and the value is deleted, nothing is stored in the cell.
If however the cube has UNDEFVALS defined in the rules, this makes the default value a special
undefined value. Now when a zero is stored in a cell of a cube, it is actually stored, just like any other
non-zero value.
The special undefined value is only a run-time value, returned from requests for cell values. It is never
stored in an actual cell in memory, and is never written to disk. Including UNDEFVALS in the rule for
a cube has no effect on memory usage or disk storage, except for cells that actually contain zero as
a value. When UNDEFVALS is included in the rule for a cube, zero values in that cube will consume
memory space and will be written to disk, just like any other data value. If UNDEFVALS is not specified,
zero value cells are not stored in memory nor are they written to disk.
• Data Retrieval
For a cube without UNDEFVALS in the rules, the default value is zero. When a cell is retrieved, and there
is no value currently stored for that value in the cube, a value of zero (as the default value) is returned.
This means that an application cannot tell whether a cell actually exists and contains zero as the cell
value, or whether the cell does not exist (as can be the case with sparse data).
If however the cube has UNDEFVALS defined in the rules, this make the default value a special
undefined value. In this case, when a non-existent cell is retrieved, the value retrieved will be this
special undefined value. This can be used to distinguish a cell that does not exist (special undefined

Chapter 2. Rules functions 111

 returned) from a cell that exists, but whose value is zero (zero returned). Any client written to run
against Planning Analytics, which can encounter a cube with UNDEFVALS set, must be prepared to
handle a cell value of this special undefined rather than a zero. A client can detect whether a value
returned from Planning Analytics is this special undefined value with the TM1ValIsUndefined API
function. For details on the TM1ValIsUndefined API function, see the TM1 API documentation.
Note: This special undefined value is not the value returned by the UNDEF() TurboIntegrator function.
The value returned by UNDEF() is an undefined value used for such things as an attempt to divide by
zero, or take the logarithm of an illegal number, etc.
In TurboIntegrator, for normal arithmetic operations (+, -, *, /, \, ^) and normal arithmetic comparisons (<,
>, >=, <=, =, <>), the special undefined value is treated as a zero. Because of this, the following code does
not work:

NoCellVal = UndefinedCellValue( 'cube-name' );

If ( vv = NoCellVal );

In this comparison, NoCellVal, which is the special undefined value for an UNDEFVALS cube, is treated
as a zero. This means the comparison is really If ( vv = 0 ).
In TurboIntegrator you must use the IsUndefinedCellValue to test if a cell value is the special undefined
value. For example:

vv = CellGetN( 'cube-name', elements-list);

if ( IsUndefinedCellValue( vv, 'cube-name' ) = 1 );
#the cells does not exist
cell_does_not_exist = 1;
else;
#cell exists
cell_does_not_exist = 0;
Endif;

Syntax
UNDEFVALS

Arguments
None.

Date and time rules functions

Rules functions that work with dates and time.

DATE
DATE returns the date string in yy-mm-dd or yyyy-mm-dd format for a given serial number.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DATE(SerialNumber, ReturnFourDigitYear)

Argument Description

SerialNumber A date expressed in serial format.

112 IBM Planning Analytics: Reference

 Argument Description

ReturnFourDigitYear An optional Boolean argument that determines whether the DATE

function returns a string using two- or four-digit notation for the
year.
If ReturnFourDigitYear is true, the function returns date falling
within the range of Jan. 1, 1960 and Dec. 31, 9999, using four-
digit notation for the year. Serial date 0 corresponds to Jan. 1,
1960 and serial date 2936549 corresponds to Dec. 31, 9999.
If ReturnFourDigitYear is false, or if this optional argument is
omitted from the DATE function, the function returns a date
falling within the range Jan. 1, 1960 and Dec. 31, 2059, using
two-digit notation for the year. Serial date 0 corresponds to Jan 1,
1960 and serial date 36524 corresponds to Dec. 31, 2059.
If ReturnFourDigitYear is false or is omitted and you specify
a serial date greater than 36524, the serial date used by the
function is determined by the formula n - 36525. For example, if
you specify a serial date of 36530, then 36530 - 36525 = 5. In
this case, DATE uses 5 as the serial date and returns the date Jan.
6, 1960.

Example
DATE(13947) returns 98-03-09.
DATE(13947, 1) returns 1998-03-09.

DATES
DATES returns a date string, in the form 'yy-mm-dd' or 'yyyy-mm-dd', corresponding to a given year,
month, and day.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DATES(year, month, day)

Argument Description

year A year, expressed in either yy or yyyy format.

month A month, expressed in mm format.

day A day, expressed in dd format.

Example
DATES(98, 2, 10) returns '98-02-10'.
DATES(1998, 2, 10) returns '1998-02-10'.

Chapter 2. Rules functions 113

DAY
DAY returns a numeric value for the day in a given date string.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DAY(DateString)

Argument Description

DateString A date string in either YY-MM-DD or YYYY-MM-DD

format.

Example
DAY('02-05-25') returns 25.

DAYNO
DAYNO returns the serial date number corresponding to a given date string.
This function is valid in both rules and TurboIntegrator processes.
Note: DAYNO can return serial dates for date strings starting at January 1, 1960 (dates string 1960-01-01
or 60-01-01). For dates after December 31, 2059, you use a four digit year in the date string. For
example, the date string for January 5, 2061 would be 2061-01-05.

Syntax
DAYNO('DateString')

Argument Description

DateString A date string in either YY-MM-DD or YYYY-MM-DD

format.

Example
DAYNO('98-03-09') returns 13947.

MONTH
MONTH returns a numeric value for the month in a given date string.
This function is valid in both rules and TurboIntegrator processes.

Syntax
MONTH(date)

Argument Description

date A date string in either YY-MM-DD or YYYY-MM-DD

format.

114 IBM Planning Analytics: Reference

 Example
MONTH('02-05-25') returns 5.

NOW
NOW returns the current date/time value in serial number format.
This function is valid in both rules and TurboIntegrator processes.
Note: If you are using NOW as a calculated consolidation value, set
RestrictVolatileValuesFromCache to True in the [Link] configuration file to automatically
update the consolidation value whenever you refresh or recalculate.

Syntax
NOW

Arguments
None.

Example

['current_date'] = C: Now()

NOW returns the current date/time value in serial number format.

TIME
TIME returns a string, in HH:MM format, representing the system time on the Planning Analytics database.
This function is valid in both rules and TurboIntegrator processes.

Syntax
TIME

Arguments
None.

Example
Given a system time of 9:33 AM, TIME returns the string '09:33'.
Given a system time of 9:33 PM, TIME returns the string '21:33'.

TIMST
TIMST returns a formatted date/time string.
This function is valid in both rules and TurboIntegrator processes.

Syntax
TIMST(datetime, format, ExtendedYears)

Chapter 2. Rules functions 115

 Argument Modifier/
Description

datetime A date/time serial number.

The integer part of the number specifies the date,
and the decimal part specifies the time within
the day. Day number 0 corresponds to '60-01-01'.
Negative numbers correspond to prior years. Years
in the 21st Century, up to 2059, are represented by
years 00 through 59. An hour is 1/24th of a day, a
minute 1/60th of an hour, and a second 1/60th of a
minute.

format A string that formats the result of the function.

All the characters in the format argument appear
in the result, except for the following characters,
which return date/time component values:

\y
the last two digits of the year (97, 98, etc.)

\Y
the four digits of the year (1997, 1998, etc.)

\m
the two digits of the month (01 through 12)

\M
the abbreviation of the month (JAN, FEB, etc.)

\d
the two digits of the day (01 through 31)

\D
the digit of the day (1 through 31)

\h
the hour in military time (00 through 23)

\H
the standard hour (1 through 12)

\i
the minute (00 through 59)

\s
the second (00 through 59)

116 IBM Planning Analytics: Reference

 Argument Modifier/
Description

\p
a.m. or p.m.

ExtendedYears This optional Boolean parameter specifies whether

the function returns a date falling within the range
1960 - 2059 or 1960 - 9999.
If ExtendedYears is true, the function returns a
date falling within the range of Jan. 1, 1960 and
Dec. 31, 9999. Serial date 0 corresponds to Jan. 1,
1960 and serial date 2936549 corresponds to Dec.
31, 9999.
If ExtendedYears is false, or if this optional
argument is omitted from the TIMST function, the
function returns a date falling within the range
Jan. 1, 1960 and Dec. 31, 2059. Serial date 0
corresponds to Jan 1, 1960 and serial date 36524
corresponds to Dec. 31, 2059.
If ExtendedYears is false or is omitted and you
specify a serial date greater than 36524, the serial
date used by the function is determined by the
formula n - 36525. For example, if you specify a
serial date of 36530, then 36530 - 36525 = 5.
In this case, TIMST uses 5 as the serial date and
returns the date Jan. 6, 1960.

Example
TIMST(366.0000, '\M \D, \Y') returns 'JAN 1, 1961'.
TIMST(366.5000, '\H\p \imin\ssec') returns '12p.m. 00min00sec'.
TIMST(366.1000, 'On \M \D, \Y at \H\p \imin\ssec') returns 'On JAN 1, 1961 at 2a.m. 24min00sec'.
TIMST(11111.1100, 'On \M \D, \Y at \H\p \imin\ssec') returns 'On JUN 3,1990 at 2a.m. 38min24sec'.

TIMVL
TIMVL returns the numeric value of a component (year, month, etc.) of a date/time value.
This function is valid in both rules and TurboIntegrator processes.

Syntax
TIMVL(datetime, type, ExtendedYears)

Chapter 2. Rules functions 117

 Argument Modifier and
Description

datetime A date and time serial number.

The integer part of the number specifies the date,
and the decimal part specifies the time within
the day. Day number 0 corresponds to '60-01-01.'
Negative numbers correspond to prior years. Years
in the 21st Century, up to 2059, are represented by
years 00 through 59. An hour is 1/24th of a day, a
minute 1/60th of an hour, and a second 1/60th of a
minute.

type A character that specifies the type of component

to be extracted. The following are valid type
arguments:

Y
year value (1997, 1998, etc.)

M
month value (1 through 12)

D
day value (1 through 31)

H
hour value (0 through 23)

I
minute value (00 through 59)

S
second value (00 through 59)

118 IBM Planning Analytics: Reference

 Argument Modifier and
Description

ExtendedYears This optional Boolean parameter specifies whether

the function returns a date falling within the range
1960 - 2059 or 1960 - 9999.
If ExtendedYears is true, the function returns a
date falling within the range of Jan. 1, 1960 and
Dec. 31, 9999. Serial date 0 corresponds to Jan. 1,
1960 and serial date 2936549 corresponds to Dec.
31, 9999.
If ExtendedYears is false, or if this optional
argument is omitted from the TIMVL function, the
function returns a date falling within the range
Jan. 1, 1960 and Dec. 31, 2059. Serial date 0
corresponds to Jan 1, 1960 and serial date 36524
corresponds to Dec. 31, 2059.
If ExtendedYears is false or is omitted and you
specify a serial date greater than 36524, the serial
date used by the function is determined by the
formula n - 36525. For example, if you specify a
serial date of 36530, then 36530 - 36525 = 5.
In this case, TIMVL uses 5 as the serial date and
returns the date Jan. 6, 1960.

Example
TIMVL(11111.1100, 'Y') returns 1990.
TIMVL(11111.1100, 'H') returns 2.

TODAY
TODAY returns the current date in yy-mm-dd format.
This function is valid in both rules and TurboIntegrator processes.

Syntax
TODAY(<ReturnFourDigitYear>)

Chapter 2. Rules functions 119

 Argument Description

ReturnFourDigitYear An optional Boolean argument that determines

whether the TODAY function returns a string using
two- or four-digit notation for the year.
If ReturnFourDigitYear is true, the function returns
date falling within the range of Jan. 1, 1960 and
Dec. 31, 9999, using four-digit notation for the
year. Serial date 0 corresponds to Jan. 1, 1960 and
serial date 2936549 corresponds to Dec. 31, 9999.
If ReturnFourDigitYear is false, or if this optional
argument is omitted from the TODAY function, the
function returns a date falling within the range
Jan. 1, 1960 and Dec. 31, 2059, using two-digit
notation for the year. Serial date 0 corresponds to
Jan 1, 1960 and serial date 36524 corresponds to
Dec. 31, 2059.
If ReturnFourDigitYear is false or is omitted and
you specify a serial date greater than 36524, the
serial date used by the function is determined by
the formula n - 36525. For example, if you specify
a serial date of 36530, then 36530 - 36525 = 5.
In this case, TODAY uses 5 as the serial date and
returns the date Jan. 6, 1960.

Example
P1=TODAY(1) returns a data string in YYYY-MM-DD format such as 2009-06-05.
P1=TODAY(0) returns a date string in YY-MM-DD format such as 09-06-05

YEAR
YEAR returns a numeric value for the year in a given date string.
This function is valid in both Planning Analytics rules and processes.

Syntax
YEAR(date)

Argument Description

date A date string formatted as either YY-MM-DD or

YYYY-MM-DD.

Example
YEAR('02-05-25') returns 2.

Dimension Information Rules Functions

Rules functions that manage dimension information.

120 IBM Planning Analytics: Reference

DIMIX
DIMIX returns the index number of an element within a dimension.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
DIMIX(server_name:dimension, element)

Argument Description

dimension A valid dimension name qualified by the database

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.

Example
Brazil has an index value of three in the Region dimension. The example returns 3.

DIMIX('planning_sample:Region','Brazil')

DIMNM
DIMNM returns the element of a dimension that corresponds to the index argument.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DIMNM(server_name:dimension, index)

Argument Description

dimension A valid dimension name qualified by the database

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
This example returns 'Belgium', which is the element within the Region dimension with an index value of
2.

DIMNM(planning_sample:'Region',2)

Chapter 2. Rules functions 121

DIMSIZ
DIMSIZ returns the number of elements within a specified dimension.
This function is valid in rules and TurboIntegrator processes.

Syntax
DIMSIZ(dimension)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_name:dimension.

Example
If the dimension Accounts contains 19 elements, the example returns the value 19.

DIMSIZ('Accounts')

DNEXT
DNEXT returns the element name that follows the element specified as an argument to the function.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DNEXT(dimension, element)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_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.

Example
If the Location dimension contains the ordered elements California, Oregon, and Washington, the
example returns Washington.

DNEXT("Location","Oregon")

DNLEV
DNLEV returns the number levels in a dimension.
This function is valid in both rules and TurboIntegrator processes.

122 IBM Planning Analytics: Reference

 Syntax
DNLEV(dimension)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_name:dimension.

Example

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.

DTYPE
DTYPE returns information about the element type of a specified element. DTYPE returns N if the element
is a numeric element, S if the element is a string element, C if the element is a consolidated element.
In the case of an element attribute dimension, DTYPE returns AN if the attribute is a numeric attribute, AS
if the attribute is a string attribute, and AA if the attribute is an alias attribute. For more information, see
Element Attributes.
This function is valid in both rules and TurboIntegrator processes.

Syntax
DTYPE(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension.

Example
The element Europe is a consolidated element of the Region dimension, so the example returns C.

DTYPE('Region','Europe')

TABDIM
TABDIM returns the dimension name that corresponds to the index argument.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
TABDIM(cube, index)

Chapter 2. Rules functions 123

 Argument Description

cube A valid cube name.

index A positive value less than or equal to the total

number of dimensions in the cube.

Example
The cube SalesCube contains five dimensions: account1, actvsbud, model, month, and region. The
example returns model, the third dimension of SalesCube.

TABDIM('SalesCube',3)

Element Information Rules Functions

Rules functions that manage element information.

ELCOMP
ELCOMP returns the name of a child of a consolidated element in a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
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.

ELCOMP('Region','Central Europe',2)

ELCOMPN
ELCOMPN returns the number of components in a specified element. If the element argument is not a
consolidated element, the function returns 0.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ELCOMPN(dimension, element)

124 IBM Planning Analytics: Reference

 Argument Description

dimension A valid dimension name.

element The name of a consolidated element within the

dimension.

Example
In the Region dimension, the element Scandinavia is a consolidation of three elements. The example
returns 3.

ELCOMPN('Region','Scandinavia')

ElementComponent
ElementComponent 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 an empty string.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementComponent(dimension, hierarchy, element, position)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

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.

Example
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.

ElementComponent('Region', 'Europe', 'Central Europe', 2)

ElementComponentCount
ElementComponentCount returns the number of components in a specified element. If the element
argument is not a consolidated element, the function returns 0.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementComponentCount(dimension, hierarchy, element)

Chapter 2. Rules functions 125

 Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element The name of a consolidated element within the

dimension.

Example
In the Region dimension, the element Scandinavia is a consolidation of three elements. The example
returns 3.

ElementComponentCount('Region', '', 'Scandinavia')

ElementCount
ElementCount returns the number of elements within a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementCount(dimension, hierarchy)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_name:dimension.

hierarchy The name of the hierarchy within the dimension.

Example
If the Receivables hierarchy in the Accounts dimension contains 19 elements, the example returns the
value 19.

ElementCount('Accounts', 'Receivables')

ElementFirst
ElementFirst returns the first element of a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementFirst(database_name:dimension, hierarchy)

Argument Description

dimension A valid dimension name.

126 IBM Planning Analytics: Reference

 Argument Description

hierarchy The name of the hierarchy within the dimension.

Example
If the North America hierarchy of the Location dimension contains the ordered elements California,
Oregon, and Washington, the example returns California.

ElementFirst("planning_sample:Location", "North America")

ElementIndex
ElementIndex returns the index number of an element within a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementIndex(dimension, hierarchy, element)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element The name of an element within the dimension.

If the element is not a member of the dimension
specified, the function returns 0.

Example
Brazil has an index value of three in the Region dimension. The example returns 3.

ElementIndex('Region', 'South America', 'Brazil')

ElementIsAncestor
ElementIsAncestor 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.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementIsAncestor(dimension, hierarchy, element1, element2)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

Chapter 2. Rules functions 127

 Argument Description

element1 The name of an element within the dimension.

element2 The name of an element within the dimension.

Example
In the Western hierarchy of the Region dimension, the element Europe is an ancestor of Germany. The
example returns 1.

ElementIsAncestor('Region', 'Western', 'Europe', 'Germany')

ElementIsComponent
ElementIsComponent 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.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementIsComponent(dimension, hierarchy, element1, element2)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element1 The name of an element within the dimension.

element2 The name of an element within the dimension.

Example
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 previous example, Germany is a child of
Central Europe. Further, Central Europe is a child of Europe.

ElementIsComponent('Region', 'Countries', 'Germany', 'Central Europe')

However, because the function returns 1 only for immediate children, the following example returns 0:

ElementIsComponent('Region', 'Countries'', 'Germany', 'Europe')

ElementIsParent
ElementIsParent 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.
This function is valid in both rules and TurboIntegrator processes.

128 IBM Planning Analytics: Reference

 Syntax
ElementIsParent(dimension, hierarchy, element1, element2)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element1 The name of an element within the dimension.

element2 The name of an element within the dimension.

Example
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 previous example, Europe is a parent of
Central Europe. Further, Central Europe is a parent of Germany.

ElementIsParent('Region', 'Countries', 'Central Europe', 'Germany')

However, because Europe is not an immediate parent of Germany, the following example returns 0:

ElementIsParent('Region', 'Countries', 'Europe', 'Germany')

ElementLevel
ElementLevel returns the level of an element within a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementLevel(dimension, hierarchy, element)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element The name of an element within the dimension.

Example

ElementLevel('Region','Countries', '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.

Chapter 2. Rules functions 129

ElementName
ElementName returns the element of a dimension that corresponds to the index argument.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementName(dimension, hierarchy, index)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

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
This example returns 'Belgium', which is the element within the Countries hierarchy of the Region
dimension with an index value of 2.

ElementName('Region', 'Countries', 2)

ElementNext
ElementNext returns the element name that follows the element specified as an argument to the function.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementNext(dimension, hierarchy, element)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_name:dimension.

130 IBM Planning Analytics: Reference

 Argument Description

hierarchy The name of the hierarchy within the dimension.

element The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example
If the Location dimension contains the ordered elements California, Oregon, and Washington, the
example returns Washington.

ElementNext("Location","Cities", "Oregon")

ElementParent
ElementParent returns the parent of an element in a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementParent(dimension, hierarchy, element, index)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

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.

Example
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.

ElementParent('Model', 'Automobile', 'Wagon 4WD', 2)

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

ElementParentCount
ElementParentCount returns the number of parents of an element in a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Chapter 2. Rules functions 131

 Syntax
ElementParentCount(dimension, hierarchy, element)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element The name of an element within the dimension.

Example
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.

ElementParentCount('Model', 'Automobile', 'Wagon 4WD')

ElementType
ElementType returns information about the element type of a specified element.
ElementType returns N if the element is a numeric element, S if the element is a string element, and C if
the element is a consolidated element.
In the case of an element attribute dimension, ElementType returns AN if the attribute is a numeric
attribute, AS if the attribute is a string attribute, and AA if the attribute is an alias attribute. For more
information, see Element Attributes.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ElementType(dimension, hierarchy, element)

Table 1. ElementType syntax

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element The name of an element within the dimension.

Example
The element Europe is a consolidated element of the Region dimension, so the example returns C.

ElementType('Region', 'Countries', 'Europe')

ElementWeight
ElementWeight returns the weight of a child in a consolidated element.
This function is valid in both rules and TurboIntegrator processes.

132 IBM Planning Analytics: Reference

 Syntax
ElementWeight(dimension, hierarchy, element1, element2)

Argument Description

dimension A valid dimension name.

hierarchy The name of the hierarchy within the dimension.

element1 The name of a consolidated element within the

dimension.

element2 The name of a child of the consolidated element.

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

ElementWeight('Account1', 'SubAccount1', 'Gross margin', 'Variable Costs')

ELISANC
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.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
In the dimension Region, the element Europe is an ancestor of Germany. The example returns 1.

ELISANC('Region', 'Europe', 'Germany')

ELISCOMP
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.
This function is valid in both rules and TurboIntegrator processes.

Chapter 2. Rules functions 133

 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.

Example
In the dimension Region, the element Central Europe is a consolidation of two elements, Germany and
France. The following example returns 1.
Note: this function returns 1 only for immediate children. In this example, Germany is a child of Central
Europe. Further, Central Europe is a child of Europe.

ELISCOMP('Region','Germany','Central Europe')

However, because the function returns 1 only for immediate children, the following example returns 0:

ELISCOMP('Region','Germany','Europe')

ELISPAR
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.
This function is valid in both rules and TurboIntegrator processes.

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.

Example
In the dimension Region, the consolidated element Central Europe is the parent of both Germany and
France. Accordingly, the following example returns 1.
Note: this function returns 1 only for immediate parents. In this example, Europe is a parent of Central
Europe. Further, Central Europe is a parent of Germany.

ELISPAR('Region','Central Europe','Germany')

134 IBM Planning Analytics: Reference

 However, because Europe is not an immediate parent of Germany, the following example returns 0:

ELISPAR('Region','Europe','Germany')

ELLEV
ELLEV returns the level of an element within a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ELLEV(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension.

Example

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.

ELPAR
ELPAR returns the parent of an element in a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ELPAR(dimension, element, index)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension.

Chapter 2. Rules functions 135

 Argument Description

index A positive value less than or equal to the total

number of consolidated elements (parents) that
use the element argument as a child.

Example
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.

ELPAR('Model','Wagon 4WD',2)

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

ELPARN
ELPARN returns the number of parents of an element in a specified dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ELPARN(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension.

Example
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.

ELPARN('Model','Wagon 4WD')

ELWEIGHT
ELWEIGHT returns the weight of a child in a consolidated element.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ELWEIGHT(dimension, element1, element2)

Argument Description

dimension A valid dimension name.

element1 The name of a consolidated element within the

dimension.

136 IBM Planning Analytics: Reference

 Argument Description

element2 The name of a child of the consolidated element.

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

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

LevelCount
LevelCount returns the number levels in a dimension.
This function is valid in both rules and TurboIntegrator processes.

Syntax
LevelCount(dimension, hierarchy)

Argument Description

dimension A valid dimension name.

Some installations may need to qualify the
dimension name with the database name, as in
database_name:dimension.

hierarchy The name of the hierarchy within the dimension.

Example

LevelCount('Region', 'Countries')

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.

Financial Rules Functions

Rules functions used to manage financial information.

FV
FV returns the value of an annuity at the time of the last payment. An annuity is a series of payments
made at equal intervals of time. Payments are assumed to be made at the end of each period.
This function is valid in both rules and TurboIntegrator processes.

Syntax
FV(payment, interest, periods)

Chapter 2. Rules functions 137

 Argument Description

payment The amount of the payment made per period.

interest The interest rate paid per period.

periods The number of periods in the annuity.

Example
This example returns the value of an annuity at the end of 5 years, with payments of $1,000 per year at
14% interest.

FV(1000, .14, 5)

PAYMT
PAYMT returns the payment amount of an annuity based on a given initial value or principal, an interest
rate, and a number of periods. An annuity is a series of payments made at equal intervals of time.
This function is valid in both rules and TurboIntegrator processes.

Syntax
PAYMT(principal, interest, periods)

Argument Description

principal The present value, or the total amount that a series

of future payments is worth now.

interest The interest rate paid per period.

periods The number of periods in the annuity. Payments

are assumed to be made at the end of each period.

Example
This example returns the payment on a 5-year annuity that is paid yearly, with a principal of $100,000 at
14% interest.

PAYMT(100000, .14, 5)

PV
PV returns the initial or principal value of an annuity.
This function is valid in both rules and TurboIntegrator processes.

Syntax
PV(payment, interest, periods)

138 IBM Planning Analytics: Reference

 Argument Description

payment The amount of the payment made.

interest The interest rate paid per period.

periods The number of periods in the annuity. Payments

are assumed to be made at the end of each period.

Example
This example returns the principal value of an annuity with 5 yearly payments of $1,000 at 14% interest.

PV(1000, .14, 5)

Hierarchy Rules Functions

Functions to manage hierarchies in rules.

Hierarchy
If there is only one hierarchy included in the supplied dimension, Hierarchy returns the name of the
hierarchy. Otherwise, it returns an empty string. Hierarchy is valid in rules only.
With the introduction of support for multiple hierarchies, it is necessary to identify which hierarchies are
in context when multiple hierarchies are being used.
The Hierarchy function cannot be used in TurboIntegrator processes. The presence of this function in a
process will prevent the process from compiling.

Syntax
Hierarchy (DimName);

Argument Description

DimName A valid dimension name.

Example
This example returns 'Quarter', which is the only hierarchy in the Quarter dimension.

Hierarchy ('Quarter');

HierarchyCount
HierarchyCount returns the number of hierarchies in the supplied dimension. HierarchyCount is valid in
rules only.
The HierarchyCount function cannot be used in TurboIntegrator processes. The presence of this function
in a process will prevent the process from compiling.

Syntax
HierarchyCount (DimName);

Chapter 2. Rules functions 139

 Argument Description

DimName A valid dimension name.

Example
This example returns 3, which is the number of hierarchies in the model dimension.

HierarchyCount ('model');

HierarchyIndex
HierarchyIndex returns a 1-based index if the hierarchy is in the supplied dimension, 0 otherwise.
HierarchyIndex is valid in rules only.
HierarchyIndex cannot be used in TurboIntegrator processes. The presence of this function in a process
will prevent the process from compiling.

Syntax
HierarchyIndex (DimName, HierName);

Argument Description

DimName A valid dimension name.

HierName A valid hierarchy name that you want to find the

index position of in DimName.

Example
This example returns 3, which is the index position of the CustomerTarget hierarchy in the model
dimension.

HierarchyIndex ('model', 'CustomerTarget');

HierarchyN
HierarchyN returns the name of the hierarchy at a specified position in the supplied dimension and an
empty string if the index is out of scope. HierarchyN is valid in rules only.
HierarchyN cannot be used in TurboIntegrator processes. The presence of this function in a process will
prevent the process from compiling.

Syntax
HierarchyN (DimName, index);

Argument Description

DimName A valid dimension name.

140 IBM Planning Analytics: Reference

 Argument Description

index A value less than or equal to the number of

hierarchies in the dimension.
If this argument is less than 1, or greater than
the number of hierarchies in the dimension, the
function returns 0.

Example
This example returns 'CustomerTarget', which is the third hierarchy in the model dimension.

HierarchyN ('model', 3);

Logical Rules Functions

Logical functions to use in rules.

CONTINUE
When included as part of a rules expression, CONTINUE allows a subsequent rule with the same area
definition to be executed. Normally, Planning Analytics only executes the first rule encountered for a given
area.
This function is valid in both rules and TurboIntegrator processes.

Syntax
CONTINUE

Arguments
None.

Example

['Jan']= if(!region @= 'Argentina',10,CONTINUE);

['Jan']=20;

In this example, all cells identified by January and Argentina are assigned a value of 10. Cells identified by
Jan and any other Region element are assigned a value of 20.

IF
IF returns one value if a logical expression you specify is TRUE and another value if it is FALSE.
This function is valid in rules only.
TurboIntegrator uses its own IF function that is capable of evaluating multiple logical expressions.

Syntax
IF(expression, true_value, false_value)

Chapter 2. Rules functions 141

 Argument Description

expression Any value or expression that can be evaluated to

TRUE or FALSE.

true_value The value that is returned if expression is TRUE.

false_value The value that is returned if expression is FALSE.

Example
IF(1<2, 4, 5) returns 4.
IF(1>2, 'ABC', 'DEF') returns 'DEF'.

STET
The STET function cancels the effect of a rule for a particular element.
This is a rules function, valid only in Planning Analytics rules. This function cannot be used in
TurboIntegrator processes.

Syntax
STET

Arguments
None.

Example
In this example, the rule dictates that the value for Sales is always 100, except for the intersection of
Sales and the element France from the Region dimension.

['Sales'] = IF(!Region @= 'France',STET, 100);

Mathematical Rules Functions

Mathematical operators to use in rules.

ABS
ABS returns the absolute value of a number.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ABS(x)

Argument Description

x The number for which you want to find the

absolute value.

142 IBM Planning Analytics: Reference

 Example
ABS(-1.2) returns 1.2

ACOS
ACOS returns the angle, in radians, whose cosine is x.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ACOS(x)

Argument Description

x The cosine of the angle you want to find. x must be

between -1 and 1; otherwise the function returns
an error.

Example
ACOS(0) returns 1.5708.

ASIN
ASIN returns the angle, in radians, whose sine is x.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ASIN(x)

Argument Description

x The sine of the angle you want to find. x must be

between -1 and 1; otherwise the function returns
an error.

Example
ASIN(1) returns 1.5708.

ATAN
ATAN returns the angle, in radians, whose tangent is x. The result is between -pi/2 and +pi/2.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ATAN(x)

Argument Description

x The tangent of the angle you want to find.

Chapter 2. Rules functions 143

 Example
ATAN(1) returns .7854.

COS
COS returns the cosine of an angle expressed in radians.
This function is valid in both rules and TurboIntegrator processes.

Syntax
COS(x)

Argument Description

x An angle, expressed in radians, for which you want

to find the cosine.

Example
COS(0) returns 1.

EXP
EXP returns the natural anti-log of a number.
This function is valid in both rules and TurboIntegrator processes.

Syntax
EXP(x)

Argument Description

x A number for which you want to find the natural

anti-log.

Example
EXP(1) returns 2.71828.

INT
INT returns the largest integer that is less than or equal to a specified value.
This function is valid in both rules and TurboIntegrator processes.

Syntax
INT(x)

Argument Description

x A numeric value.

144 IBM Planning Analytics: Reference

 Example
INT(5.6) returns 5.
INT(-5.6) returns -6.

ISUND
ISUND returns 1 if a specified value is undefined; otherwise it returns 0.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ISUND(x)

Argument Description

x A number or expression.

Example
ISUND(5.2) returns 0.
ISUND(1/0) returns 1.

LN
LN returns the natural logarithm (base e) of a number.
This function is valid in both rules and TurboIntegrator processes.

Syntax
LN(x)

Argument Description

x A positive number. The function returns an error if x

is negative or zero.

Example
LN(10) returns 2.302585093.

LOG
LOG returns the base 10 logarithm of a positive number.
This function is valid in both rules and TurboIntegrator processes.

Syntax
LOG(x)

Chapter 2. Rules functions 145

 Argument Description

x A positive number. The function returns an error if x

is negative or zero.

Example
LOG(10) returns 1.

MAX
MAX returns the largest number in a pair of values.
This function is valid in both rules and TurboIntegrator processes.

Syntax
MAX(num1, num2)

Argument Description

num1 The first in a pair of values.

num2 The second in a pair of values.

Example
MAX(10, 3) returns 10.

MIN
MIN returns the smallest number in a pair of values.
This function is valid in both rules and TurboIntegrator processes.

Syntax
MIN(num1, num2)

Argument Description

num1 The first in a pair of values.

num2 The second in a pair of values.

Example
MIN(10, 3) returns 3.

MOD
MOD returns the remainder of dividing a number by a divisor.
This function is valid in both rules and TurboIntegrator processes.

146 IBM Planning Analytics: Reference

 Syntax
MOD(number, divisor)

Argument Description

number The number for which you want to find the

remainder.

divisor The value by which the number argument is

divided.

Example
MOD(10, 3) returns 1.

RAND
RAND generates a random number that is uniformly distributed between 0 and 1. The random number
generator is seeded when Planning Analytics is loaded.
This function is valid in both rules and TurboIntegrator processes.

Syntax
RAND.

Arguments
None.

Example
RAND generates a random number that is uniformly distributed between 0 and 1

ROUND
ROUND rounds a given number to the nearest integer. Rounding can be done in a variety of ways.
This function is valid in both rules and TurboIntegrator processes.
The most basic form of rounding is to replace an arbitrary number by an integer. There are many ways of
rounding a number y to an integer q.
The most common ones are:
• Round to nearest
q is the integer that is closest to y (see "Round away from zero" for tie-breaking rules).
• Round towards zero (or truncate)
q is the integer part of y, without its fraction digits.
• Round down (or take the floor)
q is the largest integer that does not exceed y.
• Round up (or take the ceiling)
q is the smallest integer that is not less than y.
• Round away from zero
If y is an integer, q is y; else q is the integer that is closest to 0 and is such that y is between 0 and q.

Chapter 2. Rules functions 147

 TurboIntegrator essentially uses the Round down method of floor(x + .5). Microsoft Excel uses the
Round to nearest method. This can result in different integers depending on whether you are using a
TurboIntegrator process or working in Excel.

Syntax
ROUND(number)

Argument Description

number The number you want to round.

Example
ROUND(1.46) returns 1.

ROUNDP
ROUNDP rounds a given number at a specified decimal precision.
This function is valid in both rules and TurboIntegrator processes.

Syntax
ROUNDP(number, decimal)

Argument Description

number The number you want to round.

decimal The decimal precision at which to apply the

rounding. If this argument is positive, the function
rounds the specified number of digits to the right
of the decimal point. If this argument is negative,
the function rounds the specified number of digits
to the left of the decimal point.
The decimal argument must be between -15 and
15, inclusive.

Example
ROUNDP(1.46, 1) returns 1.5.
ROUNDP(1.466, 2) returns 1.47.
ROUNDP(234.56, -1) returns 230.00.
ROUNDP(234.56, 0) returns 235.00.

SIGN
SIGN determines if a number is positive, negative, or zero. The function returns 1 if the number is positive,
-1 if the number is negative, and 0 if the number is zero.
This function is valid in both rules and TurboIntegrator processes.

148 IBM Planning Analytics: Reference

 Syntax
SIGN(number)

Argument Description

number A number.

Example
SIGN(-2.5) returns -1.

SIN
SIN returns the sine of a given angle.
This function is valid in both rules and TurboIntegrator processes.

Syntax
SIN(x)

Argument Description

x A value, expressed in radians, for which you want

the sine.

Example
SIN(1.5708) returns 1.

SQRT
SQRT returns the square root of a given value.
This function is valid in both rules and TurboIntegrator processes.

Syntax
SQRT(x)

Argument Description

x Any positive value. SQRT returns an error if x is

negative.

Example
SQRT(16) returns 4.

TAN
TAN returns the tangent of a given angle.
This function is valid in both rules and TurboIntegrator processes.

Chapter 2. Rules functions 149

 Syntax
TAN(x)

Argument Description

x A value, expressed in radians, for which you want

the tangent.

Example
TAN(0) returns 0.
TAN(.7854) returns 1.

Text Rules Functions

Rules to manage text in rules.

CAPIT
CAPIT applies initial capitalization to every word in a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
CAPIT(string)

Argument Description

string A text string.

Example
CAPIT('first quarter sales') returns 'First Quarter Sales'.

CHAR
CHAR returns the character identified by a given ASCII numeric code.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
CHAR(number)

Argument Description

number An ASCII code number. This number must be

between 1 and 255, inclusive.

Example
CHAR(100) returns 'd'.

150 IBM Planning Analytics: Reference

CODE
CODE returns the ASCII numeric code for a specified character within a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
CODE(string, location)

Argument Description

string A text string.

location A number specifying the character within the string

for which you want to find the ASCII code value.

Example
CODE('321', 2) returns 50.
CODE('End', 3) returns 100.

CODEW
CODEW returns the UTF-8 numeric code for a specified character within a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
CODEW(string, location)

Argument Description

string A text string.

location A number specifying the character within the string

for which you want to find the UTF-8 code value.

Example
CODEW('321', 2) returns 32.
CODEW('End', 3) returns 64.

DELET
DELET returns the result of deleting a specified number of characters from a specified starting point
within a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
DELET(string, start, number)

Chapter 2. Rules functions 151

 Argument Description

string A text string.

start The character at which to begin deletion.

number The number of characters to delete.

Example
DELET('payment', 3, 3) returns 'pant'.

FILL
FILL repeats a given string as necessary to return a string of a specified length.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
FILL(string, length)

Argument Description

string A text string. This string is repeated as necessary

to achieve the specified length.

length The length of the string you want the function to

return.

Example
FILL('-', 5) returns '-----'.
FILL('ab', 5) returns 'ababa'.

INSRT
INSRT inserts one string into another string at a specified insertion point.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
INSRT(string1, string2, location)

Argument Description

string1 A text string.

string2 A text string.

location The position in string2 at which you want to insert

string1. The function inserts string1 into string2
immediately prior to the character you specify.

152 IBM Planning Analytics: Reference

 Example
INSRT('ABC', 'DEF', 2) returns DABCEF.

LONG
LONG returns the length of a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
LONG(string)

Argument Description

string A text string.

Example
LONG('Sales') returns 5.

LOWER
LOWER converts all upper case characters in a string to lower case.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
LOWER(string)

Argument Description

string A text string.

Example
LOWER('First Quarter Sales') returns 'first quarter sales'.

NUMBR
NUMBR converts a string to a number. The string passed to the NUMBR function must use. (period) as the
decimal separator and , (comma) as the thousand separator. Any other decimal/thousand separators will
cause incorrect results.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
NUMBR(string)

Argument Description

string The string you want to convert to a number. All

characters other than '0' through '9', '+', '-', '.', and
'E' are ignored.

Chapter 2. Rules functions 153

 Example
NUMBR('-5.6') returns -5.6.
NUMBR('-5A. B6C') returns -5.6.

SCAN
SCAN returns a number indicating the starting location of the first occurrence of a specified substring
within a string. If the substring does not occur in the given string, the function returns 0.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
SCAN(substring, string)

Argument Description

substring The substring you are trying to locate.

string The string within which you are searching for the
substring.

The arguments to this function are case-sensitive. The capitalization used in the substring argument
must exactly match the capitalization used in the string argument for the function to return a non-zero
value.

Example
SCAN('scribe', 'described') returns 3.
However, SCAN('Scribe', 'described') returns 0, because the case in the substring argument
(Scribe) does not match the case in the string argument (described).

STR
STR converts a floating point number to a string representing the value in decimal notation.
The number passed to the STR function must use "." (period) as the decimal separator and "," (comma) as
the thousand separator. Any other decimal or thousand separators will cause incorrect results.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
STR(number, length, decimal)

Table 2. STR arguments

Argument Description

number The floating point number being converted to a

string.
This number can contain a positive or negative
sign.
This number can contain decimal places.

154 IBM Planning Analytics: Reference

Table 2. STR arguments (continued)

Argument Description

length The desired count of characters in the string

representation, including sign, separators, decimal,
or decimal places.
The length argument value should be a positive
number greater than "0". If the length argument
value is "0" or a negative number, the function
returns an empty string.
If the count of digits in the number is less than
the length argument value, the function inserts
leading blank spaces to attain this length after
inserting sign, separators, decimal, or decimal
places.
If the count of digits in the whole number exceeds
the length argument value and the decimal
argument value is "0", the function truncates the
whole number to attain this length.
If the count of digits in the number exceeds
the length argument value and the decimal
argument value is greater than "0", the function
preserves the whole number and uses the
specified decimal places.

decimal The number of decimal places to include in the

function result.
If this parameter is "0", a decimal point is not
included.
If the number specified has more decimal places
than the decimal argument, the function result is
rounded.

All arguments are required and you cannot pass empty argument values.
Note: There is a limitation when using STR with large floating point values. If the count of whole number
digits in the number argument value exceeds the length argument value by more than 5, the function
returns an empty string. For example, STR(14723017.2245, 4, 2) returns "14723017.22". The whole
number portion of the number argument value has 8 digits, which is not more than 5 greater than the
length argument value of 4 (8<5+4). However, STR(14723017.2245, 2, 2) returns an empty string,
because the whole number portion of the number argument value has 8 digits, which is more than 5
greater than the length argument value of 2 (8>5+2)

Examples

Function call Number Length Decimal Result

STR(3.14159, 6, 2) 3.14159 6 2 " 3.14"
STR(-3.14159, 6, -3.14159 6 0 " -3"
0)
STR(3.14159, 5, 3) 3.14159 5 3 "3.142"
STR(1000000, 4, 0) 1000000 4 0 "1000"

Chapter 2. Rules functions 155

 Function call Number Length Decimal Result

Note that the

number is
truncated.

STR(1000000, 4, 2) 1000000 4 2 "1000000.00"

Note that the
number is not
truncated because
decimal is
specified.

STR(10, 2, 4) 10 2 4 "10.0000"
STR(120536.7439 120536.74391 8 0 " 120536"
1, 8, 0)
The result includes
left padding of two
spaces to attain the
specified length of
8.

STR(120536.7439 120536.74391 5 5 "12053"

1, 5, 0)
The count of
digits in the whole
number exceeds
the length
argument value
and the decimal
argument value
is "0", so the
function truncates
the whole number
to attain the
specified length of
5.

SUBST
SUBST returns a substring of a given string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
SUBST(string, beginning, length)

Argument Description

string The string from which you want to extract the

substring.

beginning The character at which the substring begins.

length The length of the substring.

156 IBM Planning Analytics: Reference

 Example
SUBST('Retirement', 3, 4) returns 'tire'.

TRIM
TRIM returns the result of trimming any leading and trailing blanks from a string.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
TRIM(string)

Argument Description

string A text string.

Example
TRIM(' First Quarter ') returns 'First Quarter'.

UPPER
UPPER converts a text string to upper case.
This function is valid in both TM1 rules and TurboIntegrator processes.

Syntax
UPPER(string)

Argument Description

string A text string.

Example
UPPER('First Quarter Results') returns FIRST QUARTER RESULTS.

Miscellaneous Rules Functions

Rules functions not found in other categories.

FEEDERS
When you use a SKIPCHECK declaration to restore the sparse consolidation in a TM1 rule, you must
also ensure that all rules-derived cells are identified by feeder statements. To do this, insert a FEEDERS
declaration immediately following all rules statements:

FEEDERS;

Immediately following the FEEDERS declaration you should create feeders statements that identify the
rules-derived cells in the cube.
For a complete discussion of TM1 rules, including sparse consolidation and the creation of feeders, please
refer to TM1 Rules.

Chapter 2. Rules functions 157

FEEDSTRINGS
Rule-generated string values are not displayed when a view is zero-suppressed unless the string resides
in a cell that is fed. To enable feeding of string cells, insert the FEEDSTRINGS declaration as the first line
of your rule.

FEEDSTRINGS;

Once this declaration is in place, you can set up feeders for string cells in a cube view, and rely on the
string to be available to other rules even if the view is zero-suppressed. Statements that define feeders for
string cells should be created following the FEEDERS declaration in your rule.
As in the case of numeric feeders, a feed to a consolidated cell results in feeding of all components of the
consolidation. Because you can store strings in consolidated cells, you must pay special attention if such
cells are used to feed other cells. Overuse of string feeders can result in calculation explosions and poor
application performance.
For a complete discussion of TM1 rules, including the creation of feeders, please refer to TM1 Rules.

SKIPCHECK
You can restore sparse consolidation and improve performance by inserting a SKIPCHECK declaration at
the beginning of the TM1 rule.
During consolidations, TM1 uses a sparse consolidation algorithm to skip over cells that contain zero or
are empty. This algorithm speeds up consolidation calculations in cubes that are highly sparse. A sparse
cube is a cube in which the number of populated cells as a percentage of total cells is low.
When consolidating data in cubes that have rules defined, TM1 turns off this sparse consolidation
algorithm because one or more empty cells may in fact be calculated by a rule. (Skipping rules-calculated
cells will cause consolidated totals to be incorrect). When the sparse consolidation algorithm is turned off,
every cell is checked for a value during consolidation. This can slow down calculations in cubes that are
very large and sparse.

SKIPCHECK;

If your rule uses a FEEDSTRINGS statement, the SKIPCHECK statement should be the second statement
in your rule. If your rule does not use a FEEDSTRINGS statement, the SKIPCHECK statement should be
the first statement in your rule.
When you use SKIPCHECK to restore sparse consolidation, you must also ensure that your rule includes a
FEEDERS declaration and that all rules-derived cells are identified by feeder statements.
For a complete discussion of TM1 rules, including sparse consolidation and the creation of feeders, please
refer to TM1 Rules.

158 IBM Planning Analytics: Reference

Chapter 3. Macro Functions
IBM Planning Analytics includes a set of macro functions that you can incorporate in Microsoft Excel
macros. You can use macro functions in TM1 Perspectives to access servers, cube data and structures,
and TM1 options.
Note: Before running these macros, you must load the TM1 Add-In ([Link]). For information about
loading addins, see the Microsoft Excel help.

Accessing Macro Functions from Microsoft Excel 2010 and Later

Procedure
1. Right-click the sheet tab of the active worksheet.
2. From the shortcut menu, click Insert.
3. Double-click MS Excel 4.0 Macro.
4. Click the cell where you want to place the macro function.
5. Click Formulas, and then click Insert Function.
6. From the category list, select TM1.
7. Select the function you want to insert, and then click OK.
8. Type values for the arguments.
9. Click OK to place the function in the current cell in the macro sheet.

Accessing Macro Functions from VBA Modules

To access macro functions from VBA modules, use the Run method.

Run ("macro_function", arg1, ...)

Example

Sub Elemlist( )
Worksheets("Sheet1").Select
Cells(3,5).Select
[Link] = Run ("E_PICK", "local:Region")
End Sub

This procedure calls the E_PICK macro function, which accesses a list of elements in the Region
dimension. The selected element populates a cell in the Sheet1 worksheet.

D_PICK
D_PICK calls a dialog box that lists all available dimensions in the local data directory and on connected
remote servers. The dimension you select in the dialog box becomes the value of the D_PICK function.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
D_PICK

Arguments
None.

© Copyright IBM Corp. 2007, 2025 159

D_FSAVE
D_FSAVE lets you create or update very large dimensions whose dimension worksheets would exceed the
row limit of an Excel worksheet.
To use the D_FSAVE function, create a delimited ASCII file called [Link], where dim is the name of the
dimension you want to create or update. This file must reside in your local server data directory.
The structure of the ASCII file must match a dimension worksheet, as follows:
• Include three fields per line.
• In the first field, specify the element type (C for consolidated; N for numeric element; S for string
element; blank for consolidation component).
• In the second field, specify the element name.
• In the third field, specify the weight, if needed. The default weight is 1.0.
Separate the fields using the delimiter defined in your operating system. In Windows, this delimiter is
defined by the List Separator entry in the Regional Setting Properties dialog box.
If there are errors in the structure of the ASCII file such as misplaced or undefined elements, an error
message displays.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
D_FSAVE(file)

Argument Description

file The name of a delimited ASCII file that has the

file extension .dit. Do not include the file extension.
This file must reside in your local TM1 data
directory.

Example

=D_FSAVE("Region")

This example reads an ASCII file named [Link] and creates or updates the Region dimension.
Note: D_FSAVE can be used to create or update dimensions on remote servers. However, the function
always looks for the .dit file in the local data directory (as defined in [Link]). You must be sure that
the .dit file for the dimension you want to create/update resides in your local data directory, then specify
the server on which you want to create/update the dimension by prefixing the .dit file with the server
name.

=D_FSAVE("TM1Serv:Region")

This example looks for a file named [Link] in the local server data directory, but writes the Region
dimension to the data directory for the TM1Serv server.

D_SAVE
D_SAVE saves the active worksheet as a dimension worksheet file ([Link]). The name of the workbook is
used as the file name. TM1 then creates or updates the dimension specified by the workbook name.
If the active worksheet does not conform to a dimension worksheet format or is missing information, an
error message displays. For example, you must define all elements used in a level-1 consolidation as
numeric elements (N).

160 IBM Planning Analytics: Reference

 This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
D_SAVE

Arguments
None.

DBProportionalSpread
DBProportionalSpread distributes a specified value to the leaves of a consolidation proportional to
existing cell values.
The function is analogous to the Proportional Spread data spreading method, which is described in detail
in the TM1 Perspectives and TM1 Architect documentation.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
DBProportionalSpread( value, server:cube, e1, e2, e3...,
e16 )

Argument Description

value The value you want to distribute.

server:cube The name of the cube, prefixed with the

appropriate server name, into which you want to
distribute the value.
For example, to distribute values to the Sales
cube on the Accounting server, you would specify
Accounting:Sales.

e1...e16 The names of the elements that identify the

consolidation whose leaves will accept the
distributed value.

Example

DBProportionalSpread( 2000, "Accounting:Sales", "Actual", "Argentina", "S Series 1.8L Sedan",

"Sales", "1 Quarter" )

This example distributes the value 2000 to the children of the consolidation identified by the elements
Actual, Argentina, S Series 1.8L Sedan, Sales, and 1 Quarter. It distributes values to the Sales cube on the
Accounting server.

E_PICK
E_PICK calls the Subset Editor, listing all elements in the specified dimension. The element name you
select in the Subset Editor becomes the return value of the E_PICK function.
This TM1 macro function is valid in Excel macros and VBA modules only.

Chapter 3. Macro Functions 161

 Syntax
E_PICK(Dimension, Alias, Subset, Element)

Argument Description

Dimension A valid dimension name. The dimension can reside

in the local data directory or on a remote server to
which you are connected.
Use a server name prefix to indicate the server
location. For the local server, specify local:dim. For
a remote server, specify servername:dim.

Alias The name of an alias that exists for the subset.

When this parameter is set, the alias is applied
when the subset is opened in the Subset Editor and
the function returns the alias for the element you
select.
If you choose not to set an Alias parameter you
must pass an empty string to the function.

Subset The name of the subset to be opened in the Subset

Editor when E_PICK is called. The Alias parameter
must be supplied to use this parameter. The Alias
parameter can be defined as an empty string ("").
If you choose not to set a Subset parameter you
must pass an empty string to the function.

ElementNameOrIndex The name or index number of the element to be

pre-selected when the Subset Editor opens.
If you choose not to set an ElementNameOrIndex
parameter you must pass an empty string to the
function.

Example 1

=E_PICK("TM1SERV:Region"," "," "," ")

This example opens the Region dimension in the Subset Editor.

=E_PICK ("TM1SERV:Region","Deutsch","Europe","Argentina")

This example opens the Europe subset in the Subset Editor. The Deutsche alias is applied and the
Argentina element is pre-selected when the Subset Editor opens.

=E_PICK ("TM1SERV:Region"," "," ",14)

This example opens the Region dimension in the Subset Editor, with the 14th element in the dimension
definition pre-selected.

162 IBM Planning Analytics: Reference

I_EXPORT
I_EXPORT exports data from the specified cube to a delimited ASCII file, which is created in
the current user's 'My Documents' directory. In most cases, the 'My Documents' directory is
C:\Users\<user_name>\Documents.
Note: I_EXPORT applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to export a large cube, the server might be inaccessible for a
significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
I_EXPORT(cube, file, zero, calcs)

Argument Description

cube A valid cube name. The cube can reside in your

local data directory or on a remote server to which
you are connected. Use a server name prefix to
indicate the server location. For the local server,
specify local:cube. For a remote server, specify
servername:cube.

file The name of the delimited ASCII file to be created.

The file extension .cma is used; do not specify it.

zero Specifies whether zero values are included. Specify

TRUE to include them, FALSE to exclude them.

calcs Specifies whether calculated values are included.

Specify TRUE to include them, FALSE to exclude
them.

Example
=I_EXPORT("local:92act4d","Download",FALSE,TRUE)
This example exports data from the cube 92act4d to the file [Link]. Zero values are excluded and
calculated values are included.

I_NAMES
You can use I_NAMES to create a list of element names. This function reads through a delimited ASCII
file and writes all the unique names in the specified column to the corresponding column in the active
worksheet.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
I_NAMES(file, column)

Chapter 3. Macro Functions 163

 Argument Description

file The name of an delimited ASCII file, whose file

extension is .cma. Do not include the file extension.

column A number that specifies both the field in the ASCII

file from which to read names and the column in
the active worksheet to which those names are
written.

Example

=I_NAMES("98Sales",3)

This example inspects the file [Link]. All unique names in the third column are written to column C
of the active worksheet.

I_PROCESS
I_PROCESS reads in the records of an ASCII file, one at a time, into the first row of the active worksheet.
Each field populates a different cell. The worksheet is recalculated after each record is read in.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
I_PROCESS(file)

Argument Description

file The name of a delimited ASCII file, whose file

extension is .cma. Do not include the file extension.

Example
=I_PROCESS("98Sales ")
This example reads in each record of the file [Link] into the first row of the active worksheet.

M_CLEAR
M_CLEAR clears and reloads all dimensions in memory. It does not clear cubes and it does not restart the
server.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
M_CLEAR

Arguments
None.

164 IBM Planning Analytics: Reference

OPTGET
OPTGET returns the current value of an option in the [Link] file.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
OPTGET(option)

Argument Description

option A valid TM1 option name.

Valid Option Values Description

AdminHost Returns the name or address of the Admin Host

your client references.

AnsiFiles Returns T if the ANSI character set is currently

used to import data from delimited ASCII files.
Returns F if the ASCII character set is currently
used.

DataBaseDirectory Returns the full path to the data directory for the
local server.

GenDBRW Returns F if the slice worksheet contains DBR

formulas. Returns T if the slice worksheet contains
DBRW formulas.

NoChangeMessage Returns T if this option is set to return the message

NO CHANGE when a DBSn formula points to a C-
level cell. Returns F if this option is set to F.

Example

=OPTGET("DataBaseDirectory")

This example returns the full path to the data directory for the local server.

OPTSET
OPTSET sets a value for a specified TM1 option.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
OPTSET(option, value)

Argument Description

option A valid TM1 option name.

Chapter 3. Macro Functions 165

 Argument Description

value A valid value for the specified option.

Valid Option Values Description

AdminHost Specify the name of the Admin Host on which an

Admin Server is running.

AnsiFiles Specify a value that sets the character set used

during data imports. Specify T to use the ANSI
character set. Specify F to use the ASCII character
set.

DataBaseDirectory Specify a value that sets the full path to the data
directory for the local server.

GenDBRW Specify a value that determines which formula TM1

uses to link values in slice worksheets to cubes.
Specify T to generate DBRW formulas when slice
worksheets are created. Specify F to generate DBR
formulas.

NoChangeMessage Specify a value that determines whether TM1

displays the message NO CHANGE when a DBSn
formula points to a C-level cell. Specify T to display
the message. Specify F to display the value only.

Example

=OPSET("DataBaseDirectory","c:\Tm1data")

This example sets the local data directory to c:\Tm1data.

PublishSubset
PublishSubset publishes a named private subset on a server. If you attempt to publish a private subset
for which an identically named public subset exists, you will be prompted to overwrite the existing public
subset.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
PublishSubset(dimension, subset)

Argument Description

dimension The server-prefixed name of the dimension

containing the private subset you want to publish.
For example, to publish a subset of the Region
dimension on the Finance server, you would pass
"Finance:Region" as the dimension argument.

166 IBM Planning Analytics: Reference

 Argument Description

subset The name of the private subset you want to

publish.

PublishView
PublishView publishes a named private view on a server. This function cannot publish a private view that
uses private subsets.
All private subsets in a private view must first be published with the PublishSubset macro function. If you
attempt to publish a private view for which an identically named public view exists, you will be prompted
to overwrite the existing public view.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
PublishView(cube, view)

Argument Description

cube The server-prefixed name of the cube containing

the private view you want to publish. For
example, to publish a view of the Projections
cube on the Finance server, you would pass
"Finance:Projections" as the cube argument.

view The name of the private view you want to publish.

QUDEFINE
QUDEFINE sets and saves parameters for TM1 query sets. QUDEFINE is the equivalent of creating a query
set using the View Extract dialog box.
You can run queries created with this function using the View Extract dialog box.
You can also use the query set as an argument to the QUEXPORT, QULOOP, and QUSUBSET macro
functions.
Note: QUDEFINE applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to create a query that encompasses a large section of a cube,
the server might be inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
QUDEFINE(cube, query, range, LowLim, HiLim, SkpZeroes,
SkpCons)

Argument Description

cube The name of the cube to be queried.

Use a server name prefix to indicate the server
location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

Chapter 3. Macro Functions 167

 Argument Description

query The name of the query set to be saved for future

use.

range A range of worksheet cells that includes one

column for each dimension in the cube. When you
run the query, TM1 examines only the cube cells
identified by the elements specified or referenced
in the range.
The range must contain one column for each
dimension in the cube. The order of the columns
must be the same as the dimensions in the cube.
In each column, you specify or reference the
elements to be included. To include a subset
of elements, list the element names or specify
a subset name. Write the name of the subset
preceded by the backslash character (\). For
example, \quarter specifies the quarter subset.
To include all elements in a dimension (the ALL
subset), leave the column blank.
You can use DBR functions to populate the cells
in the range. If the functions return blank values
for any column in the range, QUDEFINE uses the
ALL subset for the dimension associated with that
column.

LowLim The lowest cell value to be considered for export.

HighLim The highest cell value to be considered for export.

SkpZeroes Specifies whether cells containing zeroes are

skipped. Specify TRUE to exclude them, FALSE to
include them.

SkpCons Specifies whether cells containing consolidated

values are skipped. Specify TRUE to exclude them,
FALSE to include them.

Example

=QUDEFINE("local:98sales", "Topsell", Sheet1!B3:F5, 3000, 5000, TRUE, TRUE)

This example creates a query set that contains elements listed in Sheet1, in the cell range B3:F5.
When you run this query, TM1 inspects only cube cells identified by these elements and exports non-
consolidated values in the range 3000 to 5000.
Note: If lowlim or highlim is a string comprised of numeric characters, Excel requires the string to be
enclosed in a series of four double quotation marks and single ampersands, as follows:

""""&"0123"&""""

168 IBM Planning Analytics: Reference

QUDEFINEEX
QUDEFINEEX sets and saves parameters for TM1 query sets. It is the equivalent of creating a query set
using the View Extract dialog box. This function is identical to the QUDEFINE macro, with the exception
that QUDEFINEEX includes an argument that allows you to exclude rules-derived values from the query.
You can run queries created with this function using the View Extract dialog box.
You can also use the query set as an argument to the QUEXPORT, QULOOP, and QUSUBSET macro
functions.
Note: QUDEFINEEX applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to create a query that encompasses a large section of a cube,
the server might be inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
QUDEFINEEX(cube, query, range, lowlim, hilim, skpZeroes,
skpCons, skpRuleVals)

Argument Description

cube The name of the cube to be queried.

Use a server name prefix to indicate the server

location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

query The name of the query set to be saved for future

use.

range A range of worksheet cells that includes one

column for each dimension in the cube. When you
run the query, TM1 examines only the cube cells
identified by the elements specified or referenced
in the range.
The range must contain one column for each
dimension in the cube. The order of the columns
must be the same as the dimensions in the cube.
In each column, you specify or reference the
elements to be included. To include a subset
of elements, list the element names or specify
a subset name. Write the name of the subset
preceded by the backslash character (\). For
example, \quarter specifies the quarter subset.
To include all elements in a dimension (the ALL
subset), leave the column blank.
You can use DBR functions to populate the cells
in the range. If the functions return blank values
for any column in the range, QUDEFINEEX uses the
ALL subset for the dimension associated with that
column.

lowlim The lowest cell value to be considered for export.

Chapter 3. Macro Functions 169

 Argument Description

highlim The highest cell value to be considered for export.

skpZeroes Specifies whether cells containing zeroes are

skipped. Specify TRUE to exclude them, FALSE to
include them.

skpCons Specifies whether cells containing consolidated

values are skipped. Specify TRUE to exclude them,
FALSE to include them.

skpRuleVals Specifies whether cells containing rules-derived

values are skipped. Specify TRUE to exclude them,
FALSE to include them.

Example

=QUDEFINEEX("local:SalesCube", "Topsell", Sheet1!B3:F5, 3000, 5000, TRUE, TRUE, FALSE)

This example creates a query set that contain elements listed in Sheet1, in the cell range B3:F5.
When you run this query, TM1 inspects only cube cells identified by these elements and exports non-
consolidated values in the range 3000 to 5000, including those derived through rules.
Note: If lowlim or highlim is a string comprised of numeric characters, Excel requires the string to be
enclosed in a series of four double quotation marks and single ampersands, as follows:

""""&"0123"&""""

QUEXPORT
QUEXPORT exports cells values from the specified cube to a delimited ASCII file.
To create the query set, use the QUDEFINE function.
Each output record has the following format:
• The name of the cube containing the exported values
• Names of elements that identify the cell location of a single exported value
• The exported value
For a five-dimensional cube, TM1 creates records containing seven fields:

"cube name", "elem1", "elem2", "elem3", "elem4", "elem5", value

Note: QUEXPORT applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to export values from a large query set, the server might be
inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
QUEXPORT(cube, query, file)

170 IBM Planning Analytics: Reference

 Argument Description

cube The name of the cube to be queried.

Use a server name prefix to indicate the server
location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

query The name of an existing query set.

file The name of the delimited ASCII file (.cma) to

contain the exported cube data. Do not include the
file extension. The file is created in the local data
directory.

Example

=QUEXPORT("sales:98sales", "Sedans", "Sedans")

This example exports data from the 98sales cube using the query set Sedans. The records are written to
the file [Link].

QULOOP
QULOOP exports data that meets query set criteria from the specified cube. TM1 reads in each output
record, one at a time, into the first row of the active worksheet. Each field populates a different cell. The
worksheet is recalculated after each record is read in.
Each output record has the following format:
• The name of the cube containing the exported values
• The names of elements that identify the cell location of a single exported value
• The exported value
For a five-dimensional cube, TM1 creates records containing seven fields:

"cube name", "elem1", "elem2", "elem3", "elem4", "elem5", value

Use QULOOP in conjunction with a DBSn formula to populate cells in a cube.

Note: QULOOP applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to export values from a large query set, the server might be
inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
QULOOP(cube, query)

Argument Description

cube The name of the cube to be queried. Use a server

name prefix to indicate the server location. For
the local server, specify local:cube. For a remote
server, specify servername:cube.

query The name of an existing query set.

Chapter 3. Macro Functions 171

 Example
=QULOOP("sales:98sales", "Sedans")
This example exports data from the 98sales cube using the query set Sedans.

QUSUBSET
QUSUBSET is the equivalent of running a query from the View Extract dialog box when called from the
Subset Editor.
Note: QUSUBSET applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to run a query that returns a large number of elements, the
server might be inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
QUSUBSET(cube, query, dimension, subset)

Argument Description

cube The name of the cube to be queried. Use a server

name prefix to indicate the server location. For
the local server, specify local:cube. For a remote
server, specify servername:cube.

query The name of an existing query.

dimension The name of a dimension for which the query

exists.

subset The name of the dimension subset to be created,

which will contain the list of elements that meet
the criteria of the subset. For example, a subset
can return the list of regions in which car sales
exceed a specified amount.

Example

=QUSUBSET("sales:98sales", "Top", "Region", "Topsales")

This example creates the Topsales subset for the Region dimension based on the criteria of the Top query.

R_SAVE
R_SAVE saves the active worksheet as a rules worksheet and compiles it into an .rux file. The workbook
must have the same name as the cube for which the rules are being compiled.
Any rules statements that prevent the rules from compiling are written to the [Link] file, in the
local data directory.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
RSAVE

172 IBM Planning Analytics: Reference

 Arguments
None.

SUBDEFINE
SUBDEFINE creates a dimension subset consisting of element names found in the active worksheet.
When SUBDEFINE creates the subset, it will be created as a private subset.
If the named subset already exists as a private subset when the function is run, it will overwrite the
existing private subset by that name.
If the named subset already exists as a public subset, SUBDEFINE still creates the subset as private. If
you want to overwrite the existing named public subset, you will need to publish the private subset that
was created by the SUBDEFINE function to overwrite the existing public subset.
Note: SUBDEFINE applies a lock to the server, preventing other users from accessing the server during
function execution. If you use this function to create a subset with a large number of elements, the server
might be inaccessible for a significant amount of time.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
SUBDEFINE(dimension, subset, range)

Argument Description

dimension The name of the dimension for which you want

to create a subset. Use a server name prefix to
indicate the server location. For the local server,
specify local:dim. For a remote server, specify
servername:dim.

subset The name of the dimension subset.

range The range of worksheet cells containing the names

of elements in the dimension. Any cell values in the
range that are not valid elements are ignored.

Example
=SUBDEFINE("local:Model", "Smith", B7:M7)

This example creates a subset called Smith for the Model dimension. The subset contains elements found
in the cell range B7:M7.

SUBPICK
SUBPICK calls a dialog box that lists all the elements in the specified subset. The elements you select are
inserted in the active worksheet, starting at the current cell position.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
SUBPICK(dimension, subset, vertical)

Chapter 3. Macro Functions 173

 Argument Description

dimension The name of the dimension containing subsets.

Use a server name prefix to indicate the server
location. For the local server, specify local:dim. For
a remote server, specify servername:dim.

subset The name of the subset whose elements you want

to select.

vertical Specify TRUE to insert the element names

vertically, from the current cell downward. Specify
FALSE to insert the element names horizontally,
from the current cell rightward.

Example

=SUBPICK("local:Model", "Smith", TRUE, )

This example inserts selected elements from the Smith subset into the active worksheet. The elements
are arranged vertically, starting from the current cell downward.

T_CLEAR
T_CLEAR clears all changes or additions to cube data from memory.
Note: T_CLEAR does not prompt you to save to disk any cube data in RAM. Any unsaved data is cleared
without saving to disk. Therefore, if you want to save any cube data currently in RAM, call the T_SAVE
function first.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
T_CLEAR

Arguments
None.

T_CREATE
T_CREATE creates a cube that has up to eight dimensions, which is the limit in older versions of TM1.
Note: If you use T_CREATE to create a cube with the name of an existing cube, TM1 replaces the existing
cube and deletes all of its data.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
T_CREATE(cube,d1,d2[,d3,d4,d5,d6,d7,d8])

174 IBM Planning Analytics: Reference

 Argument Description

cube The name of the cube to be created.

Use a server name prefix to indicate the server
location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

d1...d8 Names of up to eight existing dimensions, in the

order you want them stored in the cube. You must
specify at least two dimensions.

Example

=T_CREATE("local:Sales","Region","Products","Month")

This example creates a cube named Sales. This new cube has three dimensions, in the following order:
Region, Products, and Month.

T_CREATE16
T_CREATE16 creates a cube that has up to sixteen dimensions.
Note: If the first argument to this function is an existing cube name, TM1 replaces the existing cube and
deletes all of its data.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
T_CREATE16(cube,d1,d2[,d3,...,d16])

Argument Description

cube The name of the cube to be created.

Use a server name prefix to indicate the server
location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

d1...d16 Names of up to sixteen existing dimensions, in the

order you want them stored in the cube. You must
specify at least two dimensions.

Example

=T_CREATE("Sales","Region","Products","Month")

This example creates a cube named Sales. This new cube has three dimensions, in the following order:
Region, Products, and Month.

T_PICK
T_PICK calls a dialog box that lists all available cubes on the local and remote TM1 servers. The cube
name you select in the dialog box becomes the value of the T_PICK function. Your macro inserts the cube
name in the first cell of the active worksheet.
This TM1 macro function is valid in Excel macros and VBA modules only.

Chapter 3. Macro Functions 175

 Syntax
T_PICK

Arguments
None.

T_SAVE
T_SAVE saves all cube data currently in RAM to disk. T_SAVE can be used only to save data on a local
server; the function does not work with remote servers. T_SAVE does not prompt you about saving data
for individual cubes.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
T_SAVE

Arguments
None.

TM1RECALC
TM1RECALC forces a recalculation of all open worksheets. It is the equivalent of pressing F9 in Excel. A
similar macro function, TM1RECALC1, forces a recalculation of only the active worksheet.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
TM1RECALC

Arguments
None.

TM1RECALC1
TM1RECALC1 forces a recalculation of the active worksheet. It is the equivalent of pressing SHIFT-F9 in
Excel. A similar macro function, TM1RECALC, forces a recalculation of all open worksheets.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
TM1RECALC1

Arguments
None.

176 IBM Planning Analytics: Reference

VUSLICE
VUSLICE creates a slice worksheet from the specified cube view. The slice is inserted starting at the top
left cell (A1 or R1C1) in the active worksheet.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
VUSLICE(cube, view)

Argument Description

cube The name of an existing cube.

Use a server name prefix to indicate the server
location. For the local server, specify local:cube.
For a remote server, specify servername:cube.

view The name of a view associated with the cube.

Example

=VUSLICE("local:98sales","Quarterly")

This example copies data from the Quarterly view of the 98sales cube into the active worksheet.

W_DBSENABLE
W_DBSENABLE enables (or disables) automatic recalculation of DBS functions in a worksheet.
Normally when a DBS function is inserted in a worksheet, the function is not executed until the sheet
is recalculated with either the F9 or SHIFT+F9 keys. You can use the W_DBSENABLE function to
immediately execute DBS functions as they are created in a worksheet.
Note: DBS functions will not run at all in VBA modules unless W_DBSENABLE is set to TRUE.
This TM1 macro function is valid in Excel macros and VBA modules only.

Syntax
=W_DBSENABLE(LogicalFlag)

Argument Description

LogicalFlag If TRUE, DBS functions are executed immediately

when inserted into or called from a worksheet.
If FALSE, DBS functions are executed only when
the worksheet is explicitly recalculated.

Chapter 3. Macro Functions 177

178 IBM Planning Analytics: Reference
Chapter 4. Worksheet Functions
IBM Planning Analytics Worksheet functions return a numeric or string value. You can use TM1 worksheet
functions anywhere in an IBM Planning Analytics for Microsoft Excel or TM1 Perspectives worksheet.
To access these functions in Microsoft Excel, choose Formulas > Insert Function.
Note: If you are using Planning Analytics for Microsoft Excel, you must first enable the IBM Cognos Office
Reporting TM1 addin.
If a worksheet function references an object on a remote server, you must prefix the object with
the server name and a colon. For example, to refer to the SalesCube cube on the SData server, use
SData:SalesCube. You must be connected to the server referenced by the function to receive accurate
values in your worksheet. If you are not connected to the server, TM1 worksheet functions return
*KEY_ERR.
TM1 worksheet functions accept strings, values, or cell references as arguments. Strings must be
enclosed in quotation marks. Numeric element names must be enclosed in double quotation marks.
For example ""14357"". Cell references must refer to valid arguments for a given function. You can use
standard conventions for absolute and relative cell references in worksheet functions.
Due to a limitation with Microsoft Excel, worksheet functions can contain no more than 30 arguments.
When you construct a cube reference, one argument must be the cube name, which leaves 29 arguments
for specifying the cube dimensions.
If you record a worksheet macro in Microsoft Excel that includes TM1 functionality, the resulting macro
may include undocumented TM1 worksheet functions. We may, however, modify or discontinue these
undocumented functions in future releases without notification.
Worksheet functions cannot be used in TM1 rules or in TurboIntegrator processes.

DBR
DBR retrieves a value from a specified TM1 cube.
When all element arguments (e1, e2, etc.) to the function are leaf elements, the DBR function can also be
used to write values to the specified cube, provided that the user has appropriate access privileges to the
relevant cube, dimensions, elements, and/or cells. When you enter a value in a cell containing such a DBR
function, the value is sent to the server.
This worksheet function is valid in worksheets only.

Syntax
DBR(cube, e1, e2,[...en])

Argument Description

cube The name of the cube from which to retrieve the value.

e1,...en Dimension element names that define the intersection of the cube containing
the value to be retrieved.
Arguments e1 through en are sequence-sensitive. e1 must be an element
from the first dimension of the cube, e2 must be an element from the second
dimension, and so on. These arguments can also be the names of aliases for
dimension elements.
Numeric element names must be enclosed in double quotation marks. For
example ""14357"".

© Copyright IBM Corp. 2007, 2025 179

 Example

DBR("92act4d", "California", "3.5 Diskettes", "Net Sales","January")

In this example, 92act4d is the cube name, and the function returns the value at the intersection of
California, 3.5 Diskettes, Net Sales, and January.

DBRA
DBRA retrieves the value of a specified element attribute. The value returned can be either a string or
numeric value, depending on the attribute type.
The DBRA function can also be used to write element attribute values to the server. When you enter a
value, either string or numeric, in a cell containing a DBRA function, the corresponding element attribute
is updated on the server.
This worksheet function is valid in worksheets only.

Syntax
DBRA(server:dimension, element, attribute)

Argument Description

server:dimension A valid dimension name, prefixed with the appropriate server name and a
colon, for example, "SData:Region" references the Region dimension on the
SData server.
If the dimension is not prefixed with a server name, the DBRA function
attempts to run against the local server.

element An element of the dimension.

attribute The attribute for which you want to retrieve a value. This argument must be a
valid attribute of the element.

Example

DBRA("SData:Model", "L Series 1.8L Sedan", "ManufactureCode")

In this example, the function returns the value of the Manufacture Code attribute of the L Series 1.8L
Sedan element in the Model dimension on the SData server.

DBRW
DBRW retrieves a value from a specified TM1 cube.
When all element arguments (e1, e2, etc.) to the function are leaf elements, the DBRW function can also
be used to write values to the specified cube, provided that the user has appropriate access privileges to
the relevant cube, dimensions, elements, and/or cells.
DBRW works the same as the DBR function, with one major difference; DBRW reduces network traffic and
may improve performance on wide area networks.
In worksheets with a large number of TM1 worksheet functions, DBRW forces TM1 to execute functions
in "bundles" rather than individually. Normal DBR functions are executed individually during a worksheet
recalculation. DBRW functions force TM1 to execute two passes over the worksheet. In the first pass,
all changed values in cells containing DBRW functions are sent in a single bundle to the cube. In the

180 IBM Planning Analytics: Reference

 second pass, cube values are sent in a single bundle back to the worksheet. Consequently, the worksheet
recalculates twice when DBRW functions are executed.
DBRW bundling occurs when the function is used in a standalone cell. When DBRW functions are used in
complex calculations, the function operates as a DBR function so no performance gains accrue.
This worksheet function is valid in worksheets only.

Syntax
DBRW(cube, e1, e2[,...en])

Argument Description

cube The name of the cube from which to retrieve the value.

e1,...en Dimension element names that define the intersection of the cube
containing the value to be retrieved.
Arguments e1 through en are sequence-sensitive. e1 must be an element
from the first dimension of the cube, e2 must be an element from the
second dimension, and so on. These arguments can also be the names of
aliases for dimension elements.
Numeric element names must be enclosed in double quotation marks.

Example

DBRW("92act4d", "California", "3.5 Diskettes", "NetSales", "January")

In this example, the function returns the value at the intersection of California, 3.5 Diskettes, Net Sales,
and January in the 92act4d cube.

DBS
DBS sends a numeric value to a TM1 cube. This function cannot send a string to a cube. To send strings,
use the DBSS function.
When you build a DBS function with the TM1 > Edit Formula option, the Edit Formula dialog box prompts
you through a series of steps to build each function argument in the correct sequence.
If the cube does not exist or one of the arguments is invalid, the function returns KEY ERROR.
This worksheet function is valid in worksheets only.

Syntax
DBS(value, cube, e1, e2[,...en])

Argument Description

value The value being sent.

cube The cube to which the value is sent.

Chapter 4. Worksheet Functions 181

 Argument Description

e1, ...en The names of elements defining the intersection in the cube to which the
value is sent.
Arguments e1 through en are sequence-sensitive. e1 must be an element
from the first dimension of the cube, e2 must be an element from the
second dimension of the cube, and so on. These arguments can also be
the names of aliases for dimension elements.
Numeric element names must be enclosed in quotation marks.

Example
In this example, the function sends the value 5342 into the cube 92act4d at the intersection of California,
3.5 Diskettes, Net Sales, and January.

DBS(5342,"92act4d","California","3.5 Diskettes", "NetSales", "January")

DBSA
DBSA sends a value to a specified element attribute. The value sent can be either a string or numeric
value, depending on the attribute type.
This worksheet function is valid in worksheets only.

Syntax
DBSA(att_value, dimension, element, att_name)

Argument Description

att_value The value you want to send.

dimension A valid dimension name. The dimension name

must be prefixed with the appropriate server
name and a colon, for example, "SData:Region"
references the Region dimension on the SData
server.
If the dimension is not prefixed with a server name,
the DBSA function will attempt to run against the
local server.

element An element of the dimension.

att_name The attribute to which you want to send a value.

att_name must be a valid attribute of the element
specified by elem_name.

Example

DBSA(''LS-1.8-M7398", "SData:Model", "L Series 1.8LSedan", "Manufacture Code")

182 IBM Planning Analytics: Reference

DBSS
DBSS sends a string to a cube of any number of dimensions. This function cannot send a numeric value to
a cube. Use the DBS function to send numeric values.
When you build a DBSS function with the TM1 > Edit Formula option, the Edit Formula dialog box prompts
you through a series of steps to build each function argument in the correct sequence.
If the cube does not exist or one of the arguments is invalid, the function returns KEY ERROR.
This worksheet function is valid in worksheets only.

Syntax
DBSn(string, cube, e1, e2,...en)

Argument Description

string The string being sent.

cube The cube to which the string is sent.

e1, ...en The names of elements defining the intersection in

the cube to which the string is sent.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension
of the cube, e2 must be an element from the
second dimension of the cube, and so on. These
arguments can also be the names of aliases for
dimension elements.

Example

DBSS("Smith","Info","California","Last Name")

In this example, the formula sends the string Smith to the cube Info at the intersection of California and
Last Name.

DBSW
DBSW sends a numeric value to a cube. This function cannot send a string to a cube. To send strings, use
the DBSS function.
This function works the same as the DBS function, with one major difference; DBSW reduces network
traffic and may improve performance on wide area networks.
In worksheets with a large number of cube references, DBSW forces Planning Analytics to send values
in bundles rather than individually. Normal DBS functions are updated individually during a recalculation.
DBSW references force Planning Analytics to send all changed values within a worksheet in a single
bundle.
In such circumstances you can safely use a DBS/DBR function as an argument to a DBS function.
Note: If you use VBA to calculate a worksheet containing DBSW functions, you must call the TM1
macro functionto calculate the worksheet. Do not use the VB Calculate method to calculate a worksheet
containing DBSW functions; doing so causes each DBSW function to be executed individually, defeating
the purpose of the function and resulting in decreased performance.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 183

 Syntax
DBSW(value, cube, e1, e2[,...en])

Argument Description

value The value being sent.

cube The cube to which the value is sent.

e1, ...en The names of elements defining the intersection in

the cube to which the value is sent.
Arguments e1 through en are sequence sensitive.
e1 must be an element from the first dimension
of the cube, e2 must be an element from the
second dimension of the cube, and so on. These
arguments can also be the names of aliases for
dimension elements.
Numeric element names must be enclosed in
quotation marks.

Example

DBSW(5342,"92act4d","California","3.5 Diskettes", "NetSales", "January")

DFRST
DFRST returns the first element of a specified dimension.
This worksheet function is valid in worksheets only.

Syntax
DFRST(server_name:dimension)

Argument Description

dimension A valid dimension name.

Example

DFRST("planning_sample:Location")

If the dimension Location contains the ordered elements California, Oregon, and Washington, the
example returns California.

DIMIX
DIMIX returns the index number of an element within a dimension.
This worksheet function is valid in worksheets only.

184 IBM Planning Analytics: Reference

 Syntax
DIMIX(server_name:dimension, element)

Argument Description

dimension A valid dimension 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. This argument
can also be the name of an alias for a dimension
element.

Example

DIMIX("planning_sample: Location","Washington")

If the dimension Location contains the ordered elements California, Oregon, and Washington, the
example returns the value 3, as Washington is the third element of the dimension.

DIMNM
DIMNM returns the element of a dimension that corresponds to the Index argument. If you include the
Alias parameter to this function, the function returns the alias for the selected element.
When you double-click a cell that contains a DIMNM function, the Dimension dialog box opens. You can
then select a new element to place in your worksheet. The DIMNM function automatically updates the
Index argument to reflect the new element.
Note: If you are using TM1 Perspectives, the set editor is opened when a cell that contains a DIMNM
function is double-clicked.
This worksheet function is valid in worksheets only.

Syntax
DIMNM(server_name:Dimension, Index, [Alias])

Argument Description

Dimension A valid dimension name.

Index A value less than or equal to the number of

elements in the dimension.

Alias The name of an alias that exists for the dimension.

Alias is an optional argument. If it is used, the
function returns the alias for the specified element.

DIMSIZ
DIMSIZ returns the number of elements within a specified dimension.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 185

 Syntax
DIMSIZ(dimension)

Argument Description

dimension A valid dimension name.

Example

DIMSIZ("Accounts")

If the Accounts dimension contains 19 elements, the example returns the value 19.

DNEXT
DNEXT returns the element name that follows the element specified as an argument to the function.
This worksheet function is valid in worksheets only.

Syntax
DNEXT(server:dimension, element)

Argument Description

server:dimension A valid dimension name, prefixed with the

appropriate server name and a colon, for example,
"SData:Region" references the Region dimension
on the SData server.
If the dimension is not prefixed with a server name,
the DNEXT function will attempt to run against the
local server.

element The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example

DNEXT("Production:Location","Oregon")

If the Location dimension on the Production server contains the ordered elements California, Oregon, and
Washington, the example returns Washington.

DNLEV
DNLEV returns the number of hierarchy levels in a dimension.
This worksheet function is valid in worksheets only.

Syntax
DNLEV(dimension)

186 IBM Planning Analytics: Reference

 Argument Description

dimension A valid dimension name.

Example

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

In the Region dimension there are four hierarchy levels (0, 1, 2, and 3). Therefore, the example returns the
value 4.

DTYPE
DTYPE returns information about the element type of the specified element. It returns "N" if the element
is a numeric element, "S" if the element is a string element.
This worksheet function is valid in worksheets only.

Syntax
DTYPE(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example

DTYPE("Region","Europe")

The element Europe in the dimension Region is a consolidated element, so the example returns "C".

ELCOMP
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.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 187

 Syntax
ELCOMP(dimension, element, index)

Argument Description

dimension A valid dimension name.

element The name of a consolidated element within the

dimension. This argument can also be the name
of an alias for a dimension element.

index A positive value less than or equal to the total

number of children in the specified element.

Example

ELCOMP("Region","Central Europe",2)

In the dimension Region, the consolidated element Central Europe is a consolidation of the children
Germany and France. Accordingly, the example returns France.

ELCOMPN
ELCOMPN returns the number of components in a specified element. If the element argument is not a
consolidated element, the function returns 0.
This worksheet function is valid in worksheets only.

Syntax
ELCOMPN(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of a consolidated element within the

dimension. This argument can also be the name
of an alias for a dimension element.

Example

ELCOMPN("Region","Scandinavia")

In the Region dimension, the element Scandinavia is a consolidation of three elements. The example
returns 3.

ELISCOMP
ELISCOMP determines whether element1 is a child of element2 in the specified dimension. The function
returns TRUE if element1 is a child of element2, otherwise the function returns FALSE.
This worksheet function is valid in worksheets only.

188 IBM Planning Analytics: Reference

 Syntax
ELISCOMP(dimension, element1, element2)

Argument Description

dimension A valid dimension name.

element1 The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

element2 The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example

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 TRUE.
Note that this function returns TRUE 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 TRUE only for immediate children, the following example returns False:

ELISCOMP("Region","Germany","Europe")

ELISPAR
ELISPAR determines whether element1 is a parent of element2 in the specified dimension. The function
returns TRUE if element1 is a parent of element2, otherwise the function returns FALSE.
This worksheet function is valid in worksheets only.

Syntax
ELISPAR(dimension, element1, element2)

Argument Description

dimension A valid dimension name.

element1 The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

element2 The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example

ELISPAR("Region","Central Europe","Germany")

Chapter 4. Worksheet Functions 189

 In the dimension Region, the consolidated element Central Europe is the parent of both Germany and
France. Accordingly, the example returns TRUE
Note that this function returns TRUE 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 FALSE:

ELISPAR("Region","Europe","Germany")

ELLEV
ELLEV returns the level of an element within a dimension.
This worksheet function is valid in worksheets only.

Syntax
ELLEV(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension. This argument can also be
the name of an alias for a dimension element.

Example

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.

ELPAR
ELPAR returns the parent of an element in a specified dimension
This worksheet function is valid in worksheets only.

Syntax
ELPAR(dimension, element, index)

190 IBM Planning Analytics: Reference

 Argument Description

dimension A valid dimension name.

element The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

index A positive value less than or equal to the total

number of consolidated elements (parents) that
use the element argument as a child.

Example

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.

ELPARN
ELPARN returns the number of parents of an element in a specified dimension.
This worksheet function is valid in worksheets only.

Syntax
ELPARN(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of an element within the dimension. This

argument can also be the name of an alias for a
dimension element.

Example

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.

ELSLEN
ELSLEN returns the length of a string element within a dimension. If the element specified is not a
member of the dimension specified, or is not a string element, the function returns 0.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 191

 Syntax
ELSLEN(dimension, element)

Argument Description

dimension A valid dimension name.

element The name of a string element within the dimension.

This argument can also be the name of an alias for
a dimension element.

Example

ELSLEN("Region","Washington")

The element Washington is a string element 10 characters in length. The example returns 10.

ELWEIGHT
ELWEIGHT returns the weight of a child in a consolidated element.
This worksheet function is valid in worksheets only.

Syntax
ELWEIGHT(dimension, element1, element2)

Argument Description

dimension A valid dimension name.

element1 The name of a consolidated element within the

dimension. This argument can also be the name
of an alias for a dimension element.

element2 The name of a child of the consolidated element.

This argument can also be the name of an alias for
a dimension element.

Example

ELWEIGHT("Account1","Gross margin","Variable costs")

As the following figure shows, the element Variable costs, which is a child of Gross margin, has a weight of
-1.

The example returns -1.

192 IBM Planning Analytics: Reference

MakeQuery3
Universal Report static layout has a formula called MakeQuery3.
MakeQuery3 builds the MDX query from the report’s content. This formula takes in a cube name as its first
argument and the row, column, slicers, and calculation named ranges.

Syntax
In the following syntax, 0 represents the report id on the sheet:

=@MakeQuery3("plan_BudgetPlan",tm2\\_0_rh,tm2\\_0_rm,tm2\\_0_ch,tm2\\_0_cm,tm2\\_0_sh,tm2\
\_0_slicers,tm2\\_0_calcs)

The MakeQuery3 output is an MDX query representing the report that starts with /* STATICLAYOUT
*/.
Note: If you wanted to manually add an MDX query to the report instead of using MakeQuery3, /*
STATICLAYOUT */. must be at the front of the query in order for IBM Planning Analytics for Microsoft
Excel and IBM Planning Analytics TM1 Web to recognize the query as a part of a Universal Report static
layout.

Table 3. MakeQuery3 Arguments

Argument Description
Cube TM1 cube name.
tm2\\_0_rh Cell range of the row axis hierarchies. The
order is important and should match the
hierarchy order of the row axis hierarchies
desired (ex: {“[plan_chart_of_accounts].
[ plan_chart_of_accounts]”, “[plan_business_unit].
[plan_business_unit”}).
tm2\\_0_rm Cell range of the row axis members (ex:
{“Revenue”, “UK”; “Revenue”, “Canada”; …}.
tm2\\_0_ch Cell range of the column axis hierarchies. The order
is important and should match the hierarchy order
of the row axis hierarchies desired.
tm2\\_0_cm Cell range of column axis members (ex:
{“Jan-2004”, “Feb-2004”, “Mar-2004”; “FY 2004
Budget”, “FY 2004 Budget”, “FY 2004 Budget”}).
tm2\\_0_sh Cell range of the slicer hierarchies. The
order is important and should match the
hierarchy order of the row axis hierarchies
desired (“ex: {“[plan_source].[plan_source]”,
“[plan_department].[plan_department]”…}).
tm2\\_0_slicers Cell range of the slicers members (“ex: {“Goal”,
“Total Organization”, …}).
tm2\\_0_calcs Cell range of the calculated members.

Chapter 4. Worksheet Functions 193

SUBNM
SUBNM returns the element of a dimension subset corresponding to the IndexOrName argument. If
you include the optional Alias parameter to this function, the function returns the alias for the selected
element.
When you double-click a cell containing a SUBNM function, the Subset Editor opens. You can then select
a new element to place in your worksheet. The selected element becomes the return value of the SUBNM
function, and the function automatically updates the IndexOrName argument to reflect the new element.
This worksheet function is valid in worksheets only.

Syntax
SUBNM(Dimension, Subset, IndexOrName, [Alias])

Argument Description

Dimension A valid dimension name.

Subset The name of a subset of the dimension.

IndexOrName An index into the subset or the name of an element

in the subset.
If an index, a positive integer less than or equal
to the total number of elements in the specified
subset. If a name, a string representing the name
of an element of the subset.

Alias The name of an alias that exists for the subset.

This is an optional argument. If it is used, the
specified alias is applied when the Subset Editor
opens and the function returns the alias for the
selected element.

Example

SUBNM("Region","Top Producers",2)

The Top Producers subset of the Region dimension contains the ordered elements United States,
Germany, Great Britain, and Mexico. Because the Index argument points to the second element in the
subset, the example returns Germany.

SUBNM("Region","Top Producers","Germany","Deutsch")

This example returns the Deutsch alias for the Germany element (Deutschland) from the Top Producers
subset of the Region dimension.

SUBSIZ
SUBSIZ returns the number of elements in a dimension subset.
This worksheet function is valid in worksheets only.

Syntax
SUBSIZ(dimension, subset)

194 IBM Planning Analytics: Reference

 Argument Description

dimension A valid dimension name.

subset The name of a subset of the dimension.

Example

SUBSIZ("Region","Top Producers")

The Top Producers subset of the Region dimension contains four elements: United States, Germany, Great
Britain, and Mexico.
The example returns 4.

TABDIM
TABDIM returns the dimension name that corresponds to a given index argument.
The function always returns a dimension based on the original order of dimensions in the specified cube,
even if the order of dimensions in the cube has been changed through the TM1 Cube Optimizer.
This worksheet function is valid in worksheets only.

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.

Example

TABDIM("98sales",3)

The cube 98sales contains five dimensions: account1, actvsbud, model, month, and region. The example
returns model, the third dimension of 98sales.

TM1ELLIST
TM1ELLIST returns a downward array vector of values. It is useful because you can get a set of element
values from a TM1 model by using a single formula.
Note:
• TM1ELLIST does not overwrite or insert into populated cells. It is up to the workbook designer to make
sure that a multiple value response is displayed correctly.
• TM1ELLIST returns an array of values. However, only the first element displays if the function is entered
into a singular value store.
• IBM Planning Analytics for Microsoft Excel does not support default aliases for subsets and
the AliasOverride argument. TM1ELLIST does not return alias names when you use the
AliasOverride argument or if a subset is defined with an alias.

Chapter 4. Worksheet Functions 195

 This worksheet function is valid in worksheets only.

Syntax
TM1ELLIST(ServerDimension, [SetName], [ElementList],
[AliasOverride], [ExpandAbove], [MDXOverride], [IndentRate], [IndentCharacter])

Argument Description Required or Optional

ServerDimension A dimension that is specified by using the format Required

server:dimension.

SetName A named set. If this argument is empty, all Optional

elements of the dimension are used.

ElementList An array of values, which specifies a list of Optional

elements to constitute a set. For example,
ElementList can reference a cell range.
When this argument is supplied, the named set
that is specified by the SetName argument is
ignored.
If this argument is empty, the elements from the
set that is specified by the SetName argument are
used.

AliasOverride A string that defines the alias that is used for the Optional
set.
When this argument is supplied, it overrides the
default alias property that is defined by the subset
specified by the SetName argument.
If this argument is empty, the alias from the set
that is specified by the SubsetName argument is
used.

ExpandAbove A Boolean flag to turn on or off the set Expand Optional

Above property.
When this argument is supplied, it overrides the
default Expand Above property that is defined by
the subset specified by the Set argument.
If the argument value is 1, consolidated members
expand upward when drilling.
If the argument value is 0, consolidated members
expand downward when drilling. If this argument is
empty, the Expand Above property from the subset
that is specified by the Subset argument is used.

196 IBM Planning Analytics: Reference

Argument Description Required or Optional

MDXOverride An MDX statement that applies to the subset Optional

specified by the SubsetName or ElementList
argument.
When this argument is supplied, it overrides the
default MDX filter that is defined by the subset that
is specified by the SetName argument.
If this argument is empty or omitted, the members
from the set that is specified by the SetName
argument are used.

IndentRate An integer value that indicates how many Optional

indentations are applied to each level when you
drill down on a consolidated member.
If the argument value is 0, no auto-indentation is
done. IndentRate is relative to the set level of the
set elements.
If this argument is empty or omitted, one
indentation is applied to each level as you drill
down on a consolidated member.

IndentCharacter IndentChar sets the symbol that is used to provide Optional

in-string indentation. The default is the en-space
character (the normal space symbol).

Example

TM1ELLIST("PlanSamp:plan_currency","All currencies")

TM1ELLIST returns an array of elements based on given arguments.

To retrieve all the returned values, create a named range in Excel and enter the TM1ELLIST formula in the
Refers To column.

Select the number of cells (based on the return array size) in Excel, type =[namedrange], and press
Ctrl+Shift+Enter.

Chapter 4. Worksheet Functions 197

 The Excel INDEX function can then be used to extract a single element for the range.

TM1GLOBALSANDBOX
TM1GLOBALSANDBOX returns the current global active sandbox for the user.
Note: This function is valid only in Planning Analytics for Microsoft Excel and in Planning Analytics
websheets. It is not supported in IBM TM1 Perspectives.

Syntax
TM1GLOBALSANDBOX(SERVER)

Argument Description Required/Optional

Server The name of the TM1 server. Required

Example

TM1GLOBALSANDBOX("Planning Sample")

TM1INFO
TM1INFO returns information about the current TM1 or Planning Analytics for Microsoft Excel version or
client.
Note: This function is valid only in Planning Analytics for Microsoft Excel and in Planning Analytics
websheets. It is not supported in IBM TM1 Perspectives.

Syntax
TM1INFO("Property Name")

198 IBM Planning Analytics: Reference

Argument Description Required/
Optional

Property Name The property name can be one of the following: Required

clientversion
Returns the full TM1 client version number. For example,
10.2.10000
clientversionmajor
Returns the TM1 major client version number.
clientversionminor
Returns the TM1 minor client version number.
clientversionpatch
Returns the TM1 fix pack and hotfix number.
client
Returns the name of the client. For example, cor or websheet.
screlease
Note: For screlease, screleasefull, and uagent, the
Planning Analytics for Excel add-in must be initiated to
successfully return a value. If the add-in is not initiated, the
functions returns #VALUE!
Returns the short cadence and short cadence build number of
the current Planning Analytics for Excel add-in.
Planning Analytics for Excel versions use the format
[Link].b.
• mj = major version
• mn = minor version
• sc = short cadence (monthly) version
• b = short cadence build number
screleasefull
Returns the full version of the current Planning Analytics for
Excel add-in. For example, [Link].
uagent
Returns details for the Planning Analytics for Excel user agent.
The information returned may vary depending on whether
or not you are currently connected to the agent. Before
connecting to the agent, you'll see something like this: PAfE/
[Link] (1048576); Excel/16.0.14131.
After connecting to the agent, the function returns more detail:
PAfE/[Link] (1048576); Excel/16.0.14131(x86,
[Link], Sheet1).

Example

TM1INFO("clientversion")

Chapter 4. Worksheet Functions 199

TM1PRIMARYDBNAME
TM1PRIMARYDBNAME returns the primary TM1 server name that the user is authenticated through, even
if the user is implicitly logged into multiple TM1 servers. This function doesn't accept any arguments.
Note: This function is valid only in Planning Analytics for Microsoft Excel and in Planning Analytics
websheets. It is not supported in IBM TM1 Perspectives.
You can reset the returned value of TM1PRIMARYDBNAME by disconnecting from the data source or
closing the Excel session. When you log in again, the values update to the new connection.

Syntax
TM1PRIMARYDBNAME()

TM1RptElIsConsolidated
TM1RptElIsConsolidated returns a Boolean value to indicate whether an element in an Active Form is
consolidated. This worksheet function is used to create Active Forms.
This worksheet function is valid in worksheets only.

Syntax
TM1RptElIsConsolidated(RptRowFormula, Element)

Argument Description

RptRowFormula An absolute reference to a cell containing a

TM1RptRow formula.

Element A relative reference to a cell containing an element

from TM1RptRow formula.

TM1RptElIsExpanded
TM1RptElIsExpanded returns a boolean value to indicate whether an element is expanded in a row subset
within an Active Form. This worksheet function is used to create Active Forms.
This worksheet function is valid in worksheets only.

Syntax
TM1RptElIsExpanded(RptRowFormula, Element)

Argument Description

RptRowFormula An absolute reference to a cell containing a

TM1RptRow formula.

Element A relative reference to a cell containing an element

from TM1RptRow formula.

200 IBM Planning Analytics: Reference

TM1RptElLev
TM1RptElLev returns an integer value for an element level relative to root in the subset. This worksheet
function is used to create Active Forms. This function is distinct from the ElLev worksheet function.
This worksheet function is valid in worksheets only.

Syntax
TM1RptElLev(RptRowFormula, Element)

Argument Description

RptRowFormula An absolute reference to a TM1RptRow formula

cell.

Element A relative reference to a cell containing an element

from TM1RptRow formula.

TM1RptFilter
TM1RptFilter defines the filter applied to an Active Form column dimension. This worksheet function is
used to create Active Forms.
This worksheet function is valid in worksheets only.

Syntax
TM1RptFilter(ReportView,Tuple,FilterFunction,FilterValue,SortOrder)

Argument Description

ReportView A cell reference to a cell that contains a

TM1RptView formula. The filter applies to the view
specified by TM1RptView formula.

Tuple A tuple string specifying the element in the column

dimension to which the filter applies. For example,
[month].[Feb].

FilterFunction One of the following filter function names:

TOPCOUNT
BOTTOMCOUNT
TOPPERCENT
BOTTOMPERCENT
TOPSUM
BOTTOMSUM

FilterValue A filter value.

Chapter 4. Worksheet Functions 201

 Argument Description

SortOrder One of the following two sort orders:

asc
desc

Example

=TM1RptFilter($B$4,"[month].[Jan]","TOPCOUNT",5,"asc")

TM1RptRow
TM1RptRow sets the Active Form control row definition. The control row definition governs the behavior
of all rows in the Active Form. This worksheet function is used to create Active Forms.
This worksheet function is valid in worksheets only.

Syntax
TM1RptRow(ReportView, Dimension, Subset, SubsetElements,
Alias, ExpandAbove,MDXStatement, Indentations, ConsolidationDrilling)

Argument Description

ReportView A reference to a cell that contains a TM1RptView

formula.

Dimension A dimension, specified using the format

tm1_server_name:dimension_name.

Subset A named subset. If this argument is empty, all

elements of the dimension will be used.

SubsetElements A cell range reference that specifies a list of

elements to constitute a subset.
When this argument is supplied, the named subset
specified by the Subset argument is ignored.
If this argument is empty, the elements from the
subset specified by the Subset argument are used.

Alias A string that defines the alias used for the subset.
When this argument is supplied, it overrides
the default alias property defined by the subset
specified by the Subset argument.
If this argument is empty, the alias from the subset
specified by the Subset argument are used.

202 IBM Planning Analytics: Reference

 Argument Description

ExpandAbove A Boolean flag to turn on or off the subset Expand

Above property. When this argument is supplied,
it overrides the default Expand Above property
defined by the subset specified by the Subset
argument.
If the argument value is 1, consolidated elements
expand upward when drilling.
If the argument value is 0, consolidated elements
expand downward when drilling.
If this argument is empty, the Expand Above
property from the subset specified by the Subset
argument is used.

MDXStatement An MDX statement that applies to the subset

specified by the Subset argument.
When this argument is supplied, it overrides the
default MDX filter defined by the subset specified
by the Subset argument.
If this argument is empty or omitted, the elements
from the subset specified by the Subset argument
are used.

Indentations An integer value to indicate how many indentations

are applied to each level when drilling down on a
consolidated element. If the argument value is 0,
no auto-indentation is performed.
This is an optional argument. When the value is
missing, one indentation is applied to each level as
you drill down on a consolidated element.

ConsolidationDrilling A Boolean flag to turn on or off drilling on

consolidated elements.
When this argument value is 1, users can drill down
on consolidated elements in the Active Form.
When this argument value is 0, users can not drill
down on consolidated elements in the Active Form.
This is an optional argument. When the argument is
missing, the default behavior is to allow drilling on
consolidated elements.

Example

=TM1RptRow($B$9,"sdata:region","",'{AR}01'!$B$17:$B$18,"",1,"",5, 0)

TM1RptTitle
TM1RptTitle defines an Active Form title dimension. This worksheet function is used to create Active
Forms.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 203

 Syntax
TM1RptTitle(Dimension,Element)

Argument Description

Dimension A dimension, specified using the format

tm1_name:dimension_name.

Element A cell reference to a cell containing a SUBNM

function which returns an element name.

Example

TM1RptTitle("SData:model",$C$7)

TM1RptView
TM1RptView defines the view displayed in an Active Form. This worksheet function is used to create
Active Forms.
This worksheet function is valid in worksheets only.

Syntax
TM1RptView(ViewID,ZeroSuppression,TM1RptTitle,...)

Argument Description

ViewID A name for the view using the format

tm1_name:cube_name:unique_id.

ZeroSuppression A Boolean flag to turn on or off the zero

suppression property for the view. 1 = on, 0 = off

TM1RptTitle For each title dimension in the Active Form,

include a TM1RptTitle function as an argument to
TM1RptView.

FormatRange The formatting range for the Active Form.

When you create an Active Form, a named range
called TM1RPTFMTRNG is created to include all
formatting range cells. You can use this named
range as an argument.

IDColumn The column containing format IDs in the Active

Form.
When you create an Active Form, a named range
called TM1RPTFMTIDCOL is created to include all
formatting range cells. You can use this named
range as an argument.

204 IBM Planning Analytics: Reference

 Example

=TM1RPTVIEW("SData:SalesCube:6", 0,
TM1RPTTITLE("SData:actvsbud",$C$6),
TM1RPTTITLE("SData:model",$C$7),
TM1RPTTITLE("SData:account1",$C$8),
TM1RPTFMTRNG,
TM1RPTFMTIDCOL)

TM1User
TM1User returns the user name of the current TM1 user.
If the current TM1 user is not connected to a server, or if the specified server is not running, TM1User
returns an empty string.
If TM1User is executed against a server that is configured to use CAM authentication, the function returns
the internal user name/CAMID, not the display name.
This worksheet function is valid in worksheets only.

Syntax
TM1User("ServerName")

Argument Description

ServerName The name of the server to which the TM1 user is

connected.

Example

TM1User("SData")

If a user named BrianT is logged in to the SData server, and that user executes the TM1User function, the
above example returns BrianT.

TM1Val
TM1Val is a hierarchy spreadsheet formula that is available in IBM Planning Analytics TM1 Web and IBM
Planning Analytics for Microsoft Excel.
TM1Val is a hierarchy-aware writeback formula. This formula allows for cell-by-cell control of TM1 or
IBM TM1 Database 12 data by using tuple intersections that take hierarchies into consideration. TM1Val
currently only supports a low-workload count.
Note: TM1Val requires Planning Analytics for Microsoft Excel 2.0.92 and TM1 Web 2.0.92 to work.
Planning Analytics on Cloud customers must request that their TM1 Server be upgraded to [Link] IF1 or
higher for TM1 Web 2.0.92 to be deployed on cloud.

Syntax
=TM1Val("datasource uri”, “server”, “cube", 1, 945730358, "[dim1].[hier1].[elem1]","[dim2].
[hier2].[elem2]","[dim3].[hier3].[elem3]","[dim4].[hier4].[elem4]","[dim5].[hier5].[elem5]")

Chapter 4. Worksheet Functions 205

 Table 4. TM1Val arguments
Argument Purpose Optional or Required
Host In the Host argument, enter the Required
data source URI.
The host argument allows for
simultaneous use of multiple
systems, even when database
names would otherwise collide.

Server In the Server argument, input the Required

Database name

Cube In the Cube argument, input the Required

TM1 cube name

Mode The Mode argument is the Required

operating mode for the function.
The following values can be used
to set the operating mode:
• “Read” or 0 reads value from
the cube cell.
• “Write” or 1 attempts to
write the given writeValue, and
returns the current value of the
cell post-write attempt.
• “Clear” or 2 - clears the value
of the cube cell, and returns the
current value of the cell post-
clear attempt.

WriteValue The WriteValue is only consumed Optional

in mode 1 operation.

M1,...Mn These are the dimension Optional

member names that define
if there are no dimensions, use
the intersection of the cube
the default hierarchy and default
containing the value to be
member for each dimension in
retrieved.
that cube
[dim].[hier].[elem]
There is a limit of 64 dimension
member names that can be
added in TM1Val for Planning
Analytics for Microsoft Excel.

Example
=TM1VAL("[Link]
"Planning Sample",
"plan_BudgetPlan",
1,
945730358,
"[plan_version].[plan_version].[FY 2004 Budget]",
"[plan_business_unit].[plan_business_unit].[Total Business Unit]",
"[plan_department].[plan_department].[Total Organization]",

206 IBM Planning Analytics: Reference

 "[plan_chart_of_accounts].[plan_chart_of_accounts].[Revenue]",
"[plan_exchange_rates].[plan_exchange_rates].[actual]",
"[plan_source].[plan_source].[Goal]",
"[plan_time].[plan_time].[2004]")

Embedding a TM1Val function

Note: This feature is only available for Planning Analytics for Microsoft Excel.
The TM1Val function can be added to your report from Planning Analytics for Microsoft Excel:
1. Connect to a data source in Planning Analytics for Microsoft Excel.
2. Select a cell and enter the TM1Val formula.
Note: For guidance on arguments, type =TM1VAL() in a cell and press Enter. Click Insert function
to see all the arguments that you need to enter for TM1VAL. The following image shows the function
arguments that can be inputted:

TM1Val Errors
The TM1Val formula output generates #NUM if the formula cannot be evaluated due to the following:
• There is an incomplete or non-existent dimension member name.
• A user does not have access to the dimension or hierarchy.
• The ODATA query returns a server error.
The TM1Val formula output generates #VALUE if there are missing or invalid arguments.
The TM1Val formula output generates #N/A if the server disconnects, or if the user is not logged in.
The TM1Val formula does not generate an output if the server name in the TM1Val arguments is spelled
incorrectly or references an invalid server.

VIEW
VIEW creates an optimized view of the cube specified by the cube argument.
A single VIEW function is created when you slice a view from a cube browse.
All DBR and DBRW formulas that refer to the VIEW function can then access this optimized view. In this
way, results are returned much faster.
Multiple VIEW functions can reside in the same spreadsheet if you have blocks of DBR formulas that refer
to different TM1 views or cubes.
This worksheet function is valid in worksheets only.

Chapter 4. Worksheet Functions 207

 Syntax
VIEW(cube, e1,e2[,...en])

Argument Description

cube The name of the cube from which to retrieve data.

e1,...en Either specific elements in the slice to be used as

titles, or the string "!". The string "!" indicates that
the corresponding dimension is a row or column in
the view. These arguments can also be the names
of aliases for dimension elements.

Example

VIEW("93sales",$B$2,$B$3,$B$4,"!","!")

208 IBM Planning Analytics: Reference

Chapter 5. TurboIntegrator Functions
TurboIntegrator lets you manipulate Planning Analytics data and metadata when you define a process.
This is accomplished through the use of functions in the Prolog, Metadata, Data, and Epilog sub-tabs
within the Advanced tab of the TurboIntegrator window. These sub-tabs include generated statements
based on settings and options you select when defining a TurboIntegrator process. Any functions
you create must appear after the generated statements. For details on creating processes with
TurboIntegrator, see the TurboIntegrator documentation.
The TurboIntegrator functions in this section are sorted by category.
String arguments to TurboIntegrator functions must be enclosed in single quotation marks. A semi-colon
(;) must be included to indicate the end of each function in the TurboIntegrator window.
In addition to these TurboIntegrator functions, you can also incorporate all standard Planning Analytics
Rules functions in a process definition, with the exception of the STET function.
Each argument to TurboIntegrator functions is limited to 256 bytes. A TurboIntegrator function can
accept multiple arguments, and each argument is limited to 256 bytes.

TurboIntegrator reserved words

To prevent errors in your TurboIntegrator scripts, you should avoid creating variables with names that
match any of the words listed in the following categories.
There are four categories of reserved words in TurboIntegrator:
• Rules function names - See Chapter 2, “Rules functions,” on page 93 for a complete listing of all rules
function names.
• TurboIntegrator function names - See Chapter 5, “TurboIntegrator Functions,” on page 209 for a
complete listing of all TurboIntegrator function names.
• Implicit local variable names - See “TurboIntegrator Local Variables” on page 411 for a complete listing
of all TurboIntegrator implicit local variables names.
• TurboIntegrator keywords - These keywords are reserved and should not be used as variables in your
scripts:
– break
– else
– elseif
– end
– endif
– if
– while
• Process presentation keywords - These keywords are used to manage the presentation of scripts in the
process editor.
– #Section

ASCII and Text TurboIntegrator Functions

These functions pertain to ASCII and Text.

© Copyright IBM Corp. 2007, 2025 209

ASCIIDelete
ASCIIDelete deletes an ASCII file.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ASCIIDelete(FileName);

Argument Description

FileName The name of the ASCII file you want to delete. If a

full path is not specified, TM1 searches for the file
in the server data directory.

Example
This example deletes the ASCII file named [Link] from the C:\exported_data directory.

ASCIIDelete('C:\exported_data\[Link]');

ASCIIOutput
ASCIIOutput writes a comma-delimited record to an ASCII file.
This function is valid in TM1 TurboIntegrator processes only.
The ASCII file is opened when the first record is written, and is closed when the TurboIntegrator
procedure (Prolog, Metadata, Data, or Epilog) containing the ASCIIIOutput function finishes processing.
Each output record generated by ASCIIOutput is limited to 64 kilobytes. If an output record exceeds 64
kilobytes, the record is truncated and a warning is logged in the [Link] file.
When ASCIIOutput encounters a String argument that pushes the output record beyond the 64 kilobyte
limit, it ignores that argument and any further arguments. For example, if there are 10 String arguments
and output for the first seven arguments total 65,500 bytes (just under the 64 KB limit) while the output
for the eighth argument is 50 bytes, only the output for the first seven arguments will be written to the
record, as the eighth argument causes the output to exceed the 64 kilobyte limit. If there are ten String
arguments and the first argument is over 64 kilobytes, no output is written to the record.
If you use the ASCIIOutput function to write to the same file in multiple procedures (tabs) of a
TurboIntegrator process, the file will be overwritten each time it is opened for a new procedure.
The ASCIIOutput function generates a minor error if an error occurs while writing the ASCII file. In
addition, the function returns a value upon execution: 1 if the function successfully writes the ASCII file
and 0 on failure.
Note: The error will be generated and the value returned only when ASCIIOutput is writing to a disk
other than the one that the server is running on. For example, if the server is running on the C: drive and
ASCIIOutput is writing to the F: drive, and the F: drive runs out of space, the error will be trapped and the
server remains alive. If the server is running on the C: drive while ASCIIOutput is also writing to the C:
drive, and that drive runs out of space, the server will terminate (as expected).
Note: The ability to execute the ASCIIOutput function when the data source is a cube view is determined
by the Allow Export as Text capability assignment, which is set per user group. If a user is a member of
a group which is denied the ability to export data as text, any attempt by the user to execute ASCIIOutput
results in the process exiting with a permission error. The process message log indicates "Execution
was aborted. No security access for ASCIIOutput."
For details on how the Allow Export as Text capability is set, see "Capability Assignments" in TM1
Operations.

210 IBM Planning Analytics: Reference

 Note: The ASCIIOutput function places the 0x1A hexadecimal character at the end of all generated files.
However, TM1 Web cannot open a Websheet that contains the 0x1A hexadecimal character.
If you use ASCIIOutput to export TM1 data to an ASCII file and then attempt to open the file in a TM1
Websheet, you will encounter the following error.
Error occurred while converting the MS Excel workbook into XML format, hexadecimal value 0x1A is an
invalid character.
If you remove the 0x1A hexadecimal character from the Websheet, the file will open in TM1 Web.

Syntax
ASCIIOutput(FileName, String1, String2, ...Stringn);

Argument Description

FileName A full path to the ASCII file to which you want to

write the record. Path must include a file extension.

String1...Stringn A string that corresponds to each field you want

to create in the ASCII file. This argument can be a
string or a TurboIntegrator variable for a string.

Example
This example writes a record to the [Link] ASCII file. Each field in the record corresponds to a
variable assigned by TurboIntegrator to a column in your data source.

ASCIIOutput('[Link]', V1, V2, V3, V4, V5 );

ASCIIOutputOpen
ASCIIOutputOpen appends or overwrites content in a specified existing file.
This function is valid in TurboIntegrator processes only.

Syntax
ASCIIOutputOpen(FileName, OpeningMode);

Argument Description

FileName A full path or URL to the ASCII file to which you

want to write content. The file name must include a
file extension., either .txt or .csv.

Chapter 5. TurboIntegrator Functions 211

 Argument Description

OpeningMode A bit field flag used to configure the file opening

mode. The first bit (0x1 or 0b00000001), if set,
indicates the file is opened in append mode. If not
set, the existing file is opened in overwrite mode.
The second bit (0x2 or 0b00000010), if set, opens
the file in FILE_SHARE_READ mode on Windows.
The second bit has no effect on Linux.
FILE_OPEN_APPEND( ) and FILE_OPEN_SHARED( )
are two helper functions that can be used with
ASCIIOutputOpen. You can use them in place of
the bit field flag.
FILE_OPEN_APPEND( ) returns 0x1. Specify this
function as the OpeningMode value to open the file
in append mode. Omit the function to open the file
in overwrite mode.
FILE_OPEN_SHARED( ) returns 0x2. Use this in
conjunction with FILE_OPEN_APPEND( ) to open
the file in FILE_SHARE_READ mode on Windows.

Examples
Opens the [Link] file in overwrite mode, without shared read access:

ASCIIOutputOpen('[Link]', 0);

Opens the [Link] file in append mode, without shared read access:

ASCIIOutputOpen('[Link]', 1);

Opens the [Link] file in overwrite mode, shared read access enabled:

ASCIIOutputOpen('[Link]', 2);

Opens the [Link] file, in append mode, shared read access enabled:

ASCIIOutputOpen('[Link]', 3);

Opens the [Link] file in append mode, without shared read access:

ASCIIOutputOpen('[Link]', FILE_OPEN_APPEND());

Opens the [Link] file in append mode, shared read access enabled:

ASCIIOutputOpen('[Link]', FILE_OPEN_APPEND()+FILE_OPEN_SHARED());

NumberToString
NumberToString converts a number to a string, using the decimal separator for the current user locale.
This function is valid in TM1 TurboIntegrator processes only.
In Microsoft Windows, the decimal separator is a Regional Options setting.
The output of this function is similar to the 'general' number format; it does not use thousands separators
and uses the minus sign (-) to denote negative numbers.

212 IBM Planning Analytics: Reference

 Syntax
NumberToString(Value);

Argument Description

Value The real value that you want to convert to a string.

Example

nRET = NumberToString(1234.5);

NumberToStringEx
NumberToStringEx converts a number to a string, using the passed string format, decimal separator, and
thousands separator.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
NumberToStringEx(Value, NumericFormat, DecimalSep, ThousandsSep);

Argument Description

Value The real value that you want to convert to a string.

FormatString A TM1 numeric format string that defines the

format for the function output. Numeric formats
are described inIBM Cognos TM1 Perspectives, TM1
Architect, and TM1 Web documentation.

DecimalSep The decimal separator to be used in the output

string.

ThousandsSep The thousands separator to be used in the output

string.

Example

sRet=NUMBERTOSTRINGEX(7895.23,'#,0.#########', ',','.');

ASCIIOUTPUT('number_to_string.txt',sRet);

Will return in ascii file;

7.895,23

SetInputCharacterSet
SetInputCharacterSet function lets you specify the character set used in a TurboIntegrator data source.
This function is valid in TM1 TurboIntegrator processes only.
When a TurboIntegrator process reads an external file as input, it needs to know the character set
in which that external file was written. If the file contains a valid byte-order-mark, TM1 functions will
correctly convert the file to UTF-8 if required.

Chapter 5. TurboIntegrator Functions 213

 For formats lacking a valid byte-order-mark, the characters must be converted from some other encoding
to UTF-8. If the proper converters are present on the machine hosting the server, the input file will be
converted to the Unicode character set required by TM1.

Syntax
SetInputCharacterSet (CharacterSet);

Argument Description

CharacterSet The character encoding in the input file to be used

by the TurboIntegrator process.
If the CharacterSet argument is not a known
character type, the type defaults to the system
locale.

These are the valid values for CharacterSet.

Character Encoding System Locale

TM1CS_ISO_8859_1 ISO-8859-1 Latin-1, Western Europe

TM1CS_ISO_8859_2 ISO-8859-2 Latin-2, Central Europe

TM1CS_ISO_8859_3 ISO-8859-3 Latin-3, South Europe

TM1CS_ISO_8859_4 ISO-8859-4 Latin-4, North Europe

TM1CS_ISO_8859_5 ISO-8859-5 Latin/Cyrillic

TM1CS_ISO_8859_6 ISO-8859-6 Latin/Arabic

TM1CS_ISO_8859_7 ISO-8859-7 Latin/Greek

TM1CS_ISO_8859_8 ISO-8859-8 Latin/Hebrew

TM1CS_ISO_8859_9 ISO-8859-9 Latin-5, Turkish

TM1CS_ISO_8859_10 ISO-8859-10 Latin-6, Nordic,

TM1CS_ISO_8859_11 ISO-8859-11 Latin/Thai

TM1CS_ISO_8859_13 ISO-8859-13 Latin-7, Baltic Rim

TM1CS_ISO_8859_14 ISO-8859-14 Latin-8, Celtic

TM1CS_ISO_8859_15 ISO-8859-15 Latin-9, replaces ISO-8859-1

TM1CS_ISO_8859_16 ISO-8859-16 Latin-10, South-Eastern Europe

TM1CS_WCP1250 Microsoft Windows Central Europe

TM1CS_WCP1251 Windows Cyrillic

214 IBM Planning Analytics: Reference

Character Encoding System Locale

TM1CS_WCP1252 Windows Latin-1 multilingual

TM1CS_WCP1253 Windows Greek

TM1CS_WCP1254 Windows Turkish

TM1CS_WCP1255 Windows Hebrew

TM1CS_WCP1256 Windows Arabic

TM1CS_WCP1257 Windows Baltic

TM1CS_WCP1258 Windows Vietnam

TM1CS_WCP874 Windows Thai

TM1CS_WCP932 Windows Japanese

TM1CS_WCP936 Windows Simplified Chinese

TM1CS_WCP949 Windows Korean

TM1CS_WCP950 Windows Traditional Chinese

TM1CS_KOI8R Russian and Cyrillic (KOI8-R)

TM1CS_GB18030 PRC version UNICODE

TM1CS_BIG5 Traditional Chinese

TM1CS_SHIFTJIS JIS 0201 + JIS 0208, slightly different from CP932

TM1CS_SJIS0213 JIS 0213-2004, non-BMP required.

TM1CS_EUC_JP EUC Japanese

TM1CS_EUC_CN EUC Simplified Chinese

TM1CS_EUC_KR EUC Korean

TM1CS_UTF8 UTF-8

TM1CS_UTF16 UTF-16 Little Endian

TM1CS_UTF16ESC UNICODE notation

TM1CS_UTF32 UTF-32 Little Endian

TM1CS_OS_DEFAULT operating system default

TM1CS_LOCALPATH local encoding but UNICODE notation on non-

native.

Chapter 5. TurboIntegrator Functions 215

 Example

SetInputCharacterSet ('TM1CS_ISO_8859_11');

This example specifies that the input character set for the TurboIntegrator data source is ISO-8859-11
Latin/Thai.

SetOutputCharacterSet
SetOutputCharacterSet lets you specify the character set to be used when writing to a text file using
TextOutput in a TurboIntegrator process.
This function is valid in TurboIntegrator processes only.
SetOutputCharacterSet should precede the TextOutput function in the process procedure (Prolog,
Metadata, Data. Epilog) where the TextOutput function appears. For example, if you want to write to a
text file using TextOutput in the Data procedure, you should first use SetOutputCharacterSet to specify
the character set in the Data procedure.

Syntax
SetOutputCharacterSet( FileName, CharacterSet );

Argument Description

FileName A full path to the text file for which you want to
specify a character set. The path must include a file
extension.
This argument should be identical to the FileName
argument for the TextOutput function.

CharacterSet The character encoding to use when writing to the

output file.
For more information on the valid values for
CharacterSet, see “SetInputCharacterSet” on page
213.

SetOutputEscapeDoubleQuote
SetOutputEscapeDoubleQuote allows you to escape double quotes that appear in element names or data
values when exporting a cube view to a .csv file.
This function is valid in TM1 TurboIntegrator processes only.
When SetOutputEscapeDoubleQuote is included in your TurboIntegrator script and set to 1, the exported
file retains the double quote positions as they appear in your source cube view by escaping each double
quote within another pair of double quotes. For example, if an element in your source view is named
"Region", the element is exported as """Region""" in the .csv output file.
When SetOutputEscapeDoubleQuote is not included in your TurboIntegrator script or is set to 0, the
exported file does not escape any double quotes that appear in your source cube.
SetOutputEscapeDoubleQuote is used in conjunction with the ASCIIOutput function, which is the function
that actually writes the output file. SetOutputEscapeDoubleQuote should precede ASCIIOutput in your
TurboIntegrator script, and both functions should use the same FileName parameter value.

216 IBM Planning Analytics: Reference

 Syntax
SetOutputEscapeDoubleQuote(FileName, Num);

Argument Description

FileName A full path to the file to which you want to write the
cube view. Path must include a file extension.

Num A flag that determines if double quotes are

escaped in the output file.
1 indicates that double quotes will be escaped in
the output file.
0 indicates that double quotes will not be escaped
in the output file.

Example

SetOutputEscapeDoubleQuote('C:\temp\[Link]', 1);

This example escapes any double quotes encountered in the source cube view when writing output to the
C:\temp\[Link] file.

StringToNumber
StringToNumber converts a string to a number, using the decimal separator for the current user locale. If
the input string is an invalid number string, the value returned will be an invalid floating point value. In
Microsoft Windows, the decimal separator is a Regional Options setting.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
StringToNumber(String);

Argument Description

String The string you want to convert to a number.

Example

nRET = StringToNumber('123.45');

StringToNumberEx
StringToNumberEx converts a string to a number, using the passed decimal separator and thousands
separator. If the input string is an invalid number string, the value returned will be an invalid floating point
value.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
StringToNumberEx(String, DecimalSep, ThousandsSep);

Chapter 5. TurboIntegrator Functions 217

 Argument Description

String The string that you want to convert to a number.

DecimalSep The decimal separator to be used in the output

number.

ThousandsSep The thousands separator to be used in the output

number.

Example

nRET = StringToNumberEx('12453.45', ' . ', ' , ');

TextOutput
TextOutput writes a comma-delimited record to a text file.
This function is valid in TM1 TurboIntegrator processes only.
By default TextOutput writes characters in the locale character set of the server machine. To create a file
in a different character set, call the function SetOutputCharacterSet before calling TextOutput.
The text file is opened when the first record is written, and is closed when the TurboIntegrator procedure
(Prolog, Metadata, Data, or Epilog) containing the TextOutput function finishes processing.
If you use the TextOutput function to write to the same file in multiple procedures (tabs) of a
TurboIntegrator process, the file will be overwritten each time it is opened for a new procedure.
Each output record generated by TextOutput is limited to 8000 bytes. If an output record exceeds 8000
bytes, the record is truncated and a warning is logged in the [Link] file.
When TextOutput encounters a String argument that pushes the output record beyond the 8000 byte
limit, it ignores that argument and any further arguments. For example, if there are 10 String arguments
and output for the first seven arguments total 7950 bytes while the output for the eighth argument is 51
bytes, only the output for the first seven arguments will be written to the record. If there are ten String
arguments and the first argument is over 8000 bytes, no output will be written to the record.
The TextOutput function generates a minor error if an error occurs while writing the text file. In addition,
the function returns a value upon execution: 1 if the function successfully writes the text file and 0 on
failure.
The error will be generated and the value returned only when TextOutput is writing to a disk other than
the one that the server is running on. For example, if the server is running on the C: drive and TextOutput
is writing to the F: drive, and the F: drive runs out of space, the error will be trapped and the server
remains alive. If the server is running on the C: drive while TextOutput is also writing to the C: drive, and
that drive runs out of space, the server will terminate (as expected).
Note: The ability to execute the TextOutput function when the data source is a cube view is determined
by the Allow Export as Text capability assignment, which is set per user group. If a user is a member of
a group which is denied the ability to export data as text, any attempt by the user to execute TextOutput
results in the process exiting with a permission error. The process message log indicates "Execution
was aborted. No security access for TextOutput."
For details on how the Allow Export as Text capability is set, see "Capability Assignments" in the IBM
Cognos TM1 Operations documentation.

Syntax
TextOutput(FileName, String1, String2, ...Stringn);

218 IBM Planning Analytics: Reference

 Argument Description

FileName A full path to the text file to which you want to

write the record. Path must include a file extension.

String1...Stringn A string that corresponds to each field you want to

create in the text file. This argument can be a string
or a TurboIntegrator variable for a string.

Example

TextOutput('[Link]', V1, V2, V3, V4, V5 );

This example writes a record to the [Link] file. Each field in the record corresponds to a variable
assigned by TurboIntegrator to a column in your data source.

Attribute Manipulation TurboIntegrator Functions

These functions facilitate the manipulation of attributes.

ATTRNL
ATTRNL returns a numeric attribute for a specified element of a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ATTRNL(DimName, ElName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

ElName An element of the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

Chapter 5. TurboIntegrator Functions 219

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
locale if available. If the attribute value for fr-CA
is not available, the function attempts to return
the attribute value for the parent fr locale. If the
attribute value for fr is not available, the base
attribute value is returned

Example
In this example, the function returns the numeric value of the Engine Size attribute of the L Series 1.8L
Sedan element in the Model dimension for the French locale.

ATTRNL('Model', 'L Series 1.8L Sedan', 'Engine Size', 'fr');

ATTRSL
AttrSL returns a string attribute for a specified element of a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AttrSL(DimName, ElName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

ElName An element of the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

220 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
locale if available. If the attribute value for fr-CA
is not available, the function attempts to return
the attribute value for the parent fr locale. If the
attribute value for fr is not available, the base
attribute value is returned

Example
In this example, the function returns the string value of the Currency attribute of the 10100 element in
the Plan_Business_Unit dimension for the French locale.

AttrSL('Plan_Business_Unit', '10100', 'Currency', 'fr');

AttrDelete
AttrDelete deletes an element attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AttrDelete(DimName, AttrName);

Argument Description

DimName The dimension for which you want to delete an

element attribute.

AttrName The name of the attribute you want to delete.

Example
This example deletes the InteriorColor element attribute for the Model dimension.

AttrDelete('Model', 'InteriorColor');

Chapter 5. TurboIntegrator Functions 221

AttrInsert
AttrInsert creates a new element attribute for a dimension. The function can create a string, numeric, or
alias attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AttrInsert(DimName, PrevAttr, AttrName, Type);

Argument Description

DimName The dimension for which you want to create an

element attribute.

PrevAttr The attribute that precedes the attribute you are

creating.

AttrName The name you want to assign to the new attribute.

Type The type of attribute. There are three possible

values for the Type argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the InteriorColor string attribute for the Model dimension. This attribute is inserted
after the Transmission attribute.

AttrInsert('Model', 'Transmission', 'InteriorColor','S');

AttrPutN
AttrPutN assigns a value to a numeric element attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AttrPutN( Value, DimName, ElName, AttrName, [LangLocaleCode] );

Argument Description

Value The numeric value you want to assign to an

element attribute.

DimName The parent dimension of the element for which you

want to assign an attribute value.

ElName The element for which you want to assign an

attribute value.

222 IBM Planning Analytics: Reference

 Argument Description

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 2257993 to the ProdCode attribute of the S Series 1.8L Sedan in the
Model dimension.

AttrPutN(2257993, 'Model', ' S Series 1.8L Sedan ','ProdCode');

AttrPutS
AttrPutS assigns a value to a string element attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AttrPutS(Value, DimName, ElName, AttrName, [LangLocaleCode] );

Argument Description

Value The value you want to assign to an element

attribute.

DimName The parent dimension of the element for which you

want to assign an attribute value.

ElName The element for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the Value applies.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Chapter 5. TurboIntegrator Functions 223

 Example
This example assigns the string Beige to the InteriorColor attribute of the S Series 1.8L Sedan in the
Model dimension.

AttrPutS('Beige', 'Model', 'S Series 1.8L Sedan', 'InteriorColor');

ChoreAttrDelete
ChoreAttrDelete deletes a chore attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrDelete(AttrName);

Argument Description

AttrName The name of the chore attribute you want to delete.

Example
This example deletes the Description attribute for chores on your TM1 server.

ChoreAttrDelete('Description');

ChoreAttrInsert
ChoreAttrInsert creates a new attribute for chores on your TM1 server. The function can create a string,
numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing chore attribute, you must first delete the existing attribute using the
function ChoreAttrDelete. You can then use ChoreAttrInsert to recreate the attribute with your desired
changes. If you attempt to update an existing attribute without first deleting it, the insert fails without a
warning or error. The existing attribute remains unchanged; it is neither updated nor overwritten.

Syntax
ChoreAttrInsert( PrevAttrName, NewAttrName, AttrType);

Argument Description

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
chores, leave this argument empty.

NewAttrName The name you want to assign to the new chore

attribute.

224 IBM Planning Analytics: Reference

 Argument Description

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for chores. This attribute is inserted after the Owner
attribute.

ChoreAttrInsert('Owner', 'Description', 'S');

ChoreAttrN
ChoreAttrN returns a numeric attribute for a specified chore.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrN(ChoreName, AttrName);

Argument Description

ChoreName A valid chore name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
chore.

Example
In this example, the function returns the numeric value of the Division_Code attribute of the Import chore.

ChoreAttrN('Import', 'Division_Code');

ChoreAttrNL
ChoreAttrNL returns an attribute's numeric value for a specified chore with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrNL(ChoreName, AttrName, [LangLocaleCode]);

Argument Description

ChoreName A valid chore name.

Chapter 5. TurboIntegrator Functions 225

 Argument Description

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
chore.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Division_Code attribute of the Import chore
for the French locale.

ChoreAttrNL('Import', 'Division_Code', 'fr');

ChoreAttrPutN
ChoreAttrPutN assigns a value to a numeric chore attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrPutN(NumericValue, ChoreName, AttrName, [LangLocaleCode] );

Argument Description

NumericValue The value you want to assign to a chore attribute.

ChoreName The chore for which you want to assign an attribute

value.

AttrName The attribute whose value you want to assign.

226 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 7161994 to the Division_Code attribute of the Import chore for the French
language locale code.

ChoreAttrPutN(7161994, 'Import', 'Division_Code','fr');

ChoreAttrPutS
ChoreAttrPutS assigns a value to a string chore attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrPutS(String, ChoreName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a chore attribute.

ChoreName The chore for which you want to assign an attribute

value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Ricci to the Owner attribute of the Import chore, for the French
language locale code.

ChoreAttrPutS('Ricci', 'Import', 'Owner', 'fr');

Chapter 5. TurboIntegrator Functions 227

ChoreAttrS
ChoreAttrS returns a string attribute for a specified chore.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrS(ChoreName, AttrName);

Argument Description

ChoreName A valid chore name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
chore.

Example
In this example, the function returns the string value of the Owner attribute of the
Exchange_Rate_Updates chore.

ChoreAttrS('Exchange_Rate_Updates', 'Owner');

ChoreAttrSL
ChoreAttrSL returns a string attribute value for a specified chore with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreAttrSL(ChoreName, AttrName, [LangLocaleCode]);

Argument Description

ChoreName A valid chore name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
chore.

228 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Owner attribute of the Depreciate_Inventory
chore for the French locale.

ChoreAttrSL('Depreciate_Inventory', 'Owner', 'fr');

CubeAttrDelete
CubeAttrDelete deletes a cube attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeAttrDelete(AttrName);

Argument Description

AttrName The name of the cube attribute you want to delete.

Example
This example deletes the Description attribute for cubes on your TM1 server.

CubeAttrDelete('Description');

Chapter 5. TurboIntegrator Functions 229

CubeAttrInsert
CubeAttrInsert creates a new attribute for cubes on your TM1 server. The function can create a string,
numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing cube attribute, you must first delete the existing attribute using the
function CubeAttrDelete. You can then use CubeAttrInsert to recreate the attribute with your desired
changes. If you attempt to update an existing attribute without first deleting it, the insert fails without a
warning or error. The existing attribute remains unchanged; it is neither updated nor overwritten.

Syntax
CubeAttrInsert( PrevAttrName, NewAttrName, AttrType);

Argument Description

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
cubes, leave this argument empty.

NewAttrName The name you want to assign to the new cube

attribute.

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for cubes. This attribute is inserted after the Owner
attribute.

CubeAttrInsert('Owner', 'Description', 'S');

CubeAttrPutN
CubeAttrPutN assigns a value to a numeric cube attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeAttrPutN(NumericValue, CubeName, AttrName, [LangLocaleCode] );

Argument Description

NumericValue The value you want to assign to a cube attribute.

CubeName The cube for which you want to assign an attribute

value.

230 IBM Planning Analytics: Reference

 Argument Description

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 07161994 to the AccountingCode attribute of the Sales cube for the
French language locale code.

CubeAttrPutN(07161994, 'Sales', 'AccountingCode','fr');

CubeAttrPutS
CubeAttrPutS assigns a value to a string cube attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeAttrPutS(String, CubeName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a cube attribute.

CubeName The cube for which you want to assign an attribute

value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Prototype to the Description attribute of the Sales cube for the
French language locale code.

CubeAttrPutS('Prototype', 'Sales', 'Description','fr');

Chapter 5. TurboIntegrator Functions 231

CubeATTRNL
CubeATTRNL returns a numeric attribute value for a specified cube with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes.

Syntax
CubeATTRNL(CubeName, AttrName, [LangLocaleCode]);

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.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Product
cube for the French locale.

CubeATTRNL('Product', 'Accounting_Code', 'fr');

CubeATTRSL
CubeATTRSL returns a string attribute value for a specified cube with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes.

232 IBM Planning Analytics: Reference

 Syntax
CubeATTRSL(CubeName, AttrName, [LangLocaleCode]);

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.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Owner attribute of the Product cube for the
French locale.

CubeATTRSL('Product', 'Owner', 'fr');

DimensionAttrDelete
DimensionAttrDelete deletes a dimension attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionAttrDelete(AttrName);

Chapter 5. TurboIntegrator Functions 233

 Argument Description

AttrName The name of the dimension attribute you want to

delete.

Example
This example deletes the Description attribute for dimensions on your TM1 server.

DimensionAttrDelete('Description');

DimensionAttrInsert
DimensionAttrInsert creates a new attribute for dimensions on your TM1 server. The function can create a
string, numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing dimension attribute, you must first delete the existing attribute using
the function DimensionAttrDelete. You can then use DimensionAttrInsert to recreate the attribute with
your desired changes. If you attempt to update an existing attribute without first deleting it, the insert
fails without a warning or error. The existing attribute remains unchanged; it is neither updated nor
overwritten.

Syntax
DimensionAttrInsert( PrevAttrName, NewAttrName, AttrType);

Argument Description

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
dimensions, leave this argument empty.

NewAttrName The name you want to assign to the new dimension

attribute.

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for dimensions. Because there is no PrevAttrName
parameter, this attribute is inserted as the first attribute for dimensions on your TM1 server.

DimensionAttrInsert('', 'Description', 'S');

DimensionAttrPutN
DimensionAttrPutN assigns a value to a numeric dimension attribute.
This function is valid in TM1 TurboIntegrator processes only.

234 IBM Planning Analytics: Reference

 Syntax
DimensionAttrPutN(NumericValue, DimensionName, AttrName, [LocalLangCode] );

Argument Description

NumericValue The value you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 07161994 to the AccountingCode attribute of the Models dimension for
the French language locale code.

DimensionAttrPutN(07161994, 'Models', 'AccountingCode','fr');

DimensionAttrPutS
DimensionAttrPutS assigns a value to a string dimension attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionAttrPutS(String, DimensionName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

Chapter 5. TurboIntegrator Functions 235

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Prototype to the Description attribute of the Model dimension for
the French language locale code.

DimensionAttrPutS('Prototype', 'Model', 'Description','fr');

DimensionATTRNL
DimensionATTRNL returns a numeric attribute value for a specified dimension with respect to a given
locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionATTRNL(DimName, AttrName, [LangLocaleCode]);

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.

236 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the
Plan_Business_Unit dimension for the French locale.

DimensionATTRNL('Plan_Business_Unit', 'Accounting_Code', 'fr');

DimensionATTRSL
DimensionATTRSL returns a string attribute value for a specified dimension with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionATTRSL(DimName, AttrName, [LangLocaleCode]);

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.

Chapter 5. TurboIntegrator Functions 237

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Manager attribute of the Plan_Business_Unit
dimension for the French locale.

DimensionATTRSL('Plan_Business_Unit', 'Manager', 'fr');

ElementATTRNL
ElementATTRNL returns a numeric attribute for a specified element of a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementATTRNL(DimName, HierName, ElName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

HierName The name of the hierarchy within the dimension.

ElName An element of the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

238 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
locale if available. If the attribute value for fr-CA
is not available, the function attempts to return
the attribute value for the parent fr locale. If the
attribute value for fr is not available, the base
attribute value is returned

Example
In this example, the function returns the numeric value of the Engine Size attribute of the L Series 1.8L
Sedan element in the Model dimension for the French locale. This example applies to the 2015 hierarchy.

ATTRNL('Model', '2015', 'L Series 1.8L Sedan', 'Engine Size', 'fr');

ElementATTRSL
ElementATTRSL returns a string attribute for a specified element of a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementATTRSL(DimName, HierName, ElName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

HierName The name of the hierarchy within the dimension.

ElName An element of the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
element.

Chapter 5. TurboIntegrator Functions 239

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
locale if available. If the attribute value for fr-CA
is not available, the function attempts to return
the attribute value for the parent fr locale. If the
attribute value for fr is not available, the base
attribute value is returned

Example
In this example, the function returns the string value of the Currency attribute of the 10100 element in
the Plan_Business_Unit dimension for the French locale.

ElementATTRSL('Plan_Business_Unit', '10100', 'Currency', 'fr');

ElementAttrPutN
ElementAttrPutN assigns a value to a numeric element attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementAttrPutN( Value, DimName, HierName, ElName, AttrName, [LangLocaleCode] );

Argument Description

Value The numeric value you want to assign to an

element attribute.

DimName The parent dimension of the element for which you

want to assign an attribute value.

HierName The name of the hierarchy within the dimension.

ElName The element for which you want to assign an

attribute value.

240 IBM Planning Analytics: Reference

 Argument Description

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 2257993 to the ProdCode attribute of the S Series 1.8L Sedan in the
Automobile hierarchy of the Model dimension.

ElementAttrPutN(2257993, 'Model', 'Automobile', ' S Series 1.8L Sedan ','ProdCode');

ElementAttrPutS
ElementAttrPutS assigns a value to a string element attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementAttrPutS(Value, DimName, HierName, ElName, AttrName, [LangLocaleCode] );

Argument Description

Value The value you want to assign to an element

attribute.

DimName The parent dimension of the element for which you

want to assign an attribute value.

HierName The name of the hierarchy within the dimension.

ElName The element for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the Value applies.
Valid LangLocaleCode values correspond to the
international language codes listed in the Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Chapter 5. TurboIntegrator Functions 241

 Example
This example assigns the string Beige to the InteriorColor attribute of the S Series 1.8L Sedan in the
Automobile hierarchy of the Model dimension.

ElementAttrPutS('Beige', 'Model', 'Automobile', 'S Series 1.8L Sedan', 'InteriorColor');

ElementAttrInsert
ElementAttrInsert creates a new element attribute for a dimension. The function can create a string,
numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementAttrInsert(DimName, HierName, PrevAttr, AttrName, Type);

Argument Description

DimName The dimension for which you want to create an

element attribute.

HierName The name of the hierarchy within the dimension.

PrevAttr The attribute that precedes the attribute you are

creating.

AttrName The name you want to assign to the new attribute.

Type The type of attribute. There are three possible

values for the Type argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the InteriorColor string attribute in the Automobile hierarchy in the Model
dimension. This attribute is inserted after the Transmission attribute.

ElementAttrInsert('Model', 'Automobile', 'Transmission', 'InteriorColor','S');

ElementAttrDelete
ElementAttrDelete deletes an element attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementAttrDelete(DimName, HierName, AttrName);

242 IBM Planning Analytics: Reference

 Argument Description

DimName The dimension for which you want to delete an

element attribute.

HierName The name of the hierarchy within the dimension.

AttrName The name of the attribute you want to delete.

Example
This example deletes the InteriorColor element attribute from the Autombile hierarchy in the Model
dimension.

ElementAttrDelete('Model', 'Automobile', 'InteriorColor');

HierarchyAttrPutN
HierarchyAttrPutN assigns a value to a numeric attribute in a specified hierarchy within a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyAttrPutN(NumericValue, DimensionName, HierName, AttrName, [LocalLangCode] );

Argument Description

NumericValue The value you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

HierName The name of the hierarchy within the dimension.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 07161994 to the AccountingCode attribute of the Models dimension
for the French language locale code. This change is applied to the Receivables hierarchy in the Models
dimension.

HierarchyAttrPutN(07161994, 'Models', 'Receivables', 'AccountingCode','fr');

Chapter 5. TurboIntegrator Functions 243

HierarchyAttrPutS
HierarchyAttrPutS assigns a value to a string attribute in a specified hierarchy within a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyAttrPutS(String, DimensionName, HierName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

HierName The name of the hierarchy within the dimension.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Prototype to the Description attribute of the Model dimension
for the French language locale code. This change is applied to the Receivables hierarchy in the Model
dimension.

HierarchyAttrPutS('Prototype', 'Model', 'Receivables', 'Description','fr');

HierarchyATTRN
HierarchyATTRN returns a numeric attribute for a specified hierarchy within a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyATTRN(DimName, HierName, AttrName);

Argument Description

DimName A valid dimension name.

HierName The name of the hierarchy within the dimension.

244 IBM Planning Analytics: Reference

 Argument Description

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the
Plan_Business_Unit dimension. This example applies to the Equipment hierarchy.

HierarchyATTRN('Plan_Business_Unit', 'Equipment', 'Accounting_Code');

HierarchyATTRS
HierarchyATTRS returns a string attribute for a specified hierarchy within a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyATTRS(DimName, AttrName);

Argument Description

DimName A valid dimension name.

HierName The name of the hierarchy within the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Example
In this example, the function returns the string value of the Manager attribute of the Plan_Business_Unit
dimension. This example applies to the Equipment hierarchy.

HierarchyATTRS('Plan_Business_Unit', 'Equipment', 'Manager');

HierarchyATTRNL
HierarchyATTRNL returns a numeric attribute value for a specified hierarchy within a dimension with
respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyATTRNL(DimName, HierName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

Chapter 5. TurboIntegrator Functions 245

 Argument Description

HierName The name of the hierarchy within the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the
Plan_Business_Unit dimension for the French locale. This function applies to the Equipment hierarchy.

HierarchyATTRNL('Plan_Business_Unit', 'Equipment', 'Accounting_Code', 'fr');

HierarchyATTRSL
HierarchyATTRSL returns a string attribute value for a specified hierarchy within a dimension with respect
to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyATTRSL(DimName, HierName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

246 IBM Planning Analytics: Reference

 Argument Description

HierName The name of the hierarchy within the dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Manager attribute of the Plan_Business_Unit
dimension for the French locale. This function applies to the Equipment hierarchy.

HierarchyATTRSL('Plan_Business_Unit', 'Equipment', 'Manager', 'fr');

HierarchySubsetATTRS
HierarchySubsetATTRS returns a string attribute for a specified subset associated with a hierarchy in a
dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetATTRS(DimName, HierName, SubName, AttrName);

Argument Description

DimName A valid dimension name.

Chapter 5. TurboIntegrator Functions 247

 Argument Description

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Example
In this example, the function returns the string value of the Manager attribute of the Sales subset from
Europe hierarchy in the Plan_Business_Unit dimension.

HierarchySubsetATTRS('Plan_Business_Unit', 'Europe', 'Sales', 'Manager');

HierarchySubsetATTRN
HierarchySubsetATTRN returns a numeric attribute for a specified subset associated with a hierarchy in a
dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetATTRN(DimName, HierName, SubName, AttrName);

Argument Description

DimName A valid dimension name.

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Sales
subset from the Europe hierarchy in the Plan_Business_Unit dimension.

HierarchySubsetATTRN('Plan_Business_Unit', 'Europe', 'Sales', 'Accounting_Code');

HierarchySubsetATTRSL
HierarchySubsetATTRSL returns an attribute's string value for a specified subset (and locale) associated
with a hierarchy in a dimension.
This function is valid in TM1 TurboIntegrator processes only.

248 IBM Planning Analytics: Reference

 Syntax
HierarchySubsetATTRSL(DimName, HierName, SubName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Manager attribute of the Sales subset (from
the Europe hierarchy) for the French locale.

HierarchySubsetATTRSL('Plan_Business_Unit', 'Europe', 'Sales', 'Manager', 'fr');

HierarchySubsetATTRNL
HierarchySubsetATTRNL returns an attribute's numeric value for a specified subset (and locale)
associated with a hierarchy in a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 249

 Syntax
HierarchySubsetATTRNL(DimName, HierName, SubName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Sales
subset (from the Europe hierarchy) for the French locale.

HierarchySubsetATTRNL('Plan_Business_Unit', 'Europe', 'Sales', 'Accounting_Code', 'fr');

HierarchySubsetAttrPutS
HierarchySubsetAttrPutS assigns a string value to an attribute for a specified subset associated with a
hierarchy in a dimension.
This function is valid in TM1 TurboIntegrator processes only.

250 IBM Planning Analytics: Reference

 Syntax
HierarchySubsetAttrPutS(String, DimName, HierName, SubName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a dimension

attribute.

DimName The dimension for which you want to assign an

attribute value.

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Prototype to the Description attribute of the Z subset (from the
2016 hierarchy in the Model dimension) for the French language locale code.

HierarchySubsetAttrPutS('Prototype', 'Model', '2016', 'Z', 'Description','fr');

HierarchySubsetAttrPutN
HierarchySubsetAttrPutN assigns a numeric value to an attribute for a specified subset associated with a
hierarchy in a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetAttrPutN(NumericValue, DimName, HierName, SubName, AttrName, [LocalLangCode] );

Argument Description

NumericValue The value you want to assign to a dimension

attribute.

DimName The dimension for which you want to assign an

attribute value.

HierName The name of a hierarchy in a dimension.

SubName The name of a subset in a dimension.

Chapter 5. TurboIntegrator Functions 251

 Argument Description

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 07161994 to the AccountingCode attribute of the Z subset (from the 2016
hierarchy in the Models dimension) for the French language locale code.

HierarchySubsetAttrPutN(07161994, 'Models', '2016', 'Z', 'AccountingCode','fr');

HierarchySubsetAttrInsert
HierarchySubsetAttrInsert creates a new attribute for subsets on your TM1 server. The function creates a
string, numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
Note: If you update an existing subset attribute, you must first delete the existing attribute using the
function HierarchySubsetAttrDelete. You can then use HierarchySubsetAttrInsert to recreate the attribute
with your desired changes. If you attempt to update an existing attribute without first deleting it, the
insert fails without a warning or error. The existing attribute remains unchanged; it is neither updated nor
overwritten.

HierarchySubsetAttrInsert( Dimension, Hierarchy, PrevAttrName, NewAttrName, AttrType);

Argument Description

Dimension The name of the dimension whose subsets are

being updated.

Hierarchy The name of a hierarchy in a dimension.

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
subsets, leave this argument empty.

NewAttrName The name you want to assign to the new subset

attribute.

252 IBM Planning Analytics: Reference

 Argument Description

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for subsets in the Z hierarchy of the Model
dimension. Because there is no PrevAttrName parameter, this attribute is inserted as the first attribute for
subsets on your TM1 server.

HierarchySubsetAttrInsert('Model', 'Z', '', 'Description', 'S');

HierarchySubsetAttrDelete
HierarchySubsetAttrDelete deletes a subset attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetAttrDelete(Dimension, Hierarchy, AttrName);

Argument Description

Dimension The name of the dimension whose subset attribute

is being deleted.

Hierarchy The name of a hierarchy in a dimension.

AttrName The name of the dimension attribute you want to

delete.

Example
This example deletes the Description attribute for subsets from the Z hierarchy in the Model dimension.

HierarchySubsetAttrDelete('Model', 'Z, 'Description');

ProcessAttrDelete
ProcessAttrDelete deletes a process attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrDelete(AttrName);

Chapter 5. TurboIntegrator Functions 253

 Argument Description

AttrName The name of the process attribute you want to

delete.

Example
This example deletes the Description attribute for processes on your TM1 server.

ProcessAttrDelete('Description');

ProcessAttrInsert
ProcessAttrInsert creates a new attribute for processes on your TM1 server. The function can create a
string, numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing process attribute, you must first delete the existing attribute using the
function ProcessAttrDelete. You can then use ProcessAttrInsert to recreate the attribute with your desired
changes. If you attempt to update an existing attribute without first deleting it, the insert fails without a
warning or error. The existing attribute remains unchanged; it is neither updated nor overwritten.

Syntax
ProcessAttrInsert( PrevAttrName, NewAttrName, AttrType);

Argument Description

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
processes, leave this argument empty.

NewAttrName The name you want to assign to the new process

attribute.

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for processes. This attribute is inserted after the
Owner attribute.

ProcessAttrInsert('Owner', 'Description', 'S');

ProcessAttrN
ProcessAttrN returns a numeric attribute for a specified process.
This function is valid in TM1 TurboIntegrator processes only.

254 IBM Planning Analytics: Reference

 Syntax
ProcessAttrN(ProcessName, AttrName);

Argument Description

ProcessName A valid process name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
process.

Example
In this example, the function returns the numeric value of the Store_Code attribute of the Daily_Sales
process.

ProcessAttrN('Daily_Sales', 'Store_Code');

ProcessAttrNL
ProcessAttrNL returns an attribute's numeric value for a specified process with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrNL(ProcessName, AttrName, [LangLocaleCode]);

Argument Description

ProcessName A valid process name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
process.

Chapter 5. TurboIntegrator Functions 255

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Store_Code attribute of the Daily_Sales
process for the French locale.

ProcessAttrNL('Daily_Sales', 'Store_Code', 'fr');

ProcessAttrPutN
ProcessAttrPutN assigns a value to a numeric process attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrPutN(NumericValue, CubeName, AttrName, [LangLocaleCode] );

Argument Description

NumericValue The value you want to assign to a process attribute.

ProcessName The process for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

256 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 8051997 to the Store_Code attribute of the Daily_Sales process for the
French language locale code.

ProcessAttrPutN(8051997, 'Daily_Sales', 'Store_Code','fr');

ProcessAttrPutS
ProcessAttrPutS assigns a value to a string process attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrPutS(String, ProcessName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a process

attribute.

ProcessName The process for which you want to assign an

attribute value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Ricci to the Owner attribute of the Import_Transactional process,
for the French language locale code.

ProcessAttrPutS('Ricci', 'Import_transactional', 'Owner', 'fr');

Chapter 5. TurboIntegrator Functions 257

ProcessAttrS
ProcessAttrS returns a string attribute for a specified process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrS(ProcessName, AttrName);

Argument Description

ProcessName A valid process name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
process.

Example
In this example, the function returns the string value of the Owner attribute of the Refresh_Cubes
process.

ProcessAttrS('Refresh_Cubes', 'Owner');

ProcessAttrSL
ProcessAttrSL returns a string attribute value for a specified process with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessAttrSL(ProcessName, AttrName, [LangLocaleCode]);

Argument Description

ProcessName A valid process name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
process.

258 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Owner attribute of the Exchange_Rate_Update
process for the French-Canada locale.

ProcessAttrSL('Exchange_Rate_Update', 'Owner', 'fr-CA');

SubsetATTRS
SubsetATTRS returns a string attribute for a specified subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetATTRS(DimName, SubName, AttrName);

Argument Description

DimName A valid dimension name.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Chapter 5. TurboIntegrator Functions 259

 Example
In this example, the function returns the string value of the Manager attribute of the Sales subset from the
Plan_Business_Unit dimension.

SubsetATTRS('Plan_Business_Unit', 'Sales', 'Manager');

SubsetATTRN
SubsetATTRN returns a numeric attribute for a specified subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetATTRN(DimName, SubName, AttrName);

Argument Description

DimName A valid dimension name.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Sales
subset from the Plan_Business_Unit dimension.

SubsetATTRN('Plan_Business_Unit', 'Sales', 'Accounting_Code');

SubsetATTRSL
SubsetATTRSL returns an attribute's string value for a specified subset with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetATTRSL(DimName, SubName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

260 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Manager attribute of the Sales subset for the
French locale.

SubsetATTRSL('Plan_Business_Unit', 'Sales', 'Manager', 'fr');

SubsetATTRNL
SubsetATTRNL returns an attribute's numeric value for a specified subset with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetATTRNL(DimName, SubName, AttrName, [LangLocaleCode]);

Argument Description

DimName A valid dimension name.

SubName The name of a subset in a dimension.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the
dimension.

Chapter 5. TurboIntegrator Functions 261

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value of the Accounting_Code attribute of the Sales
subset for the French locale.

SubsetATTRNL('Plan_Business_Unit', 'Sales', 'Accounting_Code', 'fr');

SubsetAttrPutS
SubsetAttrPutS assigns a string value to an attribute for a specified subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetAttrPutS(String, DimensionName, SubName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

SubName The name of a subset in a dimension.

AttrName The attribute whose value you want to assign.

262 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Prototype to the Description attribute of the Z subset (from the
Model dimension) for the French language locale code.

SubsetAttrPutS('Prototype', 'Model', 'Z', 'Description','fr');

SubsetAttrPutN
SubsetAttrPutN assigns a numeric value to an attribute for a specified subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetAttrPutN(NumericValue, DimensionName, SubName, AttrName, [LocalLangCode] );

Argument Description

NumericValue The value you want to assign to a dimension

attribute.

DimensionName The dimension for which you want to assign an

attribute value.

SubName The name of a subset in a dimension.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 07161994 to the AccountingCode attribute of the Z subset (from the
Models dimension) for the French language locale code.

SubsetAttrPutN(07161994, 'Models', 'Z', 'AccountingCode','fr');

Chapter 5. TurboIntegrator Functions 263

SubsetAttrInsert
SubsetAttrInsert creates a new attribute for subsets on your TM1 server. The function creates a string,
numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing subset attribute, you must first delete the existing attribute using the
function SubsetAttrDelete. You can then use SubsetAttrInsert to recreate the attribute with your desired
changes. If you attempt to update an existing attribute without first deleting it, the insert fails without a
warning or error. The existing attribute remains unchanged; it is neither updated nor overwritten.

Syntax
SubsetAttrInsert( Dimension, PrevAttrName, NewAttrName, AttrType);

Argument Description

Dimension The name of the dimension whose subsets are

being updated.

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
subsets, leave this argument empty.

NewAttrName The name you want to assign to the new subset

attribute.

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for subsets in the Model dimension. Because there is
no PrevAttrName parameter, this attribute is inserted as the first attribute for subsets on your TM1 server.

SubsetAttrInsert('Model', '', 'Description', 'S');

SubsetAttrDelete
SubsetAttrDelete deletes a subset attribute from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetAttrDelete(Dimension, AttrName);

Argument Description

Dimension The name of the dimension whose subset attribute

is being deleted.

264 IBM Planning Analytics: Reference

 Argument Description

AttrName The name of the dimension attribute you want to

delete.

Example
This example deletes the Description attribute for subsets in the Model dimension.

SubsetAttrDelete('Model', 'Description');

ViewAttrDelete
ViewAttrDelete deletes a view attribute for a specific cube from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrDelete(CubeName, AttrName);

Argument Description

CubeName The name of the cube whose view attribute is being

deleted.

AttrName The name of the view attribute you want to delete.

Example
This example deletes the Description attribute for views of the Sales cube on your TM1 server.

ViewAttrDelete('Sales', 'Description');

ViewAttrInsert
ViewAttrInsert creates a new attribute for views of a specific cube on your TM1 server. The function can
create a string, numeric, or alias attribute.
This function is valid in TM1 TurboIntegrator processes only.
Note: If you update an existing view attribute, you must first delete the existing attribute using the
function ViewAttrDelete. You can then use ViewAttrInsert to recreate the attribute with your desired
changes. If you attempt to update an existing attribute without first deleting it, the insert fails without a
warning or error. The existing attribute remains unchanged; it is neither updated nor overwritten.

Syntax
ViewAttrInsert( CubeName, PrevAttrName, NewAttrName, AttrType);

Argument Description

CubeName The parent cube for which you want to insert a view
attribute.

Chapter 5. TurboIntegrator Functions 265

 Argument Description

PrevAttrName The attribute that precedes the attribute you are

creating. If there is no previous attribute or you
want the new attribute to be the first attribute for
views, leave this argument empty.

NewAttrName The name you want to assign to the new view

attribute.

AttrType The type of attribute. There are three possible

values for the AttrType argument:
• N - Creates a numeric attribute.
• S - Creates a string attribute.
• A - Creates an alias attribute.

Example
This example creates the Description string attribute for views of the Sales cube. This attribute is inserted
after the Owner attribute.

ViewAttrInsert('Sales', 'Owner', 'Description', 'S');

ViewAttrN
ViewAttrN returns a numeric attribute for a specified view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrN(CubeName, ViewName, AttrName);

Argument Description

CubeName A valid cube name.

ViewName A valid view name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the view.

Example
In this example, the function returns the numeric value for the Category_Code attribute of the Product
view of the Sales cube.

ViewAattrN('Sales', 'Product', 'Category_Code');

ViewAttrNL
ViewAttrNL returns an attribute's numeric value for a specified view with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

266 IBM Planning Analytics: Reference

 Syntax
ViewAttrNL(CubeName, ViewName, AttrName, [LangLocaleCode]);

Argument Description

CubeName The parent cube for the view whose attribute value
you want to retrieve.

ViewName A valid view name.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the view.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the numeric value for the Category_Code attribute of the Product
view of the Sales cube, for the French locale.

ViewAttrNL('Sales', 'Product', 'Category_Code', 'fr');

ViewAttrPutN
ViewAttrPutN assigns a value to a numeric view attribute.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrPutN(NumericValue, CubeName, ViewName, AttrName, [LangLocaleCode] );

Chapter 5. TurboIntegrator Functions 267

 Argument Description

NumericValue The value you want to assign to a view attribute.

CubeName The parent cube of the view for which you want to
assign an attribute value.

ViewName The view for which you want to assign an attribute

value.

AttrName The attribute whose value you want to assign.

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the value 8222001 to the Category_Code attribute of the Product view of the Sales
cube, for the French language locale code.

ViewAttrPutN(8222001, 'Sales', 'Product', 'Category_Code','fr');

ViewAttrPutS
ViewAttrPutS assigns a string value to an attribute for a specified view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrPutS(String, CubeName, ViewName, AttrName, [LangLocaleCode] );

Argument Description

String The string you want to assign to a view attribute.

CubeName The cube parent of the view for which you want to
assign an attribute value.

ViewName The name of the view for which you want to assign
an attribute value.

AttrName The attribute whose value you want to assign.

268 IBM Planning Analytics: Reference

 Argument Description

LangLocaleCode This optional parameter specifies the language

locale code to which the NumericValue applies.
Valid LangLocaleCode values correspond to the
ISO 639-1 international language codes listed in
the }Cultures control dimension.
When the LangLocaleCode is not specified or is
omitted, the base attribute value is updated.

Example
This example assigns the string value Rocheford to the Owner attribute of the Individual_Stores view of
the Sales cube, for the French language locale code.

ViewAttrPutS('Rocheford', 'Sales', 'Individual_Stores', 'Owner','fr');

ViewAttrS
ViewAttrS returns a string attribute for a specified view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrS(CubeName, ViewName, AttrName);

Argument Description

CubeName The parent cube of the view for which you want to
return an attribute value.

ViewName The view for which you want to return an attribute

value.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the view.

Example

ViewAttrS('Plan_Business_Unit', 'Sales', 'Manager');

In this example, the function returns the string value of the Manager attribute of the Sales view of the
Plan_Business_Unit cube.

ViewAttrSL
ViewAttrSL returns an attribute's string value for a specified view with respect to a given locale.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewAttrSL(CubeName, ViewName, AttrName, [LangLocaleCode]);

Chapter 5. TurboIntegrator Functions 269

 Argument Description

CubeName The parent cube of the view for which you want to
return an attribute value.

ViewName The view for which you want to return an attribute

value.

AttrName The attribute for which you want to retrieve a value.

This argument must be a valid attribute of the view.

LangLocaleCode This optional parameter specifies the language

locale code for which you want to return a value.
Valid LangLocaleCode values correspond to the
international language codes listed in the }Cultures
control dimension.
When the LangLocaleCode is not specified or is
omitted, the user's current locale is used as the
LangLocaleCode argument.
If an attribute value does not exist for the
LangLocaleCode, the value for an associated
parent LangLocaleCode is returned. If an attribute
value does not exist for an associated parent
LangLocaleCode, the base attribute value is
returned.
For example if the LangLocaleCode is fr-CA, the
function returns the attribute value for the fr-CA
(French-Canada) locale if available. If the attribute
value for fr-CA is not available, the function
attempts to return the attribute value for the
parent fr (French) locale. If the attribute value
for fr is not available, the base attribute value is
returned

Example
In this example, the function returns the string value of the Manager attribute of the Sales view of the
Plan_Business_Unit cube, for the French-Canada locale.

ViewAttrSL('Plan_Business_Unit', 'Sales', 'Manager', 'fr-CA');

Chore Management TurboIntegrator Functions

These functions pertain to managing chores.

ChoreError
ChoreError causes the immediate termination of a chore. It can be called from any process within a chore.
The ChoreError TurboIntegrator function causes an immediate termination of a single chore. Chores
terminated with this function are flagged with an error status.
This function is valid in TM1 TurboIntegrator processes only.

270 IBM Planning Analytics: Reference

 Syntax
ChoreError;

Arguments
None.

ChoreQuit
ChoreQuit causes the immediate termination of a chore. It can be called from any process within a chore.
The current chore is terminated with an error status, and a message is written to the server log file
indicating that ChoreQuit was called to terminate the chore.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreQuit;

Arguments
None.

ChoreRollback
ChoreRollback initiates a chore rollback. When used inside a TurboIntegrator process, this function
throws out all pending edits and cancels further processing. An error message appears in the
[Link] and [Link] files.
When used in a single-commit mode chore, ChoreRollback throws out all pending edits from all previous
processes and chore execution stops with an error code. When used in a multi-commit mode chore,
ChoreRollback throws out all pending edits from the current processes and chore execution stops with an
error code. Changes that have already been committed cannot be rolled back.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ChoreRollback;

Arguments
None.

SetChoreVerboseMessages
SetChoreVerboseMessages is used to turn on (or off) more verbose reporting of messages to the [Link]
file. You can use this function to debug chores in which several processes call each other with the
ExecuteProcess function.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
SetChoreVerboseMessages(Flag);

Chapter 5. TurboIntegrator Functions 271

 Passing a zero value turns off the output of these messages, passing a non-zero value enables the output
of more verbose messages. By default this flag is off.
Use this function to turn on (or off) more verbose reporting of messages to the [Link] file. This function
is best used as an aid to debugging chores in which several processes call one another through use of the
ExecuteProcess function.
Passing a zero value turns off the output of these messages, passing a non-zero value enables the output
of more verbose messages. By default this flag is off.

Argument Description

Flag Set to a non-zero value to enable more verbose

messaging. Set to zero (default) to turn off verbose
messaging.

Cube Manipulation TurboIntegrator Functions

These functions pertain to manipulating cubes.

AddCubeDependency
AddCubeDependency lets you predefine cube inter-dependencies to avoid lock contention problems
during normal system use.
In normal operations, cube dependencies are established when data which crosses cube boundaries
(such as data that is derived by a rule that references an external cube) is retrieved. To create the
dependency information, the server must lock the cubes while the dependency is established, potentially
maintaining the lock during a long view calculation. Since this is a 'write' lock, other users are prevented
from accessing the cubes. The AddCubeDependency function allows the dependency to be established
when the server starts up, preventing later lock contention as no new dependency need be established.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AddCubeDependency(BaseCube, DependentCube);

Argument Description

BaseCube The name of the cube upon which the

DependentCube is dependent.

DependentCube The name of a cube that depends on another cube

(BaseCube) for data. Most commonly, this would
be a cube that uses rules to pull data from an
external cube.

Example
Consider a cube named 'SalesCube' that includes the rule ['net']=!Units *
DB('PriceCube', ... );
In this example, 'SalesCube' is the dependent cube, as it is dependent on values in the base cube named
'PriceCube' to calculate the value of 'net'. To establish this dependency, you should run the following
function in a TurboIntegrator process: AddCubeDependency( 'PriceCube', 'SalesCube' );

272 IBM Planning Analytics: Reference

 To establish dependency at server load time, you can create a process that runs the
AddCubeDependency function, schedule the process as a chore, and then define that chore as one
of the StartupChores in [Link].

CellGetN
CellGetN retrieves a value from a numeric cube cell.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellGetN(Cube, e1, e2 [,...en]);

Argument Description

Cube The name of the cube from which you want to

retrieve a value.

e1,...en Dimension element names that define the

intersection of the cube containing the value to be
retrieved.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.
If any of the dimensions in your cube
use hierarchies, you can also use the
'HierarchyName':'ElementName' convention
to specify an element within a specific hierarchy.
In this case, the sequence of arguments must still
adhere to the order of dimensions in the cube.
For example, if you want to reference multiple
elements from hierarchies in the second dimension
of your cube, all such arguments must appear after
the argument for the first dimension in the cube
and before the argument for the third dimension in
the cube.

Example of CELLGETN and variables

When this function is used in a conditional statement (IF), the statement is the portion containing
the condition, not the entire conditional block. After a minor error, execution continues with the next
statement. TurboIntegrator processing has no knowledge that it was in a conditional once the minor error
is processed, so the next statement is the next line, not the line after the ENDIF;.
To avoid this situation, use variables for any operation that could encounter a minor error and then use the
variables in the conditional statement.

V1 = CELLGETN('PNLCube', 'fred','argentina','Sales','Jan');
IF(V1 = 454);
ASCIIOUTPUT('[Link]', 'if logic not working properly');
ENDIF;

Chapter 5. TurboIntegrator Functions 273

 Example of CellGetN without hierarchies
This example illustrates a function that uses simple element names as arguments and does not reference
any hierarchies. It retrieves the numeric value at the intersection of the Actual, Argentina, S Series 1.8L
Sedan, Sales, and Jan elements in the Sales cube.

CellGetN('Sales', 'Actual', 'Argentina', 'S Series1.8L Sedan', 'Sales', 'Jan');

Example of CellGetN referencing multiple hierarchies

This example illustrates a function that references multiple hierarchies in the Model dimension. It
retrieves the numeric value at the intersection of the Actual, Argentina, S Series (from the vehicles
hierarchy in the model dimension), 2.8 Litre (from the enginesize hierarchy in the model dimension), and
Jan elements in the Sales cube.

CellGetN('Sales', 'Actual', 'Argentina',

('vehicles':'S Series', 'enginesize':'2.8 Litre'), 'Sales', 'Jan');

Note: This example artificially breaks the line of code for easier reading.

CellGetS
CellGetS retrieves a value from a string cube cell.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellGetS(Cube, e1, e2 [,...en]);

Argument Description

Cube The name of the cube from which you want to

retrieve a value.

e1,...en Dimension element names that define the

intersection of the cube containing the value to be
retrieved.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

See the note at “CellGetN” on page 273 concerning IF logic with this function.

Example

CellGetS('Personnel', 'Rep', 'Europe', 'Product');

This example retrieves the string value at the intersection of the Rep, Europe, and Product elements in the
Personnel cube.

CellIncrementN
CellIncrementN increments an existing numeric cell value by a specified value.
This function is valid in TM1 TurboIntegrator processes only.

274 IBM Planning Analytics: Reference

 Syntax
CellIncrementN(x, Cube, e1, e2 [,...en]);

Argument Description

x A numeric value that you want to add to an existing

cell value.

Cube The name of the cube to which you want to send

the value.

e1,...en Dimension element names that define the

intersection of the cube to receive the value.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

Example

CellIncrementN(1000, 'y2ksales', 'Actual', 'Argentina', 'S Series 1.8L Sedan', 'Sales', 'Jan');

This example increments the value at the intersection of the Actual, Argentina, S Series 1.8L Sedan, Sales,
and Jan elements in the y2ksales cube by 1000.

CellIsUpdateable
CellIsUpdateable determines whether a cube cell can be written to. The function returns 1 if the cell can
be written to, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellIsUpdateable(Cube, e1, e2 [,...en]);

Argument Description

Cube The name of the cube to which you want to write a

value.

e1,...en Dimension element names that define the cell to

which you want to write a value.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

Chapter 5. TurboIntegrator Functions 275

 Example

CellIsUpdateable ('y2ksales', 'Actual', 'Argentina','S Series 1.8L Sedan', 'Sales', 'Jan');

This example determines if the cell defined by the elements Actual, Argentina, S Series 1.8L Sedan, Sales,
and Jan in the y2ksales cube can be written to. If the cell can receive a value, the function returns 1,
otherwise it returns 0.

CellPutN
CellPutN sends a numeric value to a cube cell.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellPutN(x, Cube, e1, e2 [,..., en]);

Table 5. CellPutN arguments

Argument Description

x A numeric value.

Cube The name of the cube to which you want to send

the value.

e1, e2, ..., en Dimension element names that define the

intersection of the cube to receive the value.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

Note: If you supply invalid arguments to the CellPutN() function in a TurboIntegrator process when the
cube does not exist, an error is sent to the [Link].

Example

CellPutN(12345, 'y2ksales', 'Actual', 'Argentina', 'S Series 1.8L Sedan', 'Sales', 'Jan');

This example sends the value 12345 to the intersection of the Actual, Argentina, S Series 1.8L Sedan,
Sales, and Jan elements in the y2ksales cube.

CellPutProportionalSpread
CellPutProportionalSpread distributes a specified value to the leaves of a consolidation proportional to
existing cell values. CellPutProportionalSpread replaces existing cell values; it cannot be used to add to or
subtract from existing cell values.
The function is analogous to the Proportional Spread data spreading method. If you must add to or
subtract from existing cell values, use the Proportional Spread method, which can be executed through
the user interface or through data spreading syntax.
Note: When using CellPutProportionalSpread to distribute a value to the leaves of a consolidation, only
those leaves already containing non-zero values are changed. This is because zero values cannot be
incremented or decremented proportionally; any proportion of zero is still zero.

276 IBM Planning Analytics: Reference

 This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellPutProportionalSpread( value, cube, e1, e2, e3...,en );

Argument Description

value The value you want to distribute.

cube The name of the cube into which you want to

distribute the value.

e1...en The names of the elements that identify the

consolidation whose leaves will accept the
distributed value.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

Example

CellPutProportionalSpread(7000,'SalesCube', 'Actual','North America',

'S Series 1.8L Sedan', 'Sales', 'Jan')

This example distributes the value 7000 to the children of the consolidation in the SalesCube identified by
the elements Actual, North America, S Series 1.8L Sedan, Sales, and Jan.

CellPutS
CellPutS sends a string value to a cube cell.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellPutS(String, Cube, e1, e2 [,...en]);

Argument Description

String A string.

Cube The name of the cube to which you want to send

the string.

Chapter 5. TurboIntegrator Functions 277

 Argument Description

e1,...en Dimension element names that define the

intersection of the cube to receive the string.
Arguments e1 through en are sequence-sensitive.
e1 must be an element from the first dimension of
the cube, e2 must be an element from the second
dimension, and so on. These arguments can also
be the names of aliases for dimension elements or
TurboIntegrator variables.

Example

CellPutS('jones', 'Personnel', 'Rep', 'Europe', 'Product');

This example sends the string 'jones' to the intersection of the Rep, Europe, and Product elements in the
personnel cube.

CubeClearData
CubeClearData clears all of the data in a cube. This function is much faster than doing an operation such
as creating a view to cover the entire cube, and then doing a ViewZeroOut() to zero out the entire cube.
When you use CubeClearData to clear data from a cube, any cells in the cube that are fed with feeders
are also cleared. You must resave the rule that establishes the feeders or use the CubeProcessFeeders
function to restore the fed cells.
This function deletes only the cube data, it does not delete and re-create the cube itself. This has
implications when sandboxes are used. If a cube is deleted and then re-created, any sandboxes a user
may have will be discarded, since the cube against which those sandboxes were created was deleted
(even though a cube may have been re-created with the same name). If, however, CubeClearData is used,
the sandbox data will still be considered valid, since the cube against which the sandbox was created
continues to exist.
CubeClearData is valid in processes only.
Note: The effect of the CubeClearData function is not recorded in the transaction log; the log will not
contain any entries relating to the removal of data from the cube resulting from the use of CubeClearData.

Syntax
CubeClearData( name-of-cube-as-string );

Argument
The name of the cube to clear, as a string.

Example

CubeClearData( 'expense' );

CubeCreate
CubeCreate creates a cube from specified dimensions. The order of dimensions specified in the function
will be the order of dimensions in the cube definition. After execution, CubeCreate automatically saves
the resulting .cub file to disk.
This function is valid in TM1 TurboIntegrator processes only.

278 IBM Planning Analytics: Reference

 Note: Transaction logging is not enabled by default for cubes that are created in TM1 Database 11.

Syntax
CubeCreate(Cube, d1, d2 [,...dn]);

Argument Description

Cube The name you want to assign to the cube.

d1,...dn The names of dimensions that comprise the cube.

You must specify at least two, but no more than
256, dimensions.

Example

CubeCreate('y2ksales', 'Actvsbud', 'Region', 'Model','Account1', 'Month');

This example creates a cube named y2ksales using the dimensions Actvsbud, Region, Model, Account1,
and Month.

CubeDestroy
CubeDestroy deletes a specified TM1 cube.
This function is valid in TM1 TurboIntegrator processes only.
You can use CubeDestroy to delete control cubes.

Syntax
CubeDestroy(Cube);

Argument Description

Cube The name of the cube you want to delete.

Example

CubeDestroy('y2ksales');

This example deletes the cube named y2ksales.

CubeDimensionCountGet
CubeDimensionCountGet returns the number of dimensions in a cube.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeDimensionCountGet(CubeName);

Chapter 5. TurboIntegrator Functions 279

 Argument Description

CubeName The name of the cube for which you want to

determine the number of dimensions.

Example
CubeDimensionCountGet('Sales');
In this example, the function returns the number of dimensions in the Sales cube.

CubeExists
CubeExists determines whether a specific cube exists on the server from which a TurboIntegrator process
is executed. The function returns 1 if the cube exists on the server, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeExists(CubeName);

Argument Description

CubeName The name of the cube whose existence you want to

confirm.

Example

CubeExists('Inventory');

This example determines if the Inventory cube exists on the server.

CubeGetLogChanges
CubeGetLogChanges returns the Boolean value of the Logging property for a specified cube.
The Logging property is set in the Security Assignments dialog box and stored in the }CubeProperties
control cube. If Logging is turned on for a cube, the function returns 1. If logging is turned off the function
returns 0.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeGetLogChanges(CubeName);

Argument Description

CubeName The cube for which you want to return the value of
the Logging property.

Example

CubeGetLogChanges('2002sales');

280 IBM Planning Analytics: Reference

 If Logging is turned on for the 2002sales cube, the function returns 1.

CubeSaveData
CubeSaveData() serializes a cube.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.
To improve performance, transaction logging may be disabled while loading data. To safeguard newly
loaded data in the unlikely event of a server crash, the changes can be serialized to disk. SaveDataAll has
been used to serialize data to disk and to truncate the transaction log. When processing a SaveDataAll
command, the server acquires a READ lock on every cube and an IX lock on every changed cube. This can
cause significant contention with user activity if SaveDataAll is run during periods of user activity.
Typically not all the cubes affected by SaveDataAll need to be serialized since not all cubes are typically
loaded with new data. CubeSaveData is used to serialize an individual cube to disk. CubeSaveData
serializes the cube's data that has been committed to memory including the modifications that have been
performed against it in the current TurboIntegrator process but not yet committed.

Syntax
CubeSaveData(Cube);

Argument Description

Cube The name of the cube you want to serialize.

Example

CubeSaveData ('SalesCube');

Consider the following TurboIntegrator process code:

CellPutN(500, 'y2ksales', 'Actual', 'Argentina', 'S Series 1.8 L Wagon', 'Sales', 'Jan');

CubeSaveData('y2ksales');

CellPutN(1000, 'y2ksales', 'Actual', 'Argentina', 'S Series 1.8 L Wagon', 'Sales', 'Jan');

When the CubeSaveData command is processed, the value of 500 for the January Sales cell will be
included in the cube's serialization to disk, even though it has not yet been committed. The update of the
January Sales cell to 1000 will not be part of the serialization.

Transaction Log
A new transaction entry appears in the Transaction log when CubeSaveData has been run. When
processing a transaction log file during recovery, all updates to a cube that have been applied so far
will be discarded when a CubeSaveData directive against the cube is encountered as all of the updates
have already been serialized to the cube.

Server Crash Recovery

The SaveDataAll command takes advantage of the fact that all cubes are locked during its processing
and truncates the transaction log knowing that all updates performed before serialization have been
safely stored to disk. This is not the case for CubeSaveData so you must modify the way data recovery is
performed when a cube has been serialized.

Chapter 5. TurboIntegrator Functions 281

 The transaction log file could contain records that represent changes that are older than the most recent
data in the cube and should not be applied when data is being recovered.

CubeSetConnParams
CubeSetConnParams is used to encrypt the password for a virtual cube in the }CubeProperties cube.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeSetConnParams(cubeName, providerName, dataSourceLocation,dataSourceName,
dataSourceCatalog, userID, password, sapClientID, sapClientLang, providerString);

Argument Description

cubeName The name of the cube for which you want to set the
password.

providerName

dataSourceLocation Name your administrator assigns to a set of

catalogs at a particular location. In Microsoft
Analysis Services, this is the name of a registered
server.

dataSourceName

dataSource catalog The name assigned by your administrator to

a particular collection of databases (Cubes,
Dimensions and other objects). For MAS, this is the
name of the database.

UserID A valid username for the database.

Password Password to use for this data source.

sapClientID SAP client ID

sapClientLang SAP language setting.

providerString

Example

CubeSetConnParams(sc, TM1OLAP, tm1server, , sdata, admin, apple, , , );

CubeSetLogChanges
CubeSetLogChanges sets the Logging property for a cube.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

282 IBM Planning Analytics: Reference

 Syntax
CubeSetLogChanges(Cube, LogChanges);

Argument Description

Cube The name of the cube for which you want to set the
LOGGING property.

LogChanges The Boolean value you want to assign to the

property. 1= LOGGING on, 0 = LOGGING off.

CubeTimeLastUpdated
CubeTimeLastUpdated returns a serial value that indicates the date and time at which a specified cube
was last updated.
The serial value that is returned by this function uses a starting time of Jan 1 1900 12:00:00 A.M., which
is equivalent to the value 1.0. Dates are represented by integers, while times are represented as decimal
numbers between .0 and .999999. This is consistent with the way date and time serial values are stored
and reported in Microsoft Excel.
Note: By default, TM1 date and time serial values use a starting time of Jan 1 1960 12:00:00
A.M. To resolve the inconsistency between Excel and TM1 date and time serial values, you can set
UseExcelSerialDate=T in your [Link] file to instruct the TM1 server to use date and time serial
values that conform to Excel standards.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeTimeLastUpdated(cube);

Argument Description

cube The name of the cube.

Example

CubeTimeLastUpdated('Sales');

This example returns a value corresponding to the time when the Sales cube was last updated.

CubeUnload
CubeUnload unloads a specified cube, along with all associated cube views, from memory.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeUnload(CubeName);

Argument Description

CubeName The cube you want to unload from memory.

Chapter 5. TurboIntegrator Functions 283

 Example

CubeUnload('ManufacturingBudget');

This example unloads the ManufacturingBudget cube, and any associated views, from server memory.

Data Reservation TurboIntegrator Functions

Use the following process functions to programmatically obtain, release and manage Data Reservations.
Data Reservation functions are not valid in processes on TM1 Database 12.
For more details about using the Data Reservation feature, see "Using Data Reservations" in the IBM
Cognos TM1 for Developers documentation.

CubeDataReservationAcquire
CubeDataReservationAcquire acquires a Data Reservation for the specified cube, user and tuple.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeDataReservationAcquire(Cube, User, bForce, Address, [AddressDelimiter])

Argument Description

Cube Name of the cube.

User Name of the owner for the new reservation.

The user name supplied will be validated to make sure it is an existing user.

bForce Boolean value that determines the behavior if the requested reservation
conflicts with an existing reservation.
If set to 0 (false), then the request is rejected if it conflicts with an existing
reservation.
If set to 1 (true) and the user running the TurboIntegrator process has
the DataReservationOverride capability, then the conflicting reservations are
released, and the requested one is granted.

Address Tokenized string sequence of element names that define the tuple. The order
must match the original dimension order of the cube.
All the cells in the cube contained by the tuple make up the region being
reserved. You can choose one element from each dimension or use an empty
string between the delimiters to select an entire dimension. Depending on
where the element is located in the hierarchy, the request reserves a single
cell, a slice, or the entire cube.

AddressDelimiter Optional character string that is used to separate element names in the
Address parameter.
Default value is '|'.

284 IBM Planning Analytics: Reference

 Return Value
Boolean - returns true if the acquisition succeeded.

Example

CubeDataReservationAcquire('DRTestCube','User1',0,'ElemX|ElemY|ElemZ');

The following example sets the bForce parameter to 1 to force the DR request if a conflict exists and uses
a different delimiter character for the AddressDelimiter parameter.

CubeDataReservationAcquire('DRTestCube','User2',1,'ElemX*ElemY*ElemZ','*');

CubeDataReservationRelease
CubeDataReservationRelease releases the specified Data Reservation.
If the user specified is not the same as the owner of the reservation, then the release will only succeed if
the user specified has the DataReservationOverride capability enabled.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeDataReservationRelease(Cube, User, Address,[AddressDelimiter])

Argument Description

Cube Name of the cube.

User Name of the owner of the reservation.

The user name supplied will be validated to make sure it is an existing user.

Address Tokenized string sequence of element names that define the tuple. The
order must match the original dimension order of the cube.

AddressDelimiter Optional character string that is used to separate element names in the
Address parameter.
Default value is '|'.

Return Value
Boolean - returns true if the release succeeded.

Example

CubeDataReservationRelease('DRTestCube','User1','ElemX|ElemY|ElemZ');

The following example uses a different character for the AddressDelimiter parameter.

CubeDataReservationRelease('DRTestCube','User2','ElemX*ElemY*ElemZ','*');

Chapter 5. TurboIntegrator Functions 285

CubeDataReservationReleaseAll
CubeDataReservationReleaseAll releases multiple existing Data Reservations.
All reservations fully contained by the specified address that match the user filter will be released. A
blank user filter means all users.
If the user filter specified is not the same as the user running the TurboIntegrator proces, then the
DataReservationOverride capability must be enabled.
Using a blank user filter and all wildcards in the address field releases all reservations.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeDataReservationReleaseAll(Cube, UserFilter, Address, [AddressDelimiter])

Argument Description

Cube Name of the cube.

UserFilter User name filter to match against existing reservations.

Address Tokenized string sequence of element names that define the tuple. The order
must match the original dimension order of the cube.

AddressDelimiter Optional character string that is used to separate element names in the
Address parameter.
Default value is '|'.

Return Value
Boolean - returns true if no errors.

Example

CubeDataReservationReleaseAll('DRTestCube','User1','ElemX|ElemY|ElemZ');

The following example releases all reservations in the specified cube for all users.

CubeDataReservationReleaseAll('DRTestCube','','||');

CubeDataReservationGet
CubeDataReservationGet finds existing reservations on a specific cube for all or one user.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeDataReservationGet(Index, Cube, User, [AddressDelimiter]) returns Address;

286 IBM Planning Analytics: Reference

Argument Description

Index A one-based loop index to use for iterating through reservations on the
specified cube.

Cube Name of the cube to search.

User Reservation owner name to use as a filter.

If left blank, the function returns reservations for any owner.
If a name is provided, the function filters the results for just the specified
owner.

AddressDelimiter Optional character string that is used to separate element names in the
returned Address parameter.
Default value is '|'.

Return Value
Address - Reservation creation time, name of the reservation owner and Element address of the
reservation. Creation time comes first, followed by delimiter, followed by UserID, followed by delimiter,
followed by Elements IDs separated by the delimiter in order of dimensions in the cube (original order).
An empty string is returned if there is no entry for the specified index.
The format of the return value is:
[creation time][delimiter][owner name][delimiter][element1][delimiter]
[element2][delimiter]…[elementN]
For example:
"20100622211601|Fred Bloggs|Element1|Element2|Element3"
Note: The reservations can change while iterating the list of reservations so the use of index is not
guaranteed to give a complete list of reservations. Reservations can be added or removed at any position
in the list, so reservations can be skipped or repeated when looping through index values.
If the owner filter is specified, then the index applies only to the members of the filtered list. If the list
of reservations has owners as follows: User1, User1, User2 and the request specifies an owner of User2
then an index of 1 will retrieve the third member of the list.

Example

CubeDataReservationGet(1,'DRTestCube','User1','*');

CubeDataReservationGet(1,'DRTestCube','');

The following sample would find all the reservations owned by user Fred Bloggs in the Expense Input
cube and do "something useful" with them:

vIndex = 1;
vCube = 'Expense Input';
vUserFilter = 'Fred Bloggs';
vDelim = '|';
vAddress = CubeDataReservationGet( vIndex, vCube, vUserFilter,vDelim);
WHILE (vAddress @<> '');
vSep1 = SCAN( vDelim, vAddress);
vDRUser = SUBST( vAddress, 1, vSep1 - 1);
vDRAddress = SUBST( vAddress, vSep1 + 1, LONG(vDRAddress) - vSep1);

# do something meaningful with the

user and reservation address here

Chapter 5. TurboIntegrator Functions 287

 vIndex = vIndex + 1;
vAddress = CubeDataReservationGet( vIndex, vCube, vUserFilter,vDelim);
END;

CubeDataReservationGetConflicts
CubeDataReservationGetConflicts finds existing reservations on a specific cube that would conflict with
the specified user, address and tuple.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
CubeDataReservationGetConflicts(Index, Cube, User, Address, [AddressDelimiter])returns
ConflictAddress;

Argument Description

Index A one-based loop index to use for iterating through conflicts that satisfy
this query.

Cube Name of the cube to search

User The query will search for reservations that will conflict with this user.

Address Tokenized string sequence of element names that define the tuple. The
order must match the original dimension order of the cube.

AddressDelimiter Optional character string that is used to separate element names in the
Address parameter.
Default value '|'.

Return Value
ConflictAddress - Reservation creation time, name of the reservation owner and Element address of
the reservation. The creation time comes first, followed by delimiter, followed by UserID, followed by
delimiter, followed by Elements IDs separated by the delimiter in order of dimensions in the cube (original
order).
An empty string is returned if there is no entry for the specified index.
The format of the return value is:

[creation time][delimiter][owner name][delimiter][element1][delimiter]

[element2][delimiter]…[elementN]

For example:
"20100622211601|Fred Bloggs|Element1|Element2|Element3"
Note: The reservations can change while iterating the list of conflict reservations so the use of index is not
guaranteed to give a complete list of reservations. Reservations can be added or removed at any position
in the list, so reservations can be skipped or repeated when looping through index values.

Date and Time TurboIntegrator Functions

These functions format and parse dates and times in a wide variety of formats and locales.

288 IBM Planning Analytics: Reference

FormatDate
FormatDate formats a date value according to a formatter defined with the NewDateFormatter function.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
FormatDate(Date, <Pattern>, <Index>)

Argument Description

Date A date value.

The type of value, serial or UNIX, should correspond to the formatter used.

Pattern Pattern used for formatting dates.

Refer to [Link]
format_parse/datetime for a complete list of format syntax.
If an empty string is passed, then the format is determined by the locale based
on the FormatterStyle and FormatterType parameters that were used with the
NewDateFormatter function.

Index Index returned by a call to the NewDateFormatter function.

The default value is 0.
If no date formatter exists at the index, then a default formatter is used as though
it had been created with the following call:
NewDateFormatter('', 'Etc/UTC', 'serial', 'medium', 'date')

Example
sDate = FormatDate(18000);

NewDateFormatter
NewDateFormatter defines a date formatter. It returns an index for use in the ParseDate and FormatDate
functions. The indices start at 0 and go up by one for each call to NewDateFormat. Date formatters are
valid during execution of the process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
NewDateFormatter(Locale, <TimeZone>, <UseUNIXTime>, <FormatterStyle>, <FormatterType>,
<TimeType>)

Argument Description

Locale Locale used for parsing or formatting dates.

If an empty string is passed, then the operating system locale is used. Locales
are specified in the format language[_territory][.variant]. For example, cs_CK is the
Czech language and Czech Republic.

Chapter 5. TurboIntegrator Functions 289

 Argument Description

TimeZone Timezone used for parsing or formatting dates.

Refer to [Link] for a
complete list of time zones.
If not specified, the time zone used is UTC ('Etc/UTC').

UseUNIXTime If 'unix' is specified, then times are treated as milliseconds since January 1,
1970. Otherwise, they are treated in TM1 serial format.
Note that only dates later than January 1, 1970 can be processed even if TM1
serial format is used.

FormatterStyle Controls the date format used when an empty pattern is specified to the
FormatDate or ParseDate functions.
Valid values are 'full', 'long', 'medium' or 'short'.
The default is 'medium'.

FormatterType Controls the type of format used when an empty pattern is specified to the
FormatDate or ParseDate functions.
Valid values are 'time', 'date' or 'datetime'.
The default is 'date'.

Example
dfUNIX = NewDateFormatter('', 'Etc/UTC', 'unix');

dfStyleFullDateTime = NewDateFormatter('en_us', 'America/Toronto', 'serial', 'full',

'datetime');

ParseDate
ParseDate parses a date string according to a formatter defined with the NewDateFormatter function.
A date value that is either serial or UNIX, depending on the formatter specified, is returned. If the date
cannot be parsed then an undefined value is returned. This can be tested with the ISUND function.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ParseDate (DateString, <Pattern>, <Index>)

Argument Description

DateString A date string.

290 IBM Planning Analytics: Reference

 Argument Description

Pattern Pattern used for parsing dates.

Refer to [Link]
format_parse/datetime for a complete list of format syntax.
If an empty string is passed, then the format is determined by the locale based
on the FormatterStyle and FormatterType parameters that were used with the
NewDateFormatter function.

Index Index returned by a call to the NewDateFormatter function. The default value is
0. If no date formatter exists at the index, then a default formatter is used as
though it had been created with the following call:
NewDateFormatter('', 'Etc/UTC', 'serial', 'medium', 'date')

Example
nDate = ParseDate('2011/11/24', 'yyyy/MM/dd');

Dimension Manipulation TurboIntegrator Functions

These functions facilitate the manipulation of dimensions.

DimensionCreate
DimensionCreate creates a new dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionCreate(DimName);

Argument Description

DimName The name you want to assign to the dimension.

Example

DimensionCreate('Product');

This example creates the Product dimension.

DimensionDeleteAllElements
DimensionDeleteAllElements deletes all the elements in a dimension. This function is useful for
recreating dimension hierarchies.
Note: Deleting an element deletes all cube data identified by that element. However, if you use
DimensionDeleteAllElements to delete elements, then recreate those elements with the same names
in the Metadata tab, any data points in a cube identified by the elements will be retained after rebuilding
the dimension.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 291

 Syntax
DimensionDeleteAllElements(DimName);

Argument Description

DimName The name of the dimension from which you want to

delete all elements.

Example

DimensionDeleteAllElements('Model');

This example deletes all elements in the Model dimension.

DimensionDeleteElements
DimensionDeleteElements deletes all elements from a dimension using the subset of elements. All
elements in the referenced subset are deleted, including C level elements.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionDeleteElements (DimensionName, Subset )

Argument Description

DimensionName The name of the dimension from which you want to

delete the subset of elements.

Subset The list of elements to delete from the indicated

dimension. The subset is usually temporary.

DimensionDestroy
DimensionDestroy deletes a dimension from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionDestroy(DimName);

Argument Description

DimName The name of the dimension you want to delete.

Example

DimensionDestroy('Product');

This example deletes the Product dimension from the TM1 database.

292 IBM Planning Analytics: Reference

DimensionElementComponentAdd
DimensionElementComponentAdd adds a component (child) to a consolidated element. You can't use this
function in the Epilog procedure of a TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementComponentAdd(DimName, ConsolidatedElName,ElName, ElWeight);

Argument Description

DimName The parent dimension of the consolidated element

to which you want to add a child.

ConsolidatedElName The element to which you want to add a child.

ElName The name of the child element.

ElWeight The weight of the child element.

Example

DimensionElementComponentAdd('Measures', 'Net Sales', 'Expenses', -1);

This example adds the child Expenses to the Net Sales consolidation in the Measures dimension. The
child has a weight of -1 in the consolidation.

DimensionElementComponentAddDirect
DimensionElementComponentAddDirect adds a component (child) to a consolidated element by directly
editing a dimension.
This function is valid in TM1 TurboIntegrator processes only.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that
pattern, an editing copy of the dimension is created, edits are applied to the editing copy, then
finally the actual dimension is rewritten using the editing copy as a template. TurboIntegrator
supports whole-copy editing automatically whenever dimension editing TurboIntegrator functions (like
DimensionElementComponentAdd) are used in the Metadata procedure of the process. TurboIntegrator
automatically creates the editing copy and applies editing operations to it, then rewrites the actual
dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Chapter 5. TurboIntegrator Functions 293

 Syntax
DimensionElementComponentAddDirect(DimName, ConsolidatedElName,ElName, ElWeight);

Argument Description

DimName The parent dimension of the consolidated element

to which you want to add a child.

ConsolidatedElName The consolidated element to which you want to

add a child.

ElName The name of the child element.

ElWeight The weight of the child element.

Example

DimensionElementComponentAddDirect('Measures', 'Net Sales', 'Expenses', -1);

This example adds the child Expenses to the Net Sales consolidation in the Measures dimension. The
child has a weight of -1 in the consolidation.

DimensionElementComponentDelete
DimensionElementComponentDelete deletes a component (child) from a consolidated element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementComponentDelete(DimName, ConsolidatedElName,ElName);

Argument Description

DimName The parent dimension of the consolidated element

from which you want to delete a child.

ConsolidatedElName The consolidated element from which you want to

delete a child.

ElName The name of the child element you want to delete.

Example

DimensionElementComponentDelete('Region', 'Benelux','Belgium');

This example deletes the Belgium child from the Benelux consolidation in the Region dimension.

DimensionElementComponentDeleteDirect
DimensionElementComponentDeleteDirect deletes a component (child) from a consolidated element by
directly editing the dimension.
This function is valid in TM1 TurboIntegrator processes only.

294 IBM Planning Analytics: Reference

 The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that
pattern, an editing copy of the dimension is created, edits are applied to the editing copy, then
finally the actual dimension is rewritten using the editing copy as a template. TurboIntegrator
supports whole-copy editing automatically whenever dimension editing TurboIntegrator functions
(like DimensionElementComponentDelete) are used in the Metadata procedure of the process.
TurboIntegrator automatically creates the editing copy and applies editing operations to it, then rewrites
the actual dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
DimensionElementComponentDeleteDirect(DimName, ConsolidatedElName,ElName);

Argument Description

DimName The parent dimension of the consolidated element

from which you want to delete a child.

ConsolidatedElName The consolidated element from which you want to

delete a child.

ElName The name of the child element you want to delete.

Example

DimensionElementComponentDeleteDirect('Region', 'Benelux','Belgium');

This example deletes the Belgium child from the Benelux consolidation in the Region dimension.

DimensionElementDelete
DimensionElementDelete deletes an element from a dimension.
Note: Deleting an element deletes all cube data identified by that element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementDelete(DimName, ElName);

Argument Description

DimName The dimension that contains the element you want

to delete.

Chapter 5. TurboIntegrator Functions 295

 Argument Description

ElName The element you want to delete.

Example

DimensionElementDelete('Region', 'Belgium');

This example deletes the element Belgium from the Region dimension.

DimensionElementDeleteDirect
DimensionElementDeleteDirect deletes an element from a dimension by directly editing the dimension.
This function is valid in TM1 TurboIntegrator processes only.
Note: Deleting an element deletes all cube data identified by that element.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like DimensionElementDelete) are
used in the Metadata procedure of the process. TurboIntegrator automatically creates the editing copy
and applies editing operations to it, then rewrites the actual dimension at the end of the Metadata
procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
DimensionElementDeleteDirect(DimName, ElName);

Argument Description

DimName The dimension that contains the element you want

to delete.

ElName The element you want to delete.

Example

DimensionElementDeleteDirect('Region', 'Belgium');

This example deletes the element Belgium from the Region dimension.

296 IBM Planning Analytics: Reference

DimensionElementExists
DimensionElementExists determines whether a specific element exists in a dimension on the server from
which a TurboIntegrator process is executed. The function returns 1 if the element exists in the dimension
on the server, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementExists(DimName, ElName);

Argument Description

DimName The dimension that contains the element that

you want to find. The dimension must exist on
the server where the TurboIntegrator process is
executed.

ElName The element that you want to find. The ElName

argument accepts both the element name and the
alias.

Example
This example determines whether the element Belgium exists in the Region dimension on the server.

DimensionElementExists('Region', 'Belgium');

DimensionElementInsert
DimensionElementInsert adds an element to a dimension. You can use this function to add numeric,
string, or consolidated elements. You can't use this function in the Data or Epilog procedures of a
TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementInsert(DimName, InsertionPoint, ElName,ElType);

Argument Description

DimName The dimension to which you want to add an

element.

InsertionPoint An existing dimension element. The element

being added to the dimension will be inserted
immediately before this existing element. If this
parameter is an empty string (''), the new element
is added to the end of the dimension.

ElName The name that you want to assign to the new

element.

Chapter 5. TurboIntegrator Functions 297

 Argument Description

ElType The element type. There are three possible ElType

values:
N - Signifies a numeric element.
S - Signifies a string element.
C - Signifies a consolidated element.

Example

DimensionElementInsert('Region','Belgium','Netherlands','S');

This example adds the string element Netherlands to the Region dimension. Netherlands is added
immediately before Belgium in the dimension.

Example with an empty insertion point

DimensionElementInsert('Region','','Netherlands','S');

This example adds the string element Netherlands to the Region dimension. Netherlands is added to the
end of the dimension.

DimensionElementInsertDirect
DimensionElementInsertDirect adds an element to a dimension by directly editing the dimension. You can
use this function to add numeric, string, or consolidated elements.
This function is valid in TM1 TurboIntegrator processes only.
The default method of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like DimensionElementInsert) are
used in the metadata tab of the process. TurboIntegrator automatically creates the editing copy and
applies editing operations to it, then rewrites the actual dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element insertion needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
DimensionElementInsertDirect(DimName, InsertionPoint, ElName,ElType);

298 IBM Planning Analytics: Reference

 Argument Description

DimName The dimension to which you want to add a new

element.

InsertionPoint An existing dimension element. The element

being added to the dimension will be inserted
immediately before this existing element. If this
parameter is empty, the new element is added to
the end of the dimension.
Note that this function is optimized for the case
where the InsertionPoint is passed as an empty
string.

ElName The name you want to assign to the new element.

ElType The element type. There are three possible ElType

values:
N - Signifies a numeric element.
S - Signifies a string element.
C - Signifies a consolidated element.

Example

DimensionElementInsertDirect('Region', 'Belgium', 'Netherlands','N');

This example adds the numeric element Netherlands to the Region dimension. Netherlands displays
immediately before Belgium in the dimension definition.

DimensionElementPrincipalName
DimensionElementPrincipalName returns the principal name of an element or element alias.
TurboIntegrator must use principal element names when updating dimensions; element aliases cannot
be used. This function is useful for determining principal element names while attempting to update a
dimension when only element aliases are available to the TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionElementPrincipalName( DimName, ElName )

Argument Description

DimName The name of the dimension from which you want to

retrieve a principal element name.

ElName An element name. ElName can be either an

element alias or a principal element name.

Example
If ElName is not in the currently saved version of DimName, the function returns ElName.

Chapter 5. TurboIntegrator Functions 299

 If ElName is in DimName, whether as an element alias or a principal element name, it returns the
principal name of the element.

DimensionExists
DimensionExists determines whether a specific dimension exists on the server from which a
TurboIntegrator process is executed. The function returns 1 if the dimension exists on the server,
otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionExists(DimName);

Argument Description

DimName The name of the dimension whose existence you

want to confirm.

Example

DimensionExists('Region');

This example determines if the Region dimension exists on the server.

DimensionHierarchyCreate
DimensionHierarchyCreate creates a new hierarchy in an existing dimension. The hierarchy cannot have
the same name as the dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionHierarchyCreate(DimName, HierName);

Argument Description

DimName The name of the existing dimension that will

contain the hierarchy.

HierName The name that you want to assign to the hierarchy.

You cannot use the name of the dimension.

Example

DimensionHierarchyCreate('Vehicles', 'Trucks');

This example creates the empty Trucks hierarchy in the Vehicles dimension.

300 IBM Planning Analytics: Reference

DimensionSortOrder
DimensionSortOrder sets a sort type and sense for dimension elements and for components of
consolidated elements within a dimension. The sort order defined by DimensionSortOrder determines
how the subset displays in the Subset Editor.
DimensionSortOrder sets properties for a dimension; the dimension is not actually sorted until it is saved
on the server.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionSortOrder(DimName, CompSortType, CompSortSense, ElSortType , ElSortSense);

Argument Description

DimName The name of the dimension for which you want to

set a sort order.

CompSortType Defines how components of consolidated elements

appear in the dimension. There are two
CompSortType values:
ByInput - Retains the order in which components
were originally inserted into consolidations.
ByName - Sorts components of consolidations by
name.

CompSortSense Defines the sort sense for components of

consolidations. This is a required argument, but it
applies only when the CompSortType is ByName.
There are two possible CompSortSense values:
Ascending - Sorts components of consolidations in
ascending alphabetical order.
Descending - Sorts components of consolidations
in descending alphabetical order.

ElSortType Defines a sort order for dimension elements. There

are four possible ElSortType values:
ByInput - Retains the order in which elements
were originally inserted into the dimension.
ByName - Sorts dimension elements by name.
ByLevel - Sorts dimension elements by level.
ByHierarchy - Sorts dimension elements by
hierarchy.

Chapter 5. TurboIntegrator Functions 301

 Argument Description

ElSortSense Defines the sort sense for dimension elements.

This is a required argument, but it applies only
when the ElSortType is ByName or ByLevel. There
are two possible ElSortSense values:
Ascending - Sorts dimension elements in
ascending order, either alphabetically or by level.
Descending - Sorts dimension elements in
descending order, either alphabetically or by level.

Example

DimensionSortOrder ('Region', 'ByName', 'Descending','ByLevel', 'Ascending');

This example sets a sort order for the Region dimension. All dimension elements are sorted by level in
ascending order, and any components of consolidations are sorted in descending alphabetical order.

DimensionTimeLastUpdated
DimensionTimeLastUpdated returns a serial value that indicates the date and time at which a specified
dimension was last updated.
The serial value returned by this function uses a starting time of Jan 1 1900 12:00:00 A.M., which is
equivalent to the value 1.0. Dates are represented by integers, while times are represented as decimal
numbers between .0 and .999999. This is consistent with the way date/time serial values are stored and
reported in Microsoft Excel.
Note: By default, TM1 date/time serial values use a starting time of Jan 1 1960 12:00:00 A.M. To resolve
the inconsistency between Excel and TM1 date/time serial values, you can set UseExcelSerialDate=T
in your [Link] file to instruct the TM1 server to use date/time serial values that conform to Excel
standards.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionTimeLastUpdated(dimension);

Argument Description

dimension The name of the dimension.

Example

DimensionTimeLastUpdated('Region');

This example returns information on when the Region dimension was last updated.

DimensionTopElementInsert
DimensionTopElementInsert creates a root element in a dimension. If the dimension already has a single
root, then this element will not be created.
This function is valid in TM1 TurboIntegrator processes only.

302 IBM Planning Analytics: Reference

 Syntax
DimensionTopElementInsert(DimName, InsertionPoint, ElName);

Argument Description

DimName The dimension for which you want to create a root

element.

InsertionPoint An existing dimension element. The root element

being added to the dimension will be inserted
immediately before this existing element.

ElName The name you want to assign to the new root

element.

Example

DimensionTopElementInsert('Region', 'Netherlands', 'World');

This example adds the root element World to the Region dimension. World is inserted displays
immediately before Netherlands in the dimension definition.

DimensionTopElementInsertDirect
DimensionTopElementInsertDirect creates a root element in a dimension by directly editing the
dimension. If the dimension already has a single root, then this element will not be created.
This function is valid in TM1 TurboIntegrator processes only.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like DimensionTopElementInsert)
are used in the Metadata procedure of the process. TurboIntegrator automatically creates the editing
copy and applies editing operations to it, then rewrites the actual dimension at the end of the Metadata
procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
DimensionTopElementInsertDirect(DimName, InsertionPoint, ElName);

Chapter 5. TurboIntegrator Functions 303

 Argument Description

DimName The dimension for which you want to create a root

element.

InsertionPoint An existing dimension element. The root element

being added to the dimension will be inserted
immediately before this existing element.

ElName The name you want to assign to the new root

element.

Example

DimensionTopElementInsertDirect('Region', 'Netherlands', 'World');

This example adds the root element World to the Region dimension. World is inserted displays
immediately before Netherlands in the dimension definition.

DimensionUpdateDirect
DimensionUpdateDirect performs a full rewrite of a dimension that has been subject to direct editing in a
TurboIntegrator process, essentially compacting the memory footprint of the dimension.
A dimension that undergoes a series of direct-only edits (element deletions, in particular) will eventually
use more memory than its fully-rewritten counterpart would. This function can optionally be used
after directly editing a dimension with DimensionElementInsertDirect, DimensionElementDeleteDirect,
DimensionElementComponentAddDirect, DimensionElementComponentDeleteDirect, and/or
DimensionTopElementInsertDirect. Calling DimensionUpdateDirect incurs an initial full-copy memory
cost, however it can be used to guarantee that the dimension is at its smallest possible memory footprint
after processing is complete.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DimensionUpdateDirect(DimName);

Argument Description

DimName The name of the dimension you want to rewrite.

Example

DimensionUpdateDirect('Region');

This example rewrites the Region dimension.

Hierarchy Manipulation TurboIntegrator Functions

These functions facilitate hierarchy manipulation.

304 IBM Planning Analytics: Reference

CreateHierarchyByAttribute
CreateHierarchyByAttribute creates a simple 3-level hierarchy from a single attribute.
The new hierarchy consists of a single high-level root element, a middle-level of consolidations
representing existing attribute values, and a lower-level of dimension leaves that include the associated
attribute value.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.
Note: This function creates a hierarchy from the current set of attribute values, but the system does not
automatically keep the hierarchy in-sync with the attribute data as it changes. Modelers must regenerate
the hierarchy as needed.

Syntax
CreateHierarchyByAttribute(DimName, AttrName [, emptyParent [, rootName ] ] );

Argument Description

DimName The name of the dimension that contains the

attribute. A hierarchy of the same name as the
dimension will be created.

AttrName The name of the attribute to create the hierarchy

from.

emptyParent Specifies the name of a consolidation to create,

which collects dimension leaves that don't have an
attribute value. If passed as an empty string, the
function does not create a consolidation.

rootName Overrides the root element name which by default

is named after the attribute.

Example

CreateHierarchyByAttribute ('Country', 'City');

This example creates a hierarchy from the City attribute in the Country dimension.

HierarchyContainsAllLeaves
HierarchyContainsAllLeaves returns true only if the specified hierarchy contains the full set of leaf
elements that are present in the dimension. That is, it contains all the leaf elements that can be seen
in the special Leaves hierarchy. If the specified hierarchy is missing one or more leaf elements, this
function returns false.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyContainsAllLeaves(DimName, HierName);

Chapter 5. TurboIntegrator Functions 305

 Argument Description

DimName The name of the dimension that contains the all

leaves hierarchy.

HierName The name of the hierarchy you are determining as

an all leaves hierarchy.

Example

HierarchyContainsAllLeaves('Region', 'Leaves');

This example determines if the Leaves hierarchy, in the Region dimension, contains all leaf members.

HierarchyCreate
HierarchyCreate creates a new hierarchy in an existing dimension. The hierarchy cannot have the same
name as the dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyCreate(DimName, HierName);

Argument Description

DimName The name of the existing dimension that will

contain the hierarchy.

HierName The name you want to assign to the hierarchy. You

cannot use the name of the dimension.

Example

HierarchyCreate('Vehicles', 'Trucks');

This example creates the empty Trucks hierarchy in the Vehicles dimension.

HierarchyDeleteAllElements
HierarchyDeleteAllElements deletes all the elements in a hierarchy. This function is useful for recreating
dimension hierarchies.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyDeleteAllElements(DimName, HierName);

Argument Description

DimName The name of the dimension from which you want to

delete all elements.

306 IBM Planning Analytics: Reference

 Argument Description

HierName The name of the hierarchy within the dimension.

Example

HierarchyDeleteAllElements('Equipment','Helmets');

This example deletes all elements in the Helmets hierarchy in the Equipment dimension.

HierarchyDeleteElements
HierarchyDeleteElements deletes elements from a hierarchy using a subset of elements.
This function is valid only in TurboIntegrator processes.

Syntax
HierarchyDeleteElements (DimensionName, HierarchyName, Subset)

Argument Description

DimensionName The name of the dimension from which you want to

delete the subset of elements.

HierarchyName The name of the hierarchy from which you want to

delete the subset of elements.
If the indicated hierarchy is the Leaves hierarchy,
then the subset should list those leaves that
should be deleted, and they are removed
completely from the dimension.

Subset The name of the subset that contains the

elements you want to delete. The function deletes
all elements in the subset from the specified
hierarchy, whether leaf or consolidated.

HierarchyDestroy
HierarchyDestroy deletes a hierarchy from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyDestroy(DimName, HierName);

Argument Description

DimName The name of the dimension that contains the

hierarchy.

HierName The name of the hierarchy you want to delete.

Chapter 5. TurboIntegrator Functions 307

 Example

HierarchyDestroy('Product','Transmissions');

This example deletes the Transmissions hierarchy from the TM1 database.

HierarchyElementComponentAdd
HierarchyElementComponentAdd adds a component (child) to a consolidated element. You can't use this
function in the Epilog procedure of a TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementComponentAdd(DimName, HierName, ConsolidatedElName, ElName, ElWeight);

Argument Description

DimName The parent dimension of the consolidated element

to which you want to add a child.

HierName The hierarchy of the specified dimension.

ConsolidatedElName The element to which you want to add a child.

ElName The name of the child element.

ElWeight The weight of the child element.

Example
HierarchyElementComponentAdd('Measures', 'Europe', 'Net Sales', 'Expenses',
-1);
This example adds the child Expenses to the Net Sales consolidation in the Europe hierarchy of the
Measures dimension. The child has a weight of -1 in the consolidation.

HierarchyElementComponentAddDirect
HierarchyElementComponentAddDirect adds a component (child) to a consolidated element by directly
editing a dimension.
This function is valid in TM1 TurboIntegrator processes only.
The default method of editing a dimension in Cognos TM1 is to use a whole-copy editing pattern.
In that pattern, an editing copy of the dimension is created, edits are applied to the editing copy,
then finally the actual dimension is rewritten using the editing copy as a template. TurboIntegrator
supports whole-copy editing automatically whenever dimension editing TurboIntegrator functions (like
HierarchyElementComponentAdd) are used in the Metadata procedure of the process. TurboIntegrator
automatically creates the editing copy and applies editing operations to it, then rewrites the actual
dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.

308 IBM Planning Analytics: Reference

 • When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
HierarchyElementComponentAddDirect(DimName, HierName, ConsolidatedElName, ElName, ElWeight);

Argument Description

DimName The parent dimension of the consolidated element

to which you want to add a child.

HierName The hierarchy of the specified dimension.

ConsolidatedElName The consolidated element to which you want to

add a child.

ElName The name of the child element.

ElWeight The weight of the child element.

Example
HierarchyElementComponentAddDirect('Measures', 'Europe', 'Net Sales',
'Expenses', -1);
This example adds the child Expenses to the Net Sales consolidation in the Europe hierarchy of the
Measures dimension. The child has a weight of -1 in the consolidation.

HierarchyElementComponentDelete
HierarchyElementComponentDelete deletes a component (child) from a consolidated element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementComponentDelete(DimName, HierName, ConsolidatedElName, ElName);

Argument Description

DimName The parent dimension of the consolidated element

from which you want to delete a child.

HierName The name of the hierarchy within the dimension.

ConsolidatedElName The consolidated element from which you want to

delete a child.

ElName The name of the child element you want to delete.

Chapter 5. TurboIntegrator Functions 309

 Example

HierarchyElementComponentDelete('Region', 'Western', 'Benelux', 'Belgium');

This example deletes the Belgium child from the Benelux consolidation in the Western hierarchy of the
Region dimension.

HierarchyElementComponentDeleteDirect
HierarchyElementComponentDeleteDirect deletes a component (child) from a consolidated element by
directly editing the dimension.
This function is valid in TM1 TurboIntegrator processes only.
The default method of editing a dimension in TM1 is to use a whole-copy editing pattern. In
that pattern, an editing copy of the dimension is created, edits are applied to the editing copy,
then finally the actual dimension is rewritten using the editing copy as a template. TurboIntegrator
supports whole-copy editing automatically whenever dimension editing TurboIntegrator functions (like
HierarchyElementComponentDelete) are used in the Metadata procedure of the process. TurboIntegrator
automatically creates the editing copy and applies editing operations to it, then rewrites the actual
dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
HierarchyElementComponentDeleteDirect(DimName, HierName, ConsolidatedElName, ElName);

Argument Description

DimName The parent dimension of the consolidated element

from which you want to delete a child.

HierName The name of the hierarchy within the dimension.

ConsolidatedElName The consolidated element from which you want to

delete a child.

ElName The name of the child element you want to delete.

Example

HierarchyElementComponentDeleteDirect('Region', 'Western', 'Benelux', 'Belgium');

This example deletes the Belgium child from the Benelux consolidation in the Western hierarchy of the
Region dimension.

310 IBM Planning Analytics: Reference

HierarchyElementDelete
HierarchyElementDelete deletes an element from a hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementDelete(DimName, HierName, ElName);

Argument Description

DimName The dimension that contains the element you want

to delete.

HierName The name of the hierarchy within the dimension.

ElName The element you want to delete from the hierarchy.

Example

HierarchyElementDelete('Region', 'Western', 'Belgium');

This example deletes the element Belgium from the Western hierarchy in the Region dimension.

HierarchyElementDeleteDirect
HierarchyElementDeleteDirect deletes an element from a dimension by directly editing the dimension.
This function is valid in TM1 TurboIntegrator processes only.
Note: Deleting an element deletes all cube data identified by that element.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like DimensionElementDelete) are
used in the Metadata procedure of the process. TurboIntegrator automatically creates the editing copy
and applies editing operations to it, then rewrites the actual dimension at the end of the Metadata
procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
HierarchyElementDeleteDirect(DimName, HierName, ElName);

Chapter 5. TurboIntegrator Functions 311

 Argument Description

DimName The dimension that contains the element you want

to delete.

HierName The name of the hierarchy within the dimension.

ElName The element you want to delete.

Example

HierarchyElementDeleteDirect('Region', 'Western', 'Belgium');

This example deletes the element Belgium from the Western hierarchy in the Region dimension.

HierarchyElementExists
HierarchyElementExists determines whether a specific elements exists in a hierarchy on the server from
which a TurboIntegrator process is executed. The function returns 1 if the elements exists in the hierarchy
on the server, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementExists(DimName, HierName, ElemName);

Argument Description

DimName The name of the dimension that contains the

element whose existence you want to confirm.

HierName The name of the hierarchy within the dimension.

ElName The element you want to find in the hierarchy.

Example

HierarchyElementExists('Region', 'Western', 'Belgium');

This example determines whether element Belgium from the Western hierarchy in the Region dimension
exists on the server.

HierarchyElementInsert
HierarchyElementInsert adds an element to a dimension. You can use this function to add numeric,
string, or consolidated elements. You can't use this function in the Data or Epilog procedures of a
TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementInsert(DimName, HierName, InsertionPoint, ElName, ElType);

312 IBM Planning Analytics: Reference

 Argument Description

DimName The dimension to which you want to add a new

element.

HierName The name of the hierarchy within the dimension.

InsertionPoint An existing dimension element. The element

being added to the dimension will be inserted
immediately before this existing element. If this
parameter is empty, the new element is added to
the end of the dimension.

ElName The name you want to assign to the new element.

ElType The element type. There are three possible ElType

values:
N - Signifies a numeric element.
S - Signifies a string element.
C - Signifies a consolidated element.

Example

HierarchyElementInsert('Region', 'Western', 'Belgium', 'Netherlands','N');

This example adds the numeric element Netherlands to the Western hierarchy in the Region dimension.
Netherland displays immediately before Belgium in the dimension definition.

HierarchyElementInsertDirect
HierarchyElementInsertDirect adds an element to a dimension by directly editing the dimension. You can
use this function to add numeric, string, or consolidated elements.
This function is valid in TM1 TurboIntegrator processes only.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like HierarchyElementInsert) are
used in the metadata tab of the process. TurboIntegrator automatically creates the editing copy and
applies editing operations to it, then rewrites the actual dimension at the end of the Metadata procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element insertion needed
to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Chapter 5. TurboIntegrator Functions 313

 Syntax
HierarchyElementInsertDirect(DimName, HierName, InsertionPoint, ElName, ElType);

Argument Description

DimName The dimension to which you want to add a new

element.

HierName The name of the hierarchy within the dimension.

InsertionPoint An existing dimension element. The element

being added to the dimension will be inserted
immediately before this existing element. If this
parameter is empty, the new element is added to
the end of the dimension.
Note that this function is optimized for the case
where the InsertionPoint is passed as an empty
string.

ElName The name you want to assign to the new element.

ElType The element type. There are three possible ElType

values:
N - Signifies a numeric element.
S - Signifies a string element.
C - Signifies a consolidated element.

Example

HierarchyElementInsertDirect('Region', 'Western', 'Belgium', 'Netherlands','N');

This example adds the numeric element Netherlands to the Western hierarchy in the Region dimension.
Netherlands displays immediately before Belgium in the dimension definition.

HierarchyElementPrincipalName
HierarchyElementPrincipalName returns the principal name of an element or element alias.
TurboIntegrator must use principal element names when updating dimensions; element aliases cannot
be used. This function is therefore useful for determining principal element names while attempting to
update a dimension when only element aliases are available to the TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementPrincipalName( DimName, HierName, ElName )

Argument Description

DimName The name of the dimension from which you want to

retrieve a principal element name.

314 IBM Planning Analytics: Reference

 Argument Description

HierName The name of the hierarchy within the dimension.

ElName An element name. ElName can be either an

element alias or a principal element name.

Example
If ElName is not in the currently saved version of DimName, the function returns ElName.
If ElName is in DimName, whether as an element alias or a principal element name, it returns the
principal name of the element.

HierarchyExists
HierarchyExists determines whether a specific hierarchy exists on the server from which a
TurboIntegrator process is executed. The function returns 1 if the hierarchy exists on the server,
otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyExists(DimName, HierName);

Argument Description

DimName The name of the dimension that contains the

hierarchy whose existence you want to confirm.

HierName The name of the hierarchy within the dimension.

Example

HierarchyExists('Region', 'Europe');

This example determines if the Europe hierarchy, in the Region dimension, exists on the server.

HierarchyHasOrphanedLeaves
HierarchyHasOrphanedLeaves returns an integer that represents the number of members in the specified
hierarchy that are not components of a parent member in that hierarchy (that is, orphaned leaves). If
there are no members, the function returns 0.
This function is valid in TurboIntegrator processes only.

Syntax
HierarchyHasOrphanedLeaves(DimName, HierName);

Argument Description

DimName The name of the dimension that contains the

hierarchy being reviewed.

Chapter 5. TurboIntegrator Functions 315

 Argument Description

HierName The name of the hierarchy you are reviewing for

orphaned leaf members.

Example

HierarchyHasOrphanedLeaves('Region', 'Europe');

This example determines if the Europe hierarchy, in the Region dimension, contains any orphaned leaves.

HierarchySortOrder
HierarchySortOrder sets a sort type and sense for dimension elements and for components of
consolidated elements within a dimension. The sort order defined by DimensionSortOrder determines
how the subset displays in the Subset Editor.
DimensionSortOrder sets properties for a dimension; the dimension is not actually sorted until it is saved
on the server.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySortOrder(DimName, HierName, CompSortType, CompSortSense,ElSortType , ElSortSense);

Argument Description

DimName The name of the dimension for which you want to

set a sort order.

HierName The name of the hierarchy within the dimension.

CompSortType Defines how components of consolidated elements

appear in the dimension. There are two
CompSortType values:
ByInput - Retains the order in which components
were originally inserted into consolidations.
ByName - Sorts components of consolidations by
name.

CompSortSense Defines the sort sense for components of

consolidations. This is a required argument, but it
applies only when the CompSortType is ByName.
There are two possible CompSortSense values:
Ascending - Sorts components of consolidations in
ascending alphabetical order.
Descending - Sorts components of consolidations
in descending alphabetical order.

316 IBM Planning Analytics: Reference

 Argument Description

ElSortType Defines a sort order for dimension elements. There

are four possible ElSortType values:
ByInput - Retains the order in which elements
were originally inserted into the dimension.
ByName - Sorts dimension elements by name.
ByLevel - Sorts dimension elements by level.
ByHierarchy - Sorts dimension elements by
hierarchy.

ElSortSense Defines the sort sense for dimension elements.

This is a required argument, but it applies only
when the ElSortType is ByName or ByLevel. There
are two possible ElSortSense values:
Ascending - Sorts dimension elements in
ascending order, either alphabetically or by level.
Descending - Sorts dimension elements in
descending order, either alphabetically or by level.

Example

HierarchySortOrder ('Region', 'Europe', 'ByName', 'Descending','ByLevel', 'Ascending');

This example sets a sort order for the Europe hierarchy in the Region dimension. All dimension elements
are sorted by level in ascending order, and any components of consolidations are sorted in descending
alphabetical order.

HierarchyTimeLastUpdated
HierarchyTimeLastUpdated indicates when a specified dimension hierarchy was last updated. The
function returns a real number that represents the current day (including the hour, minute, second, and
millisecond) since the beginning of the year 1900.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyTimeLastUpdated(dimension, hierarchy);

Argument Description

dimension The name of the dimension.

hierarchy The name of the hierarchy.

Example

HierarchyTimeLastUpdated('Region', 'Europe');

This example returns information on when the Europe hierarchy of the Region dimension was last
updated. If a value of 42548.<hours>.<minutes>.<milliseconds> is returned, you can divide 42548 by

Chapter 5. TurboIntegrator Functions 317

 365 to obtain (approximately) 116. When added to the started of 1900, the result is a current year of
2016.

HierarchyTopElementInsert
HierarchyTopElementInsert creates a root element in a dimension. If the dimension already has a single
root, then this element will not be created.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyTopElementInsert(DimName, HierName, InsertionPoint, ElName);

Argument Description

DimName The dimension for which you want to create a root

element.

HierName The name of the hierarchy within the dimension.

InsertionPoint An existing dimension element. The root element

being added to the dimension will be inserted
immediately before this existing element.

ElName The name you want to assign to the new root

element.

Example

HierarchyTopElementInsert('Region', 'Western', 'Netherlands', 'World');

This example adds the root element World to the Western hierarchy of the Region dimension. World is
inserted displays immediately before Netherlands in the dimension definition.

HierarchyTopElementInsertDirect
HierarchyTopElementInsertDirect creates a root element in a dimension by directly editing the dimension.
If the dimension already has a single root, then this element will not be created.
This function is valid in TM1 TurboIntegrator processes only.
The default means of editing a dimension in TM1 is to use a whole-copy editing pattern. In that pattern,
an editing copy of the dimension is created, edits are applied to the editing copy, then finally the actual
dimension is rewritten using the editing copy as a template. TurboIntegrator supports whole-copy editing
automatically whenever dimension editing TurboIntegrator functions (like HierarchyTopElementInsert)
are used in the Metadata procedure of the process. TurboIntegrator automatically creates the editing
copy and applies editing operations to it, then rewrites the actual dimension at the end of the Metadata
procedure.
Direct edits are different in that no editing copy is involved. Instead, the operations are performed directly
on the actual dimension. There are two different, specialized use cases for which this type of direct
editing is intended:
• When the purpose of the TurboIntegrator process is to make a small change to a large dimension. In
this case, direct editing will be more efficient because it avoids copying and completely rewriting the
large dimension.
• When the purpose of the TurboIntegrator process is to load large volumes of data into a cube. In this
case the process' Metadata procedure is deliberately kept empty, and any element modification needed

318 IBM Planning Analytics: Reference

 to support data loading is performed using direct calls in the Data procedure. When the Metadata
procedure is empty, the process skips an entire iteration over the external datasource, which can result
in faster data loads.

Syntax
HierarchyTopElementInsertDirect(DimName, HierName, InsertionPoint, ElName);

Argument Description

DimName The dimension for which you want to create a root

element.

HierName The name of the hierarchy within the dimension.

InsertionPoint An existing dimension element. The root element

being added to the dimension will be inserted
immediately before this existing element.

ElName The name you want to assign to the new root

element.

Example

HierarchyTopElementInsertDirect('Region', 'Western', 'Netherlands', 'World');

This example adds the root element World to the Western hierarchy of the Region dimension. World is
inserted displays immediately before Netherlands in the dimension definition.

HierarchyUpdateDirect
HierarchyUpdateDirect performs a full rewrite of a hierarchy that has been subject to direct editing in a
TurboIntegrator process, essentially compacting the memory footprint of the hierarchy.
A dimension that undergoes a series of direct-only edits (element deletions, in
particular) will eventually use more memory than its fully-rewritten counterpart would.
This function can optionally be used after directly editing a dimension with
HierarchyElementInsertDirect, HierarchyElementDeleteDirect, HierarchyElementComponentAddDirect,
HierarchyElementComponentDeleteDirect, and/or HierarchyTopElementInsertDirect. Calling
HierarchyUpdateDirect incurs an initial full-copy memory cost, however it can be used to guarantee that
the dimension is at its smallest possible memory footprint after processing is complete.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyUpdateDirect(DimName, HierName);

Argument Description

DimName The name of the dimension you want to rewrite.

HierName The name of the hierarchy within the dimension.

Chapter 5. TurboIntegrator Functions 319

 Example

HierarchyUpdateDirect('Region', 'Western');

This example rewrites the Western hierarchy of the Region dimension.

ODBC TurboIntegrator Functions

These functions facilitate ODBC manipulation.

ODBCClose
ODBCClose closes a connection to an ODBC data source.
This function is valid in TurboIntegrator processes only.

Syntax
ODBCClose(Source);

Argument Description

Source The name of an open ODBC data source.

Example

ODBCClose('Accounting');

This example closes the connection to the Accounting ODBC source.

ODBCOpen
ODBCOpen opens an ODBC data source for output.
This function is valid in TurboIntegrator processes only.

Syntax
ODBCOpen(Source, ClientName, Password);

Argument Description

Source An ODBC data source name.

ClientName A valid client on the data source.

Password A password for the ClientName.

Example

ODBCOpen('Accounting', 'Jdoe', 'Bstone');

This example opens the Accounting ODBC data source for the Jdoe client using the password Bstone.

320 IBM Planning Analytics: Reference

ODBCOPENEx
ODBCOPENEx opens an ODBC data source for output specifying that the connection should be opened as
a Unicode connection.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
Format is: ODBCOPENEx (dataset name, dataset client name, client password, (use-Unicode-interface
flag) )

ODBCOpenEx(Source, ClientName, Password, UseUnicodeODBC);

Argument Description

Source An ODBC data source name.

ClientName A valid client on the data source.

Password A password for the ClientName.

UseUnicodeODBC Defines the type of Unicode connection to use.

Example

ODBCOpenEx( TestTable, sa, , 1 );

chinese= ;
chinese = CHARW( 37123 );
fieldval = chinese | SomeNewText;
sql= Update TestTable set ForeName = N | fieldval | WHERE CustomerId= 1
ODBCOUTPUT( Unicode, sql );

The result SQL statement looks like:

Update TestTable set ForeName = N?SomeNewText WHERE

CustomerId = 1

ODBCOutput
ODBCOutput executes an SQL update query against an open ODBC data source. You should use the
ODBCOpen function to open the data source before calling ODBCOutput, and use ODBCClose to close the
data source before exiting the process.
This function is valid in TurboIntegrator processes only.

Syntax
ODBCOutput(Source, SQLQuery, [SQLQuery2, SQLQuery3, ...]);

Argument Description

Source The ODBC data source against which you want to

run a query.

Chapter 5. TurboIntegrator Functions 321

 Argument Description

SQLQuery An SQL query statement.

Though ODBCOutput was developed to update
tables, it can be used to execute any SQL query
on the data source.
In circumstances where the SQL query statement
exceeds 255 characters, you should split the query
into multiple SQLQuery arguments (SQLQuery2,
SQLQuery3, etc.). This lets you create query
statements that exceed the 255 character limit for
TurboIntegrator arguments. When the ODBCOutput
function is executed, all SQLQuery arguments
are concatenated and the query is successfully
executed.

Example

ODBCOutput('Accounting', 'INSERT [CategoryID], [CategoryName]FROM Categories;');

This example executes the specified query against the Accounting data source.

SetODBCUnicodeInterface
SetODBCUnicodeInterface sets whether the ODBC interface should use the Unicode wide functions or the
regular single-byte character functions. Setting this function to 1 uses the wide character ODBC interface.
Some ODBC driver support either the older single-byte interface as well as a Unicode style 'wide-
character' interface, where characters are passed and retrieved as 16-bit quantities. If the driver chosen
does not support one or the other style, a flag is provided to force TurboIntegrator to use a particular style
of interface.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
SetODBCUnicodeInterface=1

Argument Description

1 Use the wide character ODBC interface.

0 Use the single-byte interface.

Process Control TurboIntegrator Functions

These functions pertain to process control.

ExecuteCommand
ExecuteCommand executes a command line during a process. You can use ExecuteCommand to run a
desktop application, but not a service.
If you use ExecuteCommand to run an executable, the following conditions apply:

322 IBM Planning Analytics: Reference

 • If the CommandLine argument specifies only the name of a file to be executed, a Windows server looks
for the file in both the server database directory and in the directory where [Link] resides. A UNIX
server looks for the file only in the server database directory.
• If the CommandLine argument uses a relative path prefix, both the Windows and UNIX server attempt
to locate the file in the server database directory only.
• On either the Microsoft Windows or UNIX server, you can pass an absolute path to the CommandLine
argument to execute a file in any location..
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
ExecuteCommand(CommandLine, Wait);

Argument Description

CommandLine The command line you want to execute.

Wait Indicates if the process should wait for the

command to complete execution before continuing
to the next process statement. An argument
value of 0 causes the process to proceed to the
next statement without waiting for the command
line to execute. An argument value of 1 causes
the process to wait for the command line to
successfully execute before proceeding to the next
statement.

ExecuteProcess
ExecuteProcess lets you execute a TurboIntegrator process from within another process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ExecuteProcess(ProcessName, [ParamName1, ParamValue1,ParamName2, ParamValue2]);

Argument Description

ProcessName The name of the process to be executed. This process must reside on
the same server as the process from which ExecuteProcess is called.
If the process named by this argument cannot be found at runtime, the
calling process is immediately terminated. (TurboIntegrator does not
check for a valid ProcessName at compilation.)

ParamName The name of an existing parameter of the process to be executed.

This argument is required only if the process to be executed uses
parameters.

Chapter 5. TurboIntegrator Functions 323

 Argument Description

ParamValue A valid value for the ParamName parameter. If you specify a

ParamName argument, you must specify a corresponding ParamValue.
The ParamName and ParamValue arguments must occur in ordered
pairs, with the name of the parameter followed by the value. You
must specify a ParamName and corresponding ParamValue for each
parameter of the process to be executed.

The parameter names passed in the ExecuteProcess function are matched at runtime against the
parameter names specified in the process to be executed. If the passed names cannot be found in the
parameter list of the process to be executed, a serious error results, causing the immediate termination of
the process from which ExecuteProcess is called.

Return Values
ExecuteProcess returns a real value that can be tested against one of the following return value functions:

Function Description

ProcessExitByChoreQuit() indicates that the process exited due to execution of the ChoreQuit
function

ProcessExitNormal() indicates that the process executed normally

ProcessExitMinorError() Indicates that the process executed successfully but encountered

minor errors.

ProcessExitByQuit() Indicates that the process exited because of an explicit "quit"

command.

ProcessExitWithMessage() Indicates that the process exited normally, with a message written to
[Link].

ProcessExitSeriousError() Indicates that the process exited because of a serious error.

When a process exits because of a serious error, the process
is immediately terminated and no further processing occurs. For
example, if a serious error occurs in the Data procedure, the process
immediately exits and the Epilog procedure is not executed.

ProcessExitOnInit() Indicates that the process aborted during initialization.

ProcessExitByBreak() Indicates that the process exited because it encountered a

ProcessBreak function.

Example
To record when a process called by ExecuteProcess fails because of a serious error, use code similar to
the following:

return_value = ExecuteProcess('create_sales_cube');
ASCIIOutput('C:\temp\process_return_value.txt', 'Process exited
with serious errors at', TIME, 'on', TODAY);if(return_value = ProcessExitSeriousError() )
endif;

324 IBM Planning Analytics: Reference

GetProcessErrorFileDirectory
GetProcessErrorFileDirectory returns the full pathname, with trailing slash, of the directory where
TurboIntegrator process error files are written. By default, all process error log files are written to the
data directory of the server on which the process resides.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
GetProcessErrorFileDirectory;

Arguments
None.

GetProcessErrorFilename
GetProcessErrorFilename returns the name of the TurboIntegrator process error log file associated with a
process. If the process has not yet generated an error log file, the function returns an empty (null) string.
Important: A process error log file is not generated until all statements in a given process tab (Prolog,
Metadata, Data, or Epilog) have executed. Accordingly, you can use GetProcessErrorFilename to check if
any previous tabs have generated an error log file, but you cannot use the function to determine if the
current process tab causes errors to be written to a log file.
For example, by determining that GetProcessErrorFilename returns a non-null string in the Epilog tab,
you can tell that errors were generated in the Prolog, Metadata, or Data tabs. However, you cannot use
GetProcessErrorFilename in the Data tab to determine if the Data tab generates errors.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
GetProcessErrorFilename;

Arguments
None.

GetProcessName
GetProcessName returns as a string the name of the current process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
GetProcessName()

Arguments
None.

Name = GetProcessName();

Chapter 5. TurboIntegrator Functions 325

If
The If statement allows a process to execute a statement or series of statements when a given expression
is true. You can use arithmetic operators, logical operators, and comparison operators to construct an
expression.
The TurboIntegrator If statement differs from the Rules IF function in that the TurboIntegrator statement
can accept multiple ElseIf or Else statements to evaluate multiple expressions, while the Rules IF
function can evaluate only one expression.
You can nest up to 20 If/ElseIf/Else statements in a TurboIntegrator process. If you exceed 20 nested
If/ElseIf/Else statements, you will receive an error when attempting to save the process.
This function is valid in processes only.

Syntax
If(expression);
statement1;
ElseIf(expression);
statement2;
ElseIf(expression);
statement3;
Else;
statement4;
EndIf;

Arguments
None.

Examples

If (x=5);
ASCIIOutput('c:\temp\[Link]','x equals five');
ElseIf (x=1);
ASCIIOutput ('c:\temp\[Link]', 'x equals one');
ElseIf (x=2);
ASCIIOutput ('c:\temp\[Link]', 'x equals two');
ElseIf (x=3);
ASCIIOutput ('c:\temp\[Link]', 'x equals three');
ElseIf (x=4);
ASCIIOutput ('c:\temp\[Link]', 'x equals four');
Else;
ASCIIOutput ('c:\temp\[Link]', 'x falls outside expected range');
EndIf;

This example evaluates the value of X. If X=5, the ASCIIOutput function is executed to write the string
x equals five to c:\temp\[Link]. If X does not equal 5, the first ElseIf statement is evaluated. If X=1,
the ASCIIOutput function is executed to write the string x equals one to c:\temp\[Link]. This
processing continues until the EndIf is executed.
Simple If statements can also be constructed without the use of ElseIf, as in this example:

IF(expression);
statement1;
ELSE;
statement2;
ENDIF;

ItemReject
ItemReject rejects a source record and places it in the error log, along with a specified error message.
This function is valid in TM1 TurboIntegrator processes only.

326 IBM Planning Analytics: Reference

 When ItemReject is executed in the Prolog of a process, any code following the ItemReject function in the
Prolog is skipped and the process proceeds directly to the next procedure in the TurboIntgerator process.

Syntax
ItemReject(ErrorString);

Table 6. ItemReject arguments

Argument Description

ErrorString The error message you want written to the error log
when a record is rejected.

Example

ItemReject(' Value outside of acceptable range.');

This example places a source record in the error log, along with the error message Value outside of
acceptable range. when the source record contains a value that is beyond a defined range.

ItemSkip
ItemSkip forces a process to skip the current data source item.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ItemSkip;

Arguments
None.

ProcessBreak
ProcessBreak stops processing source data and proceeds to the Epilog portion of a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessBreak;

Arguments
None.

ProcessError
ProcessError causes an immediate termination of a process.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 327

 Syntax
ProcessError;

Arguments
None.

ProcessExists
ProcessExists determines whether a specific TurboIntegrator process exists.
The ProcessExists function returns one of three possible values:
• If a TurboIntegrator process with the specified name does not exist, the function returns 0.
• If a process with the specified name does exist and is valid, the function returns 1.
• If a process with the specified name does exist, but has compilation errors, the function returns -1.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessExists(ProcessName);

Argument Description

ProcessName The name of the process for which you are trying to
determine status.

ProcessExitByChoreRollback
ProcessExitByChoreRollback initiates a chore rollback and exits with an error code. Similar to
ChoreRollback, when used inside a TurboIntegrator process, this function throws out all pending
edits and cancels further processing. An error message appears in the [Link] and
[Link] files.
When used in a single-commit mode chore, ProcessExitByChoreRollback throws out all pending edits
from all previous processes and exits.
When used in a multi-commit mode chore, ProcessExitByChoreRollback throws out all pending edits from
the current processes and then exits. Changes that have already been committed cannot be rolled back.
ProcessExitByChoreRollback returns the error code number.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessExitByChoreRollback;

Arguments
None.

ProcessExitByProcessRollback
ProcessExitByProcessRollback initiates a process rollback and exits with an error code. Similar
to ProcessRollback, when used inside a TurboIntegrator process, this function throws out all

328 IBM Planning Analytics: Reference

 pending edits and cancels further processing. An error message appears in the [Link] and
[Link] files.
When used in a single-commit mode chore, ProcessExitByProcessRollback throws out all pending edits
from all previous processes and exits.
When used in a multi-commit mode chore, ProcessExitByProcessRollback throws out all pending edits
from the current process and then exits. Changes that have already been committed cannot be rolled
back.
ProcessExitByProcessRollback returns the error code number.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessExitByProcessRollback;

Arguments
None.

ProcessQuit
ProcessQuit terminates a TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ProcessQuit;

Arguments
None.

ProcessRollback
ProcessRollback initiates a process rollback. When used inside a TurboIntegrator process, this function
throws out all pending edits and cancels further processing. An error message appears in the
[Link] and [Link] files.
Note: In IBM Planning Analytics version 2.0.8 or later, when a TurboIntegrator process rolls back and
restarts, the process is now represented in the [Link] file as three steps: starting, restarting
because of lock contention or rollback, and then finishing.
An entry is added to the [Link] file that shows the TurboIntegrator process as restarting due to
lock contention or rollback instead of just starting. This logging is enabled by default without setting any
specific debug options.
When used in a single-commit mode chore, ProcessRollback throws out all pending edits from all previous
processes and continues execution at the next process in the chore. If lock contention is encountered
after the call to ProcessRollback, the entire chore is restarted.
When used in a multi-commit mode chore, ProcessRollback throws out all pending edits from the current
process and then continues execution at the next process in the chore. Changes that have already been
committed cannot be rolled back. If lock contention is encountered after the call to ProcessRollback, only
the current process is restarted.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 329

 Syntax
ProcessRollback;

Arguments
None.

RunProcess
RunProcess lets you run TurboIntegrator processes in parallel, each on its own thread that is managed by
TM1 Server. This approach speeds up data load and other operations where TurboIntegrator processes
are used to divide the work.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
RunProcess(ProcessName, [ParamName1, ParamValue1,ParamName2, ParamValue2]);

Argument Description

ProcessName The name of the process to be run. This process must reside on the
same server as the process from which RunProcess is called.
If the process named by this argument cannot be found at runtime, the
calling process is immediately terminated. (TurboIntegrator does not
check for a valid ProcessName at compilation.)

ParamName The name of an existing parameter of the process to be run. This

argument is required only if the process to be run uses parameters.

ParamValue A valid value for the ParamName parameter. If you specify a

ParamName argument, you must specify a corresponding ParamValue.
The ParamName and ParamValue arguments must occur in ordered
pairs, with the name of the parameter followed by the value. You
must specify a ParamName and corresponding ParamValue for each
parameter of the process to be run.

The parameter names passed in the RunProcess function are matched at runtime against the parameter
names specified in the process to be run. If the passed names cannot be found in the parameter list of the
process to be run, a serious error results, causing the immediate termination of the process from which
RunProcess is called.

Return values
RunProcess returns a string. The string is the JobID, or an empty string if an error occurs.

Sleep
Use this function to pause, or 'sleep' a process for a specified interval, expressed in milliseconds.

Syntax
Sleep(ms);

330 IBM Planning Analytics: Reference

 Argument Description

ms The number of milliseconds that you want the

process to pause.

Example

# Pause the process for 3 seconds

sleep ( 3000 );

Synchronized
Synchronized is used in a TurboIntegrator script to force serial execution of a designated set of
TurboIntegrator processes.
This function is valid in TurboIntegrator processes only.

Syntax
The Synchronized function uses the following syntax.

Synchronized (lockName, nonBlocking);

Synchronized takes a single required parameter that is a user-defined name for a lock object. This lock
object name can be used in multiple TurboIntegrator processes in order to serialize their execution as a
group.

Table 7. Synchronized arguments

Argument Description
lockName The user-defined name of a lock object on which to synchronize.
Names are case-insensitive and embedded spaces are ignored. Names
may not exceed 1023 characters in length.
String/Yes/None

nonBlocking Optional. If set to 1, this function does not block if the lock object is
already in use. Instead, the function returns a value of 1. This allows
the calling process to take alternative action, such as exiting early by
using the ProcessQuit function.
If set to 0 or not defined, the function blocks normally if the lock object
is already in use.

Semantics
A TurboIntegrator process may make any number of calls to Synchronized, with any number of lock
objects. Serializing is effective from the time synchronized is called, until the containing transaction
completes.
For example, if Synchronized is called from a subprocess (Ps) of primary process (Pp) or primary chore
(Cp), the Lock Object is released when Pp or Cp completes. The exception is that a SaveDataAll (SDA)
prematurely ends a transaction mid-process execution; this applies to Lock Objects as well.
The Synchronized call can be placed anywhere within a TurboIntegrator script, but serialization applies
to the entire TurboIntegrator process when it is encountered.
Consider a TurboIntegrator process with a Synchronized call somewhere in the middle of its script, and
an operation O1 preceding that call. Two instances of this TurboIntegrator process may start at the same

Chapter 5. TurboIntegrator Functions 331

 time. It is possible for one instance to run to completion, including its call to Synchronized, before the
second instance reaches its Synchronized call. In this case, the two processes appear to the user to
have run concurrently. If, instead, the second process does reach its synchronized() call before the first
completes, it will undo any work it had done (O1) and wait for the first to complete. In this case, the two
processes appear to the user to have serialized.
To avoid such confusion, and to optimize the use of Synchronized, it is recommended (but not
enforced) that Synchronized calls be the first statements of a TurboIntegrator process.

Example
Consider that TurboIntegrator process P needs to update two cubes, Cube_1 and Cube_2.
Other TurboIntegrator processes may also need to update Cube_1 or Cube_2.
To cause all TurboIntegrator processes that will update Cube_1 or Cube_2, to run one at a time, P could
call Synchronized in this manner:

sCube_1='Cube_1';
sCube_2='Cube_2';
sE1='Elm1';
sE2='Elm2';
sE4='Units';
sE5='Price';

Synchronized( sCube_1 );
Synchronized( sCube_2 );

CellPutn( 111, sCube_1, sE1, sE2 );

CellPutn( 9.99, sCube_2, sE4, sE5 );

# ...

Other TurboIntegrator processes that will update Cube_1 or Cube_2 must also call
Synchronized( sCube_1 ) and/or Synchronized( sCube_2 ) in a similar way.
In this example, the two lock objects' names were chosen to be the same as the cubes' names. But a lock
object's name does not have to be the same as other objects (cubes, dimensions, subsets).

While
The While statement allows a process to repeat a series of statements while a given condition is true.
While statements can be nested.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
WHILE(logical expression);

statement1;

statement2;

...

statement n;

END;

Note: All WHILE statements must conclude with an END statement.

Arguments
None.

332 IBM Planning Analytics: Reference

Rules Management TurboIntegrator Functions
These functions facilitate rules management.

CubeProcessFeeders
CubeProcessFeeders reprocesses all feeders in the rules for a specified cube.
This function reprocesses all feeders in the rules for a specified cube. The feeders are normally reprocess
automatically when a rule file edit is saved, however, if the data changes, and those data changes will
change some conditional feeders, this function will need to be called to get those conditional feeders
re-evaluated.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CubeProcessFeeders(CubeName);

Argument Description

CubeName The cube for which you want to reprocess feeders.

Example

CubeProcessFeeders('2003sales');

This example reprocesses all feeders in the rules for the 2003sales cube.

CubeRuleAppend
CubeRuleAppend appends a single line of rule text to a Planning Analytics cube rule.
Essentially, this function adds a single line of text to a rule (.rux) file. The line of text is typically a rule
statement, but can also be a comment. If there is no rule associated with the cube at the time this
function is executed, a new rule is created, containing only the passed line.
This function is valid only in Planning Analytics processes.

Syntax
CubeRuleAppend(CubeName, RuleText, IsCalculationRule);

Argument Description

CubeName The name of the cube associated with the rule to

which you want to append a line of text.

Chapter 5. TurboIntegrator Functions 333

 Argument Description

RuleText The single line of text you want to append to the

rule.
The entire line of text you add must be enclosed
in single quotes and must adhere to rules syntax
conventions.
If the line of text includes any element references,
the element names must be enclosed in double
single quotes to escape the single quotes that
normally enclose element names. For example,
a reference to an element named CL3 must be
specified as [''CL3''].
The following are examples of valid lines of text
you might append to a rule:
'[''CL3''] = [''CL4''] + [''Trial''];'
'skipcheck;'
'[''Trial''] => [''CL3''];'

IsCalculationRule The IsCalculationRule parameter declares whether

the line should be inserted just before any feeder
section that might exist in the cube rule. If the
IsCalculationRule parameter is omitted, or passed
as 0.0, then the new line will simply be appended
to the end of the rule.
Because rule (.rux) files consist of a calculation
section followed by an optional feeder section,
any appended lines that are calculation rule
statements (or corresponding comments) should
use a 1.0 for this argument to ensure that the new
line is inserted in at the appropriate location in the
rule file.

Examples

CubeRuleAppend( 'MyCube', '[''CL3''] = [''CL4''] + [''Trial''];', 1.0 );

This example inserts the calculation statement ['CL3'] = ['CL4'] + ['Trial']; at the end of the
calculation section of the rule for the MyCube cube.

CubeRuleAppend( 'MyCube', '[''Trial''] => [''CL3''];', 0.0 );

This example inserts the feeder statement ['Trial'] => ['CL3']; at the end of the rule for the
MyCube cube.

CubeRuleDestroy
CubeRuleDestroy deletes any rule that exists for a specified cube.
This function is valid in TM1 TurboIntegrator processes only.

334 IBM Planning Analytics: Reference

 Syntax
CubeRuleDestroy(CubeName);

Argument Description

CubeName The name of the cube associated with the rule that
you want to delete

Example

CubeRuleDestroy('SalesProjections');

This example deletes the rule for the SalesProjectionscube.

CubeRuleGet
CubeRuleGet retrieves a specified cube rule as a single string. This function is valid only in Planning
Analytics processes.

Syntax
CubeRuleGet(RuleName);

Argument Description

RuleName The name of the rule that you want to retrieve. You
do not need to specify the .rux file extension.
The rule must exist on the database where the
process is executed.

Example
CubeRuleGet('RevenueRule');
The RevenueRule contains these three lines:

['Gross Margin %']=c: (['Gross Margin']\['Gross Revenue'])*100;

['Unit Price'] = c: ['Gross Revenue']\['Units Sold'];
['Unit Cost'] = c: ['Cost of Sales']\['Units Sold'];

The example returns this single string:

'['Gross Margin %']=c: (['Gross Margin']\['Gross Revenue'])*100; ['Unit Price']
= c: ['Gross Revenue']\['Units Sold']; ['Unit Cost'] = c: ['Cost of Sales']\
['Units Sold'];'

CubeRuleSet
CubeRuleSet replaces the content of a cube rule with a specified string. This function is valid only in
Planning Analytics processes.

Syntax
CubeRuleSet(RuleName, RuleString);

Chapter 5. TurboIntegrator Functions 335

 Argument Description

RuleName The name of the cube rule for which you want
to replace content. You do not need to specify
the .rux file extension.
If the rule does not exist on the database where
the process is executed, a new rule is created
upon execution of this function, containing the rule
statements included in the RuleString.

RuleString A single text string containing the rules statements

that you want to write to the cube rule.
The entire string must be enclosed in single quotes
and must adhere to rules syntax conventions.
If the string includes any member references, the
member names must be enclosed in double single
quotes to escape the single quotes that normally
enclose member names in a rule. For example,
a reference to a member named CL3 must be
specified as [''CL3'']

Example
CubeRuleSet('RevenueRule', '[''Gross Margin %'']=c: ([''Gross Margin'']\
[''Gross Revenue''])*100; [''Unit Price''] = c: [''Gross Revenue'']\[''Units
Sold'']; [''Unit Cost''] = c: [''Cost of Sales'']\[''Units Sold''];');
Note that all member references in the RuleString are enclosed in double single quotes to escape the
single quotes that normally enclose member names.
This example replaces any existing content in RevenueRule with these three lines:

['Gross Margin %']=c: (['Gross Margin']\['Gross Revenue'])*100;

['Unit Price'] = c: ['Gross Revenue']\['Units Sold'];
['Unit Cost'] = c: ['Cost of Sales']\['Units Sold'];

If RevenueRule does not already exist, it is created on the database where the process is executed.

DeleteAllPersistentFeeders
DeleteAllPersistentFeeders deletes any .feeder files that have persisted. When this function is used, all
cubes are marked as "do not save feeders" so a subsequent SaveData will not persist feeders which
means all feeders will be re-calculated on a server re-start.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DeleteAllPersistentFeeders;

Arguments
None.

336 IBM Planning Analytics: Reference

ForceSkipCheck
ForceSkipCheck forces the query to perform as if the cube had a SKIPCHECK in the rules.
This function is valid in TM1 TurboIntegrator processes only.
This means that the query will process only values actually in the cube, as opposed to (the no SKIPCHECK
case) where every possible cell would be enumerated looking for values. This function sets the state of
the view query to select only values in the cube. The function must be added to the Prolog section of the
TurboIntegrator process. By placing the ForceSkipCheck() in the Prolog it effects the entire view query of
data elements to follow.

Syntax
ForceSkipCheck()

Arguments
None.

RuleLoadFromFile
RuleLoadFromFile creates a TM1 rule for a specified cube from a text file. Each rule statement must end
with a semi-colon (;) and comments must be prefixed with the # character. If a rule already exists for the
specified cube, the rule is overwritten by the rule created by RuleLoadFromFile.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
RuleLoadFromFile(Cube, TextFile);

Argument Description

Cube The name of the cube for which you want to create
a rule.

TextFile The name of the text file from which you want to
create a rule.
You can specify the full path to this file, including
file name and extension. (Refer to Example 1.)
If you specify only the file name and extension,
TurboIntegrator looks for the file in the server's
data directory.
If you do not specify a file extension,
TurboIntegrator assumes the .rux extension by
default. (Refer to Example 2.)

If you leave the TextFile argument empty, TurboIntegrator looks for a source file with the same name as
the cube (but with a .rux extension) in the server's data directory. (Refer to Example 3.)

Chapter 5. TurboIntegrator Functions 337

 Example 1:
The following example uses the contents of the [Link] file in the C:\temp directory to create a rule
for the Sales cube:

RuleLoadFromFile('Sales', 'C:\temp\[Link]');

Example 2:
This example creates a rule for the Sales cube using the file named [Link] in the server's data
directory:

RuleLoadFromFile('Sales', 'cuberule');

Example 3:
This example creates a rule for the Sales cube using the file named [Link] in the server's data
directory:

RuleLoadFromFile('Sales', ' ');

RuleLoadFromFileEx
RuleLoadFromFileEx creates a Planning Analytics rule for a specified cube from a text file using a
specified character set. Each rule statement in the text file must end with a semi-colon (;) and comments
must be prefixed with the # character. If a rule already exists for the specified cube, the rule is
overwritten by the rule created by RuleLoadFromFileEx.
This function is valid in TurboIntegrator processes only.
This function is similar to the “RuleLoadFromFile” on page 337 function, but provides the ability to specify
the character encoding used in the text file.

Syntax
RuleLoadFromFileEx(Cube, TextFile, CharacterSet);

Argument Description

Cube The name of the cube for which you want to create
a rule.

TextFile The name of the text file from which you want to
create a rule.
You can specify the full path to this file, including
file name and extension.
If you specify only the file name and extension,
TurboIntegrator looks for the file in the server's
data directory.
If you do not specify a file extension,
TurboIntegrator assumes the .rux extension by
default.

CharacterSet The character encoding used in the TextFile. For

a list of valid values, refer to this table.

338 IBM Planning Analytics: Reference

 Example
This example uses the contents of the [Link] file in the C:\temp directory to create a rule for
the Sales cube, specifying that [Link] uses TM1CS_EUC_CN (EUC Simplified Chinese) character
encoding.
RuleLoadFromFileEx('Sales', 'C:\temp\[Link]', 'TM1CS_EUC_CN');

Sandbox Functions
These functions are used with sandboxes.

GetUseActiveSandboxProperty
GetUseActiveSandboxProperty returns a Boolean value that indicates whether a process reads and writes
data to the base data or to the user's active sandbox.
This function is valid in TM1 TurboIntegrator processes only.
The default is for processes to read and write to the base data.
• If the return is 0, the process is currently reading and writing to the base data.
• If the return is 1, the process is currently reading and writing to the active sandbox.
Note: This function returns the permanent value for this property as set in the Architect / Server
Explorer user interface unlessyou have used the SetUseActiveSandboxProperty function in the process.
In that case, the value for this property is determined by the value that was last set with the
SetUseActiveSandboxProperty function.

Syntax
GetUseActiveSandboxProperty()

Arguments
None.

Example

return_value = GetUseActiveSandboxProperty();

This example will return a Boolean value indicating whether the process is currently reading and writing
cube data to the active sandbox or to the base data.

ServerActiveSandboxGet
ServerActiveSandboxGet returns the name of the user's active sandbox. If the user has no active sandbox,
an empty string is returned. Because chores run in the context of a special admin user, and can have no
active sandbox, this function always returns an empty string when executed using a chore.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerActiveSandboxGet();

Arguments
None.

Chapter 5. TurboIntegrator Functions 339

 Example

return_value = ServerActiveSandboxGet();

This example will return the active sandbox of the user executing the TI process in which the function call
is made.

ServerActiveSandboxSet
ServerActiveSandboxSet sets the active sandbox of the executing user. An empty string is used to clear
the executing user's active sandbox. This function throws an error if the executing user does not own a
sandbox with the passed name.
Because chores run in the context of a special admin user, and can have no active sandbox, this function
always throws an error when executed using a chore.
Note: For a TurboIntegrator process to read and write values in the context of the executing user's active
sandbox, the UseActiveSandbox property must be set. See “GetUseActiveSandboxProperty” on page 339
and “SetUseActiveSandboxProperty” on page 348.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerActiveSandboxSet(SandboxName)

Argument Description

SandboxName A string value. The name of a sandbox owned by

the executing user.

Example: Set the executing user's active sandbox to "Best case"

ServerActiveSandboxSet('Best case');

Example: Clear the executing user's active sandbox and set context back to the base data

ServerActiveSandboxSet('');

ServerSandboxClone
ServerSandboxClone clones an existing sandbox into a new sandbox.
Sandboxes are private workspaces in which a user can enter and store data values separate from TM1
base data. Sandboxes are stored on disk and, when in use, in memory.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxClone(sandboxName,newSandboxName );

Argument Description

sandboxName A string value. The name of a sandbox owned by

the executing user.

newSandboxName A string value. The name of a sandbox to be

created as a clone of sandboxName.

340 IBM Planning Analytics: Reference

 Example

ServerSandboxClone( 'Best case', 'Second best case');

ServerSandboxCreate
ServerSandboxCreate creates a new sandbox.
Sandboxes are private workspaces in which a user can enter and store data values separate from TM1
base data. Sandboxes are stored on disk and, when in use, in memory.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxCreate( sandboxName );

Argument Description

sandboxName A string value. The name of a sandbox to be

created.

Example

ServerSandboxCreate( 'My sandbox' );

ServerSandboxesDelete
ServerSandboxesDelete allows administrators to discard user sandboxes that match certain criteria.
Sandboxes are private workspaces in which a user can enter and store data values separate from TM1
base data. Sandboxes are stored on disk and, when in use, in memory.
This function operates server side and is available through TurboIntegrator and the API function
ServerSandboxesDelete. Using this feature in a TurboIntegrator process, administrators can schedule
maintenance using automated chores.
This function is valid in TM1 TurboIntegrator processes only.

Description
This function uses a "predicate" to describe the sandbox being deleted. A predicate can be read as:
"Delete sandboxes whose attribute is condition value."
For example: "Delete sandboxes whose size is greater than 10 MB." In this example, the attribute is the
"size" of the sandbox, the condition is "greater than", and the value is "10 MB".
There are two optional delimiter character parameters to the TurboIntegrator function. Because a
sandbox has no restrictions on which characters can be used in their name, administrators can supply
their own "safe" delimiter when needed.
For example, ServerSandboxesDelete( 'client:=:Admin, name:=:best case
scenario' );"
In the following example, the colon character is used in the sandbox name ("best::case::scenario") so
another delimiter is needed:

ServerSandboxesDelete( 'client|=|Admin# name|=|best::case::scenario', '|', '#' );"

Note: The exact syntax of a predicate differs between the TurbIntegrator and API forms of this function.

Chapter 5. TurboIntegrator Functions 341

 Syntax
ServerSandboxesDelete(string,string,string)

Argument Description

Predicates The name of the process to be executed. This process must reside on
the same server as the process from which RunProcess is called.
Required
String
No default
An arbitrary length list of predicates. Each predicate is a string
containing three tokens. The first token indicates an attribute of a
sandbox. The second indicates a condition, for example ">" or "=". The
third token is a possible value of the attribute on which sandboxes
should be conditionally filtered. The entire string may not exceed
10,000 characters in length.

PredicateDelimiter Optional
String
default is : (colon)
Optional delimiter character.
The string may not exceed 1 character in length.

PredicateListDelimiter Optional
String
default is , (comma)
Optional delimiter character.
The string may not exceed 1 character in length.

Filter Attributes
Filter attributes are properties of a sandbox on which it can be conditionally matched. Attribute names
and their corresponding valid conditions are case insensitive and ignore embedded whitespace. For
example, the following two calls are both valid:
ServerSandboxesDelete( 'client:=:Admin' );
ServerSandboxesDelete( 'C L I E N T : = :Admin' );

Table 8. Filter Attributes

Valid
Attribute Description Conditions Value Type
UpdateDate Timestamp of the last <, =, >. Timestamp in international standard
write action performed in format, i.e. YYYY-MM-DD. Days are the
the sandbox. most granular units.
AccessDate Timestamp of the last <, =, >. Timestamp in international standard
unload of a sandbox. format, i.e. YYYY-MM-DD. Days are the
most granular units.

342 IBM Planning Analytics: Reference

Table 8. Filter Attributes (continued)
Valid
Attribute Description Conditions Value Type
CreationDate Timestamp of the creation <, =, >. Timestamp in international standard
of a sandbox. format, i.e. YYYY-MM-DD. Days are the
most granular units.
Size The in-memory size of a <, =, >. Size following log4cxx's conversion
sandbox. rules (see configuration parameter
AuditLogMaxTemp FileSize) For example,
10 MB. Kilobytes are the most granular
units.
Name The name of a sandbox. =, String.
containing.
Client The owning client of a =. String.
sandbox.
Group A group of which the =. String.
owning client of a sandbox
is a member.

Logging and Returns

Sandbox deletion is logged using the preexisting audit logging functionality. Additionally, a more detailed
report of the effects of sandbox administration is included in the debug log ([Link]) at INFO level.
This report will include the list of affected sandboxes, as well as some of their attributes, and any errors
encountered.
ServerSandboxesDelete returns only a success or failure status.

Semantics
Predicate List
Multiple predicates passed in a single call to ServerSandboxesDelete are conjunctive. In other
words, for a sandbox to match the passed criteria, all predicates must be true. Multiple calls to
ServerSandboxesDelete can be used to achieve disjunctive behavior. Only one occurrence of each
attribute is allowed per call to ServerSandboxesDelete. For example, passing client twice is invalid
as a sandbox has only one owning client. When multiple occurrences of an attribute are detected, a
warning displays in the detailed report, however, the operation will not abort in failure. In such a case,
the predicates are tested as with any other query, but the results set is always empty.
Locking
To avoid massive locking issues, ServerSandboxesDelete looks at the sandboxes of a client as a
point-in-time snapshot and then, when possible, release any locks that would ensure a serializable
transaction. Because of this behavior, once a client is "passed" in the iteration of all clients, a sandbox
matching the filter criteria may be added to that client before the maintenance transaction completes.
This behavior is similar to the behavior that occurs when a sandbox is added to the client immediately
after the transaction completes.
Scope
Members of the ADMIN (super-user) and the DataAdmin groups will have access to all sandboxes
of all clients. They must explicitly specify the client attribute to limit the scope of their call to
ServerSandboxesDelete to only their own sandboxes. All other users have access to only their own
sandboxes; if they specify a different client, or a group to which they do not belong, the function will
abort in failure and return a privilege error.

Chapter 5. TurboIntegrator Functions 343

 In-Use Sandboxes
When a sandbox meets the criteria for deletion, but is currently in use, that sandbox will not be
deleted. An entry will appear in the debug log info-level report indicating the occurrence.
Access and Update Dates
Date attributes can be matches with, at most, day granularity. Because of this restriction, recording of
these attributes is correspondingly granular. Last Update Date is not updated on individual cell writes.
Instead, the system records the unload date of a sandbox that has had something written to it while
it was loaded in memory. For such sandboxes, Last Access Date and Last Update Date will be the
same. Only Last Access Date is updated on the unloading of a sandbox from memory. Also, because
in-memory sandboxes are not subject to ServerSandboxesDelete, Last Access Date is not updated
when a sandbox is loaded into memory.
For example, consider the follow usage scenario:

Table 9. Last Access Day Example

Day Time Action
1 1 Load Sandbox S
1 2 Write 1
2 3 Read 1
2 4 Unload Sandbox

A user is working with sandbox over the course of two days (perhaps for a much shorter period
encompassing the day change.) At time 4, when the sandbox is unloaded, Last Update Date is set to
2, rather than 1 where the last update actually occurred. Last Access Date is also set to 2 at time 4 in
this case. If Write1 were instead a read, only Last Access Date would be set to 2, while Last Update
Date wouldn't be changed.

Example

ServerSandboxesDelete( 'client:=:Admin, name:=:best case scenario' );

ServerSandboxDiscardAllChanges
ServerSandboxDiscardAllChanges discards all changes in an existing sandbox.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxDiscardAllChanges( sandboxName );

Argument Description

sandboxName A string value. The name of a sandbox owned by

the executing user.

Example

ServerSandboxDiscardAllChanges( 'MySandbox' );

344 IBM Planning Analytics: Reference

ServerSandboxMerge
ServerSandboxMerge merges a source sandbox into an existing target sandbox. If the target sandbox is
not specified, the source sandbox is merged into base.
Sandboxes are private workspaces in which a user can enter and store data values separate from TM1
base data. Sandboxes are stored on disk and, when in use, in memory.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxMerge( src, tgt, conflictRes, waitForLocks);

Argument Description

src The name of the source sandbox owned by the executing user to be
merged with the <tgt> sandbox.
The <src> sandbox is not changed.
Required
String

tgt The name of a sandbox owned by the executing user to be merged with
the <src> sandbox.
The <tgt> sandbox is updated.
If <tgt> is blank, you are merging <src> with base data and updating
base.
Required. To leave this parameter blank, use 2 concatenated single
quotes: ''.
String

conflictRes The <conflictRes> parameter is ignored.

Optional
Numeric

waitForLocks The <waitForlocks> parameter is an integer that indicates whether to

wait for locks to guarantee serialization.
1 means wait for locks, catch any conflict exceptions, and retry instead
of allowing the chore or process to roll back.
0 means do not wait for locks. Allow exceptions that cause rollback.
Optional
Numeric

Example
Merge mySandbox to base.

ServerSandboxMerge(mySandbox, '');

Chapter 5. TurboIntegrator Functions 345

ServerSandboxExists
ServerSandboxExists tests for the existence of the passed sandbox. 1 is returned when the passed
sandbox exists, 0 otherwise.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxExists( sandboxname )

or

ServerSandboxExists( sandboxname , username )

Arguments
The name of the sandbox whose existence is being tested. ServerSandboxExists takes an optional
string parameter, the owning client's name. The calling client can use the optional parameter to specify
a client other than themselves if the calling client has the appropriate privileges. A privilege error will
result if the specified client is not the executing client and the executing client is not a member of the
DataAdmin or ADMIN groups. If the optional parameter is not used, the active client's sandboxes are the
subject.

Example
The following snippet shows how the ServerSandboxExists, ServerSandboxGet, and
ServerSandboxListCountGet functions can be used to iterate the sandboxes of user called User1
and output those sandboxes to a text file. The TurboIntegrator process would successfully execute for
members of the Admin or Data Admin groups and for user called User1. The TurboIntegrator process
would fail with a privilege error for any other users.

SandboxIndex = 1;
NumSandboxes = ServerSandboxListCountGet( 'User1' );

WHILE( SandboxIndex <= NumSandboxes );

SandboxName = ServerSandboxGet( SandboxIndex, 'User1' );

IF( ServerSandboxExists( SandboxName, 'User1' ) = 1 );

ASCIIOUTPUT( 'C:\[Link]', SandboxName );

ENDIF;

SandboxIndex = SandboxIndex + 1;

END;

ServerSandboxGet
ServerSandboxGet returns the name of the sandbox identified by the number N, where N is the parameter
entered.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxGet( index )

or

ServerSandboxGet( index, username)

346 IBM Planning Analytics: Reference

 Arguments
The index of the requested sandbox in the user's sandbox collection. The index space will be contiguous,
so the first occurrence of an empty string return can be used to break iteration. Also, deleting a sandbox
will alter the indexes of any sandboxes that follow that sandbox in the list.
ServerSandboxGet takes an optional string parameter, the owning client's name. The calling client
can use the optional parameter to specify a client other than themselves if the calling client has the
appropriate privileges. A privilege error will result if the specified client is not the executing client and
the executing client is not a member of the DataAdmin or ADMIN groups. If the optional parameter is not
used, the active client's sandboxes are the subject.

Example
The following snippet shows how the ServerSandboxExists, ServerSandboxGet, and
ServerSandboxListCountGet functions can be used to iterate the sandboxes of user called User1
and output those sandboxes to a text file. The TurboIntegrator process would successfully execute for
members of the Admin or Data Admin groups and for user called User1. The TurboIntegrator process
would fail with a privilege error for any other users.

SandboxIndex = 1;
NumSandboxes = ServerSandboxListCountGet( 'User1' );

WHILE( SandboxIndex <= NumSandboxes );

SandboxName = ServerSandboxGet( SandboxIndex, 'User1' );

IF( ServerSandboxExists( SandboxName, 'User1' ) = 1 );

ASCIIOUTPUT( 'C:\[Link]', SandboxName );

ENDIF;

SandboxIndex = SandboxIndex + 1;

END;

ServerSandboxListCountGet
ServerSandboxListCountGet returns the count of sandboxes as a number.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerSandboxListCountGet()

or

ServerSandboxListCountGet( username )

Arguments
ServerSandboxListCountGet takes an optional string parameter, the owning client's name. The
calling client can use the optional parameter to specify a client other than themselves if the calling client
has the appropriate privileges. A privilege error will result if the specified client is not the executing client
and the executing client is not a member of the DataAdmin or ADMIN groups. If the optional parameter is
not used, the active client's sandboxes are the subject.

Example
The following snippet shows how the ServerSandboxExists, ServerSandboxGet, and
ServerSandboxListCountGet functions can be used to iterate the sandboxes of user called User1

Chapter 5. TurboIntegrator Functions 347

 and output those sandboxes to a text file. The TurboIntegrator process would successfully execute for
members of the Admin or Data Admin groups and for user called User1. The TurboIntegrator process
would fail with a privilege error for any other users.

SandboxIndex = 1;
NumSandboxes = ServerSandboxListCountGet( 'User1' );

WHILE( SandboxIndex <= NumSandboxes );

SandboxName = ServerSandboxGet( SandboxIndex, 'User1' );

IF( ServerSandboxExists( SandboxName, 'User1' ) = 1 );

ASCIIOUTPUT( 'C:\[Link]', SandboxName );

ENDIF;

SandboxIndex = SandboxIndex + 1;

END;

SetUseActiveSandboxProperty
SetUseActiveSandboxProperty controls whether a process reads and writes cube data to the base data or
to the user's active sandbox. The default is for processes to read and write to the base data.
The scope of this function applies only to the current running process and temporarily overrides the
permanent value for this property that is set in the Architect / Server Explorer user interface.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SetUseActiveSandboxProperty(PropertyValue)

Argument Description

PropertyValue A Boolean value that indicates whether the process

should use the active sandbox context when
reading and writing cube data.
If PropertyValue = 0, the process will disregard the
active sandbox context and read/write to the base
data.
If PropertyValue = 1, the process will read/write
cube data to the active sandbox.

Example

SetUseActiveSandboxProperty(1);

This example will cause the process to read/write cube data to the active sandbox for the rest of this
execution.

Security TurboIntegrator Functions

These functions pertain to security.

348 IBM Planning Analytics: Reference

AddClient
AddClient creates a new client on the server. Changes applied through the AddClient functions do not take
effect until the Metadata procedure in a process is completed. This function, like all functions that update
metadata, should not be used in the Data or Epilog tabs of a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AddClient(ClientName);

Argument Description

ClientName The name of the client you want to add to the

server.
The client name is limited to 255 characters/bytes.

Example

AddClient('Brian');

This example adds the client Brian to the server.

AddGroup
AddGroup creates a new user group on the server. Changes applied through the AddGroup function do not
take effect until the Metadata procedure in a process is completed. This function, like all functions that
update metadata, should not be used in the Data or Epilog tabs of a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AddGroup(GroupName);

Argument Description

GroupName The name of the group you want to create.

Example

AddGroup('Finance');

This function adds the Finance user group to the server.

AssignClientToGroup
AssignClientToGroup assigns an existing client on a server to an existing user group. This function assigns
an existing client on a server to an existing user group.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
AssignClientToGroup(ClientName, GroupName);

Chapter 5. TurboIntegrator Functions 349

 Argument Description

ClientName The name of the client you want to assign to a

group.

GroupName The group to which you want to assign the client.

Example

AssignClientToGroup('Brian', 'Finance');

This example assigns the existing client Brian to the existing user group Finance.

AssignClientPassword
AssignClientPassword assigns a password to an existing client on a server. AssignClientPassword returns
1 if the password assignment is successful and returns 0 if the assignment fails.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
AssignClientPassword (ClientName, Password);

Argument Description

ClientName The name of the client for which you want to assign
a password.

Password The password you want to assign to the client.

When assigning a password, use plain text. TM1
will encrypt the password on the server.
Passwords must be at least five characters in
length.

Example

AssignClientPassword ('Brian', 'flyfisher');

This example assigns the password 'flyfisher' to the client named Brian.

AssociateCAMIDToGroup
AssociateCAMIDToGroup creates an association between a TM1 user group and a CAMID.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
AssociateCAMIDToGroup(GroupName, CAMID, CAMIDDisplayValue);

350 IBM Planning Analytics: Reference

 Argument Description

GroupName The name of the TM1 group you want to associate

with the CAMID.

CAMID The name of the CAMID group. If the

CAMID does not exist, it will be created in
the }ClientCAMAssociatedGroups control cube.

CAMIDDefDisplayValue The alias of the CAMID group.

CellSecurityCubeCreate
CellSecurityCubeCreate creates a security cube from an existing cube using a reduced set of dimensions.
This function, like all functions that update metadata, should not be used in the Data or Epilog tabs of a
process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellSecurityCubeCreate (‘DataCube’, ‘0:0:1:0’);

Argument Description

Cube Name of the data cube.

DimensionMap String specifying whether the dimension at each

position should be used in the security cube. The
order of dimensions is the original cube order. A
1 for each included dimension and a 0 for an
excluded one. Each value separated by a colon.

Boolean return True if the operation succeeded. A major error

otherwise.

Additional information The GrantSecurityAccess property must be set for

this TurboIntegrator process to succeed. Creates
the cell security cube.

Example

CellSecurityCubeCreate (‘DataCube’, ‘0:0:1:0’);

This example creates an RDCLS cube from the cube called Data Cube.

CellSecurityCubeDestroy
CellSecurityCubeDestroy destroys a security cube that was created from an existing cube. This function,
like all functions that update metadata, should not be used in the Data or Epilog tabs of a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
CellSecurityCubeDestroy (‘DataCube’, ‘0:0:1:0’);

Chapter 5. TurboIntegrator Functions 351

 Argument Description

Cube Name of the data cube.

Boolean return True if the operation succeeded. A major error

otherwise.

Additional information The GrantSecurityAccess property must be set for

this TurboIntegrator process to succeed. Destroys
the cell security cube.

Example

CellSecurityCubeDestroy (‘DataCube’);

DeleteClient
DeleteClient deletes a client from the server. Changes applied through the DeleteClient function do not
take effect until the Metadata procedure in a process is completed. This function, like all functions that
update metadata, should not be used in the Data or Epilog tabs of a process
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DeleteClient(ClientName);

Argument Description

ClientName The name of the client you want to delete from the
server.

Example

DeleteClient('Brian');

This example removes the client Brian from the server.

DeleteGroup
DeleteGroup deletes a user group from the server. Changes applied through the DeleteGroup function do
not take effect until the Metadata procedure in a process is completed. This function, like all functions
that update metadata, should not be used in the Data or Epilog tabs of a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
DeleteGroup(GroupName);

Argument Description

GroupName The group you want to delete.

352 IBM Planning Analytics: Reference

 Example

DeleteGroup('Finance');

This example deletes the Finance user group from the server.

ElementSecurityGet
ElementSecurityGet retrieves the security level assigned to a specified group for a dimension element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementSecurityGet(DimName, ElName, Group);

Argument Description

DimName The parent dimension of the element for which you

are retrieving a security level.

ElName The element for which you are retrieving a security

level.

Group The user group for which you are retrieving a

security level.

Example

ElementSecurityGet('Region', 'Germany', 'Budgeting');

This example returns the security level assigned to the Budgeting user group for the Germany element of
the Region dimension.

ElementSecurityPut
ElementSecurityPut assigns a security level to a specified group for a dimension element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ElementSecurityPut(Level, DimName, ElName, Group);

Argument Description

Level The security level you are assigning. There are six
possible Level values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

Chapter 5. TurboIntegrator Functions 353

 Argument Description

DimName The parent dimension of the element for which you

are assigning a security level.

ElName The element for which you are assigning a security

level.

Group The user group for which you are assigning a

security level.

Example

ElementSecurityPut('Reserve', 'Region', 'Germany', 'Budgeting');

This example assigns Reserve security to the Budgeting group for the Germany element of the Region
dimension.

HierarchyElementSecurityGet
HierarchyElementSecurityGet retrieves the security level assigned to a specified group for a dimension
element.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchyElementSecurityGet(DimName, HierName, ElName, Group);

Argument Description

DimName The parent dimension of the element for which you

are retrieving a security level.

HierName The name of the hierarchy within the dimension.

ElName The element for which you are retrieving a security

level.

Group The user group for which you are retrieving a

security level.

Example

HierarchyElementSecurityGet('Region', 'Europe', 'Germany', 'Budgeting');

This example returns the security level assigned to the Budgeting user group for the Germany element.
The element appears in the Europe hierarchy of the Region dimension.

HierarchyElementSecurityPut
HierarchyElementSecurityPut assigns a security level to a specified group for a dimension element.
This function is valid in TM1 TurboIntegrator processes only.

354 IBM Planning Analytics: Reference

 Syntax
HierarchyElementSecurityPut(Level, DimName, HierName, ElName, Group);

Argument Description

Level The security level you are assigning. There are six
possible Level values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

DimName The parent dimension of the element for which you

are assigning a security level.

HierName The name of the hierarchy within the dimension.

ElName The element for which you are assigning a security

level.

Group The user group for which you are assigning a

security level.

Example

HierarchyElementSecurityPut('Reserve', 'Region', 'Europe', 'Germany', 'Budgeting');

This example assigns Reserve security to the Budgeting group for the Germany element. The element
appears in the Europe hierarchy of the Region dimension.

RemoveCAMIDAssociation
RemoveCAMIDAssociation removes all associations between TM1 user groups and a specified CAMID.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
RemoveCAMIDAssociation(CAMID, RemoveCAMID);

Argument Description

CAMID The name of the CAMID group for which you want
to remove all security associations.

Chapter 5. TurboIntegrator Functions 355

 Argument Description

RemoveCAMID Determines if the specified CAMID is deleted from

the }ClientCAMAssociatedGroups control cube.
0 leaves the CAMID in
the }ClientCAMAssociatedGroups control cube.
1 deletes the CAMID from
the }ClientCAMAssociatedGroups control cube.

RemoveCAMIDAssociationFromGroup
RemoveCAMIDAssociationFromGroup removes an association between a TM1 user group and a CAMID.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
RemoveCAMIDAssociationFromGroup(GroupName, CAMID);

Argument Description

GroupName The name of the TM1 user group for which you
want to remove the association.

CAMID The name of the CAMID group for which you want
to remove the association.

RemoveClientFromGroup
RemoveClientFromGroup removes a specified client from a user group.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
RemoveClientFromGroup(ClientName, GroupName);

Argument Description

ClientName The client you want to remove.

GroupName The user group from which you want to remove the
client.

Example

RemoveClientFromGroup('Brian', 'Finance');

This example removes the client Brian from the Finance user group.

356 IBM Planning Analytics: Reference

SetHierarchyGroupsSecurity
SetHierarchyGroupsSecurity sets the security level for all existing groups for the specified dimension
hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SetHierarchyGroupsSecurity(securityLevel, dimension, hierarchy)

Argument Description

securityLevel The security level that you are assigning. There are
six possible values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

dimension Name of the dimension.

hierarchy Name of the dimension hierarchy.

Example

SetHierarchyGroupsSecurity('Reserve', 'Region', 'Europe');

This example assigns Reserve security to all existing groups in the Europe hierarchy of the Region
dimension.

SetHierarchyElementGroupsSecurity
SetHierarchyElementGroupsSecurity sets the security level for a specified element from a hierarchy in a
dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SetHierarchyElementGroupsSecurity(securityLevel, dimension, hierarchy, element)

Chapter 5. TurboIntegrator Functions 357

 Argument Description

securityLevel The security level you are assigning. There are six
possible values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

dimension Name of the dimension.

hierarchy Name of the dimension hierarchy.

element The element for which you are assigning a security

level.

Example

SetHierarchyElementGroupsSecurity('Reserve', 'Region', 'Europe', 'Germany');

This example assigns Reserve security to the Germany element of the Europe hierarchy in the Region
dimension.

SetDimensionGroupsSecurity
SetDimensionGroupsSecurity sets the security level for all existing groups for the specified dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SetDimensionGroupsSecurity(securityLevel, dimension)

Argument Description

securityLevel The security level you are assigning. There are six
possible values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

dimension Name of the dimension.

Example

SetDimensionGroupsSecurity('Reserve', 'Region');

358 IBM Planning Analytics: Reference

 This example assigns Reserve security to all existing groups in the Region dimension.

SetElementGroupsSecurity
SetElementGroupsSecurity sets the security level for a specified element in a dimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SetElementGroupsSecurity(securityLevel, dimension, element)

Argument Description

securityLevel The security level you are assigning. There are six
possible values:
• None
• Read
• Write
• Reserve
• Lock
• Admin

dimension Name of the dimension.

element The element for which you are assigning a security

level.

Example

SetElementGroupsSecurity('Reserve', 'Region', 'Germany');

This example assigns Reserve security to the Germany element of the Region dimension.

SecurityOverlayGlobalLockCell
SecurityOverlayGlobalLockCell is used to restrict the access rights of a node to read-only by locking it.
It uses the global overlay so all users are affected. The overlay cube must be created prior to using this
command. The elements provided in the address must be only for the dimensions used in the overlay.
The process must be configured to modify security data to successfully execute
SecurityOverlayGlobalLockCell.
The function returns True if successful and a major error if unsuccessful.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SecurityOverlayGlobalLockCell(bLock, Cube, element1,..., elementN)

Argument Description

bLock If 1 lock it. 0 unlock it

Chapter 5. TurboIntegrator Functions 359

 Argument Description

Cube Name of the cube.

elementN Overlay element name that defines the tuple. The

order must match the original dimension order of
the cube.

Example

SecurityOverlayGlobalLockCell(1,’Sales’,’MA’);
SecurityOverlayGlobalLockCell(0,’Products’,’MA','2011’);

In the first example, there is only one dimension used for the overlay. The second example uses two
dimensions.

SecurityOverlayCreateGlobalDefault
SecurityOverlayCreateGlobalDefault is used to create or destroy a Security Overlay cube, and to set the
overlay for a given area of a data cube.
Creating a data cube with a name that signifies an overlay cube will cause the data cube to be made
into an overlay if the server is restarted. When the cube is loaded it will be configured as an overlay if a
matching data cube is found.
Global overlays apply to all users.
The process must be configured to modify security data to successfully execute
SecurityOverlayCreateGlobalDefault.
The function returns True if successful and a major error if unsuccessful.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SecurityOverlayCreateGlobalDefault (Cube, DimensionMap)

Argument Description

Cube Name of the cube.

DimensionMap String specifying whether the dimension at each

position should be used in the overlay. The order of
dimensions is the original cube order. A 1 for each
included dimension and a 0 for an excluded one.
Each value separated by a colon.

Example

SecurityOverlayCreateGlobalDefault(‘DataCube’,
‘0:0:1:0’);

360 IBM Planning Analytics: Reference

SecurityOverlayDestroyGlobalDefault
SecurityOverlayDestroyGlobalDefault is used to destroy a Security Overlay cube, and to set the overlay for
a given area of a data cube.
Creating a data cube with a name that signifies an overlay cube will cause the data cube to be made
into an overlay if the server is restarted. When the cube is loaded it will be configured as an overlay if a
matching data cube is found
Global overlays apply to all users.
The process must be configured to modify security data to successfully execute
SecurityOverlayDestroyGlobalDefault.
The function returns True if successful and a major error if unsuccessful.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SecurityOverlayDestroyGlobalDefault (Cube)

Argument Description

Cube Name of the cube.

Example

SecurityOverlayDestroyGlobalDefault(‘DataCube’);

SecurityOverlayGlobalLockNode
SecurityOverlayGlobalLockNode is used to restrict the access rights of a node to read-only by locking it.
It uses the global overlay so all users are affected. The overlay cube must be created prior to using this
command. The elements provided in the address must be only for the dimensions used in the overlay.
The process must be configured to modify security data to successfully execute
SecurityOverlayGlobalLockNode.
The function returns True if successful and a major error if unsuccessful.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SecurityOverlayGlobalLockNode(bLock, Cube, Address, [AddressDelimiter])

Argument Description

bLock If 1 lock it. 0 unlock it

Cube Name of the cube.

Address Tokenized string sequence of overlay element

names that define the tuple. The order must match
the original dimension order of the cube.

AddressDelimiter Optional character string used to separate element

names in the Address parameter. Default value ‘|’.

Chapter 5. TurboIntegrator Functions 361

 Examples

SecurityOverlayGlobalLockNode(1,’Sales’,’MA’);
SecurityOverlayGlobalLockNode(0,’Products’,’MA | 2011’);
SecurityOverlayGlobalLockNode(0,’Products’, ‘MA : 2011’, ‘:’);

In the first example there is only one dimension used for the overlay. The other two examples use two
dimensions.

SecurityRefresh
SecurityRefresh reads all the security control cubes and regenerates the internal structures in the server
that are used by TM1 API functions.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SecurityRefresh;

Arguments
None.

Server Manipulation TurboIntegrator Functions

These functions facilitate server manipulation.
The server manipulation functions are not valid in processes on TM1 Database 12.

BatchUpdateFinish
BatchUpdateFinish instructs the server to exit batch update mode.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Semantics
When multiple processes are running in batch update mode and applying changes to a single cube, the
TM1 locking scheme may prevent one of the processes from updating the cube. This is by design; when
one process obtains a lock to write changes to a cube, other processes will be prevented from writing to
that cube in the interest of maintaining data integrity.
This locking scheme can be illustrated using an example of two processes, Process 1 and Process 2, that
update a single cube.
• Both processes start and call the BatchUpdateStart function to initiate batch updates.
• Each process operates on a unique data source.
• Process 1 completes processing data and calls the BatchUpdateFinish function. The process obtains a
write lock to the cube and commits changes.
• While Process 1 still holds a write lock to the cube, Process 2 completes processing data and calls the
BatchUpdateFinish function. However, because Process 1 retains the lock, Process 2 cannot obtain a
lock to the cube. All data changes applied in Process 2 are rolled back and Process 2 is restarted. This
ensures data integrity.

362 IBM Planning Analytics: Reference

 Depending on the size of the datasource for Process 2, the data rollback and process re-execution can
cause a noticeable decrease in performance. To address this performance issue, consider using the
BatchUpdateFinishWait function in place of BatchUpdateFinish.

Syntax
BatchUpdateFinish(SaveChanges);

Argument Description

SaveChanges A flag that instructs the server to either save or

discard changes committed while in batch update
mode.
Specify 0 to save changes, 1 to discard changes.

Example

BatchUpdateFinish(0);

This example instructs the server to save changes to TM1 data and exit batch update mode.

BatchUpdateFinishWait
BatchUpdateFinishWait is identical to BatchUpdateFinish except the process waits until the lock becomes
available and then commits changes. If a process calls BatchUpdateFinishWait but is unable to secure a
cube write lock to commit changes, the process waits until the lock becomes available and then commits
changes.
This function is valid in processes only.
Data changes applied in the process are not rolled back and the process is not re-executed.

Chapter 5. TurboIntegrator Functions 363

 Note: While waiting for the cube write lock, the process releases any read locks it acquired for other
objects during process execution. Because these read locks are released before the process can commit
changes to the cube, the objects for which the read locks are released can be modified before the cube is
updated. This can lead to data inconsistency when using BatchUpdateFinishWait.
We recommend that BatchUpdateFinishWait be used only in controlled situations where you know
that other processes are not modifying data or metadata related to the process that calls
BatchUpdateFinishWait.
This function is not supported in processes on TM1 Database 12.

Syntax
BatchUpdateFinishWait(SaveChanges);

Argument Description

SaveChanges A flag that instructs the server to either save or

discard changes committed while in batch update
mode. Specify 0 to save changes, 1 to discard
changes.

Example

BatchUpdateFinishWait(0);

This example instructs the server to save changes to TM1 data and exit batch update mode.

BatchUpdateStart
BatchUpdateStart enables batch updates.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
BatchUpdateStart;

Arguments
None.

DisableBulkLoadMode
DisableBulkLoadMode disables bulk load processing.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
See “EnableBulkLoadMode” on page 365 for details.

364 IBM Planning Analytics: Reference

EnableBulkLoadMode
EnableBulkLoadMode enables bulk load processing for a TurboIntegrator process.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
You can enable Bulk Load Mode in either the Prolog or Epilog section of a TurboIntegrator process. For
efficiency, enable Bulk Load Mode in the first, or very close to the first, statement in the Prolog section of
your process.
After enabling Bulk Load Mode in a process, it can only be disabled on the last line in the Epilog section. If
you attempt to disable Bulk Load Mode anywhere else in the process, the process will not compile.
If the mode is enabled in one TurboIntegrator process, it remains enabled until explicitly disabled or until
the chore completes. This means you can enable the mode in a process within a chore and then run
a series of TurboIntegrator processes before disabling it. You can also enter and exit Bulk Load Mode
repeatedly, using the mode only for certain critical parts of a chore.
Use the following TurboIntegrator commands to enable and disable Bulk Load Mode in a TurboIntegrator
process.

EnableBulkLoadMode();

Use the following TurboIntegrator function only on the last line in the Epilog section of your TI process
when using Bulk Load Mode.

DisableBulkLoadMode();

RefreshMdxHierarchy
RefreshMdxHierarchy updates the MDX hierarchies in a server without requiring you to restart the server.
Use this function after configuring or editing the custom named hierarchy levels for a dimension in
the }HierarchyProperties control cube.
For details on using named levels with dimensions, see the related section in the TM1 for Developers
documentation.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
RefreshMdxHierarchy(dimensionName, hierarchy)

Argument Description

dimensionName Optional string parameter to specify a specific

dimension to update.
Leave this parameter blank to update all
dimensions.

hierarchy The name of the hierarchy within the dimension.

This is an optional parameter.

Chapter 5. TurboIntegrator Functions 365

 Example
Update all dimensions:

RefreshMdxHierarchy('');

To update only the customers dimension:

RefreshMdxHierarchy('customers');

SaveDataAll
SaveDataAll saves all TM1 data from server memory to disk and restarts the log file.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Using SaveDataAll in a Chore

SaveDataAll commits all changes a chore makes prior to calling the SaveDataAll function.
While a chore is running, it accumulates locks on the objects it accesses. The commit operation
initiated by the SaveDataAll function temporarily releases all these locks. Once the commit is complete,
SaveDataAll reacquires all the locks it had before so it can continue to access the objects it was working
on.
There is a brief window during the commit operation where the locks are released and another user
or TurboIntegrator process could delete objects the original chore was using. When the original chore
attempts to reacquire the locks on those objects, the objects will not be available and the chore will cease
processing. In this case, an error similar to the following is written to the [Link] file:

844 WARN 2008-04-01 16:40:09,734 [Link] TM1ServerImpl::FileSave could

not reacquire lock on object with index 0x200002ca

Lock contention and using SaveDataAll at the end of TurboIntegrator processes

Using SaveDataAll as last command in a TurboIntegrator process can increase lock contention in TM1
TurboIntegrator processes.
In IBM TM1 versions, SaveDataAll was often added to the end of a TurboIntegrator process that loads
data with logging disabled. The SaveDataAll provided a way to write data from memory to disk directly
after a successful import, so that the newly imported data would not be lost in case of a mishap, such as a
server crash.
However, adding SaveDataAll as the last command can result in numerous TurboIntegrator import
processes, each one with SaveDataAll as last command. This technique worked in TM1 Version 9.0
and older due to the previous lock model which used only the global write lock. At any given time in
earlier versions only one write operation could take place. Therefore competing concurrent SaveDataAll
operations never occurred from multiple concurrent write operations.
Version 9.1 and newer introduced a more granular lock-by-object model that enables concurrent write
operations, if these write operations do not compete for the same resources. If they do compete for
the same resources, a lock contention occurs forcing one of the processes to rollback. So now two
TurboIntegrator import processes may run simultaneously if they do not share any objects, for example, if
they import into two different cubes.
The TurboIntegrator function SaveDataAll relies on the transaction logfile [Link] and involves all
objects within a data model. Therefore, two TurboIntegrator import processes, both using the function
SaveDataAll, cannot run in parallel: one will be executed, the other one (and its TurboIntegrator process)
will be forced to rollback. The same is true if the TurboIntegrator processes are part of chores: only one

366 IBM Planning Analytics: Reference

 chore will proceed to execute the TurboIntegrator function SaveDataAll, the other chore will be forced to
rollback.
A rollback is undesirable from a performance point of view, as it increases the total execution time of a
TurboIntegrator process or chore. Competing concurrent SaveDataAll operations will always lead to a lock
contention and to a rollback.
There are two possible solutions to avoid competing concurrent SaveDataAll operations:
• Do not use the TurboIntegrator function SaveDataAll. Instead enable Cube Logging for the import
cubes.
• If enabling Cube Logging for the import cubes cannot be done for performance reasons, within the TM1
application there should be only one process calling the TurboIntegrator function SaveDataAll. Use a
stand-alone, single, distinct chore to execute the SaveDataAll operation.

Syntax
SaveDataAll;

Arguments
None.

ServerShutdown
ServerShutdown shuts down a server running as an application. ServerShutdown cannot be used to shut
down a server running as a Windows service.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ServerShutDown(SaveData);

Argument Description

SaveData A Boolean value that indicates whether the server

should save changes to disk before shutting down.
If SaveData = 0, the server shuts down without
saving changes.
If SaveData = 1, the server saves changes from
memory to disk before shutting down.

Example

ServerShutdown(1);

This example shuts down the server and saves data to disk.

Subset Manipulation TurboIntegrator Functions

These functions facilitate subset manipulation.

Chapter 5. TurboIntegrator Functions 367

HierarchySubsetAliasGet
HierarchySubsetAliasGet returns the alias attribute for a subset within a hierarchy. This function was
introduced in Planning Analytics [Link]/TM1 Server 11.8.9 and cannot be used in previous versions.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetAliasGet(DimName, HierName, SubName);

Table 10. HierarchySubsetAliasGet syntax

Argument Description

DimName The parent dimension of the subset for which you

want to retrieve the alias.
HierName The name of a hierarchy within the dimension.
SubName The subset within the specified hierarchy for which
you want to retrieve the alias.

Example

HierarchySubsetAliasGet('Region', 'European', 'Northern Europe');

This example retrieves the alias for the Northern Europe subset of the European hierarchy in the Region
dimension.

HierarchySubsetAliasSet
HierarchySubsetAliasSet sets the alias attribute to be used in an hierarchy subset.
HierarchySubsetAliasSet returns 1 if successful, 0 otherwise.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetAliasSet(DimName, HierName, SubName, AliasName);

Argument Description

DimName The parent dimension of the subset for which you

want to set the alias.
HierName The name of the hierarchy within the dimension.
SubName The subset for which you want to set the alias.
AliasName The alias you want to use in the subset.

HierarchySubsetCreate
HierarchySubsetCreate creates an empty public subset of a specified hierarchy and dimension.
When the optional AsTemporary argument is set to 1, the subset is temporary and persists only for the
duration of the TurboIntegrator process or chore in which the subset is created.
Note:

368 IBM Planning Analytics: Reference

 For TM1 Server version 11.2.0 and earlier, temporary subsets were visible and usable only by the process
that created it and any of its child processes. Temporary subsets were not visible to the ancestor and
sibling processes. You could create same-named subsets in sibling child processes with the same parent
process.
For TM1 Server version 11.3.0 and later, these temporary subsets are visible to the ancestor and sibling
processes. If a parent TurboIntegrator process A invokes two child TurboIntegrator processes A1 and A2,
and the child TurboIntegrator process A1 creates a temporary subset S, the temporary subset S exists
for the duration of the parent TurboIntegrator process A. You cannot create a temporary subset with the
same name S in the sibling TurboIntegrator process A2 since the subset is visible and usable by siblings
A1 and A2.
While a temporary subset exists, the temporary subset takes precedence over any same-named public
subset. If another TurboIntegrator function references a subset that exists in both a temporary and
permanent state, the function operates upon the temporary subset.
There is no locking associated with a temporary subset, as a temporary subset is never saved. This can
result in improved performance, because there is no need for TurboIntegrator to wait for locks to be
released before operating upon a temporary subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetCreate(DimName, HierName, SubName, [AsTemporary]);

Argument Description

DimName The parent dimension of the subset you are

creating.
HierName The name of the hierarchy within the dimension.
SubName The name you want to assign to the subset.
AsTemporary This is an optional argument that specifies whether
the subset being created is temporary. 1 indicates
a temporary subset, 0 indicates a permanent
subset.
If this argument is omitted, the subset is
permanent.

Example

HierarchySubsetCreate('Region', 'European', 'Northern Europe', 1);

This example creates the temporary Northern Europe subset of the European hierarchy in the Region
dimension. You can use SubsetElementInsert to add elements to the subset.

HierarchySubsetDeleteAllElements
HierarchySubsetDeleteAllElements deletes all elements from a public subset of a dimension hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetDeleteAllElements(DimName, HierName, SubsetName);

Chapter 5. TurboIntegrator Functions 369

 Argument Description

DimName The parent dimension of the subset from which you

want to delete elements.
HierName The name of the hierarchy within the dimension.
SubsetName The subset from which you want to delete
elements. This must be a public subset.
TurboIntegrator cannot access private objects.

Example

HierarchySubsetDeleteAllElements('Region', 'European', 'Central Europe');

This example deletes all elements from the Central Europe subset of the European hierarchy in the Region
dimension.

HierarchySubsetDestroy
HierarchySubsetDestroy deletes a subset from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetDestroy(DimName, HierName, SubName);

Argument Description

DimName The parent dimension of the subset you are

deleting.
HierName The name of the hierarchy within the dimension.
SubName The name of the subset you want to delete.

Example

HierarchySubsetDestroy('Region', 'European', 'Northern Europe');

This example deletes the Northern Europe subset of the European hierarchy in the Region dimension.

HierarchySubsetElementExists
HierarchySubsetElementExists determines whether a specific element exists within a specific public
subset on the server from which a TurboIntegrator process is executed. HierarchySubsetElementExists
cannot be used to determine if an element exists in a private subset.
If the element exists in the specified subset, the function returns 1, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetElementExists(DimName, HierName, SubsetName, ElementName);

370 IBM Planning Analytics: Reference

 Argument Description

DimName The dimension parent of the subset containing the

element whose existence you want to confirm.
HierName The name of the hierarchy in the specified
dimension.
SubsetName The public subset containing the element whose
existence you want to confirm.
ElementName The element whose existence you want to confirm.
The ElementName argument only accepts the
element name and not the alias.

Example

HierarchySubsetElementExists('Region', 'Eastern', 'Europe', 'Italy');

This example determines if the Italy element exists in the Europe subset of the Eastern hierarchy from the
Region dimension.

HierarchySubsetElementDelete
HierarchySubsetElementDelete deletes an element from a subset of a dimension hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetElementDelete(DimName, HierName, SubName, Index);

Argument Description

DimName The parent dimension of the subset from which you

want to delete an element.
HierName The name of the hierarchy within the dimension.
SubName The subset from which you want to delete an
element.
Index The index number of the element you want to
delete from the subset.

Example

HierarchySubsetElementDelete('Region', 'European', 'Northern Europe', 3);

This example deletes the third element from the Northern Europe subset of the European hierarchy in the
Region dimension.

HierarchySubsetElementGetIndex
HierarchySubsetElementGetIndex retrieves the index of an element in a subset of a dimension hierarchy.
The function returns the index of the first occurrence of the specified element. If the element does not
exist in the subset or cannot be found, then zero is returned. If the dimension or subset cannot be found
or an out-of-range start index is specified, then an error is thrown and the TurboIntegrator function is
stopped.

Chapter 5. TurboIntegrator Functions 371

 This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetElementGetIndex(DimName, HierName, SubsetName, ElementName, StartIndex);

Argument Description

DimName The parent dimension of the subset.

HierName The name of the hierarchy within the dimension.
SubsetName The subset that contains the element.
ElementName The element name to search for in the subset. The
ElementName argument accepts both the element
name and the alias.
StartIndex The index number to begin searching from. The
value must be between 1 and the size of the
subset.

Example

HierarchySubsetElementGetIndex('Region', 'Country', 'Europe', 'Italy', 3);

This example retrieves the index for Italy from the Europe subset of the Country hierarchy in the Region
dimension. The search starts at index 3.

HierarchySubsetElementInsert
HierarchySubsetElementInsert adds an element to an existing subset in a dimension hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetElementInsert(DimName, HierName, SubName, ElName, Position);

Argument Description

DimName The parent dimension of the subset to which you

want to add an element.
HierName The name of the hierarchy within the dimension.
SubName The name of the subset to which you are adding an
element.
ElName The name of the element you want to add to
the subset. The element must exist in the TM1
database.
Position A value that indicates the index position of the
element within the subset.

Example

HierarchySubsetElementInsert('Region', 'European', 'Northern Europe', 'Finland',3);

372 IBM Planning Analytics: Reference

 This example adds the element Finland to the Northern Europe subset of the European hierarchy in the
Region dimension. Finland is the third element in the subset definition.

HierarchySubsetExists
HierarchySubsetExists determines if a specific public subset exists on the server from which a
TurboIntegrator process is executed. The function returns 1 if the subset exists on the server, otherwise it
returns 0. Note that this function cannot be used to determine the existence of private subsets.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetExists(DimName, HierName, SubsetName);

Argument Description

DimName The name of the dimension that is the parent of the

subset whose existence you want to confirm.
HierName The name of the hierarchy within the dimension.
SubsetName The name of the public subset whose existence
you want to confirm

Example

HierarchySubsetExists('Region', 'Industrialized, 'Northern Europe');

This example determines if the Northern Europe subset exists within the Industrialized hierarchy of the
Region dimension.

HierarchySubsetGetSize
HierarchySubsetGetSize returns the number of elements in a subset of a dimension hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetGetSize(DimName, HierName, SubsetName);

Argument Description

DimName The parent dimension of the subset for which you

want to determine size.
HierName The name of the hierarchy within the dimension.
SubsetName The subset for which you want to determine size.

Example

HierarchySubsetGetSize('Region', 'Eastern', 'EurAsia');

This function returns the number of elements in the EurAsia subset of the Eastern hierarchy in the Region
dimension.

Chapter 5. TurboIntegrator Functions 373

HierarchySubsetGetElementName
HierarchySubsetGetElementName returns the name of the element at a specified index location within a
given subset of a dimension hierarchy.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetGetElementName(DimName, HierName, SubsetName, ElementIndex);

Argument Description

DimName The parent of the subset from which you want to

retrieve an element name.
HierName The name of the hierarchy within the dimension.
SubsetName The subset from which you want to retrieve an
element name.
ElementIndex A number representing the position within the
subset of the element you want to retrieve.

Example

HierarchySubsetGetElementName('Region', 'Western', 'Americas', 4);

This example returns the name of the fourth element in the Americas subset of the Western hierarchy in
Region dimension.

HierarchySubsetIsAllSet
HierarchySubsetIsAllSet sets a subset to use all elements of the parent dimension.
HierarchySubsetIsAllSet returns 1 if successful, 0 otherwise.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetIsAllSet(DimName, HierName, SubName, Flag);

Argument Description

DimName The parent dimension of the subset for which you

want to use all elements.
HierName The name of the hierarchy within the dimension.
SubName The subset for which you want to use all dimension
elements.

374 IBM Planning Analytics: Reference

 Argument Description

Flag Any non-zero value specifies that the subset uses

all the current elements from the parent dimension
and will dynamically update to use all elements
from the parent dimension whenever the subset is
called.
Specifying a zero value freezes the elements in the
subset as the current set of all elements in the
parent dimension. The subset will not dynamically
update to use all dimension elements in the future.

HierarchySubsetMDXGet
HierarchySubsetMDXGet retrieves the MDX expression used to create a subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetMDXGet(DimName, HierName, SubName);

Argument Description
DimName The parent dimension of the subset.
HierName The name of the hierarchy within the dimension.
SubName The subset for which you want to retrieve the MDX
expression.

Example

mdxString = HierarchySubsetMDXGet('Cities', 'Italy', 'testsubset');

HierarchySubsetMDXSet
HierarchySubsetMDXSet applies a specified MDX expression to an existing public subset of a hierarchy.
If the passed MDX expression is valid, the specified subset is saved as a dynamic subset defined by the
MDX expression.
If the passed MDX expression is an empty string, the subset is converted to a static subset that contains
the elements that are in place when HierarchySubsetMDXSet is executed.
The function returns the number of elements that the subset contains.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
HierarchySubsetMDXSet(DimName, HierName, SubName, MDX_expression);

Argument Description
DimName The parent dimension of the subset.
HierName The name of the hierarchy within the dimension.

Chapter 5. TurboIntegrator Functions 375

 Argument Description
SubName The subset to which you want to apply the MDX
expression. SubName must be a public subset. If
this subset does not exist, an error is logged.
MDX_expression The MDX expression that you want to apply to
the subset. If the MDX expression is invalid,
TurboIntegrator processing stops, the subset is not
modified, and an error is logged.
If the MDX_expression argument is an empty
string, the subset is converted to a static subset.

Example

HierarchySubsetMDXSet('Cities', 'World', 'Sub1', '{ [Cities].[Cities].[level000].members }');

This example updates the Sub1 subset of the World hierarchy to a dynamic subset that contains the
current leaf elements of the Cities dimension. When leaf elements are added or removed from the
Cities dimension, the mySub1 subset is dynamically updated to reflect the changes in the parent
dimension.

PublishSubset
PublishSubset publishes a named private subset on the server. This function was introduced in Planning
Analytics [Link]/TM1 Server 11.8.9 and cannot be used in previous versions.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
PublishSubset(DimName, SubName, OverwriteExistingSubset);

Table 11. PublishSubset arguments

Argument Description

DimName The parent dimension of the private subset you

want to publish.

SubName The name of the private subset to be published.

OverwriteExistingSubset This Boolean argument (1 or 0) determines if

any existing identically named public subset are
overwritten when the private subset is published.
If OverwriteExistingSubset is true (1) , any existing
identically named public subset is overwritten
when the private subset is published.
If this argument is false (0), the public subset is not
overwritten, the private subset is not published,
and an error is written to the TurboIntegrator log
file.

Example

PublishSubset('Region', 'Northern Europe', 1);

376 IBM Planning Analytics: Reference

 This example publishes the private Northern Europe subset of the Region dimension. If a public subset
named Northern Europe already exists for the Region dimension, the public subset is overwritten then the
private subset is published.

SubsetAliasGet
SubsetAliasGet returns the alias attribute for a subset. This function was introduced in Planning Analytics
[Link]/TM1 Server 11.8.9 and cannot be used in previous versions.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetAliasGet( DimName, SubName);

Table 12. SubsetAliasGet syntax

Argument Description

DimName The parent dimension of the subset for which you

want to retrieve the alias.
SubName The subset for which you want to retrieve the alias.

Example

SubsetAliasGet('Region', 'Central Europe');

This example retrieves the alias for the Central Europe subset of the Region dimension.

SubsetAliasSet
SubsetAliasSet sets the alias attribute to be used in a subset. SubsetAliasSet returns 1 if successful, 0
otherwise.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetAliasSet( DimName, SubName, AliasName );

Argument Description

DimName The parent dimension of the subset for which you

want to set the alias.
SubName The subset for which you want to set the alias.
AliasName The alias you want to use in the subset.

SubsetCreate
SubsetCreate creates an empty public subset of a specified dimension.
When the AsTemporary argument is set to 1, the subset is temporary and persists only for the duration
of the TurboIntegrator process or a single-commit chore in which the subset is created. If a parent
TurboIntegrator process invokes child TurboIntegrator processes by using the ExecuteProcess or
ExecuteProcessWithReturn function, and the temporary subset is created in one of these child
TurboIntegrator processes, the subset persists for the duration of the parent TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 377

 Note:
For TM1 Server version 11.2.0 and earlier, temporary views and subsets were visible and usable only by
the process that created it and any of its child processes. Temporary views and subsets were not visible to
the ancestor and sibling processes. You could create same-named subsets in sibling child processes with
the same parent process.
For TM1 Server version 11.3.0 and later, these temporary subsets are visible to the ancestor and sibling
processes. If a parent TurboIntegrator process A invokes two child TurboIntegrator processes A1 and A2,
and the child TurboIntegrator process A1 creates a temporary subset S, the temporary subset S exists
for the duration of the parent TurboIntegrator process A. You cannot create a temporary subset with the
same name S in the sibling TurboIntegrator process A2 since the subset is visible and usable by siblings
A1 and A2.
A chore is a special case of a parent TurboIntegrator process that invokes a child TurboIntegrator process
that is scheduled to run at a specific time. You can use two types of chores.
Single-commit
Within the scope / execution tree of a single-commit chore, a temporary subset of the same name can
be created only for one child TurboIntegrator process.
Multi-commit
Within the scope / execution tree of a multi-commit chore, which commits after every child
TurboIntegrator process, every child TurboIntegrator process can create a temporary subset of the
same name because a temporary subset will not persist after a commit.
While a temporary subset exists, the temporary subset takes precedence over any same-named public
or private subset. If another TurboIntegrator function references a subset that exists in both a temporary
and permanent state, the function operates upon the temporary subset.
There is no locking associated with a temporary subset because a temporary subset is never saved. This
can result in improved performance because there is no need for TurboIntegrator to wait for locks to be
released before operating upon a temporary subset.

Syntax
SubsetCreate(DimName, SubName, [AsTemporary]);

Argument Description

DimName The parent dimension of the subset you are

creating.
SubName The name that you want to assign to the subset.
AsTemporary This is an optional argument that specifies whether
the subset that is being created is temporary.
1 indicates a temporary subset. 0 indicates a
permanent subset.
If this argument is omitted, the subset is
permanent.

Example

SubsetCreate('Region', 'Northern Europe', 1);

This example creates the temporary Northern Europe subset of the Region dimension. You can use
SubsetElementInsert to add elements to the subset.

378 IBM Planning Analytics: Reference

SubsetCreateByMDX
SubsetCreateByMDX creates a public subset based on a passed MDX expression.
When the AsTemporary argument is set to 1, the subset is temporary and persists during the
TurboIntegrator process or a single-commit chore in which the subset is created. If a parent
TurboIntegrator process invokes child TurboIntegrator processes by using the ExecuteProcess or
ExecuteProcessWithReturn function, and the temporary subset is created in one of these child
TurboIntegrator processes, the subset persists during the parent TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.
Note:
For TM1 Server version 11.2.0 and earlier, temporary views and subsets were visible and usable only by
the process that created it and any of its child processes. Temporary views and subsets were not visible to
the ancestor and sibling processes. You could create same-named subsets in sibling child processes with
the same parent process.
For TM1 Server version 11.3.0 and later, these temporary subsets are visible to the ancestor and sibling
processes. If a parent TurboIntegrator process A invokes two child TurboIntegrator processes A1 and A2,
and the child TurboIntegrator process A1 creates a temporary subset S, the temporary subset S exists
for the duration of the parent TurboIntegrator process A. You cannot create a temporary subset with the
same name S in the sibling TurboIntegrator process A2 since the subset is visible and usable by siblings
A1 and A2.
A chore is a special case of a parent TurboIntegrator process that invokes a child TurboIntegrator process.
You can use two types of chores.
Single-commit
Within the scope / execution tree of a single-commit chore, a temporary subset of the same name can
be created only for one child TurboIntegrator process.
Multi-commit
Within the scope / execution tree of a multi-commit chore, which commits after every child
TurboIntegrator process, every child TurboIntegrator process can create a temporary subset of the
same name because a temporary subset will not persist after a commit.
While a temporary subset exists, the temporary subset takes precedence over any same-named public
or private subset. If another TurboIntegrator function references a subset that exists in both a temporary
and permanent state, the function operates upon the temporary subset.
There is no locking associated with a temporary subset because a temporary subset is never saved. This
can result in improved performance because there is no need for TurboIntegrator to wait for locks to be
released before operating upon a temporary subset.

Syntax
SubsetCreateByMDX(SubName, MDX_expression, DimName, 1)

Argument Description

SubName The name that you want to assign to the subset.

MDX_expression An MDX expression that returns a subset.
DimName The dimension name. Specify the dimension name
to avoid errors if the subset that is being created is
empty.

Chapter 5. TurboIntegrator Functions 379

 Argument Description

AsTemporary This is an optional argument that specifies whether

the subset that is being created is temporary.
1 indicates a temporary subset. 0 indicates a
permanent subset.
If this argument is omitted, the subset is
permanent.

Example
This example creates a temporary subset based on an MDX expression that returns a subset that consists
of all the dimensions whose names start with "plan_".

SubsetCreatebyMDX ( SubName , '{TM1FILTERBYPATTERN( {TM1SubsetALL( [ "| DimName |" ] )},

“plan_.*” )}' ,1);

This example returns an empty set as the MDX tries to create a subset that consists of Engine size of 2.0
models. Since only models with an Engine size of 1.6 or 1.8 exist, an empty set returns.

SubsetCreatebyMDX ( SubName , '{FILTER({TM1SUBSETALL([model])}, [model].[Engine Size] =

"2.0")}', 'model', 1);

Example of temporary subset used by parent process

In this example, two processes are created. The parent process, Process-A, calls the child process,
Process-B. Process-B creates a temporary subset that Process-A uses as the data source.
Process-A/prolog:

ExecuteProcess('Process-B');
DatasourceDimensionSubset = 'My2003Months';

Process-B/prolog:

SubsetCreateByMdx('My2003Months', '{Descendants([plan_time].[plan_time].[2003], 3, LEAVES)}',

1);

SubsetDeleteAllElements
SubsetDeleteAllElements deletes all elements from a public subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetDeleteAllElements(DimName, SubsetName);

Argument Description

DimName The parent dimension of the subset from which you

want to delete elements.
SubsetName The subset from which you want to delete
elements. This must be a public subset.
TurboIntegrator cannot access private objects.

380 IBM Planning Analytics: Reference

 Example

SubsetDeleteAllElements('Region', 'Central Europe');

This example deletes all elements from the Central Europe subset of the Region dimension.

SubsetDestroy
SubsetDestroy deletes a subset from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetDestroy(DimName, SubName);

Argument Description

DimName The parent dimension of the subset you are

deleting.
SubName The name of the subset you want to delete.

Example

SubsetDestroy('Region', 'Northern Europe');

This example deletes the Northern Europe subset of the Region dimension.

SubsetElementDelete
SubsetElementDelete deletes an element from a subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetElementDelete(DimName, SubName, Index);

Argument Description

DimName The parent dimension of the subset from which you

want to delete an element.
SubName The subset from which you want to delete an
element.
Index The index number of the element you want to
delete from the subset.

Example

SubsetElementDelete('Region', 'Northern Europe', 3);

This example deletes the third element from the Northern Europe subset of the Region dimension.

Chapter 5. TurboIntegrator Functions 381

SubsetElementExists
SubsetElementExists determines whether a specific element exists within a specific public subset on
the server from which a TurboIntegrator process is executed. SubsetElementExists cannot be used to
determine if an element exists in a private subset.
If the element exists in the specified subset, the function returns 1, otherwise it returns 0.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetElementExists(DimName, SubsetName, ElementName);

Argument Description

DimName The dimension parent of the subset containing the

element whose existence you want to confirm.
SubsetName The public subset containing the element whose
existence you want to confirm.
ElementName The element whose existence you want to confirm.
The ElementName argument only accepts the
element name and not the alias.

Example

SubsetElementExists('Region', 'Europe', 'Italy');

This example determines if the Italy element exists in the Europe subset of the Region dimension.

SubsetElementGetIndex
SubsetElementGetIndex retrieves the index of an element in a subset. The function returns the index of
the first occurrence of the specified element.
If the element does not exist in the subset or cannot be found, then zero is returned. If the dimension
or subset cannot be found or an out-of-range start index is specified, then an error is thrown and the
TurboIntegrator function is stopped.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetElementGetIndex(DimName, SubsetName, ElementName, StartIndex);

Argument Description

DimName The parent dimension of the subset.

SubsetName The subset that contains the element.
ElementName The element name to search for in the subset. The
ElementName argument accepts both the element
name and the alias.
StartIndex The index number to begin searching from. The
value must be between 1 and the size of the
subset.

382 IBM Planning Analytics: Reference

 Example

SubsetElementGetIndex('Region', 'Europe', 'Italy', 3);

This example retrieves the index for Italy from the Europe subset of the Region dimension. The search
starts at index 3.

SubsetElementInsert
SubsetElementInsert adds an element to an existing subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetElementInsert(DimName, SubName, ElName, Position);

Argument Description

DimName The parent dimension of the subset to which you

want to add an element.
SubName The name of the subset to which you are adding an
element.
ElName The name of the element you want to add to
the subset. The element must exist in the TM1
database.
Position A value that indicates the index position of the
element within the subset.

Example

SubsetElementInsert('Region', 'Northern Europe', 'Finland',3);

This example adds the element Finland to the Northern Europe subset of the Region dimension. Finland is
the third element in the subset definition.

SubsetExists
SubsetExists determines whether a specific public subset exists on the server from which a
TurboIntegrator process is executed.
The function returns 1 if the subset exists on the server, otherwise it returns 0. Note that this function
cannot be used to determine the existence of private subsets.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetExists(DimName, SubsetName);

Argument Description

DimName The name of the dimension that is the parent of the

subset whose existence you want to confirm.
SubsetName The name of the public subset whose existence
you want to confirm

Chapter 5. TurboIntegrator Functions 383

 Example

SubsetExists('Region', 'Northern Europe');

This example determines if Northern Europe subset of the Region dimension exists on the server.

SubsetExpandAboveSet
SubsetExpandAboveSet sets the Expand Above property for a subset. The function returns 1 if successful,
otherwise it returns 0.
When this property is set to TRUE, children of a consolidation are displayed above the consolidation when
the consolidation displays on a row, and to the left of the consolidation when the consolidation displays
on a column.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetExpandAboveSet( DimName, SubsetName, ExpandAboveFlag);

Argument Description

DimName The parent dimension of the subset for which you

want to set the Expand Above property.
SubsetName The subset for which you want to set the Expand
Above property.
ExpandAboveFlag Set ExpandAboveFlag to 1 to set the Expand Above
property to TRUE. When this property is TRUE,
consolidations expand above on rows and to the
left on columns.
Set ExpandAboveFlag to 0 to set the Expand Above
property to FALSE. When this property is FALSE,
consolidations expand below on rows and to the
right on columns.

Example

SubsetExpandAboveSet('Region', 'Europe', 1 );

This example sets the Expand Above property to TRUE for the Europe subset of the Region dimension.

SubsetFormatStyleSet
SubsetFormatStyleSet applies an existing display style to a named subset.
Display styles are defined for specific elements. If you apply an existing display style to a subset that
includes elements that are not included in the display style, no formatting is applied to those elements.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetFormatStyleSet( DimName, SubsetName, FormatName);

384 IBM Planning Analytics: Reference

 Argument Description

DimName The parent dimension of the subset to which you

want to apply a display style.
SubsetName The name of the subset to which you are applying a
display style.
FormatName The name of the existing display style you want to
apply to the subset.

Example

SubsetFormatStyleSet ('Region', 'Northern Europe', 'BoldCurrencyLeftJustified');

This example applies the BoldCurrencyLeftJustified display style to the Northern Europe subset of the
Region dimension.

SubsetGetElementName
SubsetGetElementName returns the name of the element at a specified index location within a given
subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetGetElementName(DimName, SubsetName, ElementIndex);

Argument Description

DimName The parent of the subset from which you want to

retrieve an element name.
SubsetName The subset from which you want to retrieve an
element name.
ElementIndex A number representing the position within the
subset of the element you want to retrieve.

Example

SubsetGetElementName('Region', 'Americas', 4);

This example returns the name of the fourth element in the Americas subset of the Region dimension.

SubsetGetSize
SubsetGetSize returns the number of elements in a subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetGetSize(DimName, SubsetName);

Chapter 5. TurboIntegrator Functions 385

 Argument Description

DimName The parent dimension of the subset for which you

want to determine size.
SubsetName The subset for which you want to determine size.

Example

SubsetGetSize('Region', 'EurAsia');

This function returns the number of elements in the EurAsia subset of the Region dimension.

SubsetIsAllSet
SubsetIsAllSet sets a subset to use all elements of the parent dimension. SubsetIsAllSet returns 1 if
successful, 0 otherwise.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetIsAllSet(DimName, SubName, Flag);

Argument Description

DimName The parent dimension of the subset for which you

want to use all elements.
SubName The subset for which you want to use all dimension
elements.
Flag Any non-zero value specifies that the subset uses
all the current elements from the parent dimension
and will dynamically update to use all elements
from the parent dimension whenever the subset is
called.
Specifying a zero value freezes the elements in the
subset as the current set of all elements in the
parent dimension. The subset will not dynamically
update to use all dimension elements in the future.

SubsetMDXGet
SubsetMDXGet retrieves the MDX expression used to create a subset.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetMDXGet(DimName, SubName);

Argument Description
DimName The parent dimension of the subset.
SubName The subset for which you want to retrieve the MDX expression.

386 IBM Planning Analytics: Reference

 Example

mdxString = SubsetMDXGet('Cities', 'testsubset');

SubsetMDXSet
SubsetMDXSet applies a specified MDX expression to a public or temporary subset.
If the passed MDX expression is valid, the specified subset is saved as a dynamic subset defined by the
MDX expression.
If the passed MDX expression is an empty string, the subset is converted to a static subset that contains
the elements that are in place when SubsetMDXSet is executed.
The function returns the number of elements that the subset contains.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
SubsetMDXSet(DimName, SubName, MDX_expression);

Argument Description
DimName The parent dimension of the subset.
SubName The subset to which you want to apply the
MDX expression. SubName must be a public or
temporary subset. If this subset does not exist, an
error is logged.
MDX_expression The MDX expression that you want to apply to
the subset. If the MDX expression is invalid,
TurboIntegrator processing stops, the subset is not
modified, and an error is logged.
If the MDX_expression argument is an empty
string, the subset is converted to a static subset.

Examples

SubsetMdxSet( 'YZProducts', 'mySub1', '{ Filter( [YZProducts].[YZProducts].members,

IsLeaf( [YZProducts].[YZProducts].currentmember ) ) }' );

This example updates the mySub1 subset to a dynamic subset that contains the current leaf elements of
the YZProducts dimension. When leaf elements are added or removed from the YZProduct dimension,
the mySub1 subset is dynamically updated to reflect the changes in the parent dimension.
One possible use of the SubsetMDXSet function is to apply an MDX expression to update an existing
subset, and then immediately convert the subset to static.

SubsetMDXSet( 'YZProducts', 'mySub1', '{ [YZProducts].[YZProducts].[level000].members }' );

SubsetMDXSet( 'YZProducts', 'mySub1', '' );

This two-call sequence updates the mySub1 subset to a static subset that contains the current top-level
elements of the YZProducts dimension.
The first call of SubsetMDXSet applies the { [YZProducts].[YZProducts].
[level000].members } MDX expression to the mysub1 subset, resulting in a dynamic subset that
includes all top-level (level 0) elements of the YZProducts dimension.
The second call of SubsetMDXSet passes an empty string as the MDX_expression argument, so the
mysub1 subset is converted to a static subset.

Chapter 5. TurboIntegrator Functions 387

View Manipulation TurboIntegrator Functions
These functions pertain to view manipulation.

PublishView
PublishView publishes a named private view on the server.
This function is valid in TurboIntegrator processes only.

Syntax
PublishView(Cube, View, PublishPrivateSubsets, OverwriteExistingView);

Argument Description

Cube The name of the cube containing the private view

to be published.

View The name of the private view to be published.

PublishPrivateSubsets This Boolean argument (1 or 0) determines if any

private subsets present in the view should also be
published.
If PublishPrivateSubsets is true (1), all private
subsets used in the view are published along with
the view.
If this argument is false (0), private subsets are
not published. A public view cannot contain private
subsets, so the view will not be published and an
error will be written to the TurboIntegrator log file.
Note:
If a private subset contains another private
subset as a user-defined consolidation, the
subset can never be published using the
PublishView function, regardless of the value of the
PublishPrivateSubsets argument.
The PublishPrivateSubsets argument is ignored
when the PublishView function is used with an
MDX view. Any private subsets used in a MDX view
remain private. The view fails to render for users
without access to the private subset of the same
name.

388 IBM Planning Analytics: Reference

 Argument Description

OverwriteExistingView This Boolean argument (1 or 0) determines if any

existing identically named public view should be
overwritten when the private view is published.
If OverwriteExistingView is true (1) , any existing
identically named public view will be overwritten
when the private view is published.
If this argument is false (0), the public view will
not be overwritten, the private view will not be
published, and an error will be written to the
TurboIntegrator log file.

DisableMTQViewConstruct
DisableMTQViewConstruct disables multi-threaded query processing when calculating a view to be used
as a TurboIntegrator datasource for a single TurboIntegrator process. When MTQQuery=T in the [Link]
file, DisableMTQViewConstruct can be called to override this value on a TurboIntegrator process.
This function must appear in the Prolog, it has no effect in any other procedure within a process.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
Note: If the value of the MTQ parameter is 1 (or OFF), this functionality is turned off entirely and cannot be
overridden.
The value of MTQQuery can be overridden on a single TurboIntegrator process by calling the
DisableMTQViewConstruct function.
If MTQQuery=T (the default), DisableMTQViewConstruct can be called to disable the functionality for
individual TurboIntegrator processes.
After enabling EnableMTQViewConstruct in a process, it can only be disabled on the last line in the Epilog
section. If you attempt to use DisableMTQViewConstruct anywhere else in the process, the process will
not compile.
If the mode is enabled in one TurboIntegrator process, it remains enabled until explicitly disabled or
until the chore completes. This means you can enable the mode in a process and then run a series of
TurboIntegrator processes before disabling it.

Example
Use the following TurboIntegrator commands to disable multi-threaded query processing when
calculating a view to be used as a TurboIntegrator datasource for a single TurboIntegrator process.

DisableMTQViewConstruct()

See also “EnableMTQViewConstruct” on page 389.

EnableMTQViewConstruct
EnableMTQViewConstruct enables multi-threaded query processing when calculating a view to be used
as a TurboIntegrator datasource for a single TurboIntegrator process. When MTQQuery=F in the [Link]
file, EnableMTQViewConstruct can be called to override this value on a TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 389

 Syntax
Note: If the value of the MTQ parameter is 1 (or OFF), this functionality is turned off entirely and cannot be
overridden.
The value of MTQQuery can be overridden on a single TurboIntegrator process by calling the
EnableMTQViewConstruct function.
If MTQQuery=F in the [Link] file on the server where this function is run, EnableMTQViewConstruct can
be called to override this value on a single TurboIntegrator process.
You can enable EnableMTQViewConstruct in either the Prolog or Epilog section of a TurboIntegrator
process. For efficiency, enable EnableMTQViewConstruct in the first, or very close to the first, statement
in the Prolog section of your process.

Example
Use the following TurboIntegrator commands to enable multi-threaded query processing when
calculating a view to be used as a TurboIntegrator datasource for a single TurboIntegrator process.

EnableMTQViewConstruct()

See also “DisableMTQViewConstruct” on page 389.

After enabling EnableMTQViewConstruct in a process, it can only be disabled on the last line in the
Epilog section. If you attempt to use disable DisableMTQViewConstruct anywhere else in the process, the
process will not compile.
If the mode is enabled in one TurboIntegrator process, it remains enabled until explicitly disabled or
until the chore completes. This means you can enable the mode in a process and then run a series of
TurboIntegrator processes before disabling it.

ViewColumnDimensionSet
ViewColumnDimensionSet sets a column dimension for a TM1 view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewColumnDimensionSet(CubeName, ViewName, DimName, StackPosition);

Argument Description

CubeName The parent cube of the view for which you are
setting the column dimension.

ViewName The view for which you are setting the column
dimension.

DimName The dimension you want to set as a column

dimension for the view.

StackPosition A number that indicates the stack position of the

dimension in the view. This is a 1-based number. 1
indicates the top-most stack position. 2 indicates a
position below 1, and so on.

390 IBM Planning Analytics: Reference

 Example

ViewColumnDimensionSet('98sales', 'Quarter1', 'Month',1);

This example sets Month as a column dimension for the 1Quarter view of the 98sales cube. In the event
of stacked column dimensions, Month is placed in the top-most position.

ViewColumnSuppressZeroesSet
ViewColumnSuppressZeroesSet suppresses or enables the display of columns containing only zero values
in a TM1 cube view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewColumnSuppressZeroesSet(Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you want to
suppress or enable the display of zero values.

ViewName The view for which you want to enable or suppress

the display of zeroes.

Flag A binary value that enables or suppresses zeroes.

Specify 1 to suppress the display of columns
containing only zeroes in the view. Specify 0 to
enable the display of columns containing only
zeroes.

Example

ViewColumnSuppressZeroesSet('99sales', '1st QuarterActuals', 1);

This example suppresses the display of any columns containing only zeroes in the 1st Quarter Actuals
view of the 99sales cube.

ViewConstruct
ViewConstruct constructs, pre-calculates, and stores a Stargate view in memory on a server. This function
is useful for pre-calculating and storing large views so they can be quickly accessed after a data load or
update.
This function is valid in processes only.

Syntax
ViewConstruct(CubeName, ViewName);

Argument Description

CubeName The cube from which you want to construct the

view.

Chapter 5. TurboIntegrator Functions 391

 Argument Description

ViewName The view you want to construct. This view must be

an existing public native view on the server.
You cannot use an MDX view. An attempt to use an
MDX view results in a View not found error.

Example

Viewconstruct('99sales', '1st Quarter Actuals');

This example creates the view 1st Quarter Actuals of the 99sales cube.

ViewCreate
ViewCreate creates an empty view of a specified cube.
When the optional AsTemporary argument is set to 1, the view is temporary and persists only for the
duration of the TurboIntegrator process or chore in which the view is created.
Note:
For TM1 Server version 11.2.0 and earlier, temporary views were visible and usable only by the process
that created it and any of its child processes. Temporary views were not visible to the ancestor and sibling
processes. You could create same-named views in sibling child processes with the same parent process.
For TM1 Server version 11.3.0 and later, these temporary views are visible to the ancestor and sibling
processes. If a parent TurboIntegrator process A invokes two child TurboIntegrator processes A1 and A2,
and the child TurboIntegrator process A1 creates a temporary view S, the temporary view S exists for
the duration of the parent TurboIntegrator process A. You cannot create a temporary view with the same
name S in the sibling TurboIntegrator process A2 since the view is visible and usable by siblings A1 and
A2.
While a temporary view exists, the temporary view takes precedence over any same-named public view.
If another TurboIntegrator function references a view that exists in both a temporary and permanent
state, the function operates upon the temporary view.
Temporary objects have transaction scope. When a transaction is committed, all temporary objects are
cleaned up. If a chore is run in single-commit mode where all processes in the chore are logically run
within the context of one transaction, then temporary objects that are created in a process still exist,
visible, and available for use, in subsequent processes run by the chore. However, in multi-commit mode,
these processes are cleaned up at commit time of the transaction that wrapped the execution of the
process that created the temporary object.
There is no locking associated with a temporary view, as a temporary view is never saved. This can result
in improved performance, because there is no need for TurboIntegrator to wait for locks to be released
before operating upon a temporary view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewCreate(Cube, ViewName, <AsTemporary>);

Argument Description

Cube The parent cube of the view you are creating.

ViewName The name you want to assign to the view.

392 IBM Planning Analytics: Reference

 Argument Description

AsTemporary This is an optional argument that specifies whether

the view being created is temporary. 1 indicates a
temporary view, 0 indicates a permanent view.
If this argument is omitted, the view is permanent.

Example
This example creates a temporary view named 1st Quarter Actuals from the Sales cube.

ViewCreate('Sales', '1st Quarter Actuals', 1);

ViewCreateByMDX
ViewCreateByMDX creates a view with a specified MDX expression.
When the optional AsTemporary argument is set to 1, the view is temporary and persists only for the
duration of the TurboIntegrator process or chore in which the view is created.
Note:
For TM1 Server version 11.2.0 and earlier, temporary views were visible and usable only by the process
that created it and any of its child processes. Temporary views were not visible to the ancestor and sibling
processes. You could create same-named views in sibling child processes with the same parent process.
For TM1 Server version 11.3.0 and later, these temporary views are visible to the ancestor and sibling
processes. If a parent TurboIntegrator process A invokes two child TurboIntegrator processes A1 and A2,
and the child TurboIntegrator process A1 creates a temporary view S, the temporary view S exists for
the duration of the parent TurboIntegrator process A. You cannot create a temporary view with the same
name S in the sibling TurboIntegrator process A2 since the view is visible and usable by siblings A1 and
A2.
While a temporary view exists, the temporary view takes precedence over any same-named public view.
If another TurboIntegrator function references a view that exists in both a temporary and permanent
state, the function operates upon the temporary view.
Temporary objects have transaction scope. When a transaction is committed, all temporary objects are
cleaned up. If a chore is run in single-commit mode where all processes in the chore are logically run
within the context of one transaction, then temporary objects that are created in a process still exist,
visible, and available for use, in subsequent processes run by the chore. However, in multi-commit mode,
these processes are cleaned up at commit time of the transaction that wrapped the execution of the
process that created the temporary object.
There is no locking associated with a temporary view, as a temporary view is never saved. This can result
in improved performance because there is no need for TurboIntegrator to wait for locks to be released
before operating upon a temporary view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewCreateByMDX(Cube, ViewName, MDX_expression , <AsTemporary>);

Argument Description

Cube The parent cube of the view you are creating.

ViewName The name you want to assign to the view.

Chapter 5. TurboIntegrator Functions 393

 Argument Description

MDX_expression A string value containing a valid MDX view

expression.

AsTemporary This is an optional argument that specifies whether

the view being created is temporary. 1 indicates a
temporary view; 0 indicates a permanent view.
If this argument is omitted, the view is permanent.

Example
This example, based on the Planning Sample database, creates a temporary view named Account in the
plan_BudgetPlan cube.

ViewCreateByMDX('plan_BudgetPlan', 'Account',
'select {[plan_version].[FY 2003 Budget]} on 0,
{[plan_business_unit].[10300]} on 1 from plan_budgetplan where
[plan_department].[200][plan_chart_of_accounts].[41101][plan_exchange_rates].[local]
[plan_source].[goal][plan_time].[Jan-2003]'
,1);

ViewDestroy
ViewDestroy deletes a view from the TM1 database.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewDestroy(Cube, ViewName);

Argument Description

Cube The parent cube of the view you are deleting.

ViewName The name of the view you want to delete.

Example

ViewDestroy('99sales', '1st Quarter Actuals');

This example deletes the 1st Quarter Actuals view of the 99sales cube.

ViewExists
ViewExists determines whether a specific public view exists on the server from which a TurboIntegrator
process is executed. The function returns 1 if the view exists on the server, otherwise it returns 0. Note
that this function cannot be used to determine the existence of private views.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewExists(CubeName, ViewName);

394 IBM Planning Analytics: Reference

 Argument Description

CubeName The name of the cube that is the parent of the view
whose existence you want to confirm.

ViewName The name of the public view whose existence you

want to confirm

Example

ViewExists('Inventory', 'FebClosing');

This example determines if FebClosing view of the Inventory cube exists on the server.

ViewExtractFilterByTitlesSet
ViewExtractFilterByTitlesSet sets an option to filter by titles on consolidated values that are excluded
from a view or any associated view extracts.
TM1 allows the storing of strings on calculated values. When you exclude a calculated value from a view
or view extract you may want to exclude the message string also from the view.
Note: This function affects views as they exist on the server. The scope of this function is not restricted to
extracts generated from a view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewExtractFilterByTitlesSet (Cube, ViewName, FilterByTitles, Temporary);

Argument Description

Cube The parent cube of the view for which you are
setting the option.

ViewName The view for which you are setting the option.

FilterByTitles A binary value that turns the option on or off.

Specify 0 to include titles stored on consolidated
values. This is the current and default behavior.
Specify 1 to exclude titles stored on consolidated
values.

Temporary A Boolean value that indicates whether the

settings are temporary.

Example

ViewExtractFilterByTitlesSet ('99sales', '1st QuarterActuals', 1, 0);

Chapter 5. TurboIntegrator Functions 395

ViewExtractSkipCalcsSet
ViewExtractSkipCalcsSet sets an option to include/exclude consolidated values in a view and any
associated view extracts. A view extract is a view exported as an ASCII comma-delimited (.cma) file.
Note: This function affects views as they exist on the server. The scope of this function is not restricted to
extracts generated from a view.
ViewExtractSkipCalcsSet is the equivalent of the Skip Consolidated Values option in the View Extract
dialog box.
This function is valid only in Planning Analytics processes.

Syntax
ViewExtractSkipCalcsSet (Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you are
setting the option.

ViewName The view for which you are setting the option.

Flag A binary value that turns the option on or off.

Specify 1 to exclude consolidated values from the
view extract. Specify 0 to include consolidated
values.
The default is 1.

Example

ViewExtractSkipCalcsSet ('99sales', '1st Quarter Actuals',1);

This example turns on the Skip Consolidated Values option for the 1st Quarter Actuals view. The view
extract will not include any consolidated values.

Note about the impact of enabling a specific combination of view manipulation

functions
Consider the scenario when all of these conditions are true:
• the measure is a string
• ViewExtractSkipCalcsSet = 1
• ViewExtractSkipConsolidatedStringsSet = 0 (function is not used)
• ViewExtractSkipRuleValuesSet = 0 (function is not used)
In this scenario, the output is different, depending on whether you enable the ViewExtractSkipZeroesSet
function.
• If you set ViewExtractSkipZeroesSet = 0, the Planning Analytics database enumerates every possible
cube cell, not just the existing data cells. This situation is rather unusual, since enumerating all possible
cells means that the number of cells scanned is the product of the sizes of all of the dimensions of the
cube. This product can quickly become very large. In this mode, the ViewExtractSkipCalcsSet function
skips all consolidated cells, even if the measure is a string.
• If you set ViewExtractSkipZeroesSet = 1, the Planning Analytics database scans only the cells actually
in the cube. In this mode, a string stored on a consolidated cell is treated as a simple leaf (the cell after
all has a simple value and is a leaf). Therefore, even though the ViewExtractSkipCalcsSet function is

396 IBM Planning Analytics: Reference

 enabled, the entry is not skipped since this cell is not a calculated consolidated cell. In this case, if you
want the entries to be skipped, you must enable the ViewExtractSkipConsolidatedStringsSet function.

ViewExtractSkipConsolidatedStringsSet
ViewExtractSkipConsolidatedStringsSet sets an option to exclude strings on consolidated values that are
excluded from a view or any associated view extracts. A view extract is a TM1 view exported as an ASCII
comma-delimited (.cma) file.
TM1 allows the storing of strings on calculated values. When you exclude a calculated value from a view
or view extract you may want to exclude the message string also from the view.
Note: This function affects views as they exist on the server. The scope of this function is not restricted to
extracts generated from a view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewExtractSkipConsolidatedStringsSet (Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you are
setting the option.

ViewName The view for which you are setting the option.

Flag A binary value that turns the option on or off.

Specify 0 to include strings stored on consolidated
values. This is the current and default behavior.
Specify 1 to exclude strings stored on consolidated
values.

Note: Read about the impact of enabling a specific combination of view manipulation functions.

Example

ViewExtractSkipConsolidatedStringsSet ('99sales', '1st QuarterActuals', 1);

This example turns on the Skip Rule for Consolidated String option for the extract created from the 1st
Quarter Actuals view. The extract will not include any string on the consolidated value.

ViewExtractSkipRuleValuesSet
ViewExtractSkipRuleValuesSet sets an option to include/exclude rule-calculated values in a view and any
associated view extracts. A view extract is a TM1 view exported as an ASCII comma-delimited (.cma) file.
ViewExtractSkipRuleValuesSet is the equivalent of the Skip Rule Calculated Values option in the View
Extract dialog box.
Note: This function affects views as they exist on the server. The scope of this function is not restricted
to extracts generated from a view. Setting ViewExtractSkipRuleValuesSet=1 causes a "rules off"
mode, which turns off all rule evaluation. This means that not only are rule-calculated cells excluded, but
their contribution to consolidations is also ignored. This can result in consolidated values in the view being
different from the consolidated values in the cube.
This function is valid in TM1 TurboIntegrator processes only.

Chapter 5. TurboIntegrator Functions 397

 Syntax
ViewExtractSkipRuleValuesSet (Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you are
setting the option.

ViewName The view for which you are setting the option.

Flag A binary value that turns the option on or off.

Specify 1 to exclude rule-calculated values from
the extract. Specify 0 to include rule-calculated
values.

Note: Read about the impact of enabling a specific combination of view manipulation functions.

Example

ViewExtractSkipRuleValuesSet ('99sales', '1st QuarterActuals', 1);

This example turns on the Skip Rule Calculated Values option for the extract created from the 1st Quarter
Actuals view. The extract will not include any rule-calculated values.

ViewExtractSkipZeroesSet
ViewExtractSkipZeroesSet sets an option to include/exclude zero values in a view and any associated
view extracts. A view extract is a TM1 view exported as an ASCII comma-delimited (.cma) file.
ViewExtractSkipZeroesSet is the equivalent of the Skip Zero/Blank Values option in the View Extract
dialog box.
Note: This function affects views as they exist on the server. The scope of this function is not restricted to
extracts generated from a view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewExtractSkipZeroesSet (Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you are
setting the Skip Zeroes option.

ViewName The view for which you are setting the Skip Zeroes
option.

Flag A binary value that turns the option on or off.

Specify 1 to exclude zeroes from the extract.
Specify 0 to include zeros.
When UNDEFVALS is used to represent zeroes, the
values are not excluded when the Flag argument is
1.

398 IBM Planning Analytics: Reference

 Note: Read about the impact of enabling a specific combination of view manipulation functions.

Example

ViewExtractSkipZeroesSet ('99sales', '1st Quarter Actuals',1);

This example turns on the Skip Zeroes option for the extract created from the 1st Quarter Actuals view.
The extract will not include any zero or blank values.

ViewMDXSet
ViewMDXSet sets the MDX expression for an existing MDX view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewMDXSet(Cube, ViewName, MDX_expression);

Argument Description

Cube The parent cube of the view you are creating.

ViewName The name you want to assign to the view.

MDX_expression A string value containing a valid MDX view

expression.

Example

ViewMDXSet('Sales', 'Account',
"select {[plan_version].[FY 2003 Budget]} on 0,
{[plan_business_unit].[10300]} on 1 from plan_budgetplan where
[plan_department].[200][plan_chart_of_accounts].[41101][plan_exchange_rates].[local]
[plan_source].[goal][plan_time].[Jan-2003]"
);

This example sets the MDX expression for the "Account" view from the "Sales" cube.

ViewMDXGet
ViewMDXGet retrieves the MDX expression for an existing MDX view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewMDXGet(Cube, ViewName);

Argument Description

Cube The parent cube of the view you are creating.

ViewName The name you want to assign to the view.

Chapter 5. TurboIntegrator Functions 399

 Example

ViewMDXGet('Sales', 'Account');

This example retrieves the MDX expression from the "Account" view.

ViewRowDimensionSet
ViewRowDimensionSet sets a row dimension for a view.
This function is valid in TurboIntegrator processes only.

Syntax
ViewRowDimensionSet(CubeName, ViewName, DimName, StackPosition);

Argument Description

CubeName The parent cube of the view for which you are
setting the row dimension.

ViewName The view for which you are setting the row
dimension.

DimName The dimension you want to set as a row dimension

for the view.

StackPosition A number that indicates the stack position of the

dimension in the view. This is a 1-based number. 1
indicates the left-most stack position. 2 indicates a
position to the right of 1, and so on.
Note: It is possible for a TM1
client to set a [Link] parameter
(BrowseDisplayReadsRightToLeft=T) that reverses
the orientation of data in the Cube Viewer. When
the orientation of data is reversed, the stack
positions are also reversed. 1 indicates the right-
most stack position. 2 indicates a position to the
left of 1, and so on.

Example

ViewRowDimensionSet('98sales', 'Quarter1', 'Month',1)

This example sets Month as a row dimension for the 1Quarter view of the 98sales cube. In the event of
stacked row dimensions, Month is placed in the left-most position.

ViewRowSuppressZeroesSet
ViewRowSuppressZeroesSet suppresses or enables the display of rows containing only zero values in a
TM1 cube view.
This function is valid in TM1 TurboIntegrator processes only.

400 IBM Planning Analytics: Reference

 Syntax
ViewRowSuppressZeroesSet(Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you want to
suppress or enable the display of zero values.

ViewName The view for which you want to enable or suppress

the display of zeroes.

Flag A binary value that enables or suppresses zeroes.

Specify 1 to suppress the display of rows
containing only zeroes in the view. Specify 0 to
enable the display of rows containing only zeroes.

Example

ViewRowSuppressZeroesSet('99sales', '1st Quarter Actuals',1);

This example suppresses the display of any rows containing only zeroes in the 1st Quarter Actuals view of
the 99sales cube.

ViewSubsetAssign
ViewSubsetAssign assigns a named subset to a cube view.
Note: It is possible to create a temporary subset with the CreateSubset or CreateSubsetByMDX functions.
If you attempt to use ViewSubsetAssign to assign a temporary subset to a permanent view, the function
will fail with error notification.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewSubsetAssign(Cube, ViewName, DimName, SubName);

Argument Description

Cube The parent cube of the view to which you are

assigning a subset.

ViewName The view to which you are assigning a subset.

DimName The parent dimension of the subset you are

assigning to the view.

SubName The name of the subset you want to assign to the

view.

Example

ViewSubsetAssign('99sales', '1st Quarter Actuals', 'Month','Q1');

This example assigns the Q1 subset of the Month dimension to the 1st Quarter view.

Chapter 5. TurboIntegrator Functions 401

ViewSuppressZeroesSet
ViewSuppressZeroesSet suppresses or enables the display of all rows and columns containing only zero
values in a TM1 cube view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewSuppressZeroesSet(Cube, ViewName, Flag);

Argument Description

Cube The parent cube of the view for which you want to
suppress or enable the display of zero values.

ViewName The view for which you want to enable or suppress

the display of zeroes.

Flag A binary value that enables or suppresses zeroes.

Specify 1 to suppress the display of rows or
columns containing only zeroes in the view. Specify
0 to enable the display of rows and columns
containing only zeroes.

Example

ViewSuppressZeroesSet('99sales', '1st Quarter Actuals',1);

This example suppresses the display of any rows or columns containing only zeroes in the 1st Quarter
Actuals view of the 99sales cube.

ViewTitleDimensionSet
ViewTitleDimensionSet sets a title dimension for a TM1 view.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewTitleDimensionSet(CubeName, ViewName, DimName);

Argument Description

CubeName The parent cube of the view for which you are
setting the title dimension.

ViewName The view for which you are setting the title
dimension.

DimName The dimension you want to set as a title dimension

for the view.

Example

ViewTitleDimensionSet('98sales', 'Quarter1', 'Month');

402 IBM Planning Analytics: Reference

 This example sets Month as a title dimension for the 1Quarter view of the 98sales cube.

ViewTitleElementSet
ViewTitleElementSet sets a title element for a TM1 view. ViewTitleElementSet is used in conjunction with
the ViewTitleDimensionSet function.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
ViewTitleElementSet(CubeName, ViewName, DimName, Index);

Argument Description

CubeName The parent cube of the view for which you are
setting the title element.

ViewName The view for which you are setting the title
element.

DimName The parent dimension of the title element.

Index An index into the specified dimension that

indicates the element to be set as the title
element.

Example

ViewTitleElementSet('98sales', 'Quarter1', 'Model',3);

This example sets the third element of the Model dimension as a title element for the Quarter1 view of the
98sales cube.

ViewZeroOut
ViewZeroOut sets all data points in a view to zero.
This function is valid in TM1 TurboIntegrator processes only.
Note: When using ViewZeroOut on a cube which has UNDEFVALS enabled, the values in the view will be
set to zero, not the UNDEFVAL state.

Syntax
ViewZeroOut(Cube, ViewName);

Argument Description

Cube The parent cube of the view you want to zero out.

ViewName The view you want to zero out.

Example

ViewZeroOut('99sales', '1st Quarter Actuals');

Chapter 5. TurboIntegrator Functions 403

 This example sets all data points in the 1st Quarter Actuals view to zero.

Miscellaneous TurboIntegrator Functions

These functions facilitate miscellaneous tasks.

AddInfoCubeRestriction
AddInfoCubeRestriction filters InfoCube data as it is pulled into TM1. Use this function to restrict the
values that are imported for a specified characteristic. This function must be placed in the Prolog. The
function can be called multiple times to filter more than one characteristic in a single process.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
AddInfoCubeRestriction(STRING CharactName, STRING sign,STRING compOperator,
STRING lowValue, STRING highValue)

Argument Description

STRING CharactName Contains the technical name of the characteristic

to be restricted. The data type has to be a
character string with a length equal to or less than
30.

STRING sign Contains either I (= inclusive) or E (= exclusive).

Exclusive is the logical NOT for the restriction
specified by this row. The data type has to be a
character of length 1.

STRING compOperator Contains the relational comparative operator. The

data type has to be a character string of length 2.
Valid comparative operators are:
'EQ' = equal
'NE' = not equal
'LT' = less than
'GT' = grater than
'LE' = less or equal
'GE' = grater or equal
'BT' = between
'NB' = not between

STRING lowValue Contains the low value for the operator specified in
the row before. The data type has to be a character
string with a length equal to or less than 60.

404 IBM Planning Analytics: Reference

 Argument Description

STRING highValue Contains the high value for the operator specified
two rows before. The data type has to be a
character string with a length equal to or less than
60. It is only needed for the operators BT and NB,
otherwise it is ignored, and in this case an empty
string should be placed here.

Example
The following example returns all characteristic values between 1997 and 2000.

AddInfoCubeRestriction('0CALYEAR','E','BT','1997','2000');

The following example returns all characteristic values not between 1997 and 2000.

AddInfoCubeRestriction('0CALYEAR','I','NB','1997', '2000') ;

The following example returns all characteristic values not equal to USD.

AddInfoCubeRestriction('0DOC_CURRCY', 'I', 'NE', 'USD','') ;

ExecuteJavaN
ExecuteJavaN executes a Java™ TurboIntegrator process that returns a number. If you want to execute a
Java TurboIntegrator process that returns a string, use ExecuteJavaS.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
ExecuteJavaN('JavaTIClass', ['OptionalParameter1', 'OptionalParameter2', ...] )

Argument Description

JavaTIClass The fully qualified name of the Java

TurboIntegrator class you want to execute.

OptionalParameters Optional parameters that are passed to the Java

TurboIntegrator process itself. You can pass as
many parameters as necessary, including none.
You can pass only strings as parameters,
you cannot pass numbers. You can use the
StringToNumber TurboIntegrator function to pass
numbers to Java TurboIntegrator scripts. For more
information, see "StringToNumber" in the TM1
Reference.

A Java TurboIntegrator class, which returns a number and can be called from ExecuteJavaN, must use the
following pattern:

package [Link];

import [Link];

Chapter 5. TurboIntegrator Functions 405

 @JavaTI
public class MyTestTI {
public static double MyTestTI (String [] args) [
...
return ...;
}
}

Example
ExecuteJavaN('[Link]', 'First', 'Second', 'Third');

ExecuteJavaS
ExecuteJavaS executes a Java TurboIntegrator process that returns a string. If you want to execute a Java
TurboIntegrator process that returns a number, use ExecuteJavaN.
This function is valid in processes only.
This function is not supported in processes on TM1 Database 12.

Syntax
ExecuteJavaS('JavaTIClass', ['OptionalParameter1', 'OptionalParameter2', ...] )

Argument Description

JavaTIClass The fully qualified name of the Java

TurboIntegrator class you want to execute.

OptionalParameters Optional parameters that are passed to the Java

TurboIntegrator process itself. You can pass as
many parameters as necessary, including none.
You can pass only strings as parameters,
you cannot pass numbers. You can use the
StringToNumber TurboIntegrator function to pass
numbers to Java TurboIntegrator scripts. For more
information, see "StringToNumber" in the TM1
Reference.

A Java TurboIntegrator class, which returns a string and is called from ExecuteJavaS, must use the
following pattern.

package [Link];

import [Link];

@JavaTI
public class MyTestTI {
public static String MyTestTI (String [] args) [
...
return ...;
}
}

Example
ExecuteJavaS('[Link]', 'First', 'Second', 'Third');

406 IBM Planning Analytics: Reference

Expand
Expand expands TurboIntegrator variable names, enclosed in % signs, to their values at run time. A
common use of the Expand function is to pass the value of TurboIntegrator variables to the ODBCOutput
function.
If the variable name represents a string variable, the entire variable expression must be enclosed on
quotes. For example, "%V1%".
If Expand is fed with a numerical value, an implicit type conversion is performed and the numerical value
is converted into a string.
That string has a fixed minimum length of 10 characters. If the converted number is too small to fill 10
characters, it is padded with leading spaces. Only three leading decimal characters are converted. For
example, a numerical value of 0.123456789 is converted into the string "0.123".
This function is valid in TM1 TurboIntegrator processes only.

Syntax
Expand(String);

Argument Description

String Any string that includes TurboIntegrator variable

names enclosed in % signs.

Example

ODBCOutPut( 'TransData', Expand( 'INSERT INTO SALES( MONTH, PRODUCT, SALES )

VALUES ( "%V0%", "%V1%",%V2% )' ) );

This example illustrates the use of the Expand function within the ODBCOutput function. The example
inserts records into a relational table named Sales that consists of three columns: Month, Product, and
Sales.
The Expand function converts the variables V0, V1, and V2 to their actual values within the view.
Assuming that the first value in the view is 123.456, and is defined by the elements Jan and Widget

Expand( 'INSERT INTO SALES ( MONTH, PRODUCT, SALES ) VALUES ("%V0%", "%V1%",%V2% )' )

becomes

'INSERTINTO SALES ( MONTH, PRODUCT, SALES ) VALUES ( Jan, Widget,123.456 )'

at run time.

FileExists
FileExists determines whether a specified file exists. The function returns 1 if the file exists, 0 if it does
not.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
FileExists(File);

Chapter 5. TurboIntegrator Functions 407

 Argument Description

File The name of a file. If a full parth is not specified,

TM1 searches for the file in the server data
directory.

Example

FileExists('C:\tm1s7\pdata\[Link]');

This example determines if the [Link] file exists.

LogOutput
LogOutput writes a message to the [Link] file and optionally the process log file when an error
of a specified severity level is encountered in a TurboIntegrator process.
This function is valid in TM1 TurboIntegrator processes only.

Prerequisite
To enable message logging from TurboIntegrator, you must add the [Link] debugger
to the [Link] file and set the debugger to the wanted level. For example, adding
[Link]=DEBUG to [Link] enables logging for all severity levels. For more
information on the [Link] file, see "Configuring and Enabling Server Message Logging" in
TM1 Operations.

Syntax
LogOutput('SeverityLevel', 'MessageString', 'ProcessLog');

Argument Description
SeverityLevel The severity level that initiates logging to the
[Link] filelog files. Valid values for this
argument are:
• 'DEBUG'
• 'INFO'
• 'WARN'
• 'ERROR'
• 'FATAL'

MessageString The message that you want to write to the

[Link] filelog files. The message string
can be a string that is enclosed in single quotation
marks or can be another TurboIntegrator function
that returns a string.
ProcessLog Optional. If set to 1, this function also writes the
message to the TurboIntegrator process log file in
addition to the [Link] file.
If set to 0 or not defined, the function writes
messages to just the [Link].

408 IBM Planning Analytics: Reference

 Examples
LogOutput('WARN', 'TI process encountered a warning condition');

LogOutput('ERROR', TM1User(), 0);

LogOutput('INFO', 'TI process execution finished normally', 1);

TM1User
TM1User returns a string giving the current TM1 client. When executed in a process that the user is
running directly, it will return the user's TM1 client name. When executed in a chore that the user runs
directly, it will also return the user's TM1 client name.
If run from a scheduled chore, it will return a name in the form R*<chore name>, for example,
R*UpdateRegionDimension.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
TM1User()

WildcardFileSearch
WildcardFileSearch lets you use wildcard characters to search for files in a specified directory.
The results of the WildCardFileSearch function may vary depending on the operating system in use.
Files in a Windows directory are sorted in alphabetical order while files in a UNIX directory are sorted
in random order. Because the order of sorting varies between the operating systems, the identical
WildCardFileSearch function executed against identical directories, one on Windows and one on UNIX,
will yield different results.
This function is valid in TM1 TurboIntegrator processes only.

Syntax
WildcardFileSearch( Pathname, PriorFilename);

Argument Description

Pathname A pathname to files for which you want to search.

The pathname must end in a filename, which can
contain a wildcard sequence using the * and/or ?
characters.
The ? wildcard character matches any single
character.
The * wildcard character matches zero or more
characters.

Chapter 5. TurboIntegrator Functions 409

 Argument Description

PriorFilename The name of an existing file in the specified

directory. This filename cannot contain wildcard
characters. The wildcard search specified by the
Pathname argument will commence AFTER this
file.
If you pass an empty string as the PriorFilename
argument, the WildcardFileSearch function returns
the first file that matches the wildcard sequence
specified by the Pathname argument.

Example
The following example shows the use of the WildcardFileSearch function to determine the first server log
file generated in 2004:

file = WildcardFileSearch( 'C:\Program Files\Cognos\TM1\Custom\

TM1Data\SData\tm1s2004*.log', ' ');

This example returns the first file matching the wildcard sequence 'tm1s2004*.log' from the C:\Program
Files\Cognos\TM1\Custom\TM1Data\SData\ directory.
Because server log files are named and saved with sequential time stamps, and because the second
parameter to WildcardFileSearch is empty, the function returns the first server log file starting with the
characters 'tm1s2004'. This would be the first server log file generated in the year 2004.
The following example shows the use of the WildcardFileSearch function to return the first server log file
generated after [Link] was generated:

file = WildcardFileSearch( 'C:\Program Files\Cognos\TM1\Custom\

TM1Data\SData\tm1s*.log', '[Link]
');

This example begins searching the C:\Program Files\Cognos\TM1\Custom\TM1Data\SData\ directory

immediately after the [Link] file, and returns the first subsequent file matching the
'tm1s*.log' wildcard sequence.
[Link] is the first file that occurs after [Link] and matches the
wildcard sequence. Accordingly, the example returns [Link].

410 IBM Planning Analytics: Reference

Chapter 6. TurboIntegrator Variables
IBM Planning Analytics variables are listed here by categories.

TurboIntegrator Local Variables

When you execute a TurboIntegrator process, a set of implicit local variables is generated. Local variables
exist only in the context of the process in which they are used, and are not available outside of the
process. Local variables are destroyed when a process exits. These variables can be overwritten to
manipulate a process. The following is the list of local variables:

DatasourceASCIIDecimalSeparator
This TurboIntegrator local variable sets the decimal separator to be used in any conversion of
a string to a number or a number to a string. If you set this variable you must also set the
DatasourceASCIIThousandSeparator variable.
The character specified must be a standard ASCII printable character, with a decimal value between 33
and 127 inclusive.

Syntax
DatasourceASCIIDecimalSeparator='Char';

or

DatasourceASCIIDecimalSeparator=Char(xx);

Argument Description

Char The ASCII character to be used as a separator.

The character can be specified as a character
enclosed in single quotes, or as an ASCII Char
decimal code without quotes.

Either of the following examples sets the comma character (,) as the separator.

DatasourceASCIIDecimalSeparator=',';

DatasourceASCIIDecimalSeparator=Char(44);

DatasourceASCIIDelimiter
This TurboIntegrator local variable sets the ASCII character to be used as a field delimiter when the
DatasourceType is 'CHARACTERDELIMITED".
The character specified must be a standard ASCII printable character, with a decimal value between 33
and 127 inclusive.

Syntax
DatasourceASCIIDelimiter='Char';

© Copyright IBM Corp. 2007, 2025 411

 or

DatasourceASCIIDelimiter=Char(xx);

Argument Description

Char The ASCII character to be used as a delimiter.

The character can be specified as a character
enclosed in single quotes, or as an ASCII Char
decimal code without quotes.

Either of the following examples sets the hyphen character (-) as the field delimiter.

DatasourceASCIIDelimiter='-';

DatasourceASCIIDelimiter=Char(45);

DatasourceASCIIHeaderRecords
This TurboIntegrator local variable indicates the number of records to be skipped before processing the
data source.

Syntax
DatasourceASCIIHeaderRecords=N;

Argument Description

N The number of records to be skipped before

processing the data source.

DatasourceASCIIQuoteCharacter
This TurboIntegrator local variable sets the ASCII character used to enclose the fields of the source file
when DatasourceType is 'CHARACTERDELIMITED'.
The character specified must be a standard ASCII printable character, with a decimal value between 33
and 127 inclusive.

Syntax
DatasourceASCIIQuoteCharacter='Char';

or

DatasourceASCIIQuoteCharacter=Char(xx);

Argument Description

Char The ASCII character that encloses fields in the

data source.
The character can be specified as a character
enclosed in single quotes, or as an ASCII Char
decimal code without quotes.

412 IBM Planning Analytics: Reference

 Either of the following examples sets the asterisk character (*) as the field delimiter.

DatasourceASCIIQuoteCharacter='*';

DatasourceASCIIQuoteCharacter=Char(42);

DatasourceASCIIThousandSeparator
This TurboIntegrator local variable sets the thousands separator to be used in any conversion of a string
to a number or a number to a string.
If you set this variable you must also set the DatasourceASCIIDecimalSeparator variable.
The character specified must be a standard ASCII printable character, with a decimal value between 33
and 127 inclusive.

Syntax
DatasourceASCIIThousandSeparator='Char';

or

DatasourceASCIIThousandSeparator=Char(xx);

Argument Description

Char The ASCII character to be used as a separator.

The character can be specified as a character
enclosed in single quotes, or as an ASCII Char
decimal code without quotes.

Either of the following examples sets the period character (.) as the thousands separator.

DatasourceASCIIThousandSeparator='.';

DatasourceASCIIThousandSeparator=Char(46);

DatasourceCubeview
This TurboIntegrator local variable sets the view to process if the DatasourceType is 'VIEW'.

Syntax
DatasourceCubeview='ViewName';

Argument Description

ViewName The name of the view to be processed. This must

be an existing view of the cube specified by the
DataSourceNameForServer variable.

DatasourceDimensionSubset
This TurboIntegrator local variable sets the subset to process if the DatasourceType is 'SUBSET.'
DatasourceNameForServer=Dimension name is also needed in conjunction with
DATASOURCEDIMENSIONSUBSET so TM1 can identify where the subset is located.

Chapter 6. TurboIntegrator Variables 413

 Syntax
DatasourceDimensionSubset='SubsetName';

Argument Description

SubsetName The name of the subset to be processed.

DatasourceJsonRootPointer
This TurboIntegrator local variable stores a JSON-Pointer object, which identifies and locates a specific
value in the JSON document.
This variable allows TurboIntegrator processes to use JSON files as data sources. Not specifying a root
pointer results in the complete record (a JSON value) to be assigned to one variable.

Syntax
DatasourceJsonRootPointer='RootPointerValue';

Argument Description

RootPointerValue The JSON pointer, which identifies a specific value

in the JSON document that is contained within
the specified JSON resource. The JSON resource
contains the record (or collection of records in a
JSON array) that the TurboIntegrator process uses
as a data source.

DatasourceJsonVariableMapping
This TurboIntegrator local variable maps specific values in the JSON document to individual variables.
This variable allows TurboIntegrator processes to use JSON files as data sources. The mapping is defined
by using a JSON object in which each property (which identifies the variable by name) maps to a JSON-
Pointer object that identifies the specific value in the JSON document that the TurboIntegrator processes
uses as a data source.

Syntax
DatasourceJsonVariableMapping='JsonStringValue';

Argument Description

JsonStringValue A string that contains variables and values in JSON

format.

To build a JSON string with multiple lines, use multiple JsonAdd() functions.
For example, to create a JSON object that represents the following mapping:

{
"vName": "/Name",
"vStreet": "/Address/Street",
"vCity": "/Address/City",
"vSecondPhoneNumber": "/PhoneNumbers/1"
}

414 IBM Planning Analytics: Reference

 Use JsonAdd() functions to set the DatasourceJsonVariableMapping variable values:

DataSourceJsonVariableMapping = JsonAdd( '{}', 'vName', StringToJson( '/Name' ));

DataSourceJsonVariableMapping = JsonAdd( DataSourceJsonVariableMapping, 'vStreet',
StringToJson( '/Address/Street' ));
DataSourceJsonVariableMapping = JsonAdd( DataSourceJsonVariableMapping, 'vCity',
StringToJson( '/Address/City' ));
DataSourceJsonVariableMapping = JsonAdd( DataSourceJsonVariableMapping, 'vSecondPhoneNumber',
StringToJson( '/PhoneNumbers/1' ));

DatasourceNameForServer
This TurboIntegrator local variable sets the name of the data source (.cma/.csv file, cube name, ODBC
source) used by the server when executing the process.

Syntax
DatasourceNameForServer='Name';

Argument Description

Name For a .cma/.csv data source, the full path of

the .cma file.
For cubes, the cube name prefaced with the string
'local:'.
For an ODBC source, the source name.

DatasourceNameForClient
This TurboIntegrator local variable sets the name of the data source (.cma file, cube name, ODBC source)
used by the client when creating or editing the process.

Syntax
DatasourceNameForClient='Name';

Argument Description

Name For a .cma data source, the full path of the .cma
file.
For cubes, the cube name prefaced with the string
'local:'.
For an ODBC source, the source name.

DatasourcePassword
This TurboIntegrator local variable sets the password used to connect to the data source.

Syntax
DatasourcePassword='Password';

Chapter 6. TurboIntegrator Variables 415

 Argument Description

Password The password used to connect to the data source

set with DatasourceNameForServer.

DatasourceQuery
This TurboIntegrator local variable sets the query string to use with the data source.

Syntax
DatasourceQuery='Query';

Argument Description

Query The query string to use with the data source that
was set with DatasourceNameForServer.

DatasourceType
This TurboIntegrator local variable sets the type of the data source.

Syntax
DataSourceType='Type';

Argument Description

Type Valid types include:

'CHARACTERDELIMITED', 'POSITIONDELIMITED',
'VIEW', 'SUBSET', 'ODBC' , 'OLEDBOLAP', 'NULL'

DatasourceUsername
This TurboIntegrator local variable sets the name used to connect to the data source.

Syntax
DatasourceUserName='Name';

Argument Description

Name The name used to connect to the data source set

with DatasourceNameForServer.

MinorErrorLogMax
This TurboIntegrator local variable defines the number of minor errors that will be written to the
[Link] file during process execution. If this variable is not defined in the process, the
default number of minor errors written to the log file is 1000.

416 IBM Planning Analytics: Reference

 Syntax
MinorErrorLogMax=N;

Argument Description

N Value indicating the number of errors that should

be written to the log file.
Specify an integer greater than zero to set the
maximum number of errors written to the log file.
Specify a value of 0 to log no errors during process
execution.
Specify a value of -1 to allow an unlimited number
of minor errors to be written to the log file.

The following table provides an example error log message

and the corresponding result.

Example Result

MinorErrorLogMax=750; The log file will accept up to 750 errors.

MinorErrorLogMax=0; No errors will be written to the log file.

MinorErrorLogMax=-1; No limit on the number of errors written to the log

file.

NValue
When the DatasourceType is 'VIEW', this TurboIntegrator local variable determines the value of the
current cell when Value_Is_String is 0. (That is, when the current cell is numeric.)

Syntax
Nvalue=N;

Argument Description

N The value of the current cell.

OnMinorErrorDoItemSkip
This TurboIntegrator local variable instructs TurboIntegrator to skip to the next record when a minor error
is encountered while processing a record.
This variable is useful in scenarios where a single bad field/value in a record causes multiple minor errors.
For example, if you have 100 CELLPUTN functions in a process and one of the fields in a given
record is 'bad' or invalid, the minor error count is incremented by 100. (1 for each CELLPUTN function
that encounters the error.) These 100 minor errors count towards the minor error limit defined by
MinorErrorLogMax. A TurboIntegrator process fails when it surpasses the number of minor errors defined
by MinorErrorLogMax.

Chapter 6. TurboIntegrator Variables 417

 If OnMinorErrorDoItemSkip=1; is included in the Prolog tab of the process, the process immediately skips
to the next record when a 'bad' or invalid field is encountered in a source record. Using the previous
example, this results in the minor error count being incremented by just 1, rather than 100.

Syntax
OnMinorErrorDoItemSkip=N;

Argument Description

N Value indicating if item should be skipped when a

minor error is encountered.
1 (or any other non-zero value) dictates that the
process should skip to the next record when a
minor error is encountered.
0 indicates that TurboIntegrator should continue
processing the current record when a minor error
occurs.

SValue
When the DatasourceType is 'VIEW', this TurboIntegrator local variable determines the value of the
current cell when Value_Is_String is not 0. (That is, when the current cell contains a string.)

Syntax
Svalue='String';

Argument Description

String The value of the current cell.

[Link] file
When a TurboIntegrator process encounters an error, it generates a [Link] file. This log file
is saved to the data directory of the server on which the process resides.
Note: In a Planning Analytics on Cloud environment, the [Link] file is retained for three
months. Any [Link] files that are older than three months are permanently deleted during
the regularly scheduled maintenance window. If you want to retain your [Link] files beyond
the three month maintenance interval, please compress them to a zip file. For more information on log file
retention in Planning Analytics on Cloud, see Log file retention periods.
A [Link] file contains a list of errors that are encountered by the process. For each error
encountered, the log file records the tab and line that caused the error, along with a brief description of
the error.
When a process error log file is generated, TM1 assigns a unique name that lets you readily identify which
TurboIntegrator process generated the error file and the time at which the file was created. File names
are assigned with the following convention:
TM1ProcessError_<time stamp>_<UID>_<process name>.log.
In this convention:
• <time stamp> is the time (expressed as yyyymmddhhmmss GMT) at which the file was generated

418 IBM Planning Analytics: Reference

 • <UID> is a unique identifier expressed as MMMTTTTT. It is a combination of the millisecond (MMM) at
which the error file was generated and the last five digits of the thread ID (TTTTT) of the process that
caused the errors. If the thread ID contains less than five digits, the thread ID includes leading zeroes.
• <process name> is the name of the TurboIntegrator process that caused the errors
For example, an error file named TM1ProcessError_20220224203148_726008808_
[Link] indicates that the error file was generated at 20:31:48:726 GMT on February 24,
2022 and that it contains errors that are caused by the CreateSalesCube process in thread 08808. Note
the leading zero included in the thread ID.
Manual intervention is required to delete or archive these log files. A new log file is generated each time a
TurboIntegrator process has an error (1 log file per TurboIntegrator execution).
Many TurboIntegrator process error logs might be generated for TurboIntegrator processes that run
frequently and generate an error on each execution. Many log files generated in the TM1 database log
directory might impact performance of the TM1 database when it creates or updates log files.
The Planning Analytics Administration ability to download log files might be impacted by a large number
of files in the TM1 database log directory. It's recommended to limit the number of files in the TM1
database logging directory to under 2000 files.

Value_Is_String
When the DatasourceType is 'VIEW', this TurboIntegrator local variable determines whether the current
cell should be treated as a string or a numeric value.

Syntax
Value_Is_String=N;

Argument Description

N Value indicating if the current cell is a string or a

numeric value.
0 dictates that the cell is a number; anything else
means the cell is treated as a string.

TurboIntegrator Global Variables

This type of TurboIntegrator variable is associated with an individual TM1 chore or with an individual
process and any attendant sub-processes. There are two types of global variables: implicit and user-
defined. Implicit global variables are described here. User-defined global variables are described in this
document.
Global variables can be used in two ways:
• Global variables can be declared within a process that is part of a given chore. Once declared, the global
variables are available to all other processes that are part of the chore. The variables persist while the
chore is executing and for the duration of the current server session. Global variables are destroyed
upon server shutdown.
• Global variables can be declared in one process and be made available to any subsequent processes
called by the ExecuteProcess( ) function. These sub-processes must use the same global variable
declaration statements (described in the following paragraphs) to access the global variables.
In the event that a global variable name is identical to a local variable name, the local variable definition
takes precedence and overrides the global variable.
Global variables are declared in a TurboIntegrator process using one of the following two functions

Chapter 6. TurboIntegrator Variables 419

NumericGlobalVariable('VariableName');
Use this function to declare a numeric global variable.

StringGlobalVariable('VariableName');
Use this function to define a string global variable.

Implicit Global Variables

When you execute a TurboIntegrator process, a set of implicit global variables is generated. If the process
generating the variables is part of a chore, these global variables are available to and can be shared by all
other processes within the chore.
In addition, all implicit global variables in a process are available to and can be shared by any subsequent
processes called by the ExecuteProcess( ) function.
Though implicit variables are generated by the TurboIntegrator process, you must declare a variable
before it can be used in a process
Implicit global variables are declared in a TurboIntegrator process using the
NumericGlobalVariable('VariableName');:
Click the following links for details on specific implicit global variables.
• DataMinorErrorCount.
• MetadataMinorErrorCount.
• ProcessReturnCode.
• PrologMinorErrorCount.
For example, to use the PrologMinorErrorCount implicit global variable in a process, you must first declare
the variable as follows:

NumericGlobalVariable('PrologMinorErrorCount');

DataMinorErrorCount
This TurboIntegrator global variable counts the minor errors that occur in the Data portion of a
TurboIntegrator process. For each minor error encountered, the variable value is incremented by 1.

Syntax
DataMinorErrorCount=N;

Argument Description

N The number of minor errors encountered in the

Data portion of the process.

MetadataMinorErrorCount
This TurboIntegrator global variable counts the minor errors that occur in the Metadata portion of a
TurboIntegrator process. For each minor error encountered, the variable value is incremented by 1.

Syntax
MetadataMinorErrorCount=N;

420 IBM Planning Analytics: Reference

 Table 13. MetadataMinorErrorCount arguments

Argument Description

N The number of minor errors encountered in the

Metadata portion of the process.

ProcessReturnCode
This TurboIntegrator global variable stores the exit status of the most recently executed TurboIntegrator
process.

Syntax
ProcessReturnCode=StatusCode;

Status Code Description

ProcessExitByBreak() Indicates that the process exited because it

encountered a ProcessBreak function.

ProcessExitByChoreQuit() Indicates that the process exited due to execution

of the ChoreQuit function.

ProcessExitByChoreRollback() Indicates that the process exited because it

encountered a ChoreRollback function.

ProcessExitByProcessRollback() Indicates that the process exited because it

encountered a ProcessRollback function.

ProcessExitByQuit() Indicates that the process exited because of an

explicit quit command.

ProcessExitMinorError() Indicates that the process executed successfully

but encountered minor errors.

ProcessExitNormal() Indicates that the process executed normally.

ProcessExitOnInit() Indicates that the process aborted during

initialization.

ProcessExitSeriousError() Indicates that the process exited because of a

serious error.

ProcessExitWithMessage() Indicates that the process exited normally, with a

message written to [Link].

PrologMinorErrorCount
This TurboIntegrator global variable counts the minor errors that occur in the Prolog portion of a
TurboIntegrator process. For each minor error encountered, the variable value is incremented by 1.

Syntax
PrologMinorErrorCount=N;

Chapter 6. TurboIntegrator Variables 421

 Argument Description

N The number of minor errors encountered in the

Prolog.

TurboIntegrator User Variables

This type of variable is associated with an individual TM1 user, not with any particular process or chore.
User variables can be manipulated from within any TurboIntegrator process or chore while the user with
which the variable is associated is logged on to the server.
User variables must be explicitly declared. Once declared, user variables persist for the life of the user's
TM1 session (until the user logs off or is disconnected from the server).
User variables are declared in a TurboIntegrator process using one of the following two functions:
• NumericGlobalVariable('VariableName');. Use this function to declare a numeric user variable.
• StringGlobalVariable('VariableName');. Use this function to define a string user variable.
User variables are created the first time such a declaration is encountered in any running TurboIntegrator
process.
Once created, the variable name may be referenced and used just like any local or global variable, expect
that the variable value persists across processes and chores only for as long as the user who created the
variable is logged on to the server.

422 IBM Planning Analytics: Reference

Notices
This information was developed for products and services offered worldwide.
This material may be available from IBM in other languages. However, you may be required to own a copy
of the product or product version in that language in order to access it.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program,
or service that does not infringe any IBM intellectual property right may be used instead. However, it
is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or
service. This document may describe products, services, or features that are not included in the Program
or license entitlement that you have purchased.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of
the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Software Group

Attention: Licensing

© Copyright IBM Corp. 2007, 2025 423

 3755 Riverside Dr.
Ottawa, ON
K1V 1B7
Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information is for planning purposes only. The information here is subject to change before the
products described become available.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©
Copyright IBM Corp. _enter the year or years_.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
This Software Offering does not use cookies or other technologies to collect personally identifiable
information.

424 Notices
©

Product Information
This document applies to IBM Planning Analytics version 2.0.0 and may also apply to subsequent
releases.

Copyright
Licensed Materials - Property of IBM
© Copyright IBM Corp. 2007, 2022.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule
Contract with IBM Corp.
IBM, the IBM logo, and [Link] are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the web in "
Copyright and trademark information " at [Link]/legal/[Link].

Other trademarks
The following terms are trademarks or registered trademarks of other companies:
• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
• The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the
exclusive licensee of Linus Torvalds, owner of the mark on a worldwide basis.
• UNIX is a registered trademark of The Open Group in the United States and other countries.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle
and/or its affiliates.
• Red Hat®, JBoss®, OpenShift®, Fedora®, Hibernate®, Ansible®, CloudForms®, RHCA®, RHCE®, RHCSA®,
Ceph®, and Gluster® are trademarks or registered trademarks of Red Hat, Inc. or its subsidiaries in the
United States and other countries.
Microsoft product screen shot(s) used with permission from Microsoft.

Notices 425
426 IBM Planning Analytics: Reference
Index

A B
ABS 142 BatchUpdateFinish 281, 362
access BatchUpdateFinishWait 363
privileges Security Assignments 47 BatchUpdateStart 364
ACOS 143 bookmarks 43
action button buttons
properties 1 TurboIntegrator Editor 83
AddClient 349
AddCubeDependency 272
AddGroup 349
C
AddInfoCubeRestriction 404 Calculation functions 99
Admin CAPIT 150
Security Assignments 50 CellGetN 273
Server Transport Layer Security, TM1 Options 68 CellGetS 274
advanced CellIncrementN 274
Mapping Grid 4 CellIsUpdateable 275
Options 4 CellPutN 276
TurboIntegrator Editor tab 89 CellPutProportionalSpread 276
all screens CellPutS 277
Print Report Wizard 36 CellSecurityCubeCreate 351
appearance action button 4 CellSecurityCubeDestroy 351
application CellValueN 107
Server Explorer 54 CellValueS 107
arithmetic operators 93 CHAR 150
ASCII character set 213
and Text TurboIntegrator Functions 209 check syntax 43
ASCIIDelete 210 Chinese 43
ASCIIOutput 210 chore
ASCIIOutputOpen 211 Management TurboIntegrator Functions 270
ASIN 143 Quit 271
assign Server Explorer 61
Security Assignments grid 47 Setup Wizard 13
AssignClientPassword 350 ChoreAttrDelete 224
AssignClientToGroup 349 ChoreAttrInsert 224
AssociateCAMIDToGroup 350 ChoreAttrN 225
ATAN 143 ChoreAttrNL 225
AttrDelete 221 ChoreAttrPutN 226
attribute ChoreAttrPutS 227
Editor 6 ChoreAttrS 228
Manipulation TurboIntegrator Functions 219 ChoreAttrSL 228
TurboIntegrator Editor 85 ChoreError 270
AttrInsert 222 ChoreRollback 271
ATTRN 94 Clients
ATTRNL 219 /Group Window 14
AttrPutN 222 /Groups grid 14, 15
AttrPutS 223 menu Clients/Groups 15
ATTRS 95 Messaging Center Dialog Box 16
AttrSL 220 CODE 151
Audit log CODEW 151
details window 12 column dimensions
window 9 Cube Viewer 20
Audit log details window 12 comments 43
Audit log window 9 comparison 93
auto-complete 45 Connect Server 34
automatic mapping 4 ConsolidatedAvg 99
ConsolidatedCount 102

Index 427
ConsolidatedCountUnique 103 Data Reservation TurboIntegrator functions (continued)
ConsolidatedMax 104 CubeDataReservationRelease 285
ConsolidatedMin 106 CubeDataReservationReleaseAll 286
consolidation DataMinorErrorCount 420
TurboIntegrator Editor 85 DatasourceASCIIDecimalSeparator 411
CONTINUE 141 DatasourceASCIIDelimiter 411
control DatasourceASCIIHeaderRecords 412
objects 45 DatasourceASCIIQuoteCharacter 412
options 45 DatasourceASCIIThousandSeparator 413
COS 144 DatasourceCubeview 413
create DatasourceDimensionSubset 413
cube dialog box 17 DatasourceJsonRootPointer 414
dimension dialog box 17 DatasourceJsonVariableMapping 414
server replication object 17 DatasourceNameForClient 415
CreateHierarchyByAttribute 305 DatasourceNameForServer 415
cube DatasourcePassword 415
Information Subset Editor 41 DatasourceQuery 416
optimizing 18 DatasourceType 416
Properties Dialog Box 19 DatasourceUsername 416
Server Explorer 55 DATE 112
TurboIntegrator Editor 85 date and time
TurboIntegrator manipulation functions 272 TurboIntegrator functions 288
Viewer 20 DATES 113
CubeAttrDelete 229 DAY 114
CubeAttrInsert 230 DAYNO 114
CubeATTRN 96 DBProportionalSpread 161
CubeATTRNL 232 DBR 179
CubeAttrPutN 230 DBRA 180
CubeAttrPutS 231 DBRW 180
CubeATTRS 96 DBS 181
CubeATTRSL 232 DBSA 182
CubeClearData 278 DBSS 183
CubeCreate 278 DBSW 183
CubeDataReservationAcquire 284 DELET 151
CubeDataReservationGet 286 Delete Named Subsets Dialog Box 23
CubeDataReservationGetConflicts 288 Delete Named Views Dialog Box 23
CubeDataReservationRelease 285 DeleteAllPersistentFeeders 336
CubeDataReservationReleaseAll 286 DeleteClient 352
CubeDestroy 279 DeleteGroup 352
CubeDimensionCountGet 279 DFRST 184
CubeExists 280 dialog boxes 1
CubeGetLogChanges 280 dimension
CubeProcessFeeders 333 Dimension Editor menu 23
CubeRuleAppend 333 Element Insert Dialog Box 27
CubeRuleDestroy 334 Element Ordering Dialog Box 27
CubeSetConnParams 282 Element Properties Dialog Box 28
CubeSetLogChanges 282 Information Rules Functions 120
CubeTimeLastUpdated 283 Information Subset Editor 42
CubeUnload 283 Manipulation TurboIntegrator Functions 291
CubeView Server Explorer 56
Server Explorer 58 TurboIntegrator Editor 85
DimensionAttrDelete 233
DimensionAttrInsert 234
D DimensionATTRN 97
D_FSAVE 160 DimensionATTRNL 236
D_PICK 159 DimensionAttrPutN 234
D_SAVE 160 DimensionAttrPutS 235
data DimensionATTRS 97
source tab TurboIntegrator Editor 71 DimensionATTRSL 237
TurboIntegrator Editor 85, 89 DimensionCreate 291
Data Reservation TurboIntegrator functions DimensionDeleteAllElements 291
CubeDataReservationAcquire 284 DimensionDeleteElements 292
CubeDataReservationGet 286 DimensionDestroy 292
CubeDataReservationGetConflicts 288 DimensionElementComponentAdd 293

428 IBM Planning Analytics: Reference

DimensionElementComponentAddDirect 293 ElementFirst 126
DimensionElementComponentDelete 294 ElementIndex 127
DimensionElementComponentDeleteDirect 294 ElementIsAncestor 127
DimensionElementDelete 295 ElementIsComponent 128
DimensionElementDeleteDirect 296 ElementIsParent 128
DimensionElementExists 297 ElementLevel 129
DimensionElementInsert 297 ElementName 130
DimensionElementInsertDirect 298, 303 ElementNext 130
DimensionElementPrincipalName 299 ElementParent 131
DimensionExists 300 ElementParentCount 131
DimensionHierarchyCreate 300 ElementSecurityGet 353
DimensionSortOrder 301 ElementSecurityPut 353
DimensionTimeLastUpdated 302 ElementType 132
DimensionTopElementInsert 302 ElementWeight 132
DimensionUpdateDirect 304 ELISANC 133
DIMIX 121, 184 ELISCOMP 133, 188
DIMNM 121, 185 ELISPAR 134, 189
DIMSIZ 122, 185 ELLEV 135, 190
DisableBulkLoadMode 364 ELPAR 135, 190
DisableMTQViewConstruct 389 ELPARN 136, 191
DNEXT 122, 186 ELSEN 191
DNLEV 122, 186 ELWEIGHT 136, 192
DTYPE 123, 187 EnableBulkLoadMode 365
dynamic menu EnableMTQViewConstruct 389
Server Explorer 52 epilog
Dynamic Reports TurboIntegrator Editor 89
TM1ELLIST 195 Excel
TM1GLOBALSANDBOX 198 macro functions 159
TM1INFO 198 ExecuteCommand 322
TTM1PRIMARYDBNAME 200 ExecuteJavaN 405
ExecuteJavaS 406
ExecuteProcess 323, 419
E EXP 144
E_PICK 161 Expand 407
edit Exponentiation 93
Formula Dialog Box 29
Reference to Cube Dialog Box 29 F
Edit menu
Attributes 7 FEEDERS 157
Cube Viewer 21 FEEDSTRINGS 158
Dimension Editor 24 file menu
Message Log Window 35 Attributes 7
Server Explorer 62 Cube Viewer 20
Subset Editor 63 Message Log Window 35
Transaction Log Query Results 69 Server Explorer 51
TurboIntegrator Editor 70 TurboIntegrator Editor 70
Editor 70 FileExists 407
ELCOMP 124, 187 FILL 152
ELCOMPN 124, 188 filter
element elements by attribute dialog box 30
Information Rules Functions 124 elements by level dialog box 30
pane Dimension Editor 23 subset dialog box 30
pane Subset Editor 62 view dialog box 32
ElementAttrDelete 242 financial rules functions 137
ElementAttrInsert 242 Find 43
ElementAttrN 98 ForceSkipCheck 337
ElementATTRNL 238 FormatDate 289
ElementAttrPutN 240 functions
ElementAttrPutS 241 rules 93, 159
ElementAttrS 98 TurboIntegrator 209
ElementATTRSL 239 FV 137
ElementComponent 125
ElementComponentCount 125
ElementCount 126

Index 429
G HierarchySubsetExists 373
HierarchySubsetGetElementName 374
Get View Dialog Box (In-Spreadsheet Browser) 34 HierarchySubsetGetSize 373
GetProcessErrorFileDirectory 325 HierarchySubsetIsAllSet 374
GetProcessErrorFilename 325 HierarchySubsetMDXGet 375
GetProcessName 325 HierarchySubsetMDXSet 375
GetUseActiveSandboxProperty 339 HierarchyTimeLastUpdated 317
Global variables 419 HierarchyTopElementInsert 318
grid HierarchyTopElementInsertDirect 318
TurboIntegrator Editor 83 HierarchyUpdateDirect 319
groups menu
Clients/Groups
15
I
I_EXPORT 163
H I_NAMES 163
I_PROCESS 164
help menu If 326
Message Log Window 36 IF 141
hierarchy implicit global variables 420
TurboIntegrator manipulation functions 304 import 43
hierarchy rules functions 139 In-Spreadsheet Browser Menu 34
HierarchyATTRN 244 indent 43
HierarchyATTRNL 245 insert cube reference 45
HierarchyAttrPutN 243 INSRT 152
HierarchyAttrPutS 244 INT 144
HierarchyATTRS 245 ISUND 145
HierarchyATTRSL 246 ISUNDEFINEDCELLVALUE 109
HierarchyContainsAllLeaves 305 ItemReject 326
HierarchyCreate 306 ItemSkip 327
HierarchyDeleteAllElements 306
HierarchyDeleteElements 307
HierarchyDestroy 307
J
HierarchyElementComponentAdd 308 Japanese 43
HierarchyElementComponentAddDirect 308
HierarchyElementComponentDelete 309
HierarchyElementComponentDeleteDirect 310 K
HierarchyElementDelete 311
KEY_ERR 179
HierarchyElementDeleteDirect 311
Korean 43
HierarchyElementExists 312
HierarchyElementInsert 312
HierarchyElementInsertDirect 313 L
HierarchyElementPrincipalName 314
HierarchyElementSecurityGet 354 large character sets 43
HierarchyElementSecurityPut 354 left pane (Tree pane)
HierarchyExists 315 Server Explorer 51
HierarchyHasOrphanedLeaves 315 LevelCount 137
HierarchySortOrder 316 line numbers 45
HierarchySubsetAliasGet 368 LN 145
HierarchySubsetAliasSet 368 local server
HierarchySubsetAttrDelete 253 TM1 Options 67
HierarchySubsetAttrInsert 252 local variables 411
HierarchySubsetATTRN 248 lock
HierarchySubsetATTRNL 249 Security Assignments 49
HierarchySubsetAttrPutN 251 lock contention 366
HierarchySubsetAttrPutS 250 LOG 145
HierarchySubsetATTRS 247 logical
HierarchySubsetATTRSL 248 operators 93
HierarchySubsetCreate 368 Rules Functions 141
HierarchySubsetDeleteAllElements 369 login parameters
HierarchySubsetDestroy 370 TM1 Options 67
HierarchySubsetElementDelete 371 LONG 153
HierarchySubsetElementExists 370 LOWER 153
HierarchySubsetElementGetIndex 371
HierarchySubsetElementInsert 372

430 IBM Planning Analytics: Reference

M preview grid
TurboIntegrator Editor 83
M_CLEAR 164 Print 43
macro functions print report wizard 36
accessing 159 Print Report wizard 36
list 159 process
maps tab TurboIntegrator Editor 85 action button 2
mathematical rules functions 142 control TurboIntegrator functions 322
MAX 146 Server Explorer 60
Message log process options dialog box 40
window 35 Process Variable Formula 84
message log window 35 ProcessAttrDelete 253
Message log window 35 ProcessAttrInsert 254
metadata ProcessAttrN 254
TurboIntegrator Editor 89 ProcessAttrNL 255
MetadataMinorErrorCount 420 ProcessAttrPutN 256
MIN 146 ProcessAttrPutS 257
MinorErrorLogMax 416 ProcessAttrS 258
miscellaneous ProcessAttrSL 258
Rules Functions 157 ProcessBreak 327
TurboIntegrator Functions 404 ProcessError 327
MOD 146 ProcessExists 328
MONTH 114 ProcessExitByChoreRollback 328
ProcessExitByProcessRollback 328
ProcessQuit 329
N ProcessReturnCode 421
new attribute dialog box 36 ProcessRollback 329
NewDateFormatter 289 prolog
none TurboIntegrator Editor 89
Security Assignments 47 PrologMinorErrorCount 421
NOW 115 properties
NumberToString 212 Dimension Editor pane 23
NumberToStringEx 213 Dimension Element pane 28
NUMBR 153 regional settings 7
NumericGlobalVariable(VariableName) 420 Subset Editor pane 62
NumericSessionVariable(ariableName 422 PublishSubset 166, 376
NValue 417 PublishView 167, 388
PV 138

O
Q
ODBC TurboIntegrator Functions 320
ODBCClose 320 QUDEFINE 167
ODBCOpen 320 QUDEFINEEX 169
ODBCOPENEx 321 QUEXPORT 170
ODBCOutput 321 QULOOP 171
OnMinorErrorDoItemSkip 417 QUSUBSET 172
open subset dialog box 36
open view dialog box 36 R
OPTGET 165
optimizing cubes 18 R_SAVE 172
options RAND 147
Attributes 7 range parameters
cube viewer menu 22 View Extract 91
Dimension Element Properties 28 read
OPTSET 165 Security Assignments 48
RefreshMdxHierarchy function 365
regional settings properties 7
P RemoveCAMIDAssociation 355
parameters RemoveCAMIDAssociationFromGroup 356
TurboIntegrator Editor 89 RemoveClientFromGroup 356
ParseDate 290 replicate
PAYMT 138 Server Explorer 59
Preferences 45 replicate cube

Index 431
replicate cube (continued) SetChoreVerboseMessages 271
dialog box 41 SetDimensionGroupsSecurity 358
Server Explorer 60 SetElementGroupsSecurity 359
reserve SetHierarchyElementGroupsSecurity 357
Security Assignments 49 SetHierarchyGroupsSecurity 357
right pane (Properties pane) SetInputCharacterSet 213
Server Explorer 51 SetODBCUnicodeInterface 322
ROUND 147 SetOutputEscapeDoubleQuote 216
ROUNDP 148 SetUseActiveSandboxProperty 348
row SIGN 148
Cube Viewer 20 SIN 149
rule skip parameters
functions 93 View Extract 91
macro functions 159 SQRT 149
Subset Editor Information 41 status bar 45
TurboIntegrator management functions 333 STET 142, 209
RuleLoadFromFile 337 STR 154
run method 159 StringGlobalVariable(ariableName 420
RunProcess 330 StringSessionVariable(ariableName 422
StringToNumber 217
StringToNumberEx 217
S SUBDEFINE 173
Sandbox functions 339 SUBNM 194
SAPCharacteristicTexts 416 SUBPICK 173
save subset
In-Spreadsheet Browser View dialog box editor 62
46 Server Explorer 58, 59
subset dialog box 46 Subset Editor menu 63
View Dialog Box 46 TurboIntegrator manipulation functions 367
SaveDataAll 366 SubsetAliasGet 377
SCAN 154 SubsetAliasSet 377
schedule tab SubsetAttrDelete 264
TurboIntegrator Editor 90 SubsetAttrInsert 264
security SubsetATTRN 260
Assignments dialog box 47 SubsetATTRNL 261
Clients/Groups menu 14 SubsetAttrPutN 263
TurboIntegrator functions 348 SubsetAttrPutS 262
SecurityOverlayCreateGlobalDefault 360 SubsetATTRS 259
SecurityOverlayDestroyGlobalDefault 361 SubsetATTRSL 260
SecurityOverlayGlobalLockCell 359 SubsetCreate 377
SecurityOverlayGlobalLockNode 361 SubsetCreateByMDX 379
SecurityRefresh 362 SubsetDeleteAllElements 380
select cube SubsetDestroy 381
dialog box 51 SubsetElementDelete 381
for rules dialog box 51 SubsetElementExists 382
select dimension SubsetElementGetIndex 382
dialog box 51 SubsetElementInsert 383
security assignments 51 SubsetExists 383
select element SubsetExpandAboveSet 384
dialog box 51 SubsetFormatStyleSet 384
view extract 91 SubsetGetElementName 385
server SubsetGetSize 385
Explorer (Main Window) 51 SubsetIsAllSet 386
Server Explorer 52 SubsetMDXGet 386
TurboIntegrator manipulation functions 362 SubsetMDXSet 387
ServerActiveSandboxGet 339 SUBSIZ 194
ServerActiveSandboxSet 340 SUBST 156
Servers Group SValue 418
Server Explorer 52
ServerSandboxesDelete 341 T
ServerSandboxExists 346
ServerSandboxGet 346 T_CLEAR 174
ServerSandboxListCountGets 347 T_CREATE 174
ServerShutdown 367 T_CREATE16 175

432 IBM Planning Analytics: Reference

T_PICK 175 V
T_SAVE 176
TABDIM 123, 195 Value_Is_String 419
tabs variables
TurboIntegrator Editor 71 global 419
TAN 149 implicit global 420
text rules functions 150 Tab TurboIntegrator Editor 83
TextOutput 218 TurboIntegrator user 422
TIME 115 VBA modules
TIMST 115 macro functions 159
TIMVL 117 view
title dimensions Extract Window 91
Cube Viewer 20 styles dialog box 91
TM1 Aliases Dialog Box 67 TurboIntegrator manipulation functions 388
TM1 Options Dialog Box 67 VIEW 207
TM1 worksheet functions view menu
TM1ELLIST 195 Cube Viewer 21
TM1GLOBALSANDBOX 198 Dimension Editor 26
TM1INFO 198 Server Explorer 62
TM1PRIMARYDBNAME 200 Subset Editor 65
TM1ELLIST 195 ViewAttrDelete 265
TM1GLOBALSANDBOX 198 ViewAttrInsert 265
TM1INFO 198 ViewAttrN 266
[Link] 159 ViewAttrNL 266
TM1PRIMARYDBNAME 200 ViewAttrPutN 267
[Link] 418 ViewAttrPutS 268
TM1RECALC 176 ViewAttrS 269
TM1RECALC1 176 ViewAttrSL 269
TM1RptElIsConsolidated 200 ViewColumnDimensionSet 390
TM1RPTELISCONSOLIDATED 205 ViewColumnSuppressZeroesSet 391
TM1RptElIsExpanded 200 ViewConstruct 391
TM1RptElLev 201 ViewCreate 392
TM1RPTELLSEXPANDED 205 ViewCreateByMDX 393
TM1RptFilter 201 ViewDestroy 394
TM1RptRow 202 ViewExists 394
TM1RptTitle 203 ViewExtractFilterByTitlesSet 395
TM1RptView 204 ViewExtractSkipCalcsSet 396
TM1User 205, 409 ViewExtractSkipConsolidatedStringsSet 397
TODAY 119 ViewExtractSkipRuleValuesSet 397
toolbar 45 ViewExtractSkipZeroesSet 398
tools menu ViewMDXGet 399
Subset Editor 66 ViewMDXSet 399
tooltips 45 ViewRowDimensionSet 400
transaction log query ViewRowSuppressZeroesSet 400
dialog box 68 ViewSubsetAssign 401
results dialog box 69 ViewSuppressZeroesSet 402
TRIM 157 ViewTitleDimensionSet 402
TurboIntegrator ViewTitleElementSet 403
functions 209 ViewZeroOut 403
Global Variables 419 VUSLICE 177
limits 209
User Variables 422
W
U W_DBSENABLE 177
While 332
uncomment 43 WildcardFileSearch 409
UNDEFINEDCELLVALUE 110 windows dialog boxes 1
unindent 43 word wrap 45
UPPER 157 worksheet
user-defined regions 45 action button 2
UTF-8 213 write
Security Assignments 48

Index 433
Y
YEAR 120

434 IBM Planning Analytics: Reference

IBM®